@zudojs/queue 1.1.0 → 1.3.0

package/README.md

@@ -2,6 +2,12 @@
 
 Background job and asynchronous task infrastructure with in-memory and adapter-based queue implementations.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-queue](https://zudojs.oyinlola.site/docs/packages-queue) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-queue.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -43,9 +49,6 @@ await queue.add(
 // The queue polls in the background; give it a tick before reading counts.
 await new Promise((resolve) => setTimeout(resolve, 100));
 
-// The queue polls in the background; give it a tick before reading counts.
-await new Promise((resolve) => setTimeout(resolve, 100));
-
 // Jobs that exhaust their attempts land here rather than vanishing.
 console.log((await queue.getDeadLetterJobs()).length);
 console.log(await queue.getStats());
@@ -66,8 +69,64 @@ await queue.close();
 - Draining shutdown with a bounded `closeTimeout`, then cooperative abort
 - Stalled-job reclaim (`stalledAfter`, `maxStalledCount`) for consumers that die
   mid-job
-- Bounded retention of settled jobs, so a long-lived queue does not grow without
-  limit
+- Bounded retention of settled jobs and of dead-lettered jobs, so a long-lived
+  queue does not grow without limit
+
+## Workers, timeouts and context
+
+**One consumer at a time.** `queue.process()` registers a processor and, by
+default, the queue's own poller runs jobs. Creating a `Worker` for the queue
+turns that poller off as a consumer (`queue.setAutoProcess(false)`), so the
+worker's `middleware`, `timeoutMs` and `concurrency` apply to every job, and
+`worker.stop()` really stops consumption. Pass `autoProcess: false` to keep the
+queue from consuming before any worker exists.
+
+**Timeouts are cooperative.** A timeout aborts `context.signal`; honour it. The
+job's concurrency slot and its retry wait up to `timeoutGraceMs` (5000 ms by
+default) for the processor to settle, so a retry never runs beside the attempt
+it replaces. A processor still running after the grace period is abandoned.
+
+**Carrying context across the queue.** AsyncLocalStorage does not follow a job
+into the poller or worker that runs it. A `QueueContextCarrier` captures a value
+at `add()` into job metadata and restores it around the middleware and the
+processor:
+
+```typescript
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createInMemoryQueue, createQueueName } from "@zudojs/queue";
+import type { QueueContextCarrier } from "@zudojs/queue";
+
+const tenants = new AsyncLocalStorage<{ tenantId: string }>();
+
+const tenantCarrier: QueueContextCarrier<string> = {
+  key: "tenantId",
+  capture: () => tenants.getStore()?.tenantId,
+  restore: (tenantId, run) => tenants.run({ tenantId }, run),
+};
+
+const jobs = createInMemoryQueue<{ id: number }>(createQueueName("reports"), {
+  contextCarriers: [tenantCarrier],
+});
+jobs.process("build", async () => {
+  console.log("building for", tenants.getStore()?.tenantId); // "acme"
+});
+
+await tenants.run({ tenantId: "acme" }, () => jobs.add("build", { id: 1 }));
+await new Promise((resolve) => setTimeout(resolve, 100));
+await jobs.close();
+```
+
+Keep captured values small and serializable (ids, not live objects). With
+`@zudojs/tenancy`, capture the tenant id and restore it with the tenant context
+storage's `run`.
+
+The `zudo:context` metadata key is reserved: it is written only by the queue's
+own carriers and is stripped from any `metadata` passed to `add()`, so an
+enqueuer cannot choose the context its job runs under.
+
+Errors with no caller to receive them (a worker's failing poll, a throwing event
+listener) go to `logger.error` when a logger is configured, and otherwise to
+`process.emitWarning`, never to `console`.
 
 ## Use Cases
 

