@zudojs/queue 1.3.0 → 1.4.0

package/README.md

@@ -72,6 +72,70 @@ await queue.close();
 - Bounded retention of settled jobs and of dead-lettered jobs, so a long-lived
   queue does not grow without limit
 
+## Polling and process lifetime
+
+The queue's own consumer polls every `pollInterval` milliseconds when you set
+one; unset, it starts at 50 ms and backs off to 2000 ms while idle. It never
+waits out that interval when work arrives: `add()`, a delayed job coming due, a
+retry's backoff elapsing, `resume()` and a finished job all wake it at once. A
+`Worker` is woken the same way through `queue.onJobReady`, so its
+`pollInterval` only bounds how often an idle worker re-checks.
+
+Pending work keeps the Node.js process alive. While the queue has waiting,
+delayed, retrying or running jobs that one of its processors can run, a script
+whose only work is the queue does not exit before the jobs run. A started
+`Worker` keeps the process alive until `stop()` or `forceStop()`. An idle queue,
+a paused one, work that no processor handles, and a closed queue never hold the
+process open. Pass `keepAlive: false` (to the queue or the worker) for the old
+behaviour, where every timer was unreferenced.
+
+## Payloads
+
+Payloads round-trip through the serializer on `add()`, so the stored job is a
+copy. The default `JsonSerializer` preserves `Date`, `BigInt`, `Map`, `Set`,
+`Uint8Array` and `Error`, so a field typed `Date` arrives as a `Date`:
+
+```typescript
+const reminders = createInMemoryQueue<{ at: Date }>(createQueueName("reminders"));
+reminders.process("remind", async (job) => job.data.at.getTime()); // a real Date
+```
+
+`createJsonSerializer({ preserveTypes: false })` gives plain JSON, where a
+`Date` becomes its ISO string (type it as `string`). `PassthroughSerializer`
+(or `serializePayloads: false`) stores payloads by reference, class instances
+included, with no copy and no serialization.
+
+## Ordering
+
+Higher `priority` runs first. Within a priority, jobs run in the order they
+became runnable: when they were added, or for a delayed job when its delay
+elapsed, so a delayed job never jumps ahead of jobs that were already waiting
+when it came due. A retried job keeps its original place in line.
+
+## Attempts
+
+`job.attempt` counts the attempts already made, so it is `0` while the first
+attempt runs. `context.attemptNumber` is the 1-based number of the attempt in
+progress (`job.attempt + 1`), the same convention as `ctx.attempt` in
+`@zudojs/scheduler`:
+
+```typescript
+queue.process("sync", async (job, context) => {
+  context.log(`attempt ${context.attemptNumber} of ${job.maxAttempts}`);
+});
+```
+
+## Events
+
+`queue.events` works without configuration: a queue created without an
+`eventEmitter` gets an in-memory one.
+
+```typescript
+queue.events?.on("job:completed", ({ job, result }) => {
+  console.log(job.id, result);
+});
+```
+
 ## Workers, timeouts and context
 
 **One consumer at a time.** `queue.process()` registers a processor and, by

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

@@ -24,7 +24,9 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     /** Whether the internal poller claims jobs; see `setAutoProcess`. */
     private autoProcess;
     private activeCount;
-    private pollTimer;
+    private readonly poller;
+    /** Consumers to tell when a job may have become runnable. */
+    private readonly readyListeners;
     private readonly scheduledTimers;
     private readonly retryTimers;
     private readonly inFlight;
@@ -40,9 +42,16 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     private readonly ownsDeadLetterStore;
     private readonly emitter;
     private readonly counters;
-    private emptySince;
-    private backoffMs;
     constructor(name: QueueName, options?: QueueOptions);
+    /**
+     * Subscribes to "a job may have become runnable": one was added, released
+     * or reclaimed, a delay or retry backoff elapsed, or the queue resumed.
+     *
+     * A `Worker` uses this to claim immediately instead of on its next poll.
+     *
+     * @returns A function that unsubscribes.
+     */
+    onJobReady(listener: () => void): () => void;
     /**
      * Turns the internal poller on or off as a consumer.
      *
@@ -55,8 +64,9 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     /**
      * 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.
+     * An in-memory emitter when the queue was created without one, so
+     * `queue.events.on(...)` works out of the box and a worker can report its
+     * lifecycle unconditionally.
      */
     get events(): QueueEventEmitter;
     add(jobName: string, data: TData, options?: JobOptions): Promise<Job<TData>>;
