@superfunctions/queue 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.2.0
+
+Breaking: `QueueAdapter` is now a lease-based, fully async interface, and a durable SQL adapter is added.
+
+- `QueueAdapter<T>` methods are `enqueue(queue, payload, { delayMs?, dedupeKey? })`, `claim(queue, { leaseMs })`, `ack(id)`, `fail(id, { retryAt } | { deadLetter: true, reason })`, `extendLease(id, leaseMs)`, `peek(queue, limit)` and `size(queue)`. All return Promises.
+- `ack`, `fail` and `extendLease` accept an optional `{ attempt }` fence (the `attempt` returned by `claim`), so a claimer whose lease expired and was reclaimed cannot act on the new lease.
+- New `DatabaseQueueAdapter` stores jobs in a `queue_jobs` table on SQLite (SQLite >= 3.35), Cloudflare D1 and Postgres. Construct it with `{ db }`, a `@superfunctions/db` 0.3.1 `drizzleAdapter` or `kyselyAdapter`, whose new `rawSql` executor runs the statements; or with `{ client }` from `createSqliteQueueClient`, `createD1QueueClient` or `createPostgresQueueClient`. `@superfunctions/db` is an optional peer dependency; the `db` option is typed structurally (`QueueRawSqlSource`), so the published declarations do not import it. `claim` is one atomic `UPDATE … WHERE id = (SELECT … LIMIT 1) RETURNING` statement (`FOR UPDATE SKIP LOCKED` on Postgres). Migrations ship in `migrations/sqlite` and `migrations/postgres`, and `adapter.migrate()` applies the same DDL.
+- `MemoryQueueAdapter` implements the new interface. `maxSize` now counts pending and leased jobs.
+- Errors are `QueueError` instances whose `message` and `code` are the error code, for example `FLOWFN_QUEUE_JOB_NOT_LEASED`.
+- `FlowFnQueueAdapter` no longer implements `QueueAdapter`, because the FlowFn HTTP API has no leases. It keeps `enqueue(queue, payload)` and `dequeue(queue)`; `dequeueMatching`, `peek` and `size`, which always threw, are removed.
+
+### Migrating from 0.1
+
+| 0.1 | 0.2 |
+| --- | --- |
+| `await queue.enqueue(name, payload)` | Unchanged; now resolves `{ id, deduplicated }` |
+| `const payload = await queue.dequeue(name)` | `const job = await queue.claim(name, { leaseMs })`, use `job.payload`, then `await queue.ack(job.id, { attempt: job.attempt })` |
+| Retrying by enqueueing again | `await queue.fail(job.id, { retryAt, attempt: job.attempt })` |
+| Dropping a poison message | `await queue.fail(job.id, { deadLetter: true, reason, attempt: job.attempt })` |
+| `queue.dequeueMatching(name, matcher)` | Removed; use separate queue names or filter after `claim` and `fail` with an immediate `retryAt` |
+| `queue.peek(name)` returning payloads | `await queue.peek(name, limit)` returning `QueueJob` records; use `.map((job) => job.payload)` |
+| `queue.size(name)` | `await queue.size(name)` |
+
+A job that is claimed but never acked or failed becomes claimable again when its lease expires, with `attempt` incremented. Callers that do not want redelivery should dead-letter when `attempt` exceeds their limit.
+
+## 0.1.0
+
+- Initial `MemoryQueueAdapter` and `FlowFnQueueAdapter`.

package/README.md

