# `FeedReader.Collector`

Bounded collectors for local feed parsing.

The collector consumes the event stream produced by `FeedReader.Parser` and
returns a `FeedReader.ParseResult`. Callers must provide a positive integer
`:max_items`; accepted items beyond that limit produce an error instead of a
partial result. The parser stops after the feed's root element, so content
appended after a complete feed is not parsed.

Binary and chunk-enumerable inputs are written incrementally to a temporary
file before parsing. The temporary file is owned and removed by the collector;
caller-owned files passed to `collect/2` are never removed.

# `collect`

```elixir
@spec collect(Path.t(), keyword()) ::
  {:ok, FeedReader.ParseResult.t()} | {:error, term()}
```

Collects events from a caller-owned local feed file.

The `:item_filter` option may contain a one-argument function. It is applied
before items are counted and retained. The result contains normalized feed
metadata and the accepted items, or an error without partial data.

# `collect_session`

```elixir
@spec collect_session(FeedReader.Session.t(), keyword()) ::
  {:ok, FeedReader.ParseResult.t()} | {:error, term()}
```

Collects a session and releases its owned source on every outcome.

# `max_items`

```elixir
@spec max_items(keyword()) :: {:ok, pos_integer()} | {:error, term()}
```

Validates the required collection limit.

Returns `{:ok, max_items}` for a positive integer and
`{:error, {:invalid_option, :max_items}}` for all other values.

# `parse_stream`

```elixir
@spec parse_stream(Enumerable.t(), keyword()) ::
  {:ok, FeedReader.ParseResult.t()} | {:error, term()}
```

Collects XML chunks from an enumerable.

Chunks must be binaries. They are written incrementally to a library-owned
temporary file, which is removed on success, parser failure, or write
failure. Collection options have the same meaning as `collect/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*