@zudojs/queue 1.2.0 → 1.4.0

package/dist/inMemoryQueue/polling/inMemoryQueue.select.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Which job runs next, and whether any job is still owed a run.
+ *
+ * @module inMemoryQueue/polling/inMemoryQueue.select
+ */
+import type { Job } from "../../job/job.type.js";
+/**
+ * When a job became runnable, in epoch milliseconds: its creation, or for a
+ * delayed job the moment its delay elapsed.
+ *
+ * Ordering a due delayed job by `createdAt` let it jump ahead of every job
+ * that had been ready and waiting while it was still delayed.
+ */
+export declare function runnableAt(job: Job<unknown>): number;
+/**
+ * Selects the job that runs next among those that are waiting and due.
+ *
+ * Higher priority first; within a priority, the job that became runnable
+ * first ({@link runnableAt}); among equals, the one added first. The
+ * incumbent is tracked by reference rather than by a sentinel priority, so
+ * negative priorities are selectable like any other.
+ */
+export declare function selectNextJob<TData>(jobs: Iterable<Job<TData>>, now: number, predicate?: (job: Job<TData>) => boolean): Job<TData> | null;
+/** Whether any job a consumer can run is still owed a run. */
+export declare function hasPendingWork<TData>(jobs: Iterable<Job<TData>>, isConsumable: (job: Job<TData>) => boolean): boolean;
+//# sourceMappingURL=inMemoryQueue.select.d.ts.map

package/dist/inMemoryQueue/polling/inMemoryQueue.select.js