@@ -0,0 +1,101 @@
+# @superfunctions/queue
+
+Lease-based job queues for Superfunctions libraries. `MemoryQueueAdapter` keeps jobs in process; `DatabaseQueueAdapter` stores them in a SQL table so they survive restarts on SQLite, Cloudflare D1 and Postgres. Callers drive `claim`; there is no worker loop or scheduler.
+
+```ts
+interface QueueAdapter<T> {
+  enqueue(queue: string, payload: T, options?: { delayMs?: number; dedupeKey?: string }): Promise<{ id: string; deduplicated: boolean }>;
+  claim(queue: string, options: { leaseMs: number }): Promise<{ id: string; payload: T; attempt: number } | null>;
+  ack(id: string, fence?: { attempt?: number }): Promise<void>;
+  fail(id: string, options: { retryAt: Date | number; reason?: string; attempt?: number } | { deadLetter: true; reason: string; attempt?: number }): Promise<void>;
+  extendLease(id: string, leaseMs: number, fence?: { attempt?: number }): Promise<void>;
+  peek(queue: string, limit: number): Promise<QueueJob<T>[]>;
+  size(queue: string): Promise<number>;
+}
+```
+
+## Semantics
+
+- A job is held by at most one claimer at a time. `claim` leases the oldest available job (by `availableAt`, then `id`) for `leaseMs` and returns it with `attempt` incremented, starting at 1.
+- If the lease expires before `ack` or `fail`, the job can be claimed again with the next `attempt`. Use `extendLease` for long work.
+- Pass `{ attempt: job.attempt }` to `ack`, `fail` and `extendLease`. Without it, a claimer whose lease expired and was reclaimed could act on the new claimer's lease. All three reject with `FLOWFN_QUEUE_JOB_NOT_LEASED` when the job is not leased (or the fence does not match).
+- `ack` removes the job. `fail` with `retryAt` makes it pending again at that time; `fail` with `deadLetter` keeps it in the `dead` state (database adapter only) and it is never claimed again.
+- `dedupeKey`: while a job with the same key is pending or leased in the same queue, `enqueue` is a no-op that returns the existing id with `deduplicated: true`. Acked or dead-lettered jobs release the key.
+- `peek` and `size` cover pending and leased jobs.
+- `delayMs` and `leaseMs` are integer milliseconds up to 100 years; invalid input rejects with a `QueueError` code such as `FLOWFN_QUEUE_LEASE_INVALID` before storage is touched.
+- Delivery is at least once: a claimer can crash after its side effects and before `ack`. Make handlers idempotent.
+
+## Durable adapter
+
+`DatabaseQueueAdapter` runs on a `@superfunctions/db` SQL adapter. `drizzleAdapter` and `kyselyAdapter` (0.3.1 or later) expose `rawSql`, a parameterized-statement executor on the adapter's own connection, because the CRUD API cannot express the single-statement claim. Pass the same adapter the rest of the app uses:
+
+```ts
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { drizzleAdapter } from '@superfunctions/db/adapters/drizzle';
+import { DatabaseQueueAdapter } from '@superfunctions/queue';
+
+const sqlite = new Database('app.db');
+sqlite.pragma('journal_mode = WAL');
+sqlite.pragma('busy_timeout = 5000');
+const db = drizzleAdapter({ db: drizzle(sqlite), dialect: 'sqlite' });
+
+const queue = new DatabaseQueueAdapter<{ url: string }>({ db });
+await queue.migrate();
+
+await queue.enqueue('fetch', { url: 'https://example.com' }, { dedupeKey: 'https://example.com' });
+
+const job = await queue.claim('fetch', { leaseMs: 30_000 });
+if (job) {
+  try {
+    await handle(job.payload);
+    await queue.ack(job.id, { attempt: job.attempt });
+  } catch (error) {
+    await queue.fail(job.id, job.attempt >= 5
+      ? { deadLetter: true, reason: String(error), attempt: job.attempt }
+      : { retryAt: Date.now() + 2 ** job.attempt * 1_000, reason: String(error), attempt: job.attempt });
+  }
+}
+```
+
+The same works for the other backends:
+
+- D1: `drizzleAdapter({ db: drizzle(env.DB), dialect: 'sqlite' })` with `drizzle-orm/d1`.
+- Postgres: `drizzleAdapter({ db: drizzle(pool), dialect: 'postgres' })` with `drizzle-orm/node-postgres` (or `drizzle-orm/pglite`), or `kyselyAdapter({ db: new Kysely({ dialect: new PostgresDialect({ pool }) }), dialect: 'postgres', schema: {} })`.
+- SQLite through Kysely: `kyselyAdapter({ db: new Kysely({ dialect: new SqliteDialect({ database }) }), dialect: 'sqlite', schema: {} })`.
+
+An adapter without `rawSql` (memory, Prisma, DynamoDB, Cloudflare KV) is rejected with `FLOWFN_QUEUE_RAW_SQL_UNAVAILABLE`, and a MySQL one with `FLOWFN_QUEUE_DIALECT_INVALID`. `rawSql` bypasses the db adapter's schema mapping and row-level namespaces, so the queue table is shared by every namespace; use `tableName` to separate queues per app.
+
+Without `@superfunctions/db`, pass a driver client instead of `db`:
+
+- `createSqliteQueueClient(db)` for a better-sqlite3 database (SQLite >= 3.35 for `RETURNING`). Use WAL and a `busy_timeout` when several processes share the file.
+- `createD1QueueClient(env.DB)` for a Cloudflare D1 binding.
+- `createPostgresQueueClient(pool)` for a node-postgres `Pool` or `Client`, or anything with `query(text, values) => { rows }`, such as PGlite.
+
+Any other driver can implement `QueueSqlClient`, which has the shape of `rawSql`: `dialect`, `query(sql, params)` returning rows and `execute(sql, params)`, where each `?` is a positional parameter.
+
+`claim` is one statement, `UPDATE … WHERE id = (SELECT … ORDER BY available_at, id LIMIT 1) RETURNING …`. On Postgres the subquery uses `FOR UPDATE SKIP LOCKED`, so concurrent claimers take different rows without waiting; SQLite and D1 run the statement under their single writer lock.
+
+Lease times come from the adapter's `now` option (default `Date.now`), not the database clock. Processes sharing a table need synchronized clocks, with leases much longer than any skew.
+
+### Migrations
+
+The `queue_jobs` table (`id`, `queue`, `payload` JSON, `state`, `attempt`, `available_at`, `lease_until`, `dedupe_key`, `last_error`, `created_at`, `updated_at`; times in epoch milliseconds) is created by:
+
+- `await queue.migrate()`, which runs idempotent `CREATE … IF NOT EXISTS` statements. Run it once at deploy time, not from many processes at once.
+- The shipped files `@superfunctions/queue/migrations/sqlite/0001_queue_jobs.sql` (SQLite and D1, for example with `wrangler d1 migrations`) and `@superfunctions/queue/migrations/postgres/0001_queue_jobs.sql`.
+- `queueJobsMigrationSql(dialect, tableName)` for a custom table name, which must match the adapter's `tableName` option.
+
+Dead-lettered rows stay in the table with `state = 'dead'` and `last_error`; delete them when they are no longer needed.
+
+## Memory adapter
+
+`new MemoryQueueAdapter({ maxSize?, now? })` has the same semantics in one process. Jobs are lost on restart, payloads are kept by reference, and dead-lettered jobs are discarded. `maxSize` caps pending and leased jobs per queue (`FLOWFN_QUEUE_FULL`).
+
+## FlowFn client
+
+`FlowFnQueueAdapter` calls a hosted FlowFn queue over HTTP with `enqueue(queue, payload)` and a destructive `dequeue(queue)`. The FlowFn API has no leases, so it does not implement `QueueAdapter`.
+
+## Tests
+
+`npm test` runs the shared contract against memory, a better-sqlite3 file, D1 under workerd (Miniflare) and Postgres via PGlite, each through a driver client and through `@superfunctions/db` (`drizzleAdapter`, plus `kyselyAdapter` on SQLite), and 8 claimer threads against 500 jobs on SQLite through both paths. Set `SUPERFUNCTIONS_QUEUE_POSTGRES_URL` to also run the contract (client, Drizzle and Kysely), an 8-connection concurrency test on each path and concurrent dedupe against a Postgres server; each test uses its own table and drops it.

