# `Slither.Stage`
[🔗](https://github.com/nshkrdotcom/slither/blob/v0.1.0/lib/slither/stage.ex#L1)

Behaviour for a single processing step in a Slither pipeline.

Every stage can implement `handle_item/3` (scalar path) and/or
`handle_batch/3` (vectorized path). The pipe runner chooses the
most efficient path based on stage capabilities and batch boundaries.

## Result Types

  * `{:ok, [items]}` — emit items downstream (1:1 or 1:many)
  * `{:route, destination, [items]}` — route items to a named output
  * `{:routed, %{dest => [items]}}` — batch routing to multiple outputs
  * `{:skip, reason}` — drop the item
  * `{:error, reason}` — error

# `batch_result`

```elixir
@type batch_result() ::
  {:ok, [Slither.Item.t()]}
  | {:routed, %{required(atom()) => [Slither.Item.t()]}}
  | {:error, term()}
```

# `item_result`

```elixir
@type item_result() ::
  {:ok, [Slither.Item.t()]}
  | {:route, atom(), [Slither.Item.t()]}
  | {:skip, term()}
  | {:error, term()}
```

# `handle_batch`
*optional* 

```elixir
@callback handle_batch([Slither.Item.t()], Slither.Context.t(), state :: term()) ::
  batch_result()
```

Process a batch of items. Optional — defaults to mapping `handle_item/3`.

# `handle_item`

```elixir
@callback handle_item(Slither.Item.t(), Slither.Context.t(), state :: term()) ::
  item_result()
```

Process a single item. Return transformed items for downstream.

# `init`
*optional* 

```elixir
@callback init(keyword()) :: {:ok, term()} | {:error, term()}
```

Initialize the stage with options. Returns state passed to handlers.

# `shutdown`
*optional* 

```elixir
@callback shutdown(state :: term()) :: :ok
```

Clean up stage resources.

---

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