package/dist/contextCarrier/contextCarrier.core.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Context capture at `add()` and restoration around processing.
+ *
+ * @module contextCarrier/contextCarrier.core
+ */
+import type { Job } from "../job/job.type.js";
+import type { QueueContextCarrier } from "./contextCarrier.type.js";
+/**
+ * Job metadata key under which captured context values are stored, as a
+ * `{ [carrier.key]: value }` record.
+ */
+export declare const CONTEXT_METADATA_KEY = "zudo:context";
+/**
+ * Captures every carrier's value into a metadata record.
+ *
+ * {@link CONTEXT_METADATA_KEY} is owned by the queue: a value the caller put
+ * under that key is always discarded, whether or not a carrier captured
+ * anything, so an enqueuer cannot forge the tenant, correlation id or trace
+ * the processor runs under.
+ *
+ * @param carriers - The queue's context carriers.
+ * @param metadata - The job's own metadata, if any.
+ * @returns The metadata with a {@link CONTEXT_METADATA_KEY} entry added, or
+ *   without one when no carrier captured anything.
+ */
+export declare function captureContext(carriers: readonly QueueContextCarrier[] | undefined, metadata: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Runs `fn` inside every context the job carries, first carrier outermost.
+ *
+ * @param carriers - The queue's context carriers.
+ * @param job - The job about to run.
+ * @param fn - The work to run inside the restored context.
+ * @returns Whatever `fn` resolves to.
+ */
+export declare function runWithContext<T>(carriers: readonly QueueContextCarrier[] | undefined, job: Job<unknown>, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=contextCarrier.core.d.ts.map

package/dist/contextCarrier/contextCarrier.core.js

@@ -0,0 +1,80 @@
+/**
+ * Context capture at `add()` and restoration around processing.
+ *
+ * @module contextCarrier/contextCarrier.core
+ */
+/**
+ * Job metadata key under which captured context values are stored, as a
+ * `{ [carrier.key]: value }` record.
+ */
+export const CONTEXT_METADATA_KEY = "zudo:context";
+/**
+ * Strips the reserved context key from caller-supplied metadata.
+ *
+ * The key is owned by the queue on every path: whatever the enqueuer put
+ * there is dropped, so `add()` metadata can never supply a context record of
+ * its own. Returns the input untouched when there is nothing to strip, so the
+ * common case still allocates nothing.
+ */
+function withoutStoredContext(metadata) {
+    if (!metadata || !Object.hasOwn(metadata, CONTEXT_METADATA_KEY)) {
+        return metadata;
+    }
+    const { [CONTEXT_METADATA_KEY]: _discarded, ...rest } = metadata;
+    return rest;
+}
+/**
+ * Captures every carrier's value into a metadata record.
+ *
+ * {@link CONTEXT_METADATA_KEY} is owned by the queue: a value the caller put
+ * under that key is always discarded, whether or not a carrier captured
+ * anything, so an enqueuer cannot forge the tenant, correlation id or trace
+ * the processor runs under.
+ *
+ * @param carriers - The queue's context carriers.
+ * @param metadata - The job's own metadata, if any.
+ * @returns The metadata with a {@link CONTEXT_METADATA_KEY} entry added, or
+ *   without one when no carrier captured anything.
+ */
+export function captureContext(carriers, metadata) {
+    if (!carriers || carriers.length === 0)
+        return withoutStoredContext(metadata);
+    const captured = {};
+    let any = false;
+    for (const carrier of carriers) {
+        const value = carrier.capture();
+        if (value === undefined)
+            continue;
+        captured[carrier.key] = value;
+        any = true;
+    }
+    if (!any)
+        return withoutStoredContext(metadata);
+    return { ...metadata, [CONTEXT_METADATA_KEY]: Object.freeze(captured) };
+}
+/**
+ * Runs `fn` inside every context the job carries, first carrier outermost.
+ *
+ * @param carriers - The queue's context carriers.
+ * @param job - The job about to run.
+ * @param fn - The work to run inside the restored context.
+ * @returns Whatever `fn` resolves to.
+ */
+export function runWithContext(carriers, job, fn) {
+    const raw = job.metadata?.[CONTEXT_METADATA_KEY];
+    if (!carriers || carriers.length === 0)
+        return fn();
+    if (typeof raw !== "object" || raw === null)
+        return fn();
+    const stored = raw;
+    let run = fn;
+    for (let i = carriers.length - 1; i >= 0; i--) {
+        const carrier = carriers[i];
+        if (!Object.hasOwn(stored, carrier.key))
+            continue;
+        const inner = run;
+        run = () => carrier.restore(stored[carrier.key], inner);
+    }
+    return run();
+}
+//# sourceMappingURL=contextCarrier.core.js.map

package/dist/contextCarrier/contextCarrier.type.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Context carrier contract.
+ *
+ * @module contextCarrier/contextCarrier.type
+ */
+/**
+ * Captures one piece of ambient context when a job is added and restores it
+ * while the job runs.
+ *
+ * AsyncLocalStorage does not follow a job from the request that enqueued it
+ * into the poller or worker that runs it, so without a carrier every job runs
+ * with no tenant, no correlation id and no trace. Keep the captured value
+ * small and serializable (an id, not a live object): a broker-backed queue
+ * has to store it with the job.
+ *
+ * @example
+ * ```typescript
+ * const tenantCarrier: QueueContextCarrier<string> = {
+ *   key: "tenantId",
+ *   capture: () => tenantStorage.get()?.tenant?.id,
+ *   restore: (tenantId, run) =>
+ *     tenantStorage.run(contextFor(tenantId), run),
+ * };
+ * createInMemoryQueue("emails", { contextCarriers: [tenantCarrier] });
+ * ```
+ */
+export interface QueueContextCarrier<TValue = unknown> {
+    /** Unique name under which the value is stored with the job. */
+    readonly key: string;
+    /**
+     * Reads the value from the caller's context at `add()`. Returning
+     * `undefined` stores nothing.
+     */
+    capture(): TValue | undefined;
+    /**
+     * Runs `run` inside the restored context. Called only for jobs that
+     * carry a value for this carrier's `key`.
+     */
+    restore<T>(value: TValue, run: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=contextCarrier.type.d.ts.map

package/dist/contextCarrier/contextCarrier.type.js

@@ -0,0 +1,7 @@
+/**
+ * Context carrier contract.
+ *
+ * @module contextCarrier/contextCarrier.type
+ */
+export {};
+//# sourceMappingURL=contextCarrier.type.js.map

package/dist/contextCarrier/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/queue/contextCarrier
+ *
+ * Carries ambient execution context (tenant, correlation id, trace ids)
+ * across the queue boundary: captured into job metadata at `add()` and
+ * restored around the processor, so a background job runs in the context of
+ * the request that enqueued it.
+ */
+export type { QueueContextCarrier } from "./contextCarrier.type.js";
+export { CONTEXT_METADATA_KEY, captureContext, runWithContext, } from "./contextCarrier.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/contextCarrier/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/queue/contextCarrier
+ *
+ * Carries ambient execution context (tenant, correlation id, trace ids)
+ * across the queue boundary: captured into job metadata at `add()` and
+ * restored around the processor, so a background job runs in the context of
+ * the request that enqueued it.
+ */
+export { CONTEXT_METADATA_KEY, captureContext, runWithContext, } from "./contextCarrier.core.js";
+//# sourceMappingURL=index.js.map

package/dist/deadLetter/deadLetter.core.d.ts

@@ -1,9 +1,34 @@
 import type { Job } from "../job/job.type.js";
 import type { DeadLetterStore } from "./deadLetter.type.js";
+/**
+ * Dead-lettered jobs retained by the in-memory store when no cap is given.
+ *
+ * Mirrors the queue's own `DEFAULT_RETAINED_JOBS`: the dead letter store
+ * keeps a full copy of every failed job — payload, metadata and error — so an
+ * unbounded one grows for the life of the process at whatever the failure
+ * rate happens to be.
+ */
+export declare const DEFAULT_DEAD_LETTER_JOBS = 1000;
+/**
+ * Options for {@link createInMemoryDeadLetterStore}.
+ */
+export interface InMemoryDeadLetterStoreOptions {
+    /**
+     * Maximum number of dead-lettered jobs retained before the oldest are
+     * evicted. Defaults to {@link DEFAULT_DEAD_LETTER_JOBS}. Pass
+     * `Number.POSITIVE_INFINITY` for the previous unbounded behaviour.
+     */
+    readonly maxEntries?: number;
+}
 /**
  * Creates an in-memory dead letter store.
+ *
+ * Retention is bounded: past `maxEntries` the oldest entry is evicted, so a
+ * long-lived queue with a steady failure rate does not grow without limit.
+ *
+ * @param options - Retention options.
  */
-export declare function createInMemoryDeadLetterStore<TData = unknown>(): DeadLetterStore<TData>;
+export declare function createInMemoryDeadLetterStore<TData = unknown>(options?: InMemoryDeadLetterStoreOptions): DeadLetterStore<TData>;
 /**
  * Moves a failed job to the dead letter store.
  */

package/dist/deadLetter/deadLetter.core.js

@@ -1,12 +1,38 @@
 import { toQueueError } from "@zudojs/errors";
+/**
+ * Dead-lettered jobs retained by the in-memory store when no cap is given.
+ *
+ * Mirrors the queue's own `DEFAULT_RETAINED_JOBS`: the dead letter store
+ * keeps a full copy of every failed job — payload, metadata and error — so an
+ * unbounded one grows for the life of the process at whatever the failure
+ * rate happens to be.
+ */
+export const DEFAULT_DEAD_LETTER_JOBS = 1_000;
 /**
  * Creates an in-memory dead letter store.
+ *
+ * Retention is bounded: past `maxEntries` the oldest entry is evicted, so a
+ * long-lived queue with a steady failure rate does not grow without limit.
+ *
+ * @param options - Retention options.
  */
-export function createInMemoryDeadLetterStore() {
+export function createInMemoryDeadLetterStore(options) {
     const store = new Map();
+    const configured = options?.maxEntries ?? DEFAULT_DEAD_LETTER_JOBS;
+    const maxEntries = configured > 0 ? configured : DEFAULT_DEAD_LETTER_JOBS;
     return {
         async add(deadLetterJob) {
+            // Re-inserting an existing id must not count as a new entry, so
+            // delete first: a Map keeps its original insertion order otherwise,
+            // which would also evict the wrong entry.
+            store.delete(deadLetterJob.job.id);
             store.set(deadLetterJob.job.id, deadLetterJob);
+            while (store.size > maxEntries) {
+                const oldest = store.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                store.delete(oldest);
+            }
         },
         async get(jobId) {
             return store.get(jobId) ?? null;

package/dist/deadLetter/index.d.ts

@@ -4,6 +4,7 @@
  * Provides storage and management for jobs that have
  * exceeded their retry attempts.
  */
-export { createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
+export { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
+export type { InMemoryDeadLetterStoreOptions } from "./deadLetter.core.js";
 export type { DeadLetterJob, DeadLetterStore } from "./deadLetter.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/deadLetter/index.js

@@ -4,5 +4,5 @@
  * Provides storage and management for jobs that have
  * exceeded their retry attempts.
  */
-export { createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
+export { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
 //# sourceMappingURL=index.js.map

package/dist/inMemoryQueue/inMemoryQueue.core.d.ts

@@ -4,6 +4,7 @@ import type { Queue, QueueOptions, QueueStats } from "../queue/queue.type.js";
 import type { Processor } from "../processor/processor.type.js";
 import type { JobOptions } from "../jobOptions/jobOptions.type.js";
 import type { QueueMiddleware } from "../middleware/middleware.type.js";
+import type { QueueEventEmitter } from "../queueEmitter/queueEmitter.type.js";
 import type { DeadLetterJob } from "../deadLetter/deadLetter.type.js";
 /**
  * In-memory queue implementation.
@@ -20,6 +21,8 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     private readonly middleware;
     private paused;
     private disposed;
+    /** Whether the internal poller claims jobs; see `setAutoProcess`. */
+    private autoProcess;
     private activeCount;
     private pollTimer;
     private readonly scheduledTimers;
@@ -30,11 +33,32 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     private readonly stalledCounts;
     private readonly deduplicationIndex;
     private readonly deadLetterStore;
+    /**
+     * Whether this queue created its own dead letter store. A store handed in
+     * by the caller outlives the queue and is theirs to clear.
+     */
+    private readonly ownsDeadLetterStore;
     private readonly emitter;
     private readonly counters;
     private emptySince;
     private backoffMs;
     constructor(name: QueueName, options?: QueueOptions);
+    /**
+     * Turns the internal poller on or off as a consumer.
+     *
+     * While off, the poller still promotes scheduled jobs and reclaims stalled
+     * ones, but claims nothing: an external `Worker` is the only consumer, so
+     * stopping it really stops consumption and its middleware, timeout and
+     * concurrency apply to every job.
+     */
+    setAutoProcess(enabled: boolean): void;
+    /**
+     * The emitter this queue publishes lifecycle events on.
+     *
+     * A no-op emitter when the queue was created without one, so a worker can
+     * report its lifecycle unconditionally.
+     */
+    get events(): QueueEventEmitter;
     add(jobName: string, data: TData, options?: JobOptions): Promise<Job<TData>>;
     process(name: string, processor: Processor<TData>): void;
     getJob(jobId: JobId): Promise<Job<TData> | null>;

package/dist/inMemoryQueue/inMemoryQueue.core.js

@@ -4,9 +4,10 @@ import { assertProcessor } from "../processor/processor.type.js";
 import { createJob, updateJobState } from "../job/job.core.js";
 import { JobState as JobStateEnum, createJobName, } from "../jobTypes/jobTypes.type.js";
 import { JsonSerializer } from "../serializer/serializer.core.js";
-import { createInMemoryDeadLetterStore } from "../deadLetter/deadLetter.core.js";
-import { createNoopQueueEventEmitter } from "../queueEmitter/queueEmitter.core.js";
+import { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, } from "../deadLetter/deadLetter.core.js";
+import { InMemoryQueueEventEmitter, createNoopQueueEventEmitter, } from "../queueEmitter/queueEmitter.core.js";
 import { processJob } from "./inMemoryQueue.processing.js";
+import { captureContext } from "../contextCarrier/contextCarrier.core.js";
 import { scheduleJob, promoteDueScheduledJobs, } from "./inMemoryQueue.scheduling.js";
 /** Terminal states a job never leaves. */
 const TERMINAL_STATES = new Set([
@@ -34,6 +35,8 @@ export class InMemoryQueue {
     middleware;
     paused = false;
     disposed = false;
+    /** Whether the internal poller claims jobs; see `setAutoProcess`. */
+    autoProcess;
     activeCount = 0;
     pollTimer = null;
     scheduledTimers = new Map();
@@ -44,6 +47,11 @@ export class InMemoryQueue {
     stalledCounts = new Map();
     deduplicationIndex = new Map();
     deadLetterStore;
+    /**
+     * Whether this queue created its own dead letter store. A store handed in
+     * by the caller outlives the queue and is theirs to clear.
+     */
+    ownsDeadLetterStore;
     emitter;
     counters = {
         processedCount: 0,
@@ -60,8 +68,40 @@ export class InMemoryQueue {
         this.serializer = this.options.serializer ?? JsonSerializer;
         this.middleware = this.options.middleware ?? [];
         this.emitter = options?.eventEmitter ?? createNoopQueueEventEmitter();
+        // A supplied emitter is built before the queue exists, so it cannot have
+        // been given the queue's logger. Hand it over, so a throwing listener is
+        // reported through structured logging rather than `process.emitWarning`.
+        if (this.options.logger &&
+            this.emitter instanceof InMemoryQueueEventEmitter) {
+            this.emitter.setLogger(this.options.logger);
+        }
+        this.ownsDeadLetterStore = this.options.deadLetterStore === undefined;
         this.deadLetterStore =
-            this.options.deadLetterStore ?? createInMemoryDeadLetterStore();
+            this.options.deadLetterStore ??
+                createInMemoryDeadLetterStore({
+                    maxEntries: DEFAULT_DEAD_LETTER_JOBS,
+                });
+        this.autoProcess = this.options.autoProcess ?? true;
+    }
+    /**
+     * Turns the internal poller on or off as a consumer.
+     *
+     * While off, the poller still promotes scheduled jobs and reclaims stalled
+     * ones, but claims nothing: an external `Worker` is the only consumer, so
+     * stopping it really stops consumption and its middleware, timeout and
+     * concurrency apply to every job.
+     */
+    setAutoProcess(enabled) {
+        this.autoProcess = enabled;
+    }
+    /**
+     * The emitter this queue publishes lifecycle events on.
+     *
+     * A no-op emitter when the queue was created without one, so a worker can
+     * report its lifecycle unconditionally.
+     */
+    get events() {
+        return this.emitter;
     }
     async add(jobName, data, options) {
         if (this.disposed)
@@ -74,7 +114,9 @@ export class InMemoryQueue {
                 queueName: this.name,
             });
         }
-        const mergedOptions = { ...this.options.defaultJobOptions, ...options };
+        const merged = { ...this.options.defaultJobOptions, ...options };
+        const metadata = captureContext(this.options.contextCarriers, merged.metadata);
+        const mergedOptions = metadata === merged.metadata ? merged : { ...merged, metadata };
         if (mergedOptions.deduplicationKey) {
             const existing = this.deduplicationIndex.get(mergedOptions.deduplicationKey);
             if (existing && this.jobs.has(existing)) {
@@ -260,6 +302,11 @@ export class InMemoryQueue {
         this.settledOrder.length = 0;
         this.stalledCounts.clear();
         this.inFlight.clear();
+        // A dead letter store the queue created dies with it; one handed in by
+        // the caller is theirs and is left alone.
+        if (this.ownsDeadLetterStore) {
+            await this.deadLetterStore.clear();
+        }
         this.activeCount = 0;
         this.paused = false;
         this.emptySince = 0;
@@ -383,17 +430,23 @@ export class InMemoryQueue {
         }
         const abortController = new AbortController();
         // A consumer's own signal (a worker draining, say) must reach the
-        // job it dispatched.
-        if (options?.signal) {
-            if (options.signal.aborted) {
-                abortController.abort(options.signal.reason);
+        // job it dispatched. The forwarder is held so it can be removed once
+        // the job settles: a worker uses one long-lived signal for every job
+        // it dispatches, so a listener left behind accumulates for the life
+        // of the worker and pins that job's controller with it.
+        const consumerSignal = options?.signal;
+        let forwardAbort;
+        if (consumerSignal) {
+            if (consumerSignal.aborted) {
+                abortController.abort(consumerSignal.reason);
             }
             else {
-                options.signal.addEventListener("abort", () => {
+                forwardAbort = () => {
                     if (!abortController.signal.aborted) {
-                        abortController.abort(options.signal?.reason);
+                        abortController.abort(consumerSignal.reason);
                     }
-                }, { once: true });
+                };
+                consumerSignal.addEventListener("abort", forwardAbort, { once: true });
             }
         }
         this.inFlight.set(job.id, abortController);
@@ -402,6 +455,12 @@ export class InMemoryQueue {
             await processJob(job, processor, {
                 timeoutMs: job.timeoutMs ?? options?.timeoutMs,
                 abortController,
+                ...(this.options.timeoutGraceMs !== undefined
+                    ? { timeoutGraceMs: this.options.timeoutGraceMs }
+                    : {}),
+                ...(this.options.contextCarriers
+                    ? { contextCarriers: this.options.contextCarriers }
+                    : {}),
             }, {
                 jobs: this.jobs,
                 emitter: this.emitter,
@@ -413,6 +472,9 @@ export class InMemoryQueue {
                 registerRetryTimer: (jobId, timer) => {
                     this.retryTimers.set(jobId, timer);
                 },
+                deregisterRetryTimer: (jobId) => {
+                    this.retryTimers.delete(jobId);
+                },
                 onSettled: (settled) => this.recordSettled(settled),
                 isDisposed: () => this.disposed,
                 ...(this.options.logger ? { logger: this.options.logger } : {}),
@@ -427,7 +489,9 @@ export class InMemoryQueue {
         finally {
             this.activeCount--;
             this.inFlight.delete(job.id);
-            this.retryTimers.delete(job.id);
+            if (forwardAbort && consumerSignal) {
+                consumerSignal.removeEventListener("abort", forwardAbort);
+            }
         }
     }
     async processTick() {
@@ -435,7 +499,7 @@ export class InMemoryQueue {
             return;
         const concurrency = Math.max(1, this.options.concurrency ?? 1);
         let processed = 0;
-        while (this.activeCount < concurrency) {
+        while (this.autoProcess && this.activeCount < concurrency) {
             // `claimNextJob` only returns jobs that have a registered
             // processor and moves them out of `waiting`, so this loop always
             // terminates. Returning an unrunnable job here is what previously

package/dist/inMemoryQueue/inMemoryQueue.processing.d.ts

@@ -5,6 +5,7 @@ import type { QueueMiddleware } from "../middleware/middleware.type.js";
 import type { QueueEventEmitter } from "../queueEmitter/queueEmitter.type.js";
 import type { DeadLetterStore } from "../deadLetter/deadLetter.type.js";
 import type { QueueLogger } from "../queue/queue.type.js";
+import type { QueueContextCarrier } from "../contextCarrier/contextCarrier.type.js";
 /**
  * Mutable throughput counters.
  *
@@ -32,6 +33,8 @@ export interface ProcessJobDependencies<TData> {
      * queue can clear it on close instead of leaking it.
      */
     readonly registerRetryTimer: (jobId: JobId, timer: ReturnType<typeof setTimeout>) => void;
+    /** Forgets a retry timer once it has fired. */
+    readonly deregisterRetryTimer?: (jobId: JobId) => void;
     /** Invoked whenever a job reaches a terminal state. */
     readonly onSettled?: (job: Job<TData>) => void;
     /** Whether the owning queue has been disposed. */
@@ -52,6 +55,10 @@ export interface ProcessJobDependencies<TData> {
 export declare function processJob<TData>(job: Job<TData>, processor: Processor<TData>, options: {
     timeoutMs?: number;
     abortController?: AbortController;
+    /** See `QueueOptions.timeoutGraceMs`. */
+    timeoutGraceMs?: number;
+    /** See `QueueOptions.contextCarriers`. */
+    contextCarriers?: readonly QueueContextCarrier[];
 }, deps: ProcessJobDependencies<TData>): Promise<void>;
 /**
  * Handle job failure with retry logic.

package/dist/inMemoryQueue/inMemoryQueue.processing.js

@@ -5,6 +5,8 @@ import { createJobContext } from "../jobContext/jobContext.core.js";
 import { createMiddlewareChain, createTimeoutMiddleware, } from "../middleware/middleware.core.js";
 import { calculateRetryDelay, resolveBackoff, shouldRetry, } from "../retryPolicy/retryPolicy.core.js";
 import { moveToDeadLetter } from "../deadLetter/deadLetter.core.js";
+import { runWithContext } from "../contextCarrier/contextCarrier.core.js";
+import { DEFAULT_TIMEOUT_GRACE_MS, settleWithin, } from "./inMemoryQueue.settle.js";
 import { JobMaxAttemptsError } from "@zudojs/errors";
 /**
  * Narrows a processor's return value to a `JobResult`.
@@ -46,10 +48,15 @@ export async function processJob(job, processor, options, deps) {
         },
     });
     const timeoutMs = options.timeoutMs ?? DEFAULT_JOB_OPTIONS.timeout ?? 30_000;
+    // Whether this job's own timeout is what aborted it. An abort from
+    // anywhere else — a draining worker, `close()`, a consumer's signal — is a
+    // cancellation, and is reported as one.
+    let timedOut = false;
     const timeoutMiddleware = createTimeoutMiddleware(timeoutMs, () => {
         // Let a cooperative processor observe the timeout and stop working
         // instead of running on with its result discarded.
         if (!abortController.signal.aborted) {
+            timedOut = true;
             abortController.abort(new Error(`Job "${updatedJob.id}" timed out after ${timeoutMs}ms.`));
         }
     });
@@ -57,14 +64,18 @@ export async function processJob(job, processor, options, deps) {
         timeoutMiddleware,
         ...deps.middleware,
     ]);
+    // The processor promise itself, so a failure (a timeout above all) can
+    // wait for it to stop before the slot and the retry are released.
+    let running;
     try {
-        const result = await middlewareChain({
+        const result = await runWithContext(options.contextCarriers, updatedJob, () => middlewareChain({
             job: updatedJob,
             context,
             next: async () => {
-                return processor(updatedJob, context);
+                running = Promise.resolve(processor(updatedJob, context));
+                return running;
             },
-        });
+        }));
         if (isJobResult(result) && !result.success) {
             await handleJobFailure(updatedJob, result.error ?? "Job failed", deps);
         }
@@ -85,6 +96,10 @@ export async function processJob(job, processor, options, deps) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        await settleWithin(running, options.timeoutGraceMs ?? DEFAULT_TIMEOUT_GRACE_MS);
+        if (abortController.signal.aborted && !timedOut) {
+            emitter.emit("job:cancelled", { job: updatedJob });
+        }
         await handleJobFailure(updatedJob, errorMessage, deps);
     }
     finally {
@@ -122,6 +137,7 @@ export async function handleJobFailure(job, errorMessage, deps) {
         const backoff = resolveBackoff(incrementedJob.backoff);
         const delay = calculateRetryDelay(incrementedJob.attempt, backoff);
         const timer = setTimeout(() => {
+            deps.deregisterRetryTimer?.(job.id);
             if (deps.isDisposed()) {
                 return;
             }

package/dist/inMemoryQueue/inMemoryQueue.settle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Waiting for a timed-out processor to actually stop.
+ *
+ * The timeout middleware rejects as soon as the timer fires, but the
+ * processor promise it raced keeps running until it notices the aborted
+ * signal. Freeing the concurrency slot and scheduling the retry at that
+ * moment let the retry run beside the original attempt.
+ *
+ * @module inMemoryQueue/inMemoryQueue.settle
+ */
+/** Default grace for a timed-out processor to settle, in milliseconds. */
+export declare const DEFAULT_TIMEOUT_GRACE_MS = 5000;
+/**
+ * Resolves once `pending` settles or `graceMs` elapses, whichever is first.
+ *
+ * Never rejects: the processor's own outcome has already been superseded by
+ * the failure being handled.
+ *
+ * @param pending - The processor promise, if the processor was started.
+ * @param graceMs - The longest to wait.
+ * @returns True when the processor settled within the grace period.
+ */
+export declare function settleWithin(pending: Promise<unknown> | undefined, graceMs: number): Promise<boolean>;
+//# sourceMappingURL=inMemoryQueue.settle.d.ts.map

package/dist/inMemoryQueue/inMemoryQueue.settle.js

@@ -0,0 +1,39 @@
+/**
+ * Waiting for a timed-out processor to actually stop.
+ *
+ * The timeout middleware rejects as soon as the timer fires, but the
+ * processor promise it raced keeps running until it notices the aborted
+ * signal. Freeing the concurrency slot and scheduling the retry at that
+ * moment let the retry run beside the original attempt.
+ *
+ * @module inMemoryQueue/inMemoryQueue.settle
+ */
+/** Default grace for a timed-out processor to settle, in milliseconds. */
+export const DEFAULT_TIMEOUT_GRACE_MS = 5_000;
+/**
+ * Resolves once `pending` settles or `graceMs` elapses, whichever is first.
+ *
+ * Never rejects: the processor's own outcome has already been superseded by
+ * the failure being handled.
+ *
+ * @param pending - The processor promise, if the processor was started.
+ * @param graceMs - The longest to wait.
+ * @returns True when the processor settled within the grace period.
+ */
+export async function settleWithin(pending, graceMs) {
+    if (pending === undefined)
+        return true;
+    let timer;
+    const settled = pending.then(() => true, () => true);
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), Math.max(0, graceMs));
+    });
+    try {
+        return await Promise.race([settled, expired]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=inMemoryQueue.settle.js.map

package/dist/index.d.ts

@@ -23,4 +23,5 @@ export * from "./middleware/index.js";
 export * from "./worker/index.js";
 export * from "./inMemoryQueue/index.js";
 export * from "./deadLetter/index.js";
+export * from "./contextCarrier/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -39,4 +39,6 @@ export * from "./worker/index.js";
 export * from "./inMemoryQueue/index.js";
 // Dead letter
 export * from "./deadLetter/index.js";
+// Context propagation across the queue boundary
+export * from "./contextCarrier/index.js";
 //# sourceMappingURL=index.js.map

package/dist/queue/queue.report.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Last-resort reporting for failures nobody else can receive.
+ *
+ * A worker's poll failure or a throwing event listener has no caller to
+ * reject. They used to go to `console.error`, bypassing structured logging
+ * and redaction. They now go to the configured logger's `error`, and without
+ * one to `process.emitWarning`, which Node prints once and applications can
+ * intercept with `process.on("warning")`.
+ *
+ * @module queue/queue.report
+ */
+import type { QueueLogger } from "./queue.type.js";
+/**
+ * Report an error that has no caller to receive it.
+ *
+ * @param message - What failed.
+ * @param error - The failure.
+ * @param logger - The configured logger, if any.
+ */
+export declare function reportQueueError(message: string, error: unknown, logger?: QueueLogger): void;
+//# sourceMappingURL=queue.report.d.ts.map

package/dist/queue/queue.report.js

@@ -0,0 +1,26 @@
+/**
+ * Last-resort reporting for failures nobody else can receive.
+ *
+ * A worker's poll failure or a throwing event listener has no caller to
+ * reject. They used to go to `console.error`, bypassing structured logging
+ * and redaction. They now go to the configured logger's `error`, and without
+ * one to `process.emitWarning`, which Node prints once and applications can
+ * intercept with `process.on("warning")`.
+ *
+ * @module queue/queue.report
+ */
+/**
+ * Report an error that has no caller to receive it.
+ *
+ * @param message - What failed.
+ * @param error - The failure.
+ * @param logger - The configured logger, if any.
+ */
+export function reportQueueError(message, error, logger) {
+    if (logger?.error) {
+        logger.error(message, { error });
+        return;
+    }
+    process.emitWarning(error instanceof Error ? error : new Error(String(error)), { type: "ZudoQueueWarning", detail: message });
+}
+//# sourceMappingURL=queue.report.js.map

package/dist/queue/queue.type.d.ts

@@ -5,6 +5,7 @@ import type { Processor } from "../processor/processor.type.js";
 import type { Serializer } from "../serializer/serializer.type.js";
 import type { QueueMiddleware } from "../middleware/middleware.type.js";
 import type { QueueEventEmitter } from "../queueEmitter/queueEmitter.type.js";
+import type { QueueContextCarrier } from "../contextCarrier/contextCarrier.type.js";
 import type { DeadLetterJob, DeadLetterStore } from "../deadLetter/deadLetter.type.js";
 /**
  * Somewhere for a job to write a log line.
@@ -13,6 +14,8 @@ import type { DeadLetterJob, DeadLetterStore } from "../deadLetter/deadLetter.ty
  */
 export interface QueueLogger {
     info(message: string, data?: Record<string, unknown>): void;
+    /** Receives failures that have no caller to reject (poll errors). */
+    error?(message: string, data?: Record<string, unknown>): void;
 }
 /**
  * Options for creating a queue.
@@ -79,6 +82,28 @@ export interface QueueOptions {
      * reclaimed again. Defaults to 3.
      */
     readonly maxStalledCount?: number;
+    /**
+     * Whether the queue's own poller claims and runs jobs. Defaults to
+     * `true`. Creating a `Worker` for the queue turns it off, so the worker —
+     * with its middleware, timeout and concurrency — is the only consumer.
+     */
+    readonly autoProcess?: boolean;
+    /**
+     * After a job times out, how long its concurrency slot and its retry wait
+     * for the processor to actually settle, in milliseconds. Defaults to 5000.
+     *
+     * A timeout aborts `context.signal`; a processor that ignores the signal
+     * keeps running. Without the wait, the retry started beside it and one
+     * job ran several times at once. Past this grace the processor is
+     * abandoned and the job fails anyway, so processors must honour the
+     * signal.
+     */
+    readonly timeoutGraceMs?: number;
+    /**
+     * Context carried from `add()` into the processor (tenant, correlation
+     * id, trace ids). See {@link QueueContextCarrier}.
+     */
+    readonly contextCarriers?: readonly QueueContextCarrier[];
 }
 /**
  * Statistics for a queue.
@@ -113,6 +138,14 @@ export interface QueueStats {
 export interface Queue<TData = unknown> {
     /** Queue name. */
     readonly name: QueueName;
+    /**
+     * The emitter this queue publishes lifecycle events on, when it has one.
+     *
+     * Exposed so a `Worker` can report its own lifecycle
+     * (`worker:started`, `worker:stopped`, `worker:error`) on the same
+     * emitter as the jobs it runs.
+     */
+    readonly events?: QueueEventEmitter;
     /** Add a job to the queue. */
     add(name: string, data: TData, options?: JobOptions): Promise<Job<TData>>;
     /** Process jobs with a processor. */
@@ -171,6 +204,11 @@ export interface Queue<TData = unknown> {
     getDeadLetterJobs(): Promise<readonly DeadLetterJob<TData>[]>;
     /** Close the queue, draining in-flight jobs first. */
     close(): Promise<void>;
+    /**
+     * Turns the queue's own poller on or off as a consumer. `createWorker`
+     * turns it off so a worker is never racing the queue for jobs.
+     */
+    setAutoProcess?(enabled: boolean): void;
 }
 /**
  * Event types emitted by a queue.
@@ -198,6 +236,7 @@ export type QueueEventMap = {
         job: Job;
         attempt: number;
     };
+    /** A running job was aborted from outside — a drain, a close, a cancel. */
     "job:cancelled": {
         job: Job;
     };

package/dist/queueEmitter/queueEmitter.core.d.ts

@@ -1,5 +1,5 @@
 import type { QueueEventEmitter } from "./queueEmitter.type.js";
-import type { QueueEventMap } from "../queue/queue.type.js";
+import type { QueueEventMap, QueueLogger } from "../queue/queue.type.js";
 type EventName = keyof QueueEventMap;
 type Handler<T extends EventName> = (data: QueueEventMap[T]) => void;
 /**
@@ -12,6 +12,12 @@ export interface QueueEventEmitterOptions {
      * the emitting code path.
      */
     readonly onHandlerError?: (error: unknown, event: EventName) => void;
+    /**
+     * Receives a throwing listener's error when no `onHandlerError` is given.
+     * Without one the failure goes to `process.emitWarning`, bypassing
+     * structured logging and redaction.
+     */
+    readonly logger?: QueueLogger;
 }
 /**
  * In-memory queue event emitter.
@@ -24,7 +30,20 @@ export interface QueueEventEmitterOptions {
 export declare class InMemoryQueueEventEmitter implements QueueEventEmitter {
     private readonly handlers;
     private readonly onHandlerError;
+    /** Whether `onHandlerError` was supplied, so `setLogger` leaves it alone. */
+    private readonly hasCustomHandlerError;
+    private logger;
     constructor(options?: QueueEventEmitterOptions);
+    /**
+     * Adopts a logger for the default handler-error report.
+     *
+     * Called by a queue that was configured with a logger, since the emitter is
+     * built before the queue exists and cannot have been given it. A logger or
+     * an `onHandlerError` supplied at construction always wins.
+     *
+     * @param logger - Destination for a throwing listener's error.
+     */
+    setLogger(logger: QueueLogger): void;
     emit<K extends EventName>(event: K, data: QueueEventMap[K]): void;
     on<K extends EventName>(event: K, handler: Handler<K>): () => void;
     /**

package/dist/queueEmitter/queueEmitter.core.js

@@ -1,3 +1,4 @@
+import { reportQueueError } from "../queue/queue.report.js";
 /**
  * In-memory queue event emitter.
  *
@@ -9,15 +10,34 @@
 export class InMemoryQueueEventEmitter {
     handlers = new Map();
     onHandlerError;
+    /** Whether `onHandlerError` was supplied, so `setLogger` leaves it alone. */
+    hasCustomHandlerError;
+    logger;
     constructor(options = {}) {
+        this.hasCustomHandlerError = options.onHandlerError !== undefined;
+        this.logger = options.logger;
         this.onHandlerError =
             options.onHandlerError ??
                 ((error, event) => {
                     queueMicrotask(() => {
-                        console.error(`[@zudojs/queue] Listener for "${event}" threw.`, error);
+                        reportQueueError(`[@zudojs/queue] Listener for "${event}" threw.`, error, this.logger);
                     });
                 });
     }
+    /**
+     * Adopts a logger for the default handler-error report.
+     *
+     * Called by a queue that was configured with a logger, since the emitter is
+     * built before the queue exists and cannot have been given it. A logger or
+     * an `onHandlerError` supplied at construction always wins.
+     *
+     * @param logger - Destination for a throwing listener's error.
+     */
+    setLogger(logger) {
+        if (this.hasCustomHandlerError || this.logger)
+            return;
+        this.logger = logger;
+    }
     emit(event, data) {
         const handlers = this.handlers.get(event);
         if (!handlers) {

package/dist/worker/worker.core.d.ts

@@ -6,6 +6,11 @@ import type { Worker, WorkerOptions } from "./worker.type.js";
  * The worker claims each job before running it, so a job is never picked
  * up twice — by this worker on its next poll, or by another worker on the
  * same queue.
+ *
+ * Creating a worker turns the queue's own poller off as a consumer
+ * (`queue.setAutoProcess(false)`), so the worker — with its middleware,
+ * timeout and concurrency — is the only thing running jobs, and `stop()`
+ * really stops consumption.
  */
 export declare function createWorker<TData>(id: string, queue: Queue<TData>, options?: WorkerOptions): Worker<TData>;
 /**

package/dist/worker/worker.core.js

@@ -1,5 +1,6 @@
 import { JobState as JobStateEnum, WorkerState, } from "../jobTypes/jobTypes.type.js";
 import { WorkerLifecycleError } from "@zudojs/errors";
+import { reportQueueError } from "../queue/queue.report.js";
 /** How long `stop()` waits for in-flight jobs before forcing a stop. */
 const DEFAULT_DRAIN_TIMEOUT_MS = 30_000;
 /**
@@ -8,6 +9,11 @@ const DEFAULT_DRAIN_TIMEOUT_MS = 30_000;
  * The worker claims each job before running it, so a job is never picked
  * up twice — by this worker on its next poll, or by another worker on the
  * same queue.
+ *
+ * Creating a worker turns the queue's own poller off as a consumer
+ * (`queue.setAutoProcess(false)`), so the worker — with its middleware,
+ * timeout and concurrency — is the only thing running jobs, and `stop()`
+ * really stops consumption.
  */
 export function createWorker(id, queue, options) {
     let state = WorkerState.CREATED;
@@ -19,12 +25,30 @@ export function createWorker(id, queue, options) {
     let activeJobs = 0;
     let polling = false;
     let abortController = null;
-    const onError = options?.onError ??
+    queue.setAutoProcess?.(false);
+    /**
+     * Reports the worker's own lifecycle on the queue's emitter.
+     *
+     * `worker:started`, `worker:stopped` and `worker:error` were part of
+     * `QueueEventMap` with nothing emitting them, so a consumer subscribing for
+     * readiness never heard from the worker.
+     */
+    const emitLifecycle = (event) => {
+        queue.events?.emit(event, { workerId: id });
+    };
+    const reportWorkerError = options?.onError ??
         ((error) => {
             queueMicrotask(() => {
-                console.error(`[@zudojs/queue] Worker "${id}" poll failed.`, error);
+                reportQueueError(`[@zudojs/queue] Worker "${id}" poll failed.`, error, options?.logger);
             });
         });
+    const onError = (error) => {
+        queue.events?.emit("worker:error", {
+            workerId: id,
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+        reportWorkerError(error);
+    };
     /**
      * Arms the next poll. At most one timer is ever armed: a delayed poll
      * already pending is left alone, while an immediate poll (capacity just
@@ -150,6 +174,7 @@ export function createWorker(id, queue, options) {
             abortController = new AbortController();
             try {
                 state = WorkerState.RUNNING;
+                emitLifecycle("worker:started");
                 scheduleNextPoll(0);
             }
             catch (error) {
@@ -186,11 +211,17 @@ export function createWorker(id, queue, options) {
             }
             clearPollTimer();
             state = WorkerState.STOPPED;
+            emitLifecycle("worker:stopped");
         },
         async forceStop() {
+            const wasLive = state !== WorkerState.CREATED && state !== WorkerState.STOPPED;
             abortController?.abort();
             clearPollTimer();
             state = WorkerState.STOPPED;
+            // A worker that never started never stopped: reporting it would give a
+            // readiness listener a transition that did not happen.
+            if (wasLive)
+                emitLifecycle("worker:stopped");
         },
         isRunning() {
             return state === WorkerState.RUNNING;

package/dist/worker/worker.type.d.ts

@@ -1,4 +1,4 @@
-import type { Queue } from "../queue/queue.type.js";
+import type { Queue, QueueLogger } from "../queue/queue.type.js";
 import type { QueueMiddleware } from "../middleware/middleware.type.js";
 import type { WorkerState } from "../jobTypes/jobTypes.type.js";
 /**
@@ -25,10 +25,13 @@ export interface WorkerOptions {
     readonly drainTimeout?: number;
     /**
      * Invoked for errors raised outside a job — a failing poll, a job that
-     * threw, or a drain that timed out. Defaults to reporting on the
-     * console. Poll errors are never left as unhandled rejections.
+     * threw, or a drain that timed out. Defaults to `logger.error`, or to
+     * `process.emitWarning` without a logger. Poll errors are never left as
+     * unhandled rejections.
      */
     readonly onError?: (error: unknown) => void;
+    /** Receives errors when no `onError` is given. */
+    readonly logger?: QueueLogger;
 }
 /**
  * Worker lifecycle states.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/queue",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Background job and asynchronous task infrastructure with in-memory and adapter-based queue implementations.",
   "license": "MIT",
   "author": {
@@ -25,9 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/serialization": "1.0.1"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/serialization": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",