package/dist/database.d.ts

@@ -0,0 +1,49 @@
+import type { QueueRawSqlSource, QueueSqlClient } from './sql-client.js';
+import type { ClaimOptions, ClaimedJob, EnqueueOptions, EnqueueResult, FailOptions, LeaseFence, QueueAdapter, QueueJob } from './types.js';
+interface DatabaseQueueAdapterBaseOptions {
+    /** Defaults to `queue_jobs`. */
+    tableName?: string;
+    /**
+     * Clock in epoch milliseconds, defaults to `Date.now`. Leases are compared
+     * against this clock, so processes sharing a table need synchronized clocks
+     * and leases longer than their skew.
+     */
+    now?: () => number;
+}
+export type DatabaseQueueAdapterOptions = DatabaseQueueAdapterBaseOptions & ({
+    /**
+     * A `@superfunctions/db` SQL adapter (`drizzleAdapter` or `kyselyAdapter`
+     * on SQLite, D1 or Postgres). Statements run through its `rawSql`.
+     */
+    db: QueueRawSqlSource;
+    client?: never;
+} | {
+    /** A driver client from `createSqliteQueueClient`, `createD1QueueClient` or `createPostgresQueueClient`. */
+    client: QueueSqlClient;
+    db?: never;
+});
+/**
+ * Durable queue on a SQL table, for SQLite (>= 3.35), D1 and Postgres, run
+ * through a `@superfunctions/db` SQL adapter or a driver client. Create the table with `migrate()` or the shipped migration files
+ * before use. Payloads are stored as JSON, so they must be JSON-serializable
+ * and are returned as their JSON round trip.
+ */
+export declare class DatabaseQueueAdapter<TPayload> implements QueueAdapter<TPayload> {
+    private readonly client;
+    private readonly tableName;
+    private readonly statements;
+    private readonly now;
+    constructor(options: DatabaseQueueAdapterOptions);
+    /** Creates the jobs table and its indexes if they do not exist. */
+    migrate(): Promise<void>;
+    enqueue(queueName: string, payload: TPayload, options?: EnqueueOptions): Promise<EnqueueResult>;
+    claim(queueName: string, options: ClaimOptions): Promise<ClaimedJob<TPayload> | null>;
+    ack(id: string, fence?: LeaseFence): Promise<void>;
+    fail(id: string, options: FailOptions): Promise<void>;
+    extendLease(id: string, leaseMs: number, fence?: LeaseFence): Promise<void>;
+    peek(queueName: string, limit: number): Promise<QueueJob<TPayload>[]>;
+    size(queueName: string): Promise<number>;
+    private requireLeasedChange;
+}
+export {};
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AACxF,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,UAAU,EACV,YAAY,EACZ,QAAQ,EAET,MAAM,YAAY,CAAC;AAapB,UAAU,+BAA+B;IACvC,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,2BAA2B,GAAG,+BAA+B,GACvE,CACI;IACE;;;OAGG;IACH,EAAE,EAAE,iBAAiB,CAAC;IACtB,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,GACD;IACE,4GAA4G;IAC5G,MAAM,EAAE,cAAc,CAAC;IACvB,EAAE,CAAC,EAAE,KAAK,CAAC;CACZ,CACJ,CAAC;AA0GJ;;;;;GAKG;AACH,qBAAa,oBAAoB,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,OAAO,EAAE,2BAA2B;IAOhD,mEAAmE;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA+B/F,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAYrF,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3E,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IAyBrE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAMhC,mBAAmB;CAYlC"}