@@ -0,0 +1,64 @@
+/**
+ * Which job runs next, and whether any job is still owed a run.
+ *
+ * @module inMemoryQueue/polling/inMemoryQueue.select
+ */
+import { JobState as JobStateEnum } from "../../jobTypes/jobTypes.type.js";
+/** States in which a job still has a run ahead of it. */
+const PENDING_STATES = new Set([
+    JobStateEnum.WAITING,
+    JobStateEnum.SCHEDULED,
+    JobStateEnum.RETRYING,
+    JobStateEnum.ACTIVE,
+]);
+/**
+ * When a job became runnable, in epoch milliseconds: its creation, or for a
+ * delayed job the moment its delay elapsed.
+ *
+ * Ordering a due delayed job by `createdAt` let it jump ahead of every job
+ * that had been ready and waiting while it was still delayed.
+ */
+export function runnableAt(job) {
+    const created = new Date(job.createdAt).getTime();
+    if (!job.scheduledAt)
+        return created;
+    const scheduled = new Date(job.scheduledAt).getTime();
+    return Number.isNaN(scheduled) ? created : Math.max(created, scheduled);
+}
+/**
+ * Selects the job that runs next among those that are waiting and due.
+ *
+ * Higher priority first; within a priority, the job that became runnable
+ * first ({@link runnableAt}); among equals, the one added first. The
+ * incumbent is tracked by reference rather than by a sentinel priority, so
+ * negative priorities are selectable like any other.
+ */
+export function selectNextJob(jobs, now, predicate) {
+    let next = null;
+    let nextAt = 0;
+    for (const job of jobs) {
+        if (job.state !== JobStateEnum.WAITING)
+            continue;
+        if (job.scheduledAt && new Date(job.scheduledAt).getTime() > now)
+            continue;
+        if (predicate && !predicate(job))
+            continue;
+        const at = runnableAt(job);
+        if (next === null ||
+            job.priority > next.priority ||
+            (job.priority === next.priority && at < nextAt)) {
+            next = job;
+            nextAt = at;
+        }
+    }
+    return next;
+}
+/** Whether any job a consumer can run is still owed a run. */
+export function hasPendingWork(jobs, isConsumable) {
+    for (const job of jobs) {
+        if (PENDING_STATES.has(job.state) && isConsumable(job))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=inMemoryQueue.select.js.map

package/dist/inMemoryQueue/polling/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/queue/inMemoryQueue/polling
+ *
+ * The in-memory queue's poll loop and job selection: a fixed or backing-off
+ * interval, immediate wake-ups when work arrives, keep-alive while work a
+ * consumer can run is pending, and runnable-time ordering.
+ */
+export * from "./inMemoryQueue.poller.js";
+export * from "./inMemoryQueue.select.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/inMemoryQueue/polling/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/queue/inMemoryQueue/polling
+ *
+ * The in-memory queue's poll loop and job selection: a fixed or backing-off
+ * interval, immediate wake-ups when work arrives, keep-alive while work a
+ * consumer can run is pending, and runnable-time ordering.
+ */
+export * from "./inMemoryQueue.poller.js";
+export * from "./inMemoryQueue.select.js";
+//# sourceMappingURL=index.js.map

package/dist/job/job.type.d.ts

@@ -15,7 +15,11 @@ export interface Job<TData = unknown> {
     readonly data: TData;
     /** Current state of the job. */
     readonly state: JobState;
-    /** Number of attempts made. */
+    /**
+     * Number of attempts already made, so `0` while the first attempt runs.
+     * Inside a processor, `context.attemptNumber` is the 1-based number of
+     * the attempt in progress (`attempt + 1`).
+     */
     readonly attempt: number;
     /** Maximum number of attempts allowed. */
     readonly maxAttempts: number;

package/dist/jobContext/jobContext.core.js

@@ -4,6 +4,7 @@
 export function createJobContext(job, signal, options = {}) {
     return {
         job,
+        attemptNumber: job.attempt + 1,
         signal,
         updateProgress: async (progress) => {
             if (options.onProgress) {

package/dist/jobContext/jobContext.type.d.ts

@@ -6,6 +6,13 @@ import type { JobProgress } from "../jobResult/jobResult.type.js";
 export interface JobContext<TData = unknown> {
     /** The job being processed. */
     readonly job: Job<TData>;
+    /**
+     * The attempt in progress, 1-based: `1` on the first run, `2` on the first
+     * retry. Always `job.attempt + 1`, since `job.attempt` counts the attempts
+     * already made. Matches `ctx.attempt` / `ctx.attemptNumber` in
+     * `@zudojs/scheduler`.
+     */
+    readonly attemptNumber: number;
     /** AbortSignal for cancellation support. */
     readonly signal: AbortSignal;
     /** Update job progress. */

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

@@ -32,13 +32,36 @@ export interface QueueOptions {
     readonly concurrency?: number;
     /** Default job options. */
     readonly defaultJobOptions?: Partial<JobOptions>;
-    /** Serializer for job payloads. */
+    /**
+     * Serializer for job payloads. Defaults to `JsonSerializer`, which
+     * round-trips `Date`, `BigInt`, `Map`, `Set`, `Uint8Array` and `Error`.
+     */
     readonly serializer?: Serializer;
     /** Middleware for job processing. */
     readonly middleware?: QueueMiddleware[];
-    /** Poll interval in milliseconds. */
+    /**
+     * Milliseconds between polls of the queue's own consumer.
+     *
+     * When set, every poll uses it. When unset, polls start at 50 ms and back
+     * off to 2000 ms while the queue is idle. Either way the poller does not
+     * wait for its next poll when work arrives: `add()`, a delayed job coming
+     * due, a retry's backoff elapsing, `resume()` and a job finishing all wake
+     * it immediately.
+     */
     readonly pollInterval?: number;
-    /** Event emitter for queue lifecycle events. */
+    /**
+     * Whether pending work holds the Node.js process open. Defaults to `true`:
+     * while the queue has waiting, delayed, retrying or running jobs that one of
+     * its processors can run, its poll timer is referenced, so a script whose
+     * only work is the queue does not exit before the jobs run. An idle queue,
+     * a paused one, work no processor handles, and a closed queue never hold it.
+     * Set to `false` to leave every timer unreferenced.
+     */
+    readonly keepAlive?: boolean;
+    /**
+     * Event emitter for queue lifecycle events. Defaults to an in-memory
+     * emitter, reachable as `queue.events`.
+     */
     readonly eventEmitter?: QueueEventEmitter;
     /** Store that receives jobs which exhausted their attempts. */
     readonly deadLetterStore?: DeadLetterStore<never>;
@@ -138,6 +161,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. */
@@ -201,6 +232,15 @@ export interface Queue<TData = unknown> {
      * turns it off so a worker is never racing the queue for jobs.
      */
     setAutoProcess?(enabled: boolean): void;
+    /**
+     * Subscribes to "a job may have become runnable" (added, released,
+     * reclaimed, a delay or retry backoff elapsed, the queue resumed). A
+     * `Worker` uses it to claim at once instead of on its next poll; a queue
+     * without it is simply polled.
+     *
+     * @returns A function that unsubscribes.
+     */
+    onJobReady?(listener: () => void): () => void;
 }
 /**
  * Event types emitted by a queue.
@@ -228,6 +268,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

@@ -10,15 +10,34 @@ import { reportQueueError } from "../queue/queue.report.js";
 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(() => {
-                        reportQueueError(`[@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/serializer/serializer.core.d.ts

@@ -2,19 +2,42 @@
  * @zudojs/queue — Serializer
  *
  * Job payload serialization using @zudojs/serialization's JSONSerializer.
+ *
+ * The default preserves types. Plain JSON turned a `Date` into a string
+ * while `Queue<{ d: Date }>` still typed it as a `Date`, so a processor
+ * calling `job.data.d.getTime()` crashed; `BigInt` was rejected outright.
+ * With `preserveTypes`, `Date`, `BigInt`, `Map`, `Set`, `Uint8Array` and
+ * `Error` all come back as themselves, and output for plain JSON data is
+ * unchanged.
  */
 import type { Serializer } from "./serializer.type.js";
-/** Default JSON serializer backed by @zudojs/serialization. */
+/**
+ * Default serializer: JSON that round-trips `Date`, `BigInt`, `Map`, `Set`,
+ * `Uint8Array` and `Error`, backed by @zudojs/serialization.
+ */
 export declare const JsonSerializer: Serializer;
 /**
- * Creates a serializer with custom options.
+ * Creates a JSON serializer with custom options.
  */
 export declare function createJsonSerializer(options?: {
     /** Indentation width. Any value turns on pretty-printing. */
     space?: number;
-    /** Preserve BigInt, Date, Map, Set and Uint8Array across the round trip. */
+    /**
+     * Preserve BigInt, Date, Map, Set, Uint8Array and Error across the round
+     * trip. Defaults to `true`, like `JsonSerializer`. With `false` a `Date`
+     * comes back as its ISO string, so type such payload fields as `string`.
+     */
     preserveTypes?: boolean;
 }): Serializer;
-/** No-op serializer that passes data through unchanged. */
+/**
+ * Serializer that keeps payloads as they are.
+ *
+ * It sets `passthrough`, so the in-memory queue stores payloads by reference
+ * (class instances, functions and all) instead of round-tripping them. Used
+ * standalone it must still honour the `Serializer` contract of producing a
+ * string: a string is returned untouched, anything else is JSON-encoded, and
+ * `deserialize` parses JSON where it can and returns the raw string where it
+ * cannot.
+ */
 export declare const PassthroughSerializer: Serializer;
 //# sourceMappingURL=serializer.core.d.ts.map

package/dist/serializer/serializer.core.js

@@ -2,48 +2,67 @@
  * @zudojs/queue — Serializer
  *
  * Job payload serialization using @zudojs/serialization's JSONSerializer.
+ *
+ * The default preserves types. Plain JSON turned a `Date` into a string
+ * while `Queue<{ d: Date }>` still typed it as a `Date`, so a processor
+ * calling `job.data.d.getTime()` crashed; `BigInt` was rejected outright.
+ * With `preserveTypes`, `Date`, `BigInt`, `Map`, `Set`, `Uint8Array` and
+ * `Error` all come back as themselves, and output for plain JSON data is
+ * unchanged.
  */
 import { JSONSerializer } from "@zudojs/serialization";
-/** Default JSON serializer backed by @zudojs/serialization. */
+const inner = new JSONSerializer();
+/**
+ * Default serializer: JSON that round-trips `Date`, `BigInt`, `Map`, `Set`,
+ * `Uint8Array` and `Error`, backed by @zudojs/serialization.
+ */
 export const JsonSerializer = Object.freeze({
     serialize(data) {
-        return new JSONSerializer().serialize(data);
+        return inner.serialize(data, { preserveTypes: true });
     },
     deserialize(data) {
-        return new JSONSerializer().deserialize(data);
+        return inner.deserialize(data, { preserveTypes: true });
     },
 });
 /**
- * Creates a serializer with custom options.
+ * Creates a JSON serializer with custom options.
  */
 export function createJsonSerializer(options) {
-    const inner = new JSONSerializer();
+    const preserveTypes = options?.preserveTypes ?? true;
     return Object.freeze({
         serialize(data) {
             return inner.serialize(data, {
                 pretty: options?.space !== undefined,
-                preserveTypes: options?.preserveTypes,
+                preserveTypes,
                 indent: options?.space,
             });
         },
         deserialize(data) {
-            return inner.deserialize(data, {
-                preserveTypes: options?.preserveTypes,
-            });
+            return inner.deserialize(data, { preserveTypes });
         },
     });
 }
-/** No-op serializer that passes data through unchanged. */
+/**
+ * Serializer that keeps payloads as they are.
+ *
+ * It sets `passthrough`, so the in-memory queue stores payloads by reference
+ * (class instances, functions and all) instead of round-tripping them. Used
+ * standalone it must still honour the `Serializer` contract of producing a
+ * string: a string is returned untouched, anything else is JSON-encoded, and
+ * `deserialize` parses JSON where it can and returns the raw string where it
+ * cannot.
+ */
 export const PassthroughSerializer = Object.freeze({
+    passthrough: true,
     serialize(data) {
         if (typeof data === "string") {
             return data;
         }
-        return new JSONSerializer().serialize(data);
+        return inner.serialize(data);
     },
     deserialize(data) {
         try {
-            return new JSONSerializer().deserialize(data);
+            return inner.deserialize(data);
         }
         catch {
             return data;

package/dist/serializer/serializer.type.d.ts

@@ -4,6 +4,12 @@
  * Provides serialization and deserialization of job data.
  */
 export interface Serializer {
+    /**
+     * Marks a serializer that stores values as given. The in-memory queue
+     * skips its round trip for such a serializer and keeps the payload by
+     * reference, exactly as with `serializePayloads: false`.
+     */
+    readonly passthrough?: boolean;
     /** Serialize data to a string. */
     serialize<T>(data: T): string;
     /** Deserialize a string to data. */

package/dist/worker/worker.core.js

@@ -25,13 +25,32 @@ export function createWorker(id, queue, options) {
     let activeJobs = 0;
     let polling = false;
     let abortController = null;
+    const keepAlive = options?.keepAlive ?? true;
+    let stopWatching;
     queue.setAutoProcess?.(false);
-    const onError = options?.onError ??
+    /**
+     * 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(() => {
                 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
@@ -47,7 +66,19 @@ export function createWorker(id, queue, options) {
             clearTimeout(pollTimer);
         }
         pollTimer = setTimeout(runPoll, delay);
-        pollTimer.unref?.();
+        // A started worker is the process's reason to stay alive until it is
+        // stopped; an unreferenced timer let a script exit before any job ran.
+        if (!keepAlive)
+            pollTimer.unref?.();
+    };
+    /** Claims at once when the queue reports a runnable job, if a slot is free. */
+    const onJobReady = () => {
+        if (activeJobs < concurrency)
+            scheduleNextPoll(0);
+    };
+    const unwatch = () => {
+        stopWatching?.();
+        stopWatching = undefined;
     };
     /**
      * Wraps `poll` so a rejection can never escape as an unhandled promise
@@ -157,6 +188,8 @@ export function createWorker(id, queue, options) {
             abortController = new AbortController();
             try {
                 state = WorkerState.RUNNING;
+                stopWatching = queue.onJobReady?.(onJobReady);
+                emitLifecycle("worker:started");
                 scheduleNextPoll(0);
             }
             catch (error) {
@@ -174,10 +207,12 @@ export function createWorker(id, queue, options) {
             if (state !== WorkerState.RUNNING && state !== WorkerState.STARTING) {
                 // Still clear any timer armed before the state moved on.
                 clearPollTimer();
+                unwatch();
                 return;
             }
             state = WorkerState.DRAINING;
             clearPollTimer();
+            unwatch();
             // Graceful means graceful: in-flight jobs get `drainTimeout` to
             // finish on their own. Aborting them up front — as this once did —
             // made `stop()` indistinguishable from `forceStop()` for any
@@ -193,11 +228,18 @@ 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();
+            unwatch();
             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

@@ -7,8 +7,18 @@ import type { WorkerState } from "../jobTypes/jobTypes.type.js";
 export interface WorkerOptions {
     /** Maximum number of jobs to process concurrently. */
     readonly concurrency?: number;
-    /** Poll interval in milliseconds. */
+    /**
+     * Milliseconds between polls while idle. Defaults to 100. A queue that
+     * supports `onJobReady` (the in-memory queue does) wakes the worker as soon
+     * as a job becomes runnable, so this bounds only how often it re-checks.
+     */
     readonly pollInterval?: number;
+    /**
+     * Whether a started worker holds the Node.js process open until `stop()`
+     * or `forceStop()`. Defaults to `true`; `false` leaves its timers
+     * unreferenced.
+     */
+    readonly keepAlive?: boolean;
     /**
      * Default job timeout in milliseconds, applied to jobs that do not
      * carry their own. Stall detection is a queue-level concern; configure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/queue",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Background job and asynchronous task infrastructure with in-memory and adapter-based queue implementations.",
   "license": "MIT",
   "author": {
@@ -25,13 +25,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/serialization": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/serialization": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -46,7 +46,7 @@
     "background-jobs",
     "worker"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-queue",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },