@nwire/dead-letter 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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

@@ -0,0 +1,66 @@
+# @nwire/dead-letter
+
+> Dead-letter sink contract — destination for messages whose handler exhausted retries.
+
+## What it does
+
+Defines `DeadLetterSink` (one method: `record(entry)`) and ships an in-memory default. The runtime calls `sink.record(entry)` once per failed dispatch after `max + 1` attempts have all thrown. Production wires plug in a persistent adapter (BullMQ's failed-jobs board, a Mongo collection, an SNS topic); the contract is identical.
+
+## Install
+
+```bash
+pnpm add @nwire/dead-letter
+```
+
+## Quick start
+
+```ts
+import { InMemoryDeadLetterSink } from "@nwire/dead-letter";
+import { createApp } from "@nwire/forge";
+
+const dlq = new InMemoryDeadLetterSink();
+const app = createApp("learnflow", { modules, deadLetter: dlq });
+
+// In tests:
+const entries = await dlq.list();
+expect(entries.map((e) => e.actionName)).toContain("flakyAction");
+```
+
+## API surface
+
+- `DeadLetterSink` — interface adapters implement.
+- `InMemoryDeadLetterSink` — process-local default; useful in tests.
+- `DeadLetterEntry` — record shape (actionName, input, envelope, attempts, lastError, enteredAt).
+- `buildDeadLetterEntry(...)` — helper for adapters constructing entries.
+
+## When to use
+
+Any production deployment — silently dropping retries-exhausted jobs is a production bug. Fits L3 and up.
+
+## Standalone use
+
+For developers using `@nwire/dead-letter` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/dead-letter";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Foundation tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/queue](../nwire-queue), [@nwire/queue-bullmq](../nwire-queue-bullmq)

package/dist/dead-letter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `DeadLetterSink` — destination for messages whose handler exhausted retries.
+ *
+ * The runtime calls `sink(entry)` once per failed dispatch after `max + 1`
+ * attempts have all thrown. Production wires plug in a real DLQ (BullMQ's
+ * failed-jobs board, a Mongo collection, an SNS topic). Default is in-memory:
+ * collect every entry so tests can assert on what got dead-lettered.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+export interface DeadLetterEntry {
+    readonly actionName: string;
+    readonly input: unknown;
+    readonly envelope: MessageEnvelope;
+    readonly attempts: number;
+    readonly lastError: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    readonly enteredAt: string;
+}
+export interface DeadLetterSink {
+    record(entry: DeadLetterEntry): Promise<void>;
+    /** Return everything dead-lettered so far. Test/dev introspection. */
+    list(): Promise<readonly DeadLetterEntry[]>;
+}
+export declare class InMemoryDeadLetterSink implements DeadLetterSink {
+    private readonly entries;
+    record(entry: DeadLetterEntry): Promise<void>;
+    list(): Promise<readonly DeadLetterEntry[]>;
+    clear(): void;
+}
+/**
+ * Build a DeadLetterEntry from a thrown error and the dispatch state.
+ */
+export declare function buildDeadLetterEntry(actionName: string, input: unknown, envelope: MessageEnvelope, attempts: number, error: unknown): DeadLetterEntry;
+//# sourceMappingURL=dead-letter.d.ts.map

package/dist/dead-letter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../src/dead-letter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAAC;CAC7C;AAED,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAE3C,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,IAAI,IAAI,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;IAIjD,KAAK,IAAI,IAAI;CAGd;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,eAAe,CAcjB"}

package/dist/dead-letter.js

@@ -0,0 +1,39 @@
+/**
+ * `DeadLetterSink` — destination for messages whose handler exhausted retries.
+ *
+ * The runtime calls `sink(entry)` once per failed dispatch after `max + 1`
+ * attempts have all thrown. Production wires plug in a real DLQ (BullMQ's
+ * failed-jobs board, a Mongo collection, an SNS topic). Default is in-memory:
+ * collect every entry so tests can assert on what got dead-lettered.
+ */
+export class InMemoryDeadLetterSink {
+    entries = [];
+    async record(entry) {
+        this.entries.push(entry);
+    }
+    async list() {
+        return [...this.entries];
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+}
+/**
+ * Build a DeadLetterEntry from a thrown error and the dispatch state.
+ */
+export function buildDeadLetterEntry(actionName, input, envelope, attempts, error) {
+    const err = error;
+    return {
+        actionName,
+        input,
+        envelope,
+        attempts,
+        lastError: {
+            name: err?.name ?? "Error",
+            message: err?.message ?? String(error),
+            stack: err?.stack,
+        },
+        enteredAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=dead-letter.js.map

package/dist/dead-letter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.js","sourceRoot":"","sources":["../src/dead-letter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,MAAM,OAAO,sBAAsB;IAChB,OAAO,GAAsB,EAAE,CAAC;IAEjD,KAAK,CAAC,MAAM,CAAC,KAAsB;QACjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,KAAc,EACd,QAAyB,EACzB,QAAgB,EAChB,KAAc;IAEd,MAAM,GAAG,GAAG,KAA4D,CAAC;IACzE,OAAO;QACL,UAAU;QACV,KAAK;QACL,QAAQ;QACR,QAAQ;QACR,SAAS,EAAE;YACT,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,OAAO;YAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC;YACtC,KAAK,EAAE,GAAG,EAAE,KAAK;SAClB;QACD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC"}

package/dist/dlq.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@nwire/dead-letter` — DLQ contract + InMemory default.
+ *
+ *   DeadLetterSink interface — record() per failed dispatch after retries exhausted
+ *   InMemoryDeadLetterSink — process-local; test-friendly
+ *
+ * Production deployments use a persistent adapter (`@nwire/dlq-mongo`,
+ * `@nwire/dlq-bullmq`). The runtime catches handler throws after retries
+ * and routes them here.
+ */
+export { InMemoryDeadLetterSink, buildDeadLetterEntry, type DeadLetterSink, type DeadLetterEntry, } from "./dead-letter.js";
+//# sourceMappingURL=dlq.d.ts.map

package/dist/dlq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq.d.ts","sourceRoot":"","sources":["../src/dlq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}

package/dist/dlq.js

@@ -0,0 +1,12 @@
+/**
+ * `@nwire/dead-letter` — DLQ contract + InMemory default.
+ *
+ *   DeadLetterSink interface — record() per failed dispatch after retries exhausted
+ *   InMemoryDeadLetterSink — process-local; test-friendly
+ *
+ * Production deployments use a persistent adapter (`@nwire/dlq-mongo`,
+ * `@nwire/dlq-bullmq`). The runtime catches handler throws after retries
+ * and routes them here.
+ */
+export { InMemoryDeadLetterSink, buildDeadLetterEntry, } from "./dead-letter.js";
+//# sourceMappingURL=dlq.js.map

package/dist/dlq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq.js","sourceRoot":"","sources":["../src/dlq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,GAGrB,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nwire/dead-letter",
+  "version": "0.7.0",
+  "description": "Nwire — DLQ contract + InMemory default. Production adapters: @nwire/dlq-mongo, @nwire/dlq-bullmq. The runtime routes exhausted-retry failures here.",
+  "keywords": [
+    "dead-letter",
+    "dlq",
+    "nwire",
+    "reliability"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/dlq.js",
+  "types": "./dist/dlq.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/dlq.js",
+      "types": "./dist/dlq.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/envelope": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}