@objectstack/service-queue 4.0.5 → 4.1.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Plugin, PluginContext } from '@objectstack/core';
-import { IQueueService, QueuePublishOptions, QueueHandler } from '@objectstack/spec/contracts';
+import { IQueueService, QueuePublishOptions, QueueHandler, QueueMessageRecord } from '@objectstack/spec/contracts';
 
 /**
  * Configuration options for MemoryQueueAdapter.
@@ -27,43 +27,136 @@ declare class MemoryQueueAdapter implements IQueueService {
     purge(queue: string): Promise<void>;
 }
 
+/**
+ * Narrow ObjectQL engine surface used by job/queue adapters.
+ * Keeps the adapter testable without booting a real kernel.
+ *
+ * IMPORTANT: matches the canonical engine API:
+ *   - find: `where:` (NOT `filter:`)
+ *   - update: `(table, {id, ...patch}, opts)`
+ */
+interface JobEngine {
+    find(object: string, options?: any): Promise<any[]>;
+    insert(object: string, data: any, options?: any): Promise<any>;
+    update(object: string, idOrData: any, dataOrOptions?: any, options?: any): Promise<any>;
+    delete(object: string, options?: any): Promise<any>;
+}
+/** Stamped only in tests to make `now` deterministic. */
+interface JobClock {
+    now(): Date;
+}
+interface JobLogger {
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error?(msg: string, meta?: unknown): void;
+}
+
+interface DbQueueAdapterOptions {
+    /** Polling interval for the worker loop (ms, default 1000) */
+    pollIntervalMs?: number;
+    /** Max messages claimed per poll tick (default 10) */
+    batchSize?: number;
+    /** Lease duration before another worker may reclaim (ms, default 30000) */
+    leaseMs?: number;
+    /** Idempotency window — how long the same key blocks re-publish (ms, default 24h) */
+    idempotencyWindowMs?: number;
+    /** Default maxAttempts when publish doesn't specify (default 3) */
+    defaultMaxAttempts?: number;
+    /** Unique identifier for this worker (default: random) */
+    workerId?: string;
+    /** Whether to auto-start the polling worker (default true) */
+    autoStart?: boolean;
+}
+/**
+ * DbQueueAdapter — durable, polling, DB-backed IQueueService.
+ *
+ * Persists every message to `sys_job_queue`. A polling worker leases
+ * pending messages (CAS update status pending→running with a lease),
+ * invokes registered subscribers, and retries with backoff on failure.
+ * Messages that exceed `max_attempts` land in `status='dlq'`.
+ *
+ * Idempotency: publish suppresses duplicates within a configurable
+ * window when `(queue, idempotencyKey)` is non-null.
+ *
+ * Designed for SQLite and Postgres alike — uses CAS via WHERE-clauses,
+ * not row-level locking.
+ */
+declare class DbQueueAdapter implements IQueueService {
+    private readonly engine;
+    private readonly logger?;
+    private readonly clock?;
+    private readonly opts;
+    private readonly handlers;
+    private timer?;
+    private running;
+    constructor(args: {
+        engine: JobEngine;
+        logger?: JobLogger;
+        clock?: JobClock;
+        options?: DbQueueAdapterOptions;
+    });
+    publish<T = unknown>(queue: string, data: T, options?: QueuePublishOptions): Promise<string>;
+    subscribe<T = unknown>(queue: string, handler: QueueHandler<T>): Promise<void>;
+    unsubscribe(queue: string): Promise<void>;
+    getQueueSize(queue: string): Promise<number>;
+    purge(queue: string): Promise<void>;
+    listFailed(queue?: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<QueueMessageRecord[]>;
+    replay(messageId: string): Promise<void>;
+    purgeFailed(messageId: string): Promise<void>;
+    start(): void;
+    stop(): Promise<void>;
+    /** Test-friendly synchronous poll. */
+    pollOnce(): Promise<number>;
+    private claimBatch;
+    private dispatch;
+    private computeBackoff;
+    private releasePending;
+    private loadById;
+    private rowToRecord;
+    private now;
+}
+
 /**
  * Configuration options for the QueueServicePlugin.
  */
 interface QueueServicePluginOptions {
-    /** Queue adapter type (default: 'memory') */
-    adapter?: 'memory' | 'bullmq';
+    /**
+     * Queue adapter type.
+     *  - 'auto' (default): use DbQueueAdapter when objectql engine available, else MemoryQueueAdapter
+     *  - 'db': require objectql; persists messages, retries, and DLQ to sys_job_queue
+     *  - 'memory': in-process MemoryQueueAdapter (non-durable, dev/test)
+     *  - 'bullmq': reserved for M10.43 (throws today)
+     */
+    adapter?: 'auto' | 'db' | 'memory' | 'bullmq';
     /** Options for the memory queue adapter */
     memory?: MemoryQueueAdapterOptions;
-    /** Redis connection URL (used when adapter is 'bullmq') */
+    /** Options for the DB adapter (polling, batch, lease, idempotency window…) */
+    db?: DbQueueAdapterOptions;
+    /** Redis connection URL (reserved for bullmq) */
     redisUrl?: string;
 }
 /**
  * QueueServicePlugin — Production IQueueService implementation.
  *
- * Registers a queue service with the kernel during the init phase.
- * Supports in-memory and BullMQ adapters.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { QueueServicePlugin } from '@objectstack/service-queue';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new QueueServicePlugin({ adapter: 'memory' }));
- * await kernel.bootstrap();
- *
- * const queue = kernel.getService('queue');
- * await queue.publish('orders', { orderId: 123 });
- * ```
+ * Default: registers MemoryQueueAdapter synchronously so producers can
+ * publish during plugin init; upgrades to DbQueueAdapter on `kernel:ready`
+ * when an ObjectQL engine is available. Subscribers registered against
+ * the (now-replaced) memory queue must re-subscribe after upgrade — for
+ * that reason most plugins register subscribers inside their own
+ * `kernel:ready` hook, which fires after this one.
  */
 declare class QueueServicePlugin implements Plugin {
     name: string;
     version: string;
     type: string;
     private readonly options;
+    private dbAdapter?;
     constructor(options?: QueueServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
 }
 
 /**
@@ -105,4 +198,4 @@ declare class BullMQQueueAdapter implements IQueueService {
     purge(_queue: string): Promise<void>;
 }
 
-export { BullMQQueueAdapter, type BullMQQueueAdapterOptions, MemoryQueueAdapter, type MemoryQueueAdapterOptions, QueueServicePlugin, type QueueServicePluginOptions };
+export { BullMQQueueAdapter, type BullMQQueueAdapterOptions, DbQueueAdapter, type DbQueueAdapterOptions, type JobClock, type JobEngine, type JobLogger, MemoryQueueAdapter, type MemoryQueueAdapterOptions, QueueServicePlugin, type QueueServicePluginOptions };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Plugin, PluginContext } from '@objectstack/core';
-import { IQueueService, QueuePublishOptions, QueueHandler } from '@objectstack/spec/contracts';
+import { IQueueService, QueuePublishOptions, QueueHandler, QueueMessageRecord } from '@objectstack/spec/contracts';
 
 /**
  * Configuration options for MemoryQueueAdapter.
@@ -27,43 +27,136 @@ declare class MemoryQueueAdapter implements IQueueService {
     purge(queue: string): Promise<void>;
 }
 
+/**
+ * Narrow ObjectQL engine surface used by job/queue adapters.
+ * Keeps the adapter testable without booting a real kernel.
+ *
+ * IMPORTANT: matches the canonical engine API:
+ *   - find: `where:` (NOT `filter:`)
+ *   - update: `(table, {id, ...patch}, opts)`
+ */
+interface JobEngine {
+    find(object: string, options?: any): Promise<any[]>;
+    insert(object: string, data: any, options?: any): Promise<any>;
+    update(object: string, idOrData: any, dataOrOptions?: any, options?: any): Promise<any>;
+    delete(object: string, options?: any): Promise<any>;
+}
+/** Stamped only in tests to make `now` deterministic. */
+interface JobClock {
+    now(): Date;
+}
+interface JobLogger {
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error?(msg: string, meta?: unknown): void;
+}
+
+interface DbQueueAdapterOptions {
+    /** Polling interval for the worker loop (ms, default 1000) */
+    pollIntervalMs?: number;
+    /** Max messages claimed per poll tick (default 10) */
+    batchSize?: number;
+    /** Lease duration before another worker may reclaim (ms, default 30000) */
+    leaseMs?: number;
+    /** Idempotency window — how long the same key blocks re-publish (ms, default 24h) */
+    idempotencyWindowMs?: number;
+    /** Default maxAttempts when publish doesn't specify (default 3) */
+    defaultMaxAttempts?: number;
+    /** Unique identifier for this worker (default: random) */
+    workerId?: string;
+    /** Whether to auto-start the polling worker (default true) */
+    autoStart?: boolean;
+}
+/**
+ * DbQueueAdapter — durable, polling, DB-backed IQueueService.
+ *
+ * Persists every message to `sys_job_queue`. A polling worker leases
+ * pending messages (CAS update status pending→running with a lease),
+ * invokes registered subscribers, and retries with backoff on failure.
+ * Messages that exceed `max_attempts` land in `status='dlq'`.
+ *
+ * Idempotency: publish suppresses duplicates within a configurable
+ * window when `(queue, idempotencyKey)` is non-null.
+ *
+ * Designed for SQLite and Postgres alike — uses CAS via WHERE-clauses,
+ * not row-level locking.
+ */
+declare class DbQueueAdapter implements IQueueService {
+    private readonly engine;
+    private readonly logger?;
+    private readonly clock?;
+    private readonly opts;
+    private readonly handlers;
+    private timer?;
+    private running;
+    constructor(args: {
+        engine: JobEngine;
+        logger?: JobLogger;
+        clock?: JobClock;
+        options?: DbQueueAdapterOptions;
+    });
+    publish<T = unknown>(queue: string, data: T, options?: QueuePublishOptions): Promise<string>;
+    subscribe<T = unknown>(queue: string, handler: QueueHandler<T>): Promise<void>;
+    unsubscribe(queue: string): Promise<void>;
+    getQueueSize(queue: string): Promise<number>;
+    purge(queue: string): Promise<void>;
+    listFailed(queue?: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<QueueMessageRecord[]>;
+    replay(messageId: string): Promise<void>;
+    purgeFailed(messageId: string): Promise<void>;
+    start(): void;
+    stop(): Promise<void>;
+    /** Test-friendly synchronous poll. */
+    pollOnce(): Promise<number>;
+    private claimBatch;
+    private dispatch;
+    private computeBackoff;
+    private releasePending;
+    private loadById;
+    private rowToRecord;
+    private now;
+}
+
 /**
  * Configuration options for the QueueServicePlugin.
  */
 interface QueueServicePluginOptions {
-    /** Queue adapter type (default: 'memory') */
-    adapter?: 'memory' | 'bullmq';
+    /**
+     * Queue adapter type.
+     *  - 'auto' (default): use DbQueueAdapter when objectql engine available, else MemoryQueueAdapter
+     *  - 'db': require objectql; persists messages, retries, and DLQ to sys_job_queue
+     *  - 'memory': in-process MemoryQueueAdapter (non-durable, dev/test)
+     *  - 'bullmq': reserved for M10.43 (throws today)
+     */
+    adapter?: 'auto' | 'db' | 'memory' | 'bullmq';
     /** Options for the memory queue adapter */
     memory?: MemoryQueueAdapterOptions;
-    /** Redis connection URL (used when adapter is 'bullmq') */
+    /** Options for the DB adapter (polling, batch, lease, idempotency window…) */
+    db?: DbQueueAdapterOptions;
+    /** Redis connection URL (reserved for bullmq) */
     redisUrl?: string;
 }
 /**
  * QueueServicePlugin — Production IQueueService implementation.
  *
- * Registers a queue service with the kernel during the init phase.
- * Supports in-memory and BullMQ adapters.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { QueueServicePlugin } from '@objectstack/service-queue';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new QueueServicePlugin({ adapter: 'memory' }));
- * await kernel.bootstrap();
- *
- * const queue = kernel.getService('queue');
- * await queue.publish('orders', { orderId: 123 });
- * ```
+ * Default: registers MemoryQueueAdapter synchronously so producers can
+ * publish during plugin init; upgrades to DbQueueAdapter on `kernel:ready`
+ * when an ObjectQL engine is available. Subscribers registered against
+ * the (now-replaced) memory queue must re-subscribe after upgrade — for
+ * that reason most plugins register subscribers inside their own
+ * `kernel:ready` hook, which fires after this one.
  */
 declare class QueueServicePlugin implements Plugin {
     name: string;
     version: string;
     type: string;
     private readonly options;
+    private dbAdapter?;
     constructor(options?: QueueServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
 }
 
 /**
@@ -105,4 +198,4 @@ declare class BullMQQueueAdapter implements IQueueService {
     purge(_queue: string): Promise<void>;
 }
 
-export { BullMQQueueAdapter, type BullMQQueueAdapterOptions, MemoryQueueAdapter, type MemoryQueueAdapterOptions, QueueServicePlugin, type QueueServicePluginOptions };
+export { BullMQQueueAdapter, type BullMQQueueAdapterOptions, DbQueueAdapter, type DbQueueAdapterOptions, type JobClock, type JobEngine, type JobLogger, MemoryQueueAdapter, type MemoryQueueAdapterOptions, QueueServicePlugin, type QueueServicePluginOptions };