@zudojs/queue 1.4.0 → 1.5.0

package/README.md

@@ -57,6 +57,35 @@ console.log(await queue.getStats());
 await queue.close();
 ```
 
+## Dead-letter store
+
+Each queue keeps the most recent 1000 dead-lettered jobs in a store of its own,
+cleared by `close()`. To choose the cap, or to keep the jobs after the queue
+closes, pass a store as `deadLetterStore`. No type annotation is needed, for
+an untyped store or one typed for the queue's payload.
+
+```typescript
+import {
+  createInMemoryDeadLetterStore,
+  createInMemoryQueue,
+  createQueueName,
+} from "@zudojs/queue";
+
+// Keep only the 50 most recent failures.
+const store = createInMemoryDeadLetterStore({ maxEntries: 50 });
+const broken = createInMemoryQueue(createQueueName("broken"), {
+  deadLetterStore: store,
+});
+
+// A store typed for the payload, so its entries read as DeadLetterJob<Email>.
+const failedEmails = createInMemoryDeadLetterStore<Email>();
+const emails = createInMemoryQueue<Email>(createQueueName("emails"), {
+  deadLetterStore: failedEmails,
+});
+```
+
+`close()` leaves a store you passed in alone; its contents are yours.
+
 ## Features
 
 - In-memory queue for development and testing
@@ -136,6 +165,32 @@ queue.events?.on("job:completed", ({ job, result }) => {
 });
 ```
 
+`job:failed` fires on **every** failed attempt, not only the last, and a
+processor failure reports `job.state === "failed"` on a retryable attempt
+and on the final one alike, with `job.attempt` still counting the attempts
+before this one. What follows tells them apart:
+
+| Attempt | `job:failed` `job.state` | Then |
+|---------|--------------------------|------|
+| Retryable (attempts left) | `"failed"` | `job:retrying` (`"retrying"`); after the backoff the job is `"waiting"` again |
+| Final (attempts exhausted) | `"failed"` | `job:dead-lettered` (`"dead_letter"`) |
+| Stalled, reclaimed | `"active"` (as found), `JobStalledError` | the job is `"waiting"` again |
+| Stalled `maxStalledCount` times | `"dead_letter"`, `JobStalledError` | `job:dead-lettered` |
+
+To alert only on dead letters, subscribe to `job:dead-lettered`. It fires once
+per job, when the job enters the dead-letter store, with the entry's `error`
+(`JobMaxAttemptsError`, or `JobStalledError` for a stalled job) and `reason`
+(the last attempt's error message, or `"Stalled N time(s)."`):
+
+```typescript
+queue.events?.on("job:dead-lettered", ({ job, error, reason }) => {
+  alerts.page(`${job.name} ${job.id} dead-lettered: ${reason}`, error);
+});
+```
+
+It fires even if a custom `deadLetterStore.add()` rejects, in step with
+`getStats().deadLettered`. Before 1.5.0 there was no dead-letter event.
+
 ## Workers, timeouts and context
 
 **One consumer at a time.** `queue.process()` registers a processor and, by

package/dist/inMemoryQueue/inMemoryQueue.core.js

@@ -81,6 +81,9 @@ export class InMemoryQueue {
             this.emitter.setLogger(this.options.logger);
         }
         this.ownsDeadLetterStore = this.options.deadLetterStore === undefined;
+        // A caller's store is typed `DeadLetterStore<unknown>` (see
+        // `QueueOptions.deadLetterStore`); this queue only ever adds its own
+        // `TData` jobs to it, so it is read back as a store of `TData`.
         this.deadLetterStore =
             this.options.deadLetterStore ??
                 createInMemoryDeadLetterStore({
@@ -571,16 +574,22 @@ export class InMemoryQueue {
                     failedAt: new Date().toISOString(),
                 });
                 this.jobs.set(job.id, deadLettered);
+                const reason = `Stalled ${count} time(s).`;
                 void this.deadLetterStore
                     .add({
                     job: deadLettered,
                     deadLetterAt: new Date(),
                     error,
                     attempts: deadLettered.attempt,
-                    reason: `Stalled ${count} time(s).`,
+                    reason,
                 })
                     .catch(() => { });
                 this.emitter.emit("job:failed", { job: deadLettered, error });
+                this.emitter.emit("job:dead-lettered", {
+                    job: deadLettered,
+                    error,
+                    reason,
+                });
                 this.recordSettled(deadLettered);
                 continue;
             }

package/dist/inMemoryQueue/inMemoryQueue.processing.js

@@ -171,6 +171,11 @@ export async function handleJobFailure(job, errorMessage, deps) {
     }
     const deadLetterJob = updateJobState(incrementedJob, JobStateEnum.DEAD_LETTER, { error: maxAttemptsError.message });
     jobs.set(job.id, deadLetterJob);
+    emitter.emit("job:dead-lettered", {
+        job: deadLetterJob,
+        error: maxAttemptsError,
+        reason: errorMessage,
+    });
     deps.onSettled?.(deadLetterJob);
 }
 //# sourceMappingURL=inMemoryQueue.processing.js.map

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

@@ -63,8 +63,15 @@ export interface QueueOptions {
      * emitter, reachable as `queue.events`.
      */
     readonly eventEmitter?: QueueEventEmitter;
-    /** Store that receives jobs which exhausted their attempts. */
-    readonly deadLetterStore?: DeadLetterStore<never>;
+    /**
+     * Store that receives jobs which exhausted their attempts.
+     *
+     * Any store is accepted without an annotation: the untyped
+     * `createInMemoryDeadLetterStore()` and one typed for the queue's payload,
+     * `createInMemoryDeadLetterStore<TData>()`. (1.4.0 typed this
+     * `DeadLetterStore<never>`, which rejected both.)
+     */
+    readonly deadLetterStore?: DeadLetterStore<unknown>;
     /**
      * Whether `add()` rejects while the queue is paused.
      *
@@ -260,6 +267,11 @@ export type QueueEventMap = {
         job: Job;
         result: unknown;
     };
+    /**
+     * An attempt failed. Fires on every failed attempt, retryable or final;
+     * `job.state` is `"failed"` for a processor failure either way. Use
+     * `job:retrying` or `job:dead-lettered` to tell the two apart.
+     */
     "job:failed": {
         job: Job;
         error: Error;
@@ -268,6 +280,17 @@ export type QueueEventMap = {
         job: Job;
         attempt: number;
     };
+    /**
+     * The job was moved to the dead-letter store (attempts exhausted, or
+     * stalled `maxStalledCount` times). Fires once per job, after the
+     * `job:failed` for its last attempt; `job.state` is `"dead_letter"` and
+     * `error` / `reason` are the dead-letter entry's.
+     */
+    "job:dead-lettered": {
+        job: Job;
+        error: Error;
+        reason?: string;
+    };
     /** A running job was aborted from outside — a drain, a close, a cancel. */
     "job:cancelled": {
         job: Job;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/queue",
-  "version": "1.4.0",
+  "version": "1.5.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.3.0",
-    "@zudojs/constants": "1.1.2",
-    "@zudojs/serialization": "1.2.0"
+    "@zudojs/errors": "1.3.1",
+    "@zudojs/constants": "1.1.3",
+    "@zudojs/serialization": "1.2.2"
   },
   "devDependencies": {
     "typescript": "7.0.2",