@superfunctions/queue 0.0.1 → 0.2.0

package/dist/index.js

@@ -1,136 +1,7 @@
-function normalizeQueueName(queueName) {
-    const normalized = queueName.trim();
-    if (!normalized || normalized.includes('/') || normalized.includes('\\') || normalized.includes('..')) {
-        throw new Error('FLOWFN_QUEUE_NAME_INVALID');
-    }
-    return normalized;
-}
-export class MemoryQueueAdapter {
-    queues = new Map();
-    async enqueue(queueName, payload) {
-        const normalizedQueueName = normalizeQueueName(queueName);
-        const queue = this.queues.get(normalizedQueueName) ?? [];
-        queue.push(payload);
-        this.queues.set(normalizedQueueName, queue);
-    }
-    async dequeue(queueName) {
-        const normalizedQueueName = normalizeQueueName(queueName);
-        const queue = this.queues.get(normalizedQueueName);
-        if (!queue || queue.length === 0) {
-            return null;
-        }
-        return queue.shift();
-    }
-    async dequeueMatching(queueName, matcher) {
-        const normalizedQueueName = normalizeQueueName(queueName);
-        const queue = this.queues.get(normalizedQueueName);
-        if (!queue || queue.length === 0) {
-            return null;
-        }
-        const index = queue.findIndex(matcher);
-        if (index === -1) {
-            return null;
-        }
-        const [payload] = queue.splice(index, 1);
-        return payload;
-    }
-    peek(queueName) {
-        const normalizedQueueName = normalizeQueueName(queueName);
-        return [...(this.queues.get(normalizedQueueName) ?? [])];
-    }
-    size(queueName) {
-        const normalizedQueueName = normalizeQueueName(queueName);
-        return this.queues.get(normalizedQueueName)?.length ?? 0;
-    }
-}
-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 Error('FLOWFN_QUEUE_TIMEOUT_INVALID');
-    }
-    return Math.max(0, value);
-}
-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 dequeueMatching(queueName, matcher) {
-        void matcher;
-        encodeQueueName(queueName);
-        throw new Error('FLOWFN_QUEUE_MATCHING_UNSUPPORTED');
-    }
-    peek(queueName) {
-        encodeQueueName(queueName);
-        throw new Error('FLOWFN_QUEUE_PEEK_UNSUPPORTED');
-    }
-    size(queueName) {
-        encodeQueueName(queueName);
-        throw new Error('FLOWFN_QUEUE_SIZE_UNSUPPORTED');
-    }
-    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);
-            }
-        }
-    }
-}
+export { QueueError } from './validation.js';
+export { MemoryQueueAdapter } from './memory.js';
+export { DatabaseQueueAdapter } from './database.js';
+export { createD1QueueClient, createPostgresQueueClient, createSqliteQueueClient } from './sql-client.js';
+export { DEFAULT_QUEUE_JOBS_TABLE, queueJobsMigrationSql, queueJobsMigrationStatements } from './migrations.js';
+export { FlowFnQueueAdapter } from './flowfn.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAW1G,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAChH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/memory.d.ts

