@superfunctions/queue 0.0.1 → 0.2.0

package/dist/validation.d.ts

@@ -0,0 +1,29 @@
+import type { EnqueueOptions, FailOptions, LeaseFence } from './types.js';
+export declare class QueueError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function normalizeQueueName(queueName: string): string;
+export interface NormalizedEnqueueOptions {
+    delayMs: number;
+    dedupeKey: string | null;
+}
+export declare function normalizeEnqueueOptions(options: EnqueueOptions | undefined): NormalizedEnqueueOptions;
+export declare function normalizeLeaseMs(leaseMs: unknown): number;
+export declare function normalizeLimit(limit: unknown): number;
+/** Job ids are positive decimal integers rendered as strings. */
+export declare function normalizeJobId(id: unknown): number;
+export declare function normalizeFence(fence: LeaseFence | undefined): number | null;
+export type NormalizedFailOptions = {
+    kind: 'retry';
+    retryAt: number;
+    reason: string | null;
+    attempt: number | null;
+} | {
+    kind: 'dead';
+    reason: string;
+    attempt: number | null;
+};
+export declare function normalizeFailOptions(options: FailOptions): NormalizedFailOptions;
+export declare function readClock(now: () => number): number;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAQD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,wBAAwB,CAarG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAKzD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKrD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CASlD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE7D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,qBAAqB,CAyBhF;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,MAAM,CAMnD"}

package/dist/validation.js

@@ -0,0 +1,99 @@
+export class QueueError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = 'QueueError';
+        this.code = code;
+    }
+}
+const MAX_DEDUPE_KEY_LENGTH = 512;
+/** Upper bound for `delayMs` and `leaseMs` (100 years), so `now + duration` stays a valid Date. */
+const MAX_DURATION_MS = 100 * 365 * 24 * 60 * 60 * 1000;
+/** The largest epoch-millisecond value a Date can hold. */
+const MAX_TIMESTAMP_MS = 8.64e15;
+export function normalizeQueueName(queueName) {
+    const normalized = typeof queueName === 'string' ? queueName.trim() : '';
+    if (!normalized || normalized.includes('/') || normalized.includes('\\') || normalized.includes('..')) {
+        throw new QueueError('FLOWFN_QUEUE_NAME_INVALID');
+    }
+    return normalized;
+}
+export function normalizeEnqueueOptions(options) {
+    const delayMs = options?.delayMs ?? 0;
+    if (!Number.isSafeInteger(delayMs) || delayMs < 0 || delayMs > MAX_DURATION_MS) {
+        throw new QueueError('FLOWFN_QUEUE_DELAY_INVALID');
+    }
+    const dedupeKey = options?.dedupeKey;
+    if (dedupeKey !== undefined &&
+        (typeof dedupeKey !== 'string' || dedupeKey.length === 0 || dedupeKey.length > MAX_DEDUPE_KEY_LENGTH)) {
+        throw new QueueError('FLOWFN_QUEUE_DEDUPE_KEY_INVALID');
+    }
+    return { delayMs, dedupeKey: dedupeKey ?? null };
+}
+export function normalizeLeaseMs(leaseMs) {
+    if (typeof leaseMs !== 'number' || !Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > MAX_DURATION_MS) {
+        throw new QueueError('FLOWFN_QUEUE_LEASE_INVALID');
+    }
+    return leaseMs;
+}
+export function normalizeLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 0) {
+        throw new QueueError('FLOWFN_QUEUE_LIMIT_INVALID');
+    }
+    return limit;
+}
+/** Job ids are positive decimal integers rendered as strings. */
+export function normalizeJobId(id) {
+    if (typeof id !== 'string' || !/^[1-9]\d*$/.test(id)) {
+        throw new QueueError('FLOWFN_QUEUE_JOB_ID_INVALID');
+    }
+    const value = Number(id);
+    if (!Number.isSafeInteger(value)) {
+        throw new QueueError('FLOWFN_QUEUE_JOB_ID_INVALID');
+    }
+    return value;
+}
+export function normalizeFence(fence) {
+    const attempt = fence?.attempt;
+    if (attempt === undefined) {
+        return null;
+    }
+    if (typeof attempt !== 'number' || !Number.isSafeInteger(attempt) || attempt < 1) {
+        throw new QueueError('FLOWFN_QUEUE_ATTEMPT_INVALID');
+    }
+    return attempt;
+}
+export function normalizeFailOptions(options) {
+    if (!options || typeof options !== 'object') {
+        throw new QueueError('FLOWFN_QUEUE_FAIL_OPTIONS_INVALID');
+    }
+    const attempt = normalizeFence(options);
+    if ('deadLetter' in options && 'retryAt' in options) {
+        throw new QueueError('FLOWFN_QUEUE_FAIL_OPTIONS_INVALID');
+    }
+    if ('deadLetter' in options) {
+        if (options.deadLetter !== true || typeof options.reason !== 'string' || options.reason.length === 0) {
+            throw new QueueError('FLOWFN_QUEUE_FAIL_OPTIONS_INVALID');
+        }
+        return { kind: 'dead', reason: options.reason, attempt };
+    }
+    if (!('retryAt' in options)) {
+        throw new QueueError('FLOWFN_QUEUE_FAIL_OPTIONS_INVALID');
+    }
+    const retryAt = options.retryAt instanceof Date ? options.retryAt.getTime() : options.retryAt;
+    if (typeof retryAt !== 'number' || !Number.isSafeInteger(retryAt) || retryAt < 0 || retryAt > MAX_TIMESTAMP_MS) {
+        throw new QueueError('FLOWFN_QUEUE_RETRY_AT_INVALID');
+    }
+    if (options.reason !== undefined && typeof options.reason !== 'string') {
+        throw new QueueError('FLOWFN_QUEUE_FAIL_OPTIONS_INVALID');
+    }
+    return { kind: 'retry', retryAt, reason: options.reason ?? null, attempt };
+}
+export function readClock(now) {
+    const value = now();
+    if (!Number.isSafeInteger(value) || value < 0 || value > MAX_TIMESTAMP_MS - MAX_DURATION_MS) {
+        throw new QueueError('FLOWFN_QUEUE_CLOCK_INVALID');
+    }
+    return value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/migrations/postgres/0001_queue_jobs.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS "queue_jobs" (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  queue TEXT NOT NULL,
+  payload JSON NOT NULL,
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'leased', 'dead')),
+  attempt INTEGER NOT NULL DEFAULT 0,
+  available_at BIGINT NOT NULL,
+  lease_until BIGINT,
+  dedupe_key TEXT,
+  last_error TEXT,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS "queue_jobs_available_idx" ON "queue_jobs" (queue, state, available_at, id);
+
+CREATE INDEX IF NOT EXISTS "queue_jobs_lease_idx" ON "queue_jobs" (queue, state, lease_until);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "queue_jobs_dedupe_idx" ON "queue_jobs" (queue, dedupe_key) WHERE dedupe_key IS NOT NULL AND state IN ('pending', 'leased');

