# `Honker`

Elixir binding for [Honker](https://honker.dev) — a SQLite-native
task runtime.

This module is a thin wrapper around the Honker loadable extension.
Each public function is one SQL call via `Exqlite.Sqlite3`; state
lives in the `.db` file, not in Elixir processes.

## Example

    {:ok, db} = Honker.open("app.db", extension_path: "./libhonker_ext.dylib")

    Honker.Queue.enqueue(db, "emails", %{to: "alice@example.com"})

    case Honker.Queue.claim_one(db, "emails", "worker-1") do
      {:ok, nil} -> :empty
      {:ok, job} ->
        send_email(job.payload)
        Honker.Job.ack(db, job)
    end

A `Honker.Database` struct is the handle; it wraps an `Exqlite.Sqlite3`
reference + the queue's default options (visibility timeout, max
attempts). Use `configure_queue/3` to override per-queue.

# `close`

# `configure_queue`

Set the options for a named queue (visibility timeout, max attempts).
Stored in the handle; Queue.enqueue/claim reads them.

Defaults: visibility_timeout_s = 300, max_attempts = 3.

# `get_result`

Fetch a stored result. Returns `{:ok, value}` or `{:ok, nil}` when
absent or expired.

# `notify`

Fire a pg_notify-style pub/sub signal. Returns `{:ok, id}`.

# `notify_tx`

Fire a notification inside an open transaction. The notification row
only becomes visible to listeners after the transaction commits.

# `open`

Open (or create) a SQLite database at `path`. Loads the Honker
extension from `extension_path`, applies default PRAGMAs, and
bootstraps the schema.

`:watcher_backend` is implemented by `honker-core` through the loaded
Honker extension. It accepts the same aliases as the other bindings:
`nil`, `""`, `"poll"`, `"polling"`, `"kernel"`, `"kernel-watcher"`,
`"shm"`, and `"shm-fast-path"`.

`:watcher_poll_interval_ms` raises the default 1 ms update watcher
cadence when lower idle CPU matters more than lowest-latency wakeups.

# `outbox`

Return a transactional outbox handle backed by `_outbox:<name>`.

# `prune_notifications`

Delete notifications older than `older_than_s` seconds. Returns
`{:ok, count_deleted}`.

# `save_result`

Persist a job result for later retrieval via `get_result/2`. `value`
must be a string — encode JSON yourself if you want structure. `ttl_s`
is seconds before `sweep_results/1` will delete it.

# `sweep_results`

Delete expired results. Returns `{:ok, count_deleted}`.

# `try_rate_limit`

Fixed-window rate limit. Returns `{:ok, true}` if the caller fits in
`limit` per `per` seconds, `{:ok, false}` if blocked.

---

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