@@ -0,0 +1,34 @@
+import type { ClaimOptions, ClaimedJob, EnqueueOptions, EnqueueResult, FailOptions, LeaseFence, QueueAdapter, QueueJob } from './types.js';
+export interface MemoryQueueAdapterOptions {
+    /**
+     * Maximum number of pending and leased jobs retained per queue. When
+     * reached, further `enqueue` calls reject with `FLOWFN_QUEUE_FULL` instead
+     * of growing without bound. Unset means unbounded.
+     */
+    maxSize?: number;
+    /** Clock in epoch milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Process-local queue for tests and single-process use. Jobs do not survive a
+ * restart, and dead-lettered jobs are discarded; use `DatabaseQueueAdapter`
+ * for durable storage.
+ */
+export declare class MemoryQueueAdapter<TPayload> implements QueueAdapter<TPayload> {
+    private readonly jobs;
+    private readonly queues;
+    private readonly maxSize?;
+    private readonly now;
+    private nextId;
+    constructor(options?: MemoryQueueAdapterOptions);
+    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 remove;
+    private requireLeased;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,UAAU,EACV,YAAY,EACZ,QAAQ,EAET,MAAM,YAAY,CAAC;AAapB,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AA+BD;;;;GAIG;AACH,qBAAa,kBAAkB,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;IAE/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiD;IACxE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,GAAE,yBAA8B;IAU7C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAsC/F,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAsBrF,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3E,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IAqBrE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9C,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,aAAa;CAOtB"}

package/dist/memory.js

@@ -0,0 +1,153 @@
+import { QueueError, normalizeEnqueueOptions, normalizeFailOptions, normalizeFence, normalizeJobId, normalizeLeaseMs, normalizeLimit, normalizeQueueName, readClock, } from './validation.js';
+function isClaimable(job, now) {
+    return job.state === 'pending' ? job.availableAt <= now : job.leaseUntil <= now;
+}
+function compareClaimOrder(a, b) {
+    return a.availableAt - b.availableAt || a.id - b.id;
+}
+/**
+ * Process-local queue for tests and single-process use. Jobs do not survive a
+ * restart, and dead-lettered jobs are discarded; use `DatabaseQueueAdapter`
+ * for durable storage.
+ */
+export class MemoryQueueAdapter {
+    jobs = new Map();
+    // Per-queue indexes keep enqueue O(1) and queues isolated from each other's backlogs.
+    queues = new Map();
+    maxSize;
+    now;
+    nextId = 1;
+    constructor(options = {}) {
+        if (options.maxSize !== undefined) {
+            if (!Number.isInteger(options.maxSize) || options.maxSize <= 0) {
+                throw new QueueError('FLOWFN_QUEUE_MAX_SIZE_INVALID');
+            }
+        }
+        this.maxSize = options.maxSize;
+        this.now = options.now ?? Date.now;
+    }
+    async enqueue(queueName, payload, options) {
+        const queue = normalizeQueueName(queueName);
+        const { delayMs, dedupeKey } = normalizeEnqueueOptions(options);
+        const now = readClock(this.now);
+        const existing = this.queues.get(queue);
+        const duplicate = dedupeKey === null ? undefined : existing?.dedupe.get(dedupeKey);
+        if (duplicate) {
+            return { id: String(duplicate.id), deduplicated: true };
+        }
+        if (this.maxSize !== undefined && (existing?.jobs.size ?? 0) >= this.maxSize) {
+            throw new QueueError('FLOWFN_QUEUE_FULL');
+        }
+        const id = this.nextId++;
+        const job = {
+            id,
+            queue,
+            payload,
+            state: 'pending',
+            attempt: 0,
+            availableAt: now + delayMs,
+            leaseUntil: null,
+            dedupeKey,
+            lastError: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const index = existing ?? { jobs: new Map(), dedupe: new Map() };
+        this.queues.set(queue, index);
+        this.jobs.set(id, job);
+        index.jobs.set(id, job);
+        if (dedupeKey !== null) {
+            index.dedupe.set(dedupeKey, job);
+        }
+        return { id: String(id), deduplicated: false };
+    }
+    async claim(queueName, options) {
+        const queue = normalizeQueueName(queueName);
+        const leaseMs = normalizeLeaseMs(options?.leaseMs);
+        const now = readClock(this.now);
+        let next;
+        for (const job of this.queues.get(queue)?.jobs.values() ?? []) {
+            if (isClaimable(job, now) && (!next || compareClaimOrder(job, next) < 0)) {
+                next = job;
+            }
+        }
+        if (!next) {
+            return null;
+        }
+        next.state = 'leased';
+        next.attempt += 1;
+        next.leaseUntil = now + leaseMs;
+        next.updatedAt = now;
+        return { id: String(next.id), payload: next.payload, attempt: next.attempt };
+    }
+    async ack(id, fence) {
+        const job = this.requireLeased(id, normalizeFence(fence));
+        this.remove(job);
+    }
+    async fail(id, options) {
+        const normalized = normalizeFailOptions(options);
+        const job = this.requireLeased(id, normalized.attempt);
+        if (normalized.kind === 'dead') {
+            this.remove(job);
+            return;
+        }
+        job.state = 'pending';
+        job.availableAt = normalized.retryAt;
+        job.leaseUntil = null;
+        job.lastError = normalized.reason;
+        job.updatedAt = readClock(this.now);
+    }
+    async extendLease(id, leaseMs, fence) {
+        const normalizedLeaseMs = normalizeLeaseMs(leaseMs);
+        const job = this.requireLeased(id, normalizeFence(fence));
+        const now = readClock(this.now);
+        job.leaseUntil = now + normalizedLeaseMs;
+        job.updatedAt = now;
+    }
+    async peek(queueName, limit) {
+        const queue = normalizeQueueName(queueName);
+        const normalizedLimit = normalizeLimit(limit);
+        return [...(this.queues.get(queue)?.jobs.values() ?? [])]
+            .sort(compareClaimOrder)
+            .slice(0, normalizedLimit)
+            .map((job) => ({
+            id: String(job.id),
+            queue: job.queue,
+            payload: job.payload,
+            state: job.state,
+            attempt: job.attempt,
+            availableAt: new Date(job.availableAt),
+            leaseUntil: job.leaseUntil === null ? null : new Date(job.leaseUntil),
+            dedupeKey: job.dedupeKey,
+            lastError: job.lastError,
+            createdAt: new Date(job.createdAt),
+            updatedAt: new Date(job.updatedAt),
+        }));
+    }
+    async size(queueName) {
+        const queue = normalizeQueueName(queueName);
+        return this.queues.get(queue)?.jobs.size ?? 0;
+    }
+    remove(job) {
+        this.jobs.delete(job.id);
+        const index = this.queues.get(job.queue);
+        if (!index) {
+            return;
+        }
+        index.jobs.delete(job.id);
+        if (job.dedupeKey !== null) {
+            index.dedupe.delete(job.dedupeKey);
+        }
+        if (index.jobs.size === 0) {
+            this.queues.delete(job.queue);
+        }
+    }
+    requireLeased(id, attempt) {
+        const job = this.jobs.get(normalizeJobId(id));
+        if (!job || job.state !== 'leased' || (attempt !== null && job.attempt !== attempt)) {
+            throw new QueueError('FLOWFN_QUEUE_JOB_NOT_LEASED');
+        }
+        return job;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

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

package/dist/migrations.d.ts

@@ -0,0 +1,14 @@
+import type { QueueSqlDialect } from './sql-client.js';
+export declare const DEFAULT_QUEUE_JOBS_TABLE = "queue_jobs";
+export declare function quoteQueueTableName(tableName: string): string;
+/**
+ * DDL for the jobs table, one statement per entry, safe to re-run.
+ *
+ * Times are epoch milliseconds. `id` never repeats (AUTOINCREMENT / identity),
+ * so a stale id cannot address a later job. The partial unique index makes a
+ * `dedupe_key` unique only among pending and leased jobs.
+ */
+export declare function queueJobsMigrationStatements(dialect: QueueSqlDialect, tableName?: string): string[];
+/** The migration as one SQL script, matching the files shipped under `migrations/`. */
+export declare function queueJobsMigrationSql(dialect: QueueSqlDialect, tableName?: string): string;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAIrD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,eAAe,EACxB,SAAS,GAAE,MAAiC,GAC3C,MAAM,EAAE,CA4BV;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,GAAE,MAAiC,GAAG,MAAM,CAEpH"}

package/dist/migrations.js

@@ -0,0 +1,48 @@
+import { QueueError } from './validation.js';
+export const DEFAULT_QUEUE_JOBS_TABLE = 'queue_jobs';
+const TABLE_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,47}$/;
+export function quoteQueueTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_RE.test(tableName)) {
+        throw new QueueError('FLOWFN_QUEUE_TABLE_NAME_INVALID');
+    }
+    return `"${tableName}"`;
+}
+/**
+ * DDL for the jobs table, one statement per entry, safe to re-run.
+ *
+ * Times are epoch milliseconds. `id` never repeats (AUTOINCREMENT / identity),
+ * so a stale id cannot address a later job. The partial unique index makes a
+ * `dedupe_key` unique only among pending and leased jobs.
+ */
+export function queueJobsMigrationStatements(dialect, tableName = DEFAULT_QUEUE_JOBS_TABLE) {
+    const table = quoteQueueTableName(tableName);
+    const index = (suffix) => `"${tableName}_${suffix}"`;
+    const id = dialect === 'postgres'
+        ? 'id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY'
+        : 'id INTEGER PRIMARY KEY AUTOINCREMENT';
+    const payload = dialect === 'postgres' ? 'payload JSON NOT NULL' : 'payload TEXT NOT NULL';
+    const time = dialect === 'postgres' ? 'BIGINT' : 'INTEGER';
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (
+  ${id},
+  queue TEXT NOT NULL,
+  ${payload},
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'leased', 'dead')),
+  attempt INTEGER NOT NULL DEFAULT 0,
+  available_at ${time} NOT NULL,
+  lease_until ${time},
+  dedupe_key TEXT,
+  last_error TEXT,
+  created_at ${time} NOT NULL,
+  updated_at ${time} NOT NULL
+)`,
+        `CREATE INDEX IF NOT EXISTS ${index('available_idx')} ON ${table} (queue, state, available_at, id)`,
+        `CREATE INDEX IF NOT EXISTS ${index('lease_idx')} ON ${table} (queue, state, lease_until)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS ${index('dedupe_idx')} ON ${table} (queue, dedupe_key) WHERE dedupe_key IS NOT NULL AND state IN ('pending', 'leased')`,
+    ];
+}
+/** The migration as one SQL script, matching the files shipped under `migrations/`. */
+export function queueJobsMigrationSql(dialect, tableName = DEFAULT_QUEUE_JOBS_TABLE) {
+    return `${queueJobsMigrationStatements(dialect, tableName).join(';\n\n')};\n`;
+}
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAErD,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAEtD,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,UAAU,CAAC,iCAAiC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,SAAS,GAAG,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,OAAwB,EACxB,YAAoB,wBAAwB;IAE5C,MAAM,KAAK,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,SAAS,IAAI,MAAM,GAAG,CAAC;IAC7D,MAAM,EAAE,GACN,OAAO,KAAK,UAAU;QACpB,CAAC,CAAC,oDAAoD;QACtD,CAAC,CAAC,sCAAsC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAC3F,MAAM,IAAI,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3D,OAAO;QACL,8BAA8B,KAAK;IACnC,EAAE;;IAEF,OAAO;;;iBAGM,IAAI;gBACL,IAAI;;;eAGL,IAAI;eACJ,IAAI;EACjB;QACE,8BAA8B,KAAK,CAAC,eAAe,CAAC,OAAO,KAAK,mCAAmC;QACnG,8BAA8B,KAAK,CAAC,WAAW,CAAC,OAAO,KAAK,8BAA8B;QAC1F,qCAAqC,KAAK,CAAC,YAAY,CAAC,OAAO,KAAK,sFAAsF;KAC3J,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,OAAwB,EAAE,YAAoB,wBAAwB;IAC1G,OAAO,GAAG,4BAA4B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;AAChF,CAAC"}

package/dist/sql-client.d.ts

@@ -0,0 +1,63 @@
+export type QueueSqlDialect = 'sqlite' | 'postgres';
+export type QueueSqlValue = string | number | null;
+/**
+ * The SQL primitive `DatabaseQueueAdapter` runs on. It has the shape of the
+ * `rawSql` executor on `@superfunctions/db` SQL adapters: each `?` marks one
+ * positional parameter, which the client renders for its dialect. The
+ * adapter's statements contain no other `?`.
+ */
+export interface QueueSqlClient {
+    readonly dialect: QueueSqlDialect;
+    /** Runs a statement that returns rows (`SELECT`, `… RETURNING`). */
+    query(sql: string, params: readonly QueueSqlValue[]): Promise<Record<string, unknown>[]>;
+    /** Runs a statement without a result set (the migration DDL). */
+    execute(sql: string, params: readonly QueueSqlValue[]): Promise<void>;
+}
+/**
+ * Structural form of a `@superfunctions/db` adapter's optional `rawSql`
+ * executor. It is declared here, not imported, because `@superfunctions/db`
+ * is an optional peer and the published declarations must not reference it.
+ */
+export interface QueueRawSqlExecutor {
+    readonly dialect: 'postgres' | 'mysql' | 'sqlite';
+    query(sql: string, params?: readonly QueueSqlValue[]): Promise<Record<string, unknown>[]>;
+    execute(sql: string, params?: readonly QueueSqlValue[]): Promise<void>;
+}
+/** Any `@superfunctions/db` adapter, seen only through its `rawSql`. */
+export interface QueueRawSqlSource {
+    readonly rawSql?: QueueRawSqlExecutor;
+}
+/** Structural subset of a better-sqlite3 `Database`. */
+export interface BetterSqlite3DatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+        run(...params: unknown[]): unknown;
+    };
+}
+/** Wraps a better-sqlite3 database (SQLite >= 3.35 for `RETURNING`). */
+export declare function createSqliteQueueClient(db: BetterSqlite3DatabaseLike): QueueSqlClient;
+/** Structural subset of a Cloudflare `D1Database`. */
+export interface D1DatabaseLike {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            all(): Promise<{
+                results?: unknown[];
+            }>;
+            run(): Promise<unknown>;
+        };
+    };
+}
+/** Wraps a Cloudflare D1 binding. */
+export declare function createD1QueueClient(db: D1DatabaseLike): QueueSqlClient;
+/** Structural subset of a node-postgres `Pool`/`Client`, also satisfied by PGlite. */
+export interface PostgresQueryableLike {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+/**
+ * Wraps a Postgres connection or pool. With a pool, every statement may run
+ * on a different connection; the adapter never relies on session state.
+ */
+export declare function createPostgresQueueClient(db: PostgresQueryableLike): QueueSqlClient;
+//# sourceMappingURL=sql-client.d.ts.map

package/dist/sql-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-client.d.ts","sourceRoot":"","sources":["../src/sql-client.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEpD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,oEAAoE;IACpE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACzF,iEAAiE;IACjE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IAClD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1F,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAED,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;KACpC,CAAC;CACH;AAED,wEAAwE;AACxE,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,yBAAyB,GAAG,cAAc,CAUrF;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAC1B,GAAG,IAAI,OAAO,CAAC;gBAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;aAAE,CAAC,CAAC;YACxC,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;SACzB,CAAC;KACH,CAAC;CACH;AAED,qCAAqC;AACrC,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,cAAc,GAAG,cAAc,CAWtE;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CACvE;AAOD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,qBAAqB,GAAG,cAAc,CAWnF"}

package/dist/sql-client.js

@@ -0,0 +1,46 @@
+/** Wraps a better-sqlite3 database (SQLite >= 3.35 for `RETURNING`). */
+export function createSqliteQueueClient(db) {
+    return {
+        dialect: 'sqlite',
+        async query(sql, params) {
+            return db.prepare(sql).all(...params);
+        },
+        async execute(sql, params) {
+            db.prepare(sql).run(...params);
+        },
+    };
+}
+/** Wraps a Cloudflare D1 binding. */
+export function createD1QueueClient(db) {
+    return {
+        dialect: 'sqlite',
+        async query(sql, params) {
+            const result = await db.prepare(sql).bind(...params).all();
+            return (result.results ?? []);
+        },
+        async execute(sql, params) {
+            await db.prepare(sql).bind(...params).run();
+        },
+    };
+}
+function numberPlaceholders(sql) {
+    let index = 0;
+    return sql.replace(/\?/g, () => `$${++index}`);
+}
+/**
+ * Wraps a Postgres connection or pool. With a pool, every statement may run
+ * on a different connection; the adapter never relies on session state.
+ */
+export function createPostgresQueueClient(db) {
+    return {
+        dialect: 'postgres',
+        async query(sql, params) {
+            const result = await db.query(numberPlaceholders(sql), [...params]);
+            return result.rows;
+        },
+        async execute(sql, params) {
+            await db.query(numberPlaceholders(sql), [...params]);
+        },
+    };
+}
+//# sourceMappingURL=sql-client.js.map

package/dist/sql-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-client.js","sourceRoot":"","sources":["../src/sql-client.ts"],"names":[],"mappings":"AA0CA,wEAAwE;AACxE,MAAM,UAAU,uBAAuB,CAAC,EAA6B;IACnE,OAAO;QACL,OAAO,EAAE,QAAQ;QACjB,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM;YACrB,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAA8B,CAAC;QACrE,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM;YACvB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC;AAYD,qCAAqC;AACrC,MAAM,UAAU,mBAAmB,CAAC,EAAkB;IACpD,OAAO;QACL,OAAO,EAAE,QAAQ;QACjB,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM;YACrB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC;YAC3D,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAA8B,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM;YACvB,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC;AAOD,SAAS,kBAAkB,CAAC,GAAW;IACrC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,EAAyB;IACjE,OAAO;QACL,OAAO,EAAE,UAAU;QACnB,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM;YACrB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;YACpE,OAAO,MAAM,CAAC,IAAiC,CAAC;QAClD,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM;YACvB,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/** Lifecycle state of a stored job. Acknowledged jobs are removed, so they have no state. */
+export type QueueJobState = 'pending' | 'leased' | 'dead';
+export interface EnqueueOptions {
+    /** Milliseconds to wait before the job becomes claimable. Defaults to 0. */
+    delayMs?: number;
+    /**
+     * While a job with the same key is pending or leased in the same queue, a
+     * second enqueue is a no-op that returns the existing job's id.
+     */
+    dedupeKey?: string;
+}
+export interface EnqueueResult {
+    id: string;
+    /** True when the enqueue was a no-op because of `dedupeKey`. */
+    deduplicated: boolean;
+}
+export interface ClaimOptions {
+    /** How long the claimer holds the job before it becomes claimable again. */
+    leaseMs: number;
+}
+export interface ClaimedJob<TPayload> {
+    id: string;
+    payload: TPayload;
+    /** 1 on the first claim; incremented by every later claim, including one after an expired lease. */
+    attempt: number;
+}
+/**
+ * Optional fence for `ack`, `fail` and `extendLease`. When `attempt` is the
+ * value returned by `claim`, the call only succeeds while that same claim
+ * still holds the job, so a claimer whose lease expired and was reclaimed
+ * cannot act on the new claimer's lease.
+ */
+export interface LeaseFence {
+    attempt?: number;
+}
+export type FailOptions = ({
+    retryAt: Date | number;
+    reason?: string;
+} & LeaseFence) | ({
+    deadLetter: true;
+    reason: string;
+} & LeaseFence);
+export interface QueueJob<TPayload> {
+    id: string;
+    queue: string;
+    payload: TPayload;
+    state: QueueJobState;
+    attempt: number;
+    availableAt: Date;
+    leaseUntil: Date | null;
+    dedupeKey: string | null;
+    lastError: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface QueueAdapter<TPayload> {
+    enqueue(queueName: string, payload: TPayload, options?: EnqueueOptions): Promise<EnqueueResult>;
+    /** Atomically leases the next available job, or resolves `null` when none is available. */
+    claim(queueName: string, options: ClaimOptions): Promise<ClaimedJob<TPayload> | null>;
+    /** Completes a leased job and removes it. Rejects with `FLOWFN_QUEUE_JOB_NOT_LEASED` otherwise. */
+    ack(id: string, fence?: LeaseFence): Promise<void>;
+    /** Releases a leased job for a retry at `retryAt`, or moves it to the dead-letter state. */
+    fail(id: string, options: FailOptions): Promise<void>;
+    /** Sets the lease of a leased job to expire `leaseMs` from now. */
+    extendLease(id: string, leaseMs: number, fence?: LeaseFence): Promise<void>;
+    /** Lists up to `limit` pending or leased jobs in claim order without changing them. */
+    peek(queueName: string, limit: number): Promise<QueueJob<TPayload>[]>;
+    /** Counts pending and leased jobs. */
+    size(queueName: string): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU,CAAC,QAAQ;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,QAAQ,CAAC;IAClB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GACnB,CAAC;IAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,GAC1D,CAAC;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC;AAExD,MAAM,WAAW,QAAQ,CAAC,QAAQ;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,YAAY,CAAC,QAAQ;IACpC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAChG,2FAA2F;IAC3F,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IACtF,mGAAmG;IACnG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,4FAA4F;IAC5F,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,mEAAmE;IACnE,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,uFAAuF;IACvF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtE,sCAAsC;IACtC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}