package/migrations/sqlite/0001_queue_jobs.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS "queue_jobs" (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  queue TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'leased', 'dead')),
+  attempt INTEGER NOT NULL DEFAULT 0,
+  available_at INTEGER NOT NULL,
+  lease_until INTEGER,
+  dedupe_key TEXT,
+  last_error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS "queue_jobs_available_idx" ON "queue_jobs" (queue, state, available_at, id);
+
+CREATE INDEX IF NOT EXISTS "queue_jobs_lease_idx" ON "queue_jobs" (queue, state, lease_until);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "queue_jobs_dedupe_idx" ON "queue_jobs" (queue, dedupe_key) WHERE dedupe_key IS NOT NULL AND state IN ('pending', 'leased');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@superfunctions/queue",
-  "version": "0.0.1",
-  "description": "Shared queue adapters for Superfunctions",
+  "version": "0.2.0",
+  "description": "Queue adapters for Superfunctions: in-memory and durable SQL (SQLite, D1, Postgres)",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,14 +9,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./migrations/*": "./migrations/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "migrations",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
-    "test": "vitest",
+    "test": "vitest run",
     "test:watch": "vitest --watch",
     "lint": "echo 'lint not configured'",
     "typecheck": "tsc --noEmit",
@@ -24,6 +27,10 @@
   },
   "keywords": [
     "queue",
+    "jobs",
+    "sqlite",
+    "postgres",
+    "d1",
     "flowfn",
     "superfunctions"
   ],
@@ -31,15 +38,34 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/21nCo/super-functions.git",
+    "url": "git+https://github.com/21nCo/superfunctions.git",
     "directory": "packages/queue"
   },
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "@superfunctions/db": "^0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@superfunctions/db": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.0",
+    "@superfunctions/db": "0.3.2",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
+    "@types/pg": "^8.20.0",
+    "better-sqlite3": "^12.5.0",
+    "drizzle-orm": "^0.35.0",
+    "esbuild": "^0.21.5",
+    "kysely": "^0.28.0",
+    "miniflare": "4.20251113.0",
+    "pg": "^8.20.0",
     "typescript": "^5.6.0",
     "vitest": "^3.2.4"
-  }
+  },
+  "gitHead": "699d9d09932199d660333c57fe7bc646492ea3bf"
 }