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

package/dist/index.d.ts

@@ -1,264 +1,300 @@
 import { Iso } from 'iso-fns2';
 import { Log } from '@maestro-js/log';
 
-interface QueueMessage<MessageBody extends Record<string, any> = Record<string, any>> {
-    id: string;
+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;
     queue: string;
+    scheduledDate: Iso.Instant;
+    enqueuedDate: Iso.Instant;
+    startedDate: Iso.Instant | null;
     body: MessageBody;
-    attempts: number;
+    trace: DehydratedTrace | null;
+    status: 'waiting' | 'processing' | 'success' | 'error' | 'stuck';
+    result: Result;
+    recovered: number;
+    runningTimeSeconds: number | null;
+    uniqueKey: number | null;
+    priority: number | null;
 }
+type QueueWorkFunction<MessageBody extends Record<string, any> = Record<string, any>> = (args: {
+    body: MessageBody;
+    id: number;
+    trace: DehydratedTrace | null;
+    scheduledDate: Iso.Instant;
+}) => any;
 interface QueueDriver {
-    size(): Promise<number>;
-    push(message: {
-        queue: string;
-        body: Record<string, any>;
-        scheduledDate: Iso.Instant;
-    }): Promise<string>;
-    bulk(messages: {
-        queue: string;
-        body: Record<string, any>;
+    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;
         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;
+        body: MessageBody;
     }): 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: string;
+    messageId: number;
 } | {
     event: 'messageProcessed';
     queue: string;
+    driver: QueueDriver;
     body: Record<string, any>;
-    messageId: string;
-    result: any;
+    result: unknown;
+    messageId: number;
 } | {
     event: 'messageFailed';
     queue: string;
+    driver: QueueDriver;
     body: Record<string, any>;
-    messageId: string;
     error: unknown;
+    messageId: number;
 } | {
-    event: 'messageReleased';
+    event: 'queueStarted';
     queue: string;
-    body: Record<string, any>;
-    messageId: string;
-    error: unknown;
-    attempt: number;
+    driver: QueueDriver;
+} | {
+    event: 'queueStopped';
+    queue: string;
+    driver: QueueDriver;
 };
-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;
+
+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 KeysWithFallback = keyof Queue.Provider.Keys extends never ? {
-    default: unknown;
-} : Queue.Provider.Keys;
+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;
+};
 declare function provider(key: Queue.Provider.Key): {
-    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>;
+    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;
 };
 /**
- * Driver-backed job queue with middleware, retries, and configurable backoff.
+ * Job queue for deferring work beyond the current request.
  *
- * 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.
+ * 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.
  *
  * @example
  * ```ts
+ * // Create and register a queue service
  * Queue.Provider.register('default', Queue.Provider.create({
- *   driver: myDriver,
+ *   driver: Queue.drivers.db({ db: Db.provider('default'), databaseTable: 'jobs' }),
  *   logger: Log.provider('default')
  * }))
  *
- * const emailQueue = Queue.create({
- *   name: 'send-emails',
- *   handle: async (body) => sendEmail(body.to, body.subject),
- *   tries: 3,
- *   backoffSeconds: [30, 60, 120]
+ * // Create a queue with a work function
+ * const orderQueue = Queue.create({
+ *   name: 'fulfill-orders',
+ *   workFn: async (body) => {
+ *     await fulfillOrder(body.orderId)
+ *     return { fulfilled: true }
+ *   }
  * })
  *
- * await emailQueue.dispatch({ to: 'alice@example.com', subject: 'Welcome' })
- * await Queue.work({ stopWhenEmpty: true })
+ * // Enqueue a message and start processing
+ * await orderQueue.addMessage({ orderId: 'ord_123' }, { scheduledDate: null })
+ * orderQueue.startProcessing()
  * ```
  */
 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 Config<MessageBody extends Record<string, any> = Record<string, any>, Result = any> {
+    interface QueueOptions<T extends Record<string, any> = Record<string, any>, Result = any> {
         name: string;
-        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;
+        workFn(body: T): Promise<Result>;
+        logger?: Log.LogFunctions<[QueueLogMessage]>;
         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 returned by {@link QueueService.create}.
+     * A named queue instance with methods for adding messages and controlling processing.
      *
-     * 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}.
+     * 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.
      *
      * @example
      * ```ts
-     * const emailQueue = Queue.create({
+     * const queue = Queue.create({
      *   name: 'send-emails',
-     *   handle: async (body) => sendEmail(body.to, body.subject),
-     *   tries: 3,
-     *   backoffSeconds: [30, 60, 120]
+     *   workFn: async (body) => sendEmail(body.to, body.subject),
+     *   concurrency: 3
      * })
-     *
-     * await emailQueue.dispatch({ to: 'alice@example.com', subject: 'Welcome' })
-     * await emailQueue.dispatchWithDelay(body, scheduledDate)
-     * await emailQueue.bulk([{ body: msg1 }, { body: msg2 }])
+     * await queue.addMessage({ to: 'alice@example.com', subject: 'Welcome' }, { scheduledDate: null })
+     * queue.startProcessing()
      * ```
      */
-    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: {
+    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;
             body: MessageBody;
-            scheduledDate?: Iso.Instant;
-        }[]): Promise<void>;
+        }): Promise<void>;
+    };
+    namespace Provider {
+        interface QueueServiceConfig {
+            driver: Driver;
+            logger: Log.Logger<[QueueLogMessage]>;
+            tracing?: QueueTracing;
+        }
+        type Key = keyof Keys;
+        interface Keys {
+            default: unknown;
+        }
     }
     /**
      * Container that manages multiple named queues sharing the same driver and logger.
      *
-     * 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.
+     * 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.
      *
      * @example
      * ```ts
-     * 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 })
+     * const orders = Queue.create({ name: 'orders', workFn: processOrder })
+     * const emails = Queue.create({ name: 'emails', workFn: sendEmail, concurrency: 5 })
+     * Queue.startProcessing() // starts both queues
      * ```
      */
     interface QueueService {
-        /** 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 {
-        }
+        /** 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;
     }
 }
 /**
- * Driver-backed job queue with middleware, retries, and configurable backoff.
+ * Job queue for deferring work beyond the current request.
  * 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;
-    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;
-    };
+    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;
 };
 
 export { Queue };