@@ -113,17 +123,18 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
      */
     private encodePayload;
     /**
-     * Selects the highest-priority job that is due and runnable.
-     *
-     * Ties on priority are broken by creation time, oldest first. The
-     * incumbent is tracked by reference rather than by a sentinel priority,
-     * so jobs with negative priorities are selectable like any other.
+     * Selects the next job that is due and runnable; see {@link selectNextJob}
+     * for the ordering.
      */
     private selectJob;
-    private startPolling;
-    private scheduleNextTick;
-    private scheduleTick;
-    private stopPolling;
+    /**
+     * Whether the poll loop should hold the process open: while the queue is
+     * consuming and has work one of its processors can run. Work nothing can
+     * consume, a paused queue and `keepAlive: false` never do.
+     */
+    private shouldKeepAlive;
+    /** Wakes the poll loop and tells consumers a job may be runnable. */
+    private jobReady;
     /**
      * Runs an already-claimed job through this queue's processing pipeline.
      *
@@ -138,6 +149,12 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
         /** Fallback timeout for a job that carries none of its own. */
         timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * One poll: promotes due delayed jobs, claims runnable jobs up to the
+     * concurrency limit, and reclaims stalled ones.
+     *
+     * @returns Whether any job was dispatched.
+     */
     private processTick;
     /**
      * Returns jobs stuck in `active` to the waiting pool.

package/dist/inMemoryQueue/inMemoryQueue.core.js

@@ -5,10 +5,11 @@ 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 { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, } from "../deadLetter/deadLetter.core.js";
-import { InMemoryQueueEventEmitter, createNoopQueueEventEmitter, } from "../queueEmitter/queueEmitter.core.js";
+import { InMemoryQueueEventEmitter } 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";
+import { QueuePoller, hasPendingWork, selectNextJob } from "./polling/index.js";
 /** Terminal states a job never leaves. */
 const TERMINAL_STATES = new Set([
     JobStateEnum.COMPLETED,
@@ -38,7 +39,9 @@ export class InMemoryQueue {
     /** Whether the internal poller claims jobs; see `setAutoProcess`. */
     autoProcess;
     activeCount = 0;
-    pollTimer = null;
+    poller;
+    /** Consumers to tell when a job may have become runnable. */
+    readyListeners = new Set();
     scheduledTimers = new Map();
     retryTimers = new Map();
     inFlight = new Map();
@@ -60,14 +63,16 @@ export class InMemoryQueue {
         retriedCount: 0,
         deadLetteredCount: 0,
     };
-    emptySince = 0;
-    backoffMs = 50;
     constructor(name, options) {
         this.name = name;
         this.options = options ?? {};
         this.serializer = this.options.serializer ?? JsonSerializer;
         this.middleware = this.options.middleware ?? [];
-        this.emitter = options?.eventEmitter ?? createNoopQueueEventEmitter();
+        // A working emitter by default: `queue.events` used to be a silent no-op
+        // unless one was passed in.
+        this.emitter =
+            options?.eventEmitter ??
+                new InMemoryQueueEventEmitter(this.options.logger ? { logger: this.options.logger } : {});
         // 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`.
@@ -82,6 +87,28 @@ export class InMemoryQueue {
                     maxEntries: DEFAULT_DEAD_LETTER_JOBS,
                 });
         this.autoProcess = this.options.autoProcess ?? true;
+        this.poller = new QueuePoller({
+            ...(this.options.pollInterval !== undefined
+                ? { pollInterval: this.options.pollInterval }
+                : {}),
+            tick: () => this.processTick(),
+            isLive: () => !this.disposed && this.processors.size > 0,
+            shouldKeepAlive: () => this.shouldKeepAlive(),
+        });
+    }
+    /**
+     * Subscribes to "a job may have become runnable": one was added, released
+     * or reclaimed, a delay or retry backoff elapsed, or the queue resumed.
+     *
+     * A `Worker` uses this to claim immediately instead of on its next poll.
+     *
+     * @returns A function that unsubscribes.
+     */
+    onJobReady(listener) {
+        this.readyListeners.add(listener);
+        return () => {
+            this.readyListeners.delete(listener);
+        };
     }
     /**
      * Turns the internal poller on or off as a consumer.
@@ -93,12 +120,15 @@ export class InMemoryQueue {
      */
     setAutoProcess(enabled) {
         this.autoProcess = enabled;
+        if (enabled)
+            this.poller.wake();
     }
     /**
      * 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.
+     * An in-memory emitter when the queue was created without one, so
+     * `queue.events.on(...)` works out of the box and a worker can report its
+     * lifecycle unconditionally.
      */
     get events() {
         return this.emitter;
@@ -143,10 +173,13 @@ export class InMemoryQueue {
             this.deduplicationIndex.set(mergedOptions.deduplicationKey, jobId);
         }
         if (job.state === JobStateEnum.SCHEDULED && job.scheduledAt) {
-            scheduleJob(job, this.scheduledTimers, this.jobs);
+            scheduleJob(job, this.scheduledTimers, this.jobs, () => this.jobReady());
         }
-        this.backoffMs = 50;
-        this.emptySince = 0;
+        // Wake the poller and any worker now. Resetting the back-off without
+        // re-arming the pending timer left a job added after an idle spell
+        // waiting up to 2 s; a delayed job wakes it too, so the pending work
+        // holds the process open.
+        this.jobReady();
         return job;
     }
     process(name, processor) {
@@ -154,8 +187,8 @@ export class InMemoryQueue {
             throw new QueueDisposedError(this.name);
         assertProcessor(processor, name);
         this.processors.set(name, processor);
-        if (!this.pollTimer)
-            this.startPolling();
+        // Jobs already waiting under this name are runnable now.
+        this.poller.wake();
     }
     async getJob(jobId) {
         return this.jobs.get(jobId) ?? null;
@@ -199,6 +232,7 @@ export class InMemoryQueue {
             return false;
         }
         this.jobs.set(jobId, updateJobState(job, JobStateEnum.WAITING, { startedAt: undefined }));
+        this.jobReady();
         return true;
     }
     getProcessor(name) {
@@ -263,10 +297,7 @@ export class InMemoryQueue {
         if (this.disposed)
             throw new QueueDisposedError(this.name);
         this.paused = false;
-        this.backoffMs = 50;
-        this.emptySince = 0;
-        if (!this.pollTimer && this.processors.size > 0)
-            this.startPolling();
+        this.jobReady();
     }
     isPaused() {
         return this.paused;
@@ -288,7 +319,8 @@ export class InMemoryQueue {
         // Stop accepting and dispatching work before draining, so the set of
         // in-flight jobs cannot grow while we wait for it.
         this.disposed = true;
-        this.stopPolling();
+        this.poller.stop();
+        this.readyListeners.clear();
         for (const timer of this.scheduledTimers.values())
             clearTimeout(timer);
         this.scheduledTimers.clear();
@@ -309,8 +341,6 @@ export class InMemoryQueue {
         }
         this.activeCount = 0;
         this.paused = false;
-        this.emptySince = 0;
-        this.backoffMs = 50;
     }
     /**
      * Waits for in-flight jobs to settle, aborting them past the timeout.
@@ -345,7 +375,10 @@ export class InMemoryQueue {
      * Round-trips a payload through the configured serializer.
      */
     encodePayload(jobId, data) {
-        if (this.options.serializePayloads === false) {
+        // A passthrough serializer means "store the payload as given": there is
+        // no string form to round-trip through.
+        if (this.options.serializePayloads === false ||
+            this.serializer.passthrough === true) {
             return data;
         }
         try {
@@ -356,62 +389,36 @@ export class InMemoryQueue {
         }
     }
     /**
-     * Selects the highest-priority job that is due and runnable.
-     *
-     * Ties on priority are broken by creation time, oldest first. The
-     * incumbent is tracked by reference rather than by a sentinel priority,
-     * so jobs with negative priorities are selectable like any other.
+     * Selects the next job that is due and runnable; see {@link selectNextJob}
+     * for the ordering.
      */
     selectJob(predicate) {
-        const now = Date.now();
-        let nextJob = null;
-        for (const job of this.jobs.values()) {
-            if (job.state !== JobStateEnum.WAITING)
-                continue;
-            if (job.scheduledAt && new Date(job.scheduledAt).getTime() > now)
-                continue;
-            if (predicate && !predicate(job))
-                continue;
-            if (nextJob === null) {
-                nextJob = job;
-                continue;
-            }
-            if (job.priority > nextJob.priority) {
-                nextJob = job;
-                continue;
-            }
-            if (job.priority === nextJob.priority) {
-                const candidateTime = new Date(job.createdAt).getTime();
-                const incumbentTime = new Date(nextJob.createdAt).getTime();
-                if (candidateTime < incumbentTime)
-                    nextJob = job;
-            }
-        }
-        return nextJob;
-    }
-    startPolling() {
-        this.scheduleTick(this.options.pollInterval ?? 50);
-    }
-    scheduleNextTick() {
-        this.scheduleTick(this.backoffMs);
+        return selectNextJob(this.jobs.values(), Date.now(), predicate);
     }
-    scheduleTick(interval) {
-        if (this.disposed)
-            return;
-        this.pollTimer = setTimeout(() => {
-            this.pollTimer = null;
-            this.processTick().finally(() => {
-                if (!this.disposed && this.processors.size > 0)
-                    this.scheduleNextTick();
-            });
-        }, interval);
-        // The poll timer must not be the reason a process stays alive.
-        this.pollTimer.unref?.();
+    /**
+     * Whether the poll loop should hold the process open: while the queue is
+     * consuming and has work one of its processors can run. Work nothing can
+     * consume, a paused queue and `keepAlive: false` never do.
+     */
+    shouldKeepAlive() {
+        if (this.options.keepAlive === false)
+            return false;
+        if (this.disposed || this.paused || !this.autoProcess)
+            return false;
+        if (this.activeCount > 0)
+            return true;
+        return hasPendingWork(this.jobs.values(), (job) => this.processors.has(job.name));
     }
-    stopPolling() {
-        if (this.pollTimer) {
-            clearTimeout(this.pollTimer);
-            this.pollTimer = null;
+    /** Wakes the poll loop and tells consumers a job may be runnable. */
+    jobReady() {
+        this.poller.wake();
+        for (const listener of [...this.readyListeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // A consumer's wake-up hook must not break the producer.
+            }
         }
     }
     /**
@@ -476,6 +483,7 @@ export class InMemoryQueue {
                     this.retryTimers.delete(jobId);
                 },
                 onSettled: (settled) => this.recordSettled(settled),
+                onJobReady: () => this.jobReady(),
                 isDisposed: () => this.disposed,
                 ...(this.options.logger ? { logger: this.options.logger } : {}),
             });
@@ -489,15 +497,26 @@ export class InMemoryQueue {
         finally {
             this.activeCount--;
             this.inFlight.delete(job.id);
+            // A slot is free: claim the next job now rather than on the next poll.
+            this.poller.wake();
             if (forwardAbort && consumerSignal) {
                 consumerSignal.removeEventListener("abort", forwardAbort);
             }
         }
     }
+    /**
+     * One poll: promotes due delayed jobs, claims runnable jobs up to the
+     * concurrency limit, and reclaims stalled ones.
+     *
+     * @returns Whether any job was dispatched.
+     */
     async processTick() {
         if (this.paused || this.disposed)
-            return;
+            return false;
         const concurrency = Math.max(1, this.options.concurrency ?? 1);
+        // Promote first, so a job whose delay just elapsed is claimable in this
+        // same tick.
+        promoteDueScheduledJobs(this.jobs, this.scheduledTimers);
         let processed = 0;
         while (this.autoProcess && this.activeCount < concurrency) {
             // `claimNextJob` only returns jobs that have a registered
@@ -513,22 +532,8 @@ export class InMemoryQueue {
             // sees the dispatch immediately.
             void this.runJob(job);
         }
-        if (processed > 0) {
-            this.backoffMs = 50;
-            this.emptySince = 0;
-        }
-        else if (this.emptySince === 0) {
-            this.emptySince = Date.now();
-            this.backoffMs = 50;
-        }
-        else {
-            const elapsed = Date.now() - this.emptySince;
-            if (elapsed > 500) {
-                this.backoffMs = Math.min(this.backoffMs * 2, 2000);
-            }
-        }
-        promoteDueScheduledJobs(this.jobs, this.scheduledTimers);
         this.reclaimStalledJobs();
+        return processed > 0;
     }
     /**
      * Returns jobs stuck in `active` to the waiting pool.
@@ -581,6 +586,7 @@ export class InMemoryQueue {
             }
             this.jobs.set(job.id, updateJobState(job, JobStateEnum.WAITING, { startedAt: undefined }));
             this.emitter.emit("job:failed", { job, error });
+            this.jobReady();
         }
     }
     /**

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

@@ -37,6 +37,8 @@ export interface ProcessJobDependencies<TData> {
     readonly deregisterRetryTimer?: (jobId: JobId) => void;
     /** Invoked whenever a job reaches a terminal state. */
     readonly onSettled?: (job: Job<TData>) => void;
+    /** Invoked when a retrying job's backoff elapses and it is runnable again. */
+    readonly onJobReady?: () => void;
     /** Whether the owning queue has been disposed. */
     readonly isDisposed: () => boolean;
     /**

package/dist/inMemoryQueue/inMemoryQueue.processing.js

@@ -148,10 +148,11 @@ export async function handleJobFailure(job, errorMessage, deps) {
                     failedAt: undefined,
                 });
                 jobs.set(job.id, waitingJob);
+                deps.onJobReady?.();
             }
         }, delay);
-        // `unref` keeps a pending retry from holding the process open; the
-        // queue clears the timer explicitly on close.
+        // Unreferenced: the queue's poll loop decides whether a pending retry
+        // holds the process open. The queue clears the timer on close.
         timer.unref?.();
         deps.registerRetryTimer(job.id, timer);
         return;

package/dist/inMemoryQueue/inMemoryQueue.scheduling.d.ts

@@ -4,10 +4,13 @@ import type { JobId } from "../jobTypes/jobTypes.type.js";
  * Schedule a job for future execution.
  *
  * The timer is registered so the queue can clear it on close, and
- * unreferenced so a scheduled job never by itself keeps the process
- * alive.
+ * unreferenced: the queue's poll loop, not each job's timer, decides whether
+ * pending work holds the process open.
+ *
+ * @param onDue - Told when the job has been promoted to `waiting`, so a
+ *   consumer can claim it now rather than on its next poll.
  */
-export declare function scheduleJob<TData>(job: Job<TData>, scheduledTimers: Map<JobId, ReturnType<typeof setTimeout>>, jobs: Map<string, Job<TData>>): void;
+export declare function scheduleJob<TData>(job: Job<TData>, scheduledTimers: Map<JobId, ReturnType<typeof setTimeout>>, jobs: Map<string, Job<TData>>, onDue?: () => void): void;
 /**
  * Promotes scheduled jobs whose time has arrived.
  *

package/dist/inMemoryQueue/inMemoryQueue.scheduling.js

@@ -5,10 +5,13 @@ import { MAX_TIMER_DELAY } from "../retryPolicy/retryPolicy.core.js";
  * Schedule a job for future execution.
  *
  * The timer is registered so the queue can clear it on close, and
- * unreferenced so a scheduled job never by itself keeps the process
- * alive.
+ * unreferenced: the queue's poll loop, not each job's timer, decides whether
+ * pending work holds the process open.
+ *
+ * @param onDue - Told when the job has been promoted to `waiting`, so a
+ *   consumer can claim it now rather than on its next poll.
  */
-export function scheduleJob(job, scheduledTimers, jobs) {
+export function scheduleJob(job, scheduledTimers, jobs, onDue) {
     if (!job.scheduledAt) {
         return;
     }
@@ -17,6 +20,7 @@ export function scheduleJob(job, scheduledTimers, jobs) {
         // An unparseable schedule would otherwise fire immediately via NaN
         // coercion; promote the job instead of guessing at a delay.
         jobs.set(job.id, updateJobState(job, JobStateEnum.WAITING));
+        onDue?.();
         return;
     }
     const delay = Math.min(Math.max(0, scheduledTime - Date.now()), MAX_TIMER_DELAY);
@@ -29,6 +33,7 @@ export function scheduleJob(job, scheduledTimers, jobs) {
         const currentJob = jobs.get(job.id);
         if (currentJob && currentJob.state === JobStateEnum.SCHEDULED) {
             jobs.set(job.id, updateJobState(currentJob, JobStateEnum.WAITING));
+            onDue?.();
         }
     }, delay);
     timer.unref?.();

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

@@ -0,0 +1,64 @@
+/**
+ * The in-memory queue's poll loop.
+ *
+ * A tick promotes due delayed jobs, claims runnable ones and reclaims stalled
+ * ones. Three defects lived here: `pollInterval` applied to the first tick
+ * only (every later tick used a built-in 50 ms that backed off to 2 s while
+ * idle), nothing woke the loop when work arrived (so an add after an idle
+ * spell waited out the back-off), and every timer was unreferenced (so a
+ * script whose only work was a queue exited before any job ran).
+ *
+ * @module inMemoryQueue/polling/inMemoryQueue.poller
+ */
+/** First interval, and the floor of the idle back-off, when none is set. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 50;
+/** Ceiling of the idle back-off when no `pollInterval` is set. */
+export declare const MAX_IDLE_POLL_INTERVAL_MS = 2000;
+/** What the poller drives. */
+export interface QueuePollerOptions {
+    /**
+     * A fixed interval between ticks. When set it is used for every tick;
+     * when unset the interval starts at {@link DEFAULT_POLL_INTERVAL_MS} and
+     * backs off while idle.
+     */
+    readonly pollInterval?: number;
+    /** Runs one tick. Resolves true when it dispatched any job. */
+    readonly tick: () => Promise<boolean>;
+    /** Whether the loop should keep running at all. */
+    readonly isLive: () => boolean;
+    /** Whether the armed timer should hold the process open. */
+    readonly shouldKeepAlive: () => boolean;
+}
+/**
+ * Drives a queue's ticks: a fixed or backing-off interval, an immediate
+ * `wake()` when work may have arrived, and at most one tick at a time.
+ */
+export declare class QueuePoller {
+    private readonly options;
+    private timer;
+    private armedDelay;
+    private ticking;
+    private wakeRequested;
+    private backoffMs;
+    private emptySince;
+    constructor(options: QueuePollerOptions);
+    /** Whether a tick is armed or running. */
+    get isRunning(): boolean;
+    /** Arms the first tick, unless the loop is already running. */
+    start(): void;
+    /** Runs a tick as soon as possible, and clears the idle back-off. */
+    wake(): void;
+    /** Clears the idle back-off without arming anything. */
+    resetBackoff(): void;
+    /** Disarms the loop. A tick already running finishes but re-arms nothing. */
+    stop(): void;
+    private arm;
+    /**
+     * Referenced while there is work a consumer can run, so the process waits
+     * for it; unreferenced otherwise, so an idle queue never holds it open.
+     */
+    private applyKeepAlive;
+    private run;
+    private nextDelay;
+}
+//# sourceMappingURL=inMemoryQueue.poller.d.ts.map

package/dist/inMemoryQueue/polling/inMemoryQueue.poller.js

@@ -0,0 +1,132 @@
+/**
+ * The in-memory queue's poll loop.
+ *
+ * A tick promotes due delayed jobs, claims runnable ones and reclaims stalled
+ * ones. Three defects lived here: `pollInterval` applied to the first tick
+ * only (every later tick used a built-in 50 ms that backed off to 2 s while
+ * idle), nothing woke the loop when work arrived (so an add after an idle
+ * spell waited out the back-off), and every timer was unreferenced (so a
+ * script whose only work was a queue exited before any job ran).
+ *
+ * @module inMemoryQueue/polling/inMemoryQueue.poller
+ */
+/** First interval, and the floor of the idle back-off, when none is set. */
+export const DEFAULT_POLL_INTERVAL_MS = 50;
+/** Ceiling of the idle back-off when no `pollInterval` is set. */
+export const MAX_IDLE_POLL_INTERVAL_MS = 2_000;
+/** How long the loop must find nothing before an unset interval backs off. */
+const IDLE_BEFORE_BACKOFF_MS = 500;
+/**
+ * Drives a queue's ticks: a fixed or backing-off interval, an immediate
+ * `wake()` when work may have arrived, and at most one tick at a time.
+ */
+export class QueuePoller {
+    options;
+    timer = null;
+    armedDelay = 0;
+    ticking = false;
+    wakeRequested = false;
+    backoffMs = DEFAULT_POLL_INTERVAL_MS;
+    emptySince = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Whether a tick is armed or running. */
+    get isRunning() {
+        return this.timer !== null || this.ticking;
+    }
+    /** Arms the first tick, unless the loop is already running. */
+    start() {
+        if (this.isRunning)
+            return;
+        this.arm(this.options.pollInterval ?? DEFAULT_POLL_INTERVAL_MS);
+    }
+    /** Runs a tick as soon as possible, and clears the idle back-off. */
+    wake() {
+        this.resetBackoff();
+        if (!this.options.isLive())
+            return;
+        if (this.ticking) {
+            this.wakeRequested = true;
+            return;
+        }
+        if (this.timer !== null && this.armedDelay === 0) {
+            // Already due; the work that woke us may change whether it holds the
+            // process open.
+            this.applyKeepAlive();
+            return;
+        }
+        this.arm(0);
+    }
+    /** Clears the idle back-off without arming anything. */
+    resetBackoff() {
+        this.backoffMs = DEFAULT_POLL_INTERVAL_MS;
+        this.emptySince = 0;
+    }
+    /** Disarms the loop. A tick already running finishes but re-arms nothing. */
+    stop() {
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.wakeRequested = false;
+        this.resetBackoff();
+    }
+    arm(delay) {
+        if (!this.options.isLive())
+            return;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.armedDelay = delay;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.run();
+        }, delay);
+        this.applyKeepAlive();
+    }
+    /**
+     * Referenced while there is work a consumer can run, so the process waits
+     * for it; unreferenced otherwise, so an idle queue never holds it open.
+     */
+    applyKeepAlive() {
+        if (this.timer === null)
+            return;
+        if (this.options.shouldKeepAlive())
+            this.timer.ref?.();
+        else
+            this.timer.unref?.();
+    }
+    async run() {
+        this.ticking = true;
+        let dispatched = false;
+        try {
+            dispatched = await this.options.tick();
+        }
+        catch {
+            // A tick never rejects by design; a defect must not stop the loop.
+        }
+        finally {
+            this.ticking = false;
+        }
+        if (!this.options.isLive() || this.timer !== null)
+            return;
+        const woken = this.wakeRequested;
+        this.wakeRequested = false;
+        this.arm(woken ? 0 : this.nextDelay(dispatched));
+    }
+    nextDelay(dispatched) {
+        if (this.options.pollInterval !== undefined) {
+            return Math.max(0, this.options.pollInterval);
+        }
+        if (dispatched) {
+            this.resetBackoff();
+        }
+        else if (this.emptySince === 0) {
+            this.emptySince = Date.now();
+        }
+        else if (Date.now() - this.emptySince > IDLE_BEFORE_BACKOFF_MS) {
+            this.backoffMs = Math.min(this.backoffMs * 2, MAX_IDLE_POLL_INTERVAL_MS);
+        }
+        return this.backoffMs;
+    }
+}
+//# sourceMappingURL=inMemoryQueue.poller.js.map

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>;
@@ -209,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.

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,6 +25,8 @@ 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);
     /**
      * Reports the worker's own lifecycle on the queue's emitter.
@@ -64,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
@@ -174,6 +188,7 @@ export function createWorker(id, queue, options) {
             abortController = new AbortController();
             try {
                 state = WorkerState.RUNNING;
+                stopWatching = queue.onJobReady?.(onJobReady);
                 emitLifecycle("worker:started");
                 scheduleNextPoll(0);
             }
@@ -192,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
@@ -217,6 +234,7 @@ export function createWorker(id, queue, options) {
             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.

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.3.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.2.0",
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/serialization": "1.1.1"
+    "@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"
   },