@maestro-js/queue 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -1,300 +1,264 @@
 import { Iso } from 'iso-fns2';
 import { Log } from '@maestro-js/log';
 
-interface DehydratedTrace {
-    traceId: string;
-    spanId: string;
-    traceFlags: number;
-    traceState: string | undefined;
-}
-interface QueueTracing {
-    hydrate: <T>(trace: DehydratedTrace | null, callback: () => T) => T;
-    dehydrate: () => DehydratedTrace | null;
-    startActiveSpan: <R>(name: string | {
-        name: string;
-        attributes?: Record<string, unknown>;
-    }, fn: () => R) => R;
-    getActiveSpan: () => {
-        setAttribute(key: string, value: unknown): void;
-        setStatus(status: {
-            code: number;
-            message: string;
-        }): void;
-    } | undefined;
-}
-interface QueueMessage<MessageBody extends Record<string, any> = Record<string, any>, Result = any> {
-    id: number;
-    batchId: number | null;
+interface QueueMessage<MessageBody extends Record<string, any> = Record<string, any>> {
+    id: string;
     queue: string;
-    scheduledDate: Iso.Instant;
-    enqueuedDate: Iso.Instant;
-    startedDate: Iso.Instant | null;
     body: MessageBody;
-    trace: DehydratedTrace | null;
-    status: 'waiting' | 'processing' | 'success' | 'error' | 'stuck';
-    result: Result;
-    recovered: number;
-    runningTimeSeconds: number | null;
-    uniqueKey: number | null;
-    priority: number | null;
+    attempts: number;
 }
-type QueueWorkFunction<MessageBody extends Record<string, any> = Record<string, any>> = (args: {
-    body: MessageBody;
-    id: number;
-    trace: DehydratedTrace | null;
-    scheduledDate: Iso.Instant;
-}) => any;
 interface QueueDriver {
-    start<MessageBody extends Record<string, any> = Record<string, any>>(options: {
-        queueName: string;
-        workFn: QueueWorkFunction<MessageBody>;
-        concurrency?: number;
-    }): void;
-    stop(options: {
-        queueName: string;
-    }): void;
-    listMessages<MessageBody extends Record<string, any> = Record<string, any>, Result = any>(options: {
-        pageSize: number;
-        pageNumber: number;
-        queueName: string;
-    }): Promise<QueueMessage<MessageBody, Result>[]>;
-    addMessage<MessageBody extends Record<string, any> = Record<string, any>>(options: {
-        body: MessageBody;
-        scheduledDate: Iso.Instant | null;
-        queueName: string;
-        traceData: DehydratedTrace | null;
-    }): Promise<{
-        id: number;
-    }>;
-    updateMessage<MessageBody extends Record<string, any> = Record<string, any>>(options: {
-        queueName: string;
-        messageId: number;
+    size(): Promise<number>;
+    push(message: {
+        queue: string;
+        body: Record<string, any>;
         scheduledDate: Iso.Instant;
-        body: MessageBody;
+    }): Promise<string>;
+    bulk(messages: {
+        queue: string;
+        body: Record<string, any>;
+        scheduledDate: Iso.Instant;
+    }[]): Promise<void>;
+    pop(): Promise<QueueMessage | null>;
+    fail(options: {
+        id: string;
+        attempts: number;
+        error: Error;
+    }): Promise<void>;
+    success(options: {
+        id: string;
+        attempts: number;
+        result: any;
+    }): Promise<void>;
+    release(options: {
+        id: string;
+        attempts: number;
+        error: Error;
+        delaySeconds: number;
     }): Promise<void>;
-    isQueueEmpty(options: {
-        queueName: string;
-    }): Promise<boolean>;
 }
+
+interface DbQueueDriverConfig {
+    db: {
+        update(query: string, params?: any[]): Promise<{
+            changedRows: number;
+        }>;
+        select(query: string, params?: any[]): Promise<Array<Record<string, any>>>;
+        insert(query: string, params?: any[]): Promise<{
+            insertId: number;
+        }>;
+    };
+    databaseTable: string;
+    queue?: string | string[];
+    batchingMaxWaitSeconds?: number;
+}
+declare function DbQueueDriver({ db, databaseTable, queue: queueFilter, batchingMaxWaitSeconds }: DbQueueDriverConfig): QueueDriver;
+
+interface LocalQueueDriverConfig {
+    queue?: string | string[];
+}
+declare function localQueueDriver({ queue: queueFilter }?: LocalQueueDriverConfig): QueueDriver;
+
+declare function createService({ driver, logger: serviceLogger }: Queue.Provider.QueueServiceConfig): Queue.QueueService;
 type QueueLogMessage = {
     event: 'messageEnqueued';
     queue: string;
-    driver: QueueDriver;
-    scheduledDate: Iso.Instant | null;
     body: Record<string, any>;
-    messageId: number;
 } | {
     event: 'messageDequeued';
     queue: string;
-    driver: QueueDriver;
     body: Record<string, any>;
-    messageId: number;
+    messageId: string;
 } | {
     event: 'messageProcessed';
     queue: string;
-    driver: QueueDriver;
     body: Record<string, any>;
-    result: unknown;
-    messageId: number;
+    messageId: string;
+    result: any;
 } | {
     event: 'messageFailed';
     queue: string;
-    driver: QueueDriver;
     body: Record<string, any>;
+    messageId: string;
     error: unknown;
-    messageId: number;
 } | {
-    event: 'queueStarted';
+    event: 'messageReleased';
     queue: string;
-    driver: QueueDriver;
-} | {
-    event: 'queueStopped';
-    queue: string;
-    driver: QueueDriver;
+    body: Record<string, any>;
+    messageId: string;
+    error: unknown;
+    attempt: number;
 };
-
-interface DbQueueDriverConfig {
-    db: {
-        update(query: string, params?: any[]): Promise<{
-            changedRows: number;
-        }>;
-        select(query: string, params?: any[]): Promise<Array<Record<string, any>>>;
-        insert(query: string, params?: any[]): Promise<{
-            insertId: number;
-        }>;
-    };
-    databaseTable: string;
-    extraFields?: string[];
-    fastestPollingRateMs?: number;
-    slowestPollingRateMs?: number;
-    pollingBackoffRate?: number;
+type QueueMiddleware<MessageBody extends Record<string, any> = Record<string, any>, Result = any> = (message: MessageBody, next: {
+    next: () => Promise<Result>;
+} & QueueActions) => Promise<Result>;
+interface QueueActions {
+    fail(error: Error): never;
+    release(error: Error, delaySeconds?: number): never;
 }
-declare function DbQueueDriver({ db, databaseTable, extraFields, fastestPollingRateMs, slowestPollingRateMs, pollingBackoffRate }: DbQueueDriverConfig): QueueDriver;
-
-declare function createService(config: Queue.Provider.QueueServiceConfig): {
-    list: () => string[];
-    get: <MessageBody extends Record<string, any>, Result = any>(name: string) => Queue.Queue<MessageBody, Result> | undefined;
-    create: <MessageBody extends Record<string, any>, Result = any>(options: Queue.QueueOptions<MessageBody, Result>) => Queue.Queue<MessageBody, Result>;
-    startProcessing: () => void;
-    stopProcessing: () => void;
-};
+type KeysWithFallback = keyof Queue.Provider.Keys extends never ? {
+    default: unknown;
+} : Queue.Provider.Keys;
 declare function provider(key: Queue.Provider.Key): {
-    list: () => string[];
-    get: <MessageBody extends Record<string, any>, Result = any>(name: string) => Queue.Queue<MessageBody, Result> | undefined;
-    create: <MessageBody extends Record<string, any>, Result = any>(options: Queue.QueueOptions<MessageBody, Result>) => Queue.Queue<MessageBody, Result>;
-    startProcessing: () => void;
-    stopProcessing: () => void;
+    work: (options: Queue.WorkOptions) => Promise<void> & {
+        abort(reason?: string | undefined): void;
+    };
+    stopAllWork: () => Promise<void>;
+    processMessage: <MessageBody extends Record<string, any> = Record<string, any>>(queueMessage: Queue.Message<MessageBody>) => Promise<unknown>;
+    create: <MessageBody extends Record<string, any> = {}, Result = any>(config: Queue.Config<MessageBody, Result>) => Queue.QueueHandle<MessageBody, Result>;
 };
 /**
- * Job queue for deferring work beyond the current request.
+ * Driver-backed job queue with middleware, retries, and configurable backoff.
  *
- * Messages are stored by a pluggable driver and processed asynchronously by a
- * worker — either in the same process or a dedicated consumer. Each message
- * tracks its full lifecycle (waiting → processing → success/error/stuck) and
- * supports scheduled future execution, concurrent processing, and distributed
- * trace propagation across the producer/consumer boundary.
+ * Register a service with `Queue.Provider.register('default', Queue.Provider.create({ driver }))`,
+ * then define individual queues with `Queue.create({ name, handle })`. Messages can be dispatched
+ * immediately, with a delay, or synchronously. Handlers receive `fail` and `release` callbacks
+ * to permanently fail a message or release it for retry with backoff.
  *
  * @example
  * ```ts
- * // Create and register a queue service
  * Queue.Provider.register('default', Queue.Provider.create({
- *   driver: Queue.drivers.db({ db: Db.provider('default'), databaseTable: 'jobs' }),
+ *   driver: myDriver,
  *   logger: Log.provider('default')
  * }))
  *
- * // Create a queue with a work function
- * const orderQueue = Queue.create({
- *   name: 'fulfill-orders',
- *   workFn: async (body) => {
- *     await fulfillOrder(body.orderId)
- *     return { fulfilled: true }
- *   }
+ * const emailQueue = Queue.create({
+ *   name: 'send-emails',
+ *   handle: async (body) => sendEmail(body.to, body.subject),
+ *   tries: 3,
+ *   backoffSeconds: [30, 60, 120]
  * })
  *
- * // Enqueue a message and start processing
- * await orderQueue.addMessage({ orderId: 'ord_123' }, { scheduledDate: null })
- * orderQueue.startProcessing()
+ * await emailQueue.dispatch({ to: 'alice@example.com', subject: 'Welcome' })
+ * await Queue.work({ stopWhenEmpty: true })
  * ```
  */
 declare namespace Queue {
+    /** Union of all queue lifecycle log event shapes */
+    type LogMessage = QueueLogMessage;
+    /** Middleware function for wrapping queue message handling */
+    type Middleware<MessageBody extends Record<string, any> = Record<string, any>, Result = any> = QueueMiddleware<MessageBody, Result>;
+    /** A single message popped from the queue */
+    type Message<MessageBody extends Record<string, any> = Record<string, any>> = QueueMessage<MessageBody>;
+    /** Pluggable storage backend — see driver implementations for built-in options */
+    type Driver = QueueDriver;
+    /** Callbacks passed to handlers and middleware for explicit message control */
+    type Actions = QueueActions;
     /** Per-queue configuration passed to {@link QueueService.create} */
-    interface QueueOptions<T extends Record<string, any> = Record<string, any>, Result = any> {
+    interface Config<MessageBody extends Record<string, any> = Record<string, any>, Result = any> {
         name: string;
-        workFn(body: T): Promise<Result>;
-        logger?: Log.LogFunctions<[QueueLogMessage]>;
+        handle(params: MessageBody, actions: Actions): Promise<Result>;
+        middleware?: Middleware<MessageBody, Result>[];
+        tries?: number;
+        backoffSeconds?: number | number[];
+        logger?: Log.LogFunctions<[LogMessage]>;
+    }
+    /** Options for controlling the work polling loop */
+    interface WorkOptions {
+        maxJobs?: number;
+        stopWhenEmpty?: boolean;
+        maxTimeSeconds?: number;
+        sleepSeconds?: number;
         concurrency?: number;
     }
-    /** Pluggable storage backend that handles message persistence, polling, and locking */
-    type Driver = QueueDriver;
-    /** A single message stored in the queue with its full lifecycle metadata */
-    type QueueMessage<MessageBody extends Record<string, any> = Record<string, any>, Result = any> = QueueMessage<MessageBody, Result>;
-    /** Union of all queue lifecycle log event shapes */
-    type LogMessage = QueueLogMessage;
-    /** Distributed tracing adapter for propagating trace context across producer/consumer boundaries */
-    type Tracing = QueueTracing;
     /**
-     * A named queue instance with methods for adding messages and controlling processing.
+     * A named queue instance returned by {@link QueueService.create}.
      *
-     * Each queue has its own work function, concurrency setting, and independent
-     * start/stop lifecycle. Messages are typed via the `MessageBody` and `Result`
-     * generics — the body is what the producer enqueues, the result is what the
-     * work function returns on success.
+     * Each handle is bound to a single queue name and provides methods to enqueue
+     * messages immediately, with a delay, synchronously (bypassing the driver), or
+     * in bulk. Dispatched messages are picked up by {@link QueueService.work}.
      *
      * @example
      * ```ts
-     * const queue = Queue.create({
+     * const emailQueue = Queue.create({
      *   name: 'send-emails',
-     *   workFn: async (body) => sendEmail(body.to, body.subject),
-     *   concurrency: 3
+     *   handle: async (body) => sendEmail(body.to, body.subject),
+     *   tries: 3,
+     *   backoffSeconds: [30, 60, 120]
      * })
-     * await queue.addMessage({ to: 'alice@example.com', subject: 'Welcome' }, { scheduledDate: null })
-     * queue.startProcessing()
+     *
+     * await emailQueue.dispatch({ to: 'alice@example.com', subject: 'Welcome' })
+     * await emailQueue.dispatchWithDelay(body, scheduledDate)
+     * await emailQueue.bulk([{ body: msg1 }, { body: msg2 }])
      * ```
      */
-    type Queue<MessageBody extends Record<string, any> = Record<string, any>, Result = any> = {
-        /** Starts polling for and processing messages on this queue */
-        startProcessing(): void;
-        /** Starts processing and resolves when no waiting or in-progress messages remain */
-        processUntilEmpty(options?: {
-            pollingMs?: number;
-        }): Promise<void>;
-        /** Stops polling for new messages on this queue */
-        stopProcessing(): void;
-        name: string;
-        /** Returns a paginated list of messages in this queue */
-        listMessages(options: {
-            pageSize: number;
-            pageNumber: number;
-        }): Promise<QueueMessage<MessageBody, Result>[]>;
-        /** Adds a message to this queue for immediate or scheduled processing */
-        addMessage(body: MessageBody, options: {
-            scheduledDate: Iso.Instant | null;
-            tracingContext?: DehydratedTrace | null;
-        }): Promise<void>;
-        /** Updates the body and scheduled date of a waiting message */
-        updateMessage(options: {
-            messageId: number;
-            scheduledDate: Iso.Instant;
+    interface QueueHandle<MessageBody extends Record<string, any> = Record<string, any>, Result = any> {
+        /** Dispatches a message onto the queue for immediate processing */
+        dispatch(...params: {} extends MessageBody ? [] | [MessageBody] : [MessageBody]): Promise<void>;
+        /** Dispatches a message onto the queue with a scheduled processing date */
+        dispatchWithDelay(...params: {} extends MessageBody ? [scheduledDate: Iso.Instant] | [message: MessageBody, scheduledDate: Iso.Instant] : [message: MessageBody, scheduledDate: Iso.Instant]): Promise<void>;
+        /** Executes the handler synchronously without going through the driver — bypasses the driver entirely, useful for testing */
+        dispatchSync(...params: {} extends MessageBody ? [] | [MessageBody] : [MessageBody]): Promise<Result>;
+        /** Dispatches multiple messages in a single bulk operation */
+        bulk(messages: {
             body: MessageBody;
-        }): Promise<void>;
-    };
-    namespace Provider {
-        interface QueueServiceConfig {
-            driver: Driver;
-            logger: Log.Logger<[QueueLogMessage]>;
-            tracing?: QueueTracing;
-        }
-        type Key = keyof Keys;
-        interface Keys {
-            default: unknown;
-        }
+            scheduledDate?: Iso.Instant;
+        }[]): Promise<void>;
     }
     /**
      * Container that manages multiple named queues sharing the same driver and logger.
      *
-     * Create individual queues with {@link create}, then start or stop processing
-     * across all queues at once or individually. Each queue has its own work function,
-     * concurrency, and message lifecycle.
+     * Returned by `Queue.Provider.create()` or resolved via `Queue.provider()`.
+     * Use {@link QueueService.create create} to define queues, then call
+     * {@link QueueService.work work} to start polling for and processing messages.
+     * Handlers receive `fail` and `release` callbacks to permanently fail a message
+     * or release it for retry with backoff.
      *
      * @example
      * ```ts
-     * const orders = Queue.create({ name: 'orders', workFn: processOrder })
-     * const emails = Queue.create({ name: 'emails', workFn: sendEmail, concurrency: 5 })
-     * Queue.startProcessing() // starts both queues
+     * const service = Queue.Provider.create({
+     *   driver: Queue.drivers.db({ db, databaseTable: 'queue' }),
+     *   logger: Log.provider('default')
+     * })
+     * Queue.Provider.register('default', service)
+     *
+     * const q = Queue.create({ name: 'emails', handle: async (body) => send(body) })
+     * await q.dispatch({ to: 'alice@example.com' })
+     * await Queue.work({ stopWhenEmpty: true })
      * ```
      */
     interface QueueService {
-        /** Returns the names of all queues registered with this service */
-        list(): string[];
-        /** Returns the queue with the given name, or `undefined` if not found */
-        get<MessageBody extends Record<string, any>, Result = any>(name: string): Queue.Queue<MessageBody, Result> | undefined;
-        /** Creates a new named queue with the given work function and options */
-        create<MessageBody extends Record<string, any>, Result = any>(options: Queue.QueueOptions<MessageBody, Result>): Queue<MessageBody, Result>;
-        /** Stops processing messages on all queues */
-        stopProcessing(): void;
-        /** Starts processing messages on all queues */
-        startProcessing(): void;
+        /** Starts polling for and processing messages — returns a promise with an `abort()` method to stop the loop */
+        work(options: WorkOptions): Promise<void> & {
+            abort(reason?: string | undefined): void;
+        };
+        /** Aborts all active work loops and waits for in-flight messages to finish */
+        stopAllWork(): Promise<void>;
+        /** Processes a single message directly — looks up the queue handler by `queueMessage.queue` */
+        processMessage<MessageBody extends Record<string, any> = Record<string, any>>(queueMessage: Message<MessageBody>): Promise<unknown>;
+        /** Creates a new named queue with the given handler, retry, and middleware options */
+        create<MessageBody extends Record<string, any> = {}, Result = any>(config: Config<MessageBody, Result>): QueueHandle<MessageBody, Result>;
+    }
+    namespace Provider {
+        interface QueueServiceConfig {
+            driver: Driver;
+            logger?: Log.Logger<[LogMessage]>;
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
     }
 }
 /**
- * Job queue for deferring work beyond the current request.
+ * Driver-backed job queue with middleware, retries, and configurable backoff.
  * Call `Queue.Provider.create()` with a driver, register it, then use `Queue.create()` to define queues.
  */
 declare const Queue: {
-    drivers: {
-        db: typeof DbQueueDriver;
-    };
     Provider: {
         create: typeof createService;
         register: (name: Queue.Provider.Key, item: Queue.QueueService) => void;
-        list: () => "default"[];
     };
     provider: typeof provider;
-    list: () => string[];
-    get: <MessageBody extends Record<string, any>, Result = any>(name: string) => Queue.Queue<MessageBody, Result> | undefined;
-    create: <MessageBody extends Record<string, any>, Result = any>(options: Queue.QueueOptions<MessageBody, Result>) => Queue.Queue<MessageBody, Result>;
-    startProcessing: () => void;
-    stopProcessing: () => void;
+    work: (options: Queue.WorkOptions) => Promise<void> & {
+        abort(reason?: string | undefined): void;
+    };
+    stopAllWork: () => Promise<void>;
+    processMessage: <MessageBody extends Record<string, any> = Record<string, any>>(queueMessage: Queue.Message<MessageBody>) => Promise<unknown>;
+    create: <MessageBody extends Record<string, any> = {}, Result = any>(config: Queue.Config<MessageBody, Result>) => Queue.QueueHandle<MessageBody, Result>;
+    drivers: {
+        db: typeof DbQueueDriver;
+        local: typeof localQueueDriver;
+    };
 };
 
 export { Queue };