@zudojs/queue 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,21 +10,48 @@ npm install @zudojs/queue
 
 ## Quick Start
 
+Runs as written — queue names are branded, so build one with
+`createQueueName`:
+
 ```typescript
-import { createInMemoryQueue } from "@zudojs/queue";
+import { createInMemoryQueue, createQueueName } from "@zudojs/queue";
+
+interface Email {
+  to: string;
+  subject: string;
+}
 
-const queue = createInMemoryQueue("emails", {
+const queue = createInMemoryQueue<Email>(createQueueName("emails"), {
   concurrency: 5,
+  // Give jobs somewhere to log; without this `context.log()` goes nowhere.
+  logger: console,
 });
 
-queue.process("send-email", async (job) => {
-  await sendEmail(job.data.to, job.data.subject);
+// A processor may return a value, a JobResult, or nothing.
+queue.process("send-email", async (job, context) => {
+  context.log("sending", { to: job.data.to });
+  return { delivered: job.data.to };
 });
 
-await queue.add("send-email", {
-  to: "user@example.com",
-  subject: "Welcome",
-});
+await queue.add(
+  "send-email",
+  { to: "user@example.com", subject: "Welcome" },
+  // Backoff accepts either BackoffType.FIXED or the plain string.
+  { attempts: 3, backoff: { type: "exponential", delay: 500, jitter: "full" } },
+);
+
+// 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());
+
+// Draining shutdown: in-flight jobs finish before the queue tears down.
+await queue.close();
 ```
 
 ## Features
@@ -36,6 +63,11 @@ await queue.add("send-email", {
 - Scheduled and delayed jobs
 - Middleware pipeline for job processing
 - Concurrency control
+- 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
 
 ## Use Cases
 

package/dist/deadLetter/deadLetter.core.js

@@ -1,4 +1,4 @@
-import { QueueError, toQueueError } from "@zudojs/errors";
+import { toQueueError } from "@zudojs/errors";
 /**
  * Creates an in-memory dead letter store.
  */

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

@@ -3,6 +3,8 @@ import type { Job } from "../job/job.type.js";
 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 { DeadLetterJob } from "../deadLetter/deadLetter.type.js";
 /**
  * In-memory queue implementation.
  *
@@ -20,29 +22,118 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
     private disposed;
     private activeCount;
     private pollTimer;
-    private scheduledTimers;
+    private readonly scheduledTimers;
+    private readonly retryTimers;
+    private readonly inFlight;
+    private readonly settledOrder;
+    /** How many times each job has been reclaimed after stalling. */
+    private readonly stalledCounts;
     private readonly deduplicationIndex;
     private readonly deadLetterStore;
-    private processedCount;
-    private succeededCount;
-    private failedCount;
     private readonly emitter;
+    private readonly counters;
     private emptySince;
     private backoffMs;
     constructor(name: QueueName, options?: QueueOptions);
     add(jobName: string, data: TData, options?: JobOptions): Promise<Job<TData>>;
     process(name: string, processor: Processor<TData>): void;
     getJob(jobId: JobId): Promise<Job<TData> | null>;
+    /**
+     * Returns the job that would be processed next without claiming it.
+     *
+     * This is a read-only peek. Consumers that intend to run the job must
+     * use {@link claimNextJob}, which transitions it to `active` so no
+     * other consumer can pick up the same job.
+     */
     getNextJob(): Promise<Job<TData> | null>;
+    /**
+     * Atomically selects the next runnable job and marks it `active`.
+     *
+     * Claiming is what prevents two consumers — or one consumer polling in
+     * a loop — from processing the same job repeatedly.
+     */
+    claimNextJob(): Promise<Job<TData> | null>;
+    /**
+     * Returns a claimed job to the waiting pool.
+     */
+    releaseJob(jobId: JobId): Promise<boolean>;
     getProcessor(name: string): Processor<TData> | undefined;
     getStats(): Promise<QueueStats>;
+    /**
+     * Returns the jobs that exhausted their attempts.
+     */
+    getDeadLetterJobs(): Promise<readonly DeadLetterJob<TData>[]>;
     pause(): Promise<void>;
     resume(): Promise<void>;
     isPaused(): boolean;
+    isDisposed(): boolean;
+    /**
+     * Closes the queue, draining in-flight jobs first.
+     *
+     * Nothing is torn down until running jobs have settled, so a job can
+     * never write back into a cleared queue. Jobs that outlast
+     * `closeTimeout` have their `AbortSignal` aborted and are then
+     * abandoned so shutdown cannot hang indefinitely.
+     */
     close(): Promise<void>;
+    /**
+     * Waits for in-flight jobs to settle, aborting them past the timeout.
+     */
+    private drain;
+    /**
+     * Generates a collision-resistant job id.
+     */
+    private createJobId;
+    /**
+     * Round-trips a payload through the configured serializer.
+     */
+    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.
+     */
+    private selectJob;
     private startPolling;
     private scheduleNextTick;
+    private scheduleTick;
     private stopPolling;
+    /**
+     * Runs an already-claimed job through this queue's processing pipeline.
+     *
+     * The queue owns job state, so every consumer — the internal poller and
+     * any external `Worker` — must run jobs through here. A consumer that
+     * invokes a processor directly leaves the job stuck in `active` and
+     * skips retry, dead-lettering and middleware entirely.
+     */
+    runJob(job: Job<TData>, options?: {
+        middleware?: readonly QueueMiddleware[];
+        signal?: AbortSignal;
+        /** Fallback timeout for a job that carries none of its own. */
+        timeoutMs?: number;
+    }): Promise<void>;
     private processTick;
+    /**
+     * Returns jobs stuck in `active` to the waiting pool.
+     *
+     * A consumer can claim a job and then die, or be killed mid-run.
+     * Without this the job stays `active` forever and no one picks it up
+     * again. A job that stalls repeatedly is dead-lettered rather than
+     * cycled indefinitely.
+     */
+    private reclaimStalledJobs;
+    /**
+     * Records a job that reached a terminal state and prunes history.
+     *
+     * Without this the queue retains every job it has ever run, and every
+     * deduplication key it has ever seen, for the life of the process.
+     */
+    private recordSettled;
+    /**
+     * Drops the oldest terminal jobs beyond the retention limit.
+     */
+    private pruneSettled;
 }
 //# sourceMappingURL=inMemoryQueue.core.d.ts.map