package/dist/database.js

@@ -0,0 +1,204 @@
+import { DEFAULT_QUEUE_JOBS_TABLE, queueJobsMigrationStatements, quoteQueueTableName } from './migrations.js';
+import { QueueError, normalizeEnqueueOptions, normalizeFailOptions, normalizeFence, normalizeJobId, normalizeLeaseMs, normalizeLimit, normalizeQueueName, readClock, } from './validation.js';
+function resolveClient(options) {
+    if (options?.db !== undefined) {
+        const rawSql = options.db?.rawSql;
+        if (!rawSql) {
+            throw new QueueError('FLOWFN_QUEUE_RAW_SQL_UNAVAILABLE');
+        }
+        if (rawSql.dialect !== 'sqlite' && rawSql.dialect !== 'postgres') {
+            throw new QueueError('FLOWFN_QUEUE_DIALECT_INVALID');
+        }
+        return rawSql;
+    }
+    const client = options?.client;
+    if (client?.dialect !== 'sqlite' && client?.dialect !== 'postgres') {
+        throw new QueueError('FLOWFN_QUEUE_DIALECT_INVALID');
+    }
+    return client;
+}
+const LIVE_STATES = "state IN ('pending', 'leased')";
+const MAX_DEDUPE_ATTEMPTS = 3;
+function buildStatements(client, table) {
+    const postgres = client.dialect === 'postgres';
+    const payload = postgres ? 'payload::text AS payload' : 'payload';
+    const columns = `id, queue, ${payload}, state, attempt, available_at, lease_until, dedupe_key, last_error, created_at, updated_at`;
+    const leased = (fenced) => `id = ? AND state = 'leased'${fenced ? ' AND attempt = ?' : ''} RETURNING id`;
+    return {
+        insert: `INSERT INTO ${table} (queue, payload, state, attempt, available_at, dedupe_key, created_at, updated_at) ` +
+            `VALUES (?, ?, 'pending', 0, ?, ?, ?, ?) ` +
+            `ON CONFLICT (queue, dedupe_key) WHERE dedupe_key IS NOT NULL AND ${LIVE_STATES} DO NOTHING RETURNING id`,
+        findDeduped: `SELECT id FROM ${table} WHERE queue = ? AND dedupe_key = ? AND ${LIVE_STATES}`,
+        // One statement: the subquery picks the next claimable job and the UPDATE
+        // leases it, so two claimers can never lease the same row. Postgres skips
+        // rows another transaction has locked instead of waiting on them; SQLite
+        // runs the whole statement under its single writer lock.
+        claim: `UPDATE ${table} SET state = 'leased', attempt = attempt + 1, lease_until = ?, updated_at = ? ` +
+            `WHERE id = (SELECT id FROM ${table} WHERE queue = ? AND ` +
+            `((state = 'pending' AND available_at <= ?) OR (state = 'leased' AND lease_until <= ?)) ` +
+            `ORDER BY available_at, id LIMIT 1${postgres ? ' FOR UPDATE SKIP LOCKED' : ''}) ` +
+            `RETURNING id, ${payload}, attempt`,
+        ack: `DELETE FROM ${table} WHERE ${leased(false)}`,
+        ackFenced: `DELETE FROM ${table} WHERE ${leased(true)}`,
+        retry: `UPDATE ${table} SET state = 'pending', available_at = ?, lease_until = NULL, last_error = ?, updated_at = ? WHERE ${leased(false)}`,
+        retryFenced: `UPDATE ${table} SET state = 'pending', available_at = ?, lease_until = NULL, last_error = ?, updated_at = ? WHERE ${leased(true)}`,
+        deadLetter: `UPDATE ${table} SET state = 'dead', lease_until = NULL, last_error = ?, updated_at = ? WHERE ${leased(false)}`,
+        deadLetterFenced: `UPDATE ${table} SET state = 'dead', lease_until = NULL, last_error = ?, updated_at = ? WHERE ${leased(true)}`,
+        extend: `UPDATE ${table} SET lease_until = ?, updated_at = ? WHERE ${leased(false)}`,
+        extendFenced: `UPDATE ${table} SET lease_until = ?, updated_at = ? WHERE ${leased(true)}`,
+        peek: `SELECT ${columns} FROM ${table} WHERE queue = ? AND ${LIVE_STATES} ORDER BY available_at, id LIMIT ?`,
+        size: `SELECT COUNT(*) AS count FROM ${table} WHERE queue = ? AND ${LIVE_STATES}`,
+    };
+}
+function toNumber(value) {
+    const result = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(result)) {
+        throw new QueueError('FLOWFN_QUEUE_ROW_INVALID');
+    }
+    return result;
+}
+function toNullableNumber(value) {
+    return value === null || value === undefined ? null : toNumber(value);
+}
+function parsePayload(value) {
+    if (typeof value !== 'string') {
+        throw new QueueError('FLOWFN_QUEUE_ROW_INVALID');
+    }
+    return JSON.parse(value);
+}
+function serializePayload(payload) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(payload);
+    }
+    catch {
+        throw new QueueError('FLOWFN_QUEUE_PAYLOAD_INVALID');
+    }
+    if (serialized === undefined) {
+        throw new QueueError('FLOWFN_QUEUE_PAYLOAD_INVALID');
+    }
+    return serialized;
+}
+/**
+ * Durable queue on a SQL table, for SQLite (>= 3.35), D1 and Postgres, run
+ * through a `@superfunctions/db` SQL adapter or a driver client. Create the table with `migrate()` or the shipped migration files
+ * before use. Payloads are stored as JSON, so they must be JSON-serializable
+ * and are returned as their JSON round trip.
+ */
+export class DatabaseQueueAdapter {
+    client;
+    tableName;
+    statements;
+    now;
+    constructor(options) {
+        this.client = resolveClient(options);
+        this.tableName = options.tableName ?? DEFAULT_QUEUE_JOBS_TABLE;
+        this.statements = buildStatements(this.client, quoteQueueTableName(this.tableName));
+        this.now = options.now ?? Date.now;
+    }
+    /** Creates the jobs table and its indexes if they do not exist. */
+    async migrate() {
+        for (const statement of queueJobsMigrationStatements(this.client.dialect, this.tableName)) {
+            await this.client.execute(statement, []);
+        }
+    }
+    async enqueue(queueName, payload, options) {
+        const queue = normalizeQueueName(queueName);
+        const { delayMs, dedupeKey } = normalizeEnqueueOptions(options);
+        const serialized = serializePayload(payload);
+        // A conflicting live job can be acked between the insert and the lookup;
+        // the next insert then succeeds, so a few rounds always settle.
+        for (let round = 0; round < MAX_DEDUPE_ATTEMPTS; round += 1) {
+            const now = readClock(this.now);
+            const inserted = await this.client.query(this.statements.insert, [
+                queue,
+                serialized,
+                now + delayMs,
+                dedupeKey,
+                now,
+                now,
+            ]);
+            if (inserted.length > 0) {
+                return { id: String(inserted[0].id), deduplicated: false };
+            }
+            if (dedupeKey === null) {
+                break;
+            }
+            const existing = await this.client.query(this.statements.findDeduped, [queue, dedupeKey]);
+            if (existing.length > 0) {
+                return { id: String(existing[0].id), deduplicated: true };
+            }
+        }
+        throw new QueueError('FLOWFN_QUEUE_ENQUEUE_CONFLICT');
+    }
+    async claim(queueName, options) {
+        const queue = normalizeQueueName(queueName);
+        const leaseMs = normalizeLeaseMs(options?.leaseMs);
+        const now = readClock(this.now);
+        const rows = await this.client.query(this.statements.claim, [now + leaseMs, now, queue, now, now]);
+        if (rows.length === 0) {
+            return null;
+        }
+        const row = rows[0];
+        return { id: String(row.id), payload: parsePayload(row.payload), attempt: toNumber(row.attempt) };
+    }
+    async ack(id, fence) {
+        const jobId = normalizeJobId(id);
+        const attempt = normalizeFence(fence);
+        await this.requireLeasedChange(attempt === null ? this.statements.ack : this.statements.ackFenced, [], jobId, attempt);
+    }
+    async fail(id, options) {
+        const normalized = normalizeFailOptions(options);
+        const jobId = normalizeJobId(id);
+        const now = readClock(this.now);
+        if (normalized.kind === 'dead') {
+            await this.requireLeasedChange(normalized.attempt === null ? this.statements.deadLetter : this.statements.deadLetterFenced, [normalized.reason, now], jobId, normalized.attempt);
+            return;
+        }
+        await this.requireLeasedChange(normalized.attempt === null ? this.statements.retry : this.statements.retryFenced, [normalized.retryAt, normalized.reason, now], jobId, normalized.attempt);
+    }
+    async extendLease(id, leaseMs, fence) {
+        const normalizedLeaseMs = normalizeLeaseMs(leaseMs);
+        const jobId = normalizeJobId(id);
+        const attempt = normalizeFence(fence);
+        const now = readClock(this.now);
+        await this.requireLeasedChange(attempt === null ? this.statements.extend : this.statements.extendFenced, [now + normalizedLeaseMs, now], jobId, attempt);
+    }
+    async peek(queueName, limit) {
+        const queue = normalizeQueueName(queueName);
+        const normalizedLimit = normalizeLimit(limit);
+        if (normalizedLimit === 0) {
+            return [];
+        }
+        const rows = await this.client.query(this.statements.peek, [queue, normalizedLimit]);
+        return rows.map((row) => {
+            const leaseUntil = toNullableNumber(row.lease_until);
+            return {
+                id: String(row.id),
+                queue: String(row.queue),
+                payload: parsePayload(row.payload),
+                state: row.state,
+                attempt: toNumber(row.attempt),
+                availableAt: new Date(toNumber(row.available_at)),
+                leaseUntil: leaseUntil === null ? null : new Date(leaseUntil),
+                dedupeKey: row.dedupe_key ?? null,
+                lastError: row.last_error ?? null,
+                createdAt: new Date(toNumber(row.created_at)),
+                updatedAt: new Date(toNumber(row.updated_at)),
+            };
+        });
+    }
+    async size(queueName) {
+        const queue = normalizeQueueName(queueName);
+        const rows = await this.client.query(this.statements.size, [queue]);
+        return toNumber(rows[0]?.count ?? 0);
+    }
+    async requireLeasedChange(sql, values, jobId, attempt) {
+        const params = attempt === null ? [...values, jobId] : [...values, jobId, attempt];
+        const rows = await this.client.query(sql, params);
+        if (rows.length === 0) {
+            throw new QueueError('FLOWFN_QUEUE_JOB_NOT_LEASED');
+        }
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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"}

package/dist/flowfn.d.ts

@@ -0,0 +1,22 @@
+export interface FlowFnQueueAdapterConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * HTTP client for a hosted FlowFn queue. The FlowFn API only offers enqueue
+ * and a destructive dequeue, without leases, acknowledgements or retries, so
+ * this client does not implement `QueueAdapter`.
+ */
+export declare class FlowFnQueueAdapter<TPayload> {
+    private readonly config;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    private readonly baseUrl;
+    constructor(config: FlowFnQueueAdapterConfig);
+    enqueue(queueName: string, payload: TPayload): Promise<void>;
+    dequeue(queueName: string): Promise<TPayload | null>;
+    private fetchWithTimeout;
+}
+//# sourceMappingURL=flowfn.d.ts.map

package/dist/flowfn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowfn.d.ts","sourceRoot":"","sources":["../src/flowfn.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwBD;;;;GAIG;AACH,qBAAa,kBAAkB,CAAC,QAAQ;IAK1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,MAAM,EAAE,wBAAwB;IAMvD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5D,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;YAqB5C,gBAAgB;CAgB/B"}

package/dist/flowfn.js

@@ -0,0 +1,84 @@
+import { QueueError, normalizeQueueName } from './validation.js';
+function normalizeBaseUrl(baseUrl) {
+    let normalized = baseUrl;
+    while (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+function encodeQueueName(queueName) {
+    return encodeURIComponent(normalizeQueueName(queueName));
+}
+function normalizeTimeoutMs(value) {
+    if (value === undefined) {
+        return 15_000;
+    }
+    if (!Number.isFinite(value)) {
+        throw new QueueError('FLOWFN_QUEUE_TIMEOUT_INVALID');
+    }
+    return Math.max(0, value);
+}
+/**
+ * HTTP client for a hosted FlowFn queue. The FlowFn API only offers enqueue
+ * and a destructive dequeue, without leases, acknowledgements or retries, so
+ * this client does not implement `QueueAdapter`.
+ */
+export class FlowFnQueueAdapter {
+    config;
+    fetcher;
+    timeoutMs;
+    baseUrl;
+    constructor(config) {
+        this.config = config;
+        this.fetcher = config.fetch ?? globalThis.fetch;
+        this.timeoutMs = normalizeTimeoutMs(config.timeoutMs);
+        this.baseUrl = normalizeBaseUrl(config.baseUrl);
+    }
+    async enqueue(queueName, payload) {
+        const encodedQueueName = encodeQueueName(queueName);
+        const response = await this.fetchWithTimeout(`${this.baseUrl}/queues/${encodedQueueName}/enqueue`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.config.apiKey}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            throw new Error(`FlowFn enqueue failed: ${response.status} ${response.statusText}`);
+        }
+    }
+    async dequeue(queueName) {
+        const encodedQueueName = encodeQueueName(queueName);
+        const response = await this.fetchWithTimeout(`${this.baseUrl}/queues/${encodedQueueName}/dequeue`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+            },
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new Error(`FlowFn dequeue failed: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        return 'payload' in data ? data.payload : null;
+    }
+    async fetchWithTimeout(url, init) {
+        const controller = typeof AbortController === 'function' ? new AbortController() : undefined;
+        const timeoutId = controller && this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
+        try {
+            return await this.fetcher(url, {
+                ...init,
+                signal: controller?.signal,
+            });
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+}
+//# sourceMappingURL=flowfn.js.map

package/dist/flowfn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowfn.js","sourceRoot":"","sources":["../src/flowfn.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,46 +1,12 @@
-export interface QueueAdapter<TPayload> {
-    enqueue(queueName: string, payload: TPayload): Promise<void>;
-    dequeue(queueName: string): Promise<TPayload | null>;
-    dequeueMatching(queueName: string, matcher: (payload: TPayload) => boolean): Promise<TPayload | null>;
-    peek(queueName: string): TPayload[];
-    size(queueName: string): number;
-}
-export interface MemoryQueueAdapterOptions {
-    /**
-     * Maximum number of items retained per queue. When reached, further
-     * `enqueue` calls reject with `FLOWFN_QUEUE_FULL` instead of growing the
-     * backing array without bound (which would leak memory until OOM if
-     * producers outpace consumers). Unset means unbounded (legacy behaviour).
-     */
-    maxSize?: number;
-}
-export declare class MemoryQueueAdapter<TPayload> implements QueueAdapter<TPayload> {
-    private readonly queues;
-    private readonly maxSize?;
-    constructor(options?: MemoryQueueAdapterOptions);
-    enqueue(queueName: string, payload: TPayload): Promise<void>;
-    dequeue(queueName: string): Promise<TPayload | null>;
-    dequeueMatching(queueName: string, matcher: (payload: TPayload) => boolean): Promise<TPayload | null>;
-    peek(queueName: string): TPayload[];
-    size(queueName: string): number;
-}
-export interface FlowFnQueueAdapterConfig {
-    baseUrl: string;
-    apiKey: string;
-    fetch?: typeof globalThis.fetch;
-    timeoutMs?: number;
-}
-export declare class FlowFnQueueAdapter<TPayload> implements QueueAdapter<TPayload> {
-    private readonly config;
-    private readonly fetcher;
-    private readonly timeoutMs;
-    private readonly baseUrl;
-    constructor(config: FlowFnQueueAdapterConfig);
-    enqueue(queueName: string, payload: TPayload): Promise<void>;
-    dequeue(queueName: string): Promise<TPayload | null>;
-    dequeueMatching(queueName: string, matcher: (payload: TPayload) => boolean): Promise<TPayload | null>;
-    peek(queueName: string): TPayload[];
-    size(queueName: string): number;
-    private fetchWithTimeout;
-}
+export type { ClaimOptions, ClaimedJob, EnqueueOptions, EnqueueResult, FailOptions, LeaseFence, QueueAdapter, QueueJob, QueueJobState, } from './types.js';
+export { QueueError } from './validation.js';
+export { MemoryQueueAdapter } from './memory.js';
+export type { MemoryQueueAdapterOptions } from './memory.js';
+export { DatabaseQueueAdapter } from './database.js';
+export type { DatabaseQueueAdapterOptions } from './database.js';
+export { createD1QueueClient, createPostgresQueueClient, createSqliteQueueClient } from './sql-client.js';
+export type { BetterSqlite3DatabaseLike, D1DatabaseLike, PostgresQueryableLike, QueueRawSqlExecutor, QueueRawSqlSource, QueueSqlClient, QueueSqlDialect, QueueSqlValue, } from './sql-client.js';
+export { DEFAULT_QUEUE_JOBS_TABLE, queueJobsMigrationSql, queueJobsMigrationStatements } from './migrations.js';
+export { FlowFnQueueAdapter } from './flowfn.js';
+export type { FlowFnQueueAdapterConfig } from './flowfn.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY,CAAC,QAAQ;IACpC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACrD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACtG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC;IACpC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAUD,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAkB,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;gBAEtB,OAAO,GAAE,yBAA8B;IAS7C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5D,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAUpD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAgB3G,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAKnC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAIhC;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwBD,qBAAa,kBAAkB,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IAK7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,MAAM,EAAE,wBAAwB;IAMvD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5D,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAqBpD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAM3G,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAKnC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;YAKjB,gBAAgB;CAgB/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1G,YAAY,EACV,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAChH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}