# `Honker.Stream`

Append-only topic log with named-consumer offsets. Thin wrapper over
`honker_stream_*` SQL functions.

    {:ok, off1} = Honker.Stream.publish(db, "orders", %{id: 1})
    {:ok, events} = Honker.Stream.read_since(db, "orders", 0, 100)
    {:ok, true}  = Honker.Stream.save_offset(db, "billing", "orders", off1)

# `get_offset`

Current saved offset for `consumer` on `topic`, or 0 if unset.

# `publish`

Publish an event on `topic`. Returns `{:ok, offset}` — a monotonic
per-topic offset assigned by the extension.

Options:

  * `:key` — optional partition key (string) for per-key ordering
    downstream. Defaults to `nil`.

# `publish_tx`

Publish inside an open transaction.

# `read_from_consumer`

Read from the saved offset of `consumer` on `topic`. Does **not**
advance the offset — call `save_offset/4` after you've processed.

# `read_since`

Read up to `limit` events from `topic` with offset strictly greater
than `offset`. Returns `{:ok, [%Honker.StreamEvent{}, ...]}`.

# `save_offset`

Persist a consumer's offset. Monotonic: saving a lower offset than
already stored is a no-op (returns `{:ok, false}`).

# `save_offset_tx`

Save offset inside an open transaction.

---

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