@zudojs/queue 1.4.1 → 1.5.0

package/README.md

@@ -165,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

@@ -574,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

@@ -267,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;
@@ -275,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.1",
+  "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.1"
+    "@zudojs/errors": "1.3.1",
+    "@zudojs/constants": "1.1.3",
+    "@zudojs/serialization": "1.2.2"
   },
   "devDependencies": {
     "typescript": "7.0.2",