@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

pnpm add @nwire/dead-letter

Quick start

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.

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 }).

import { createApp } from "@nwire/forge";

const app = createApp({
  /* ...config... */
});
// Adapter/plugin wiring happens here when applicable.