@cqrs-ddd/pipeline-deadletter 0.5.0

package/README.md

@@ -0,0 +1,31 @@
+# @cqrs-ddd/pipeline-deadletter
+
+Dead letters for `@cqrs-ddd/pipeline`: a failed operation (events by default) is
+captured with its request, error, tenant and correlation id, through a BullMQ, RabbitMQ
+or PostgreSQL transport, and `DeadLetterRedriver` runs it again later.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-deadletter/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-deadletter/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-deadletter @cqrs-ddd/pipeline
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+const pipeline = createPipeline({ behaviors: [new DeadLetterBehavior(transport)] });
+
+export const sendWelcome = pipeline.wrap({ name: 'sendWelcome', kind: 'event' }, deadLetter())(
+  async (event: UserCreated) => mailer.welcome(event.userId),
+);
+```
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

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

@@ -0,0 +1,58 @@
+import { type IPipelineBehavior, type IPipelineBehaviorContract, type IPipelineContext, type NextDelegate, PIPELINE_BEHAVIOR_CONTRACT, type PipelineItemToken, type PipelineLogger } from '@cqrs-ddd/pipeline';
+import type { DeadLetterBehaviorOptions } from './interfaces/dead-letter-options.interface.js';
+import type { DeadLetterTransport } from './interfaces/dead-letter-transport.interface.js';
+/**
+ * Unique symbol key set on `context.items` to `true` or `false` recording whether
+ * delivery to the dead-letter transport succeeded.
+ *
+ * @example
+ * ```ts
+ * const delivered = context.items.get(DEAD_LETTER_ITEM) === true;
+ * ```
+ */
+export declare const DEAD_LETTER_ITEM: unique symbol;
+/**
+ * Typed token for {@link DEAD_LETTER_ITEM}: the dead-letter delivery outcome. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const DEAD_LETTER_ITEM_TOKEN: PipelineItemToken<boolean>;
+/**
+ * Pipeline behavior that forwards **failed** requests to a dead-letter sink.
+ *
+ * When the wrapped handler (and anything nested inside it, such as
+ * `ResilienceBehavior` retries) throws, this behavior captures a
+ * {@link DeadLetterRecord} and hands it to the configured
+ * {@link DeadLetterTransport}, then — by default — re-throws so the caller still
+ * sees the failure. Payload and metadata must be serializable by that transport.
+ *
+ * Transport-agnostic by design: it depends only on {@link DeadLetterTransport},
+ * so the backend (BullMQ, RabbitMQ, Postgres, …) is a one-line swap: the
+ * transport passed to the constructor.
+ *
+ * **Ordering:** place this **outside** retry behaviors so it only fires once
+ * retries are exhausted, but **inside** request validation behaviors so expected
+ * client validation errors are not dead-lettered.
+ *
+ * @example Fire-and-forget event — capture and swallow
+ * ```ts
+ * class SendWelcomeEmailOnUserCreated {
+ *   @pipeline.wrap({ kind: 'event' }, [DeadLetterBehavior, { rethrow: false }])
+ *   async handle(event: UserCreatedEvent) {}
+ * }
+ * ```
+ */
+export declare class DeadLetterBehavior implements IPipelineBehavior {
+    private readonly transport;
+    static readonly [PIPELINE_BEHAVIOR_CONTRACT]: IPipelineBehaviorContract;
+    private readonly logger;
+    private readonly defaults;
+    constructor(transport: DeadLetterTransport, defaults?: DeadLetterBehaviorOptions, logger?: PipelineLogger);
+    handle(context: IPipelineContext, next: NextDelegate): Promise<unknown>;
+    /** Forwards the failed request; returns the record id once the transport has it. */
+    private capture;
+    /** Whether this request kind and error are configured to be captured. */
+    private shouldCapture;
+    /** Merges per-handler options over the constructor defaults. */
+    private resolveOptions;
+}
+//# sourceMappingURL=dead-letter.behavior.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.behavior.d.ts","sourceRoot":"","sources":["../src/dead-letter.behavior.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,0BAA0B,EAG1B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+CAA+C,CAAC;AAC/F,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,iDAAiD,CAAC;AASzD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAiB,CAAC,OAAO,CACK,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IA0BxD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAzB5B,MAAM,CAAC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,yBAAyB,CAmBrE;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,YACmB,SAAS,EAAE,mBAAmB,EAC/C,QAAQ,CAAC,EAAE,yBAAyB,EACpC,MAAM,CAAC,EAAE,cAAc,EAUxB;IAEK,MAAM,CACV,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,OAAO,CAAC,CAuClB;IAED,oFAAoF;YACtE,OAAO;IAyBrB,yEAAyE;IACzE,OAAO,CAAC,aAAa;IAiBrB,gEAAgE;IAChE,OAAO,CAAC,cAAc;CAoCvB"}

package/dist/dead-letter.behavior.js

@@ -0,0 +1,173 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { createPipelineItem, PIPELINE_BEHAVIOR_CONTRACT, setPipelineItem, } from '@cqrs-ddd/pipeline';
+import { buildDeadLetterRecord } from './helpers/build-record.js';
+import { currentRedriveId } from './helpers/redrive-scope.js';
+/**
+ * Kinds captured when `captureKinds` is omitted: events. A command's or a
+ * query's caller already receives the error; an event handler's failure has
+ * no caller to receive it.
+ */
+const DEFAULT_CAPTURE_KINDS = ['event'];
+/**
+ * Unique symbol key set on `context.items` to `true` or `false` recording whether
+ * delivery to the dead-letter transport succeeded.
+ *
+ * @example
+ * ```ts
+ * const delivered = context.items.get(DEAD_LETTER_ITEM) === true;
+ * ```
+ */
+export const DEAD_LETTER_ITEM = Symbol('DEAD_LETTER_ITEM');
+/**
+ * Typed token for {@link DEAD_LETTER_ITEM}: the dead-letter delivery outcome. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const DEAD_LETTER_ITEM_TOKEN = createPipelineItem('DEAD_LETTER_ITEM', DEAD_LETTER_ITEM);
+/**
+ * Pipeline behavior that forwards **failed** requests to a dead-letter sink.
+ *
+ * When the wrapped handler (and anything nested inside it, such as
+ * `ResilienceBehavior` retries) throws, this behavior captures a
+ * {@link DeadLetterRecord} and hands it to the configured
+ * {@link DeadLetterTransport}, then — by default — re-throws so the caller still
+ * sees the failure. Payload and metadata must be serializable by that transport.
+ *
+ * Transport-agnostic by design: it depends only on {@link DeadLetterTransport},
+ * so the backend (BullMQ, RabbitMQ, Postgres, …) is a one-line swap: the
+ * transport passed to the constructor.
+ *
+ * **Ordering:** place this **outside** retry behaviors so it only fires once
+ * retries are exhausted, but **inside** request validation behaviors so expected
+ * client validation errors are not dead-lettered.
+ *
+ * @example Fire-and-forget event — capture and swallow
+ * ```ts
+ * class SendWelcomeEmailOnUserCreated {
+ *   @pipeline.wrap({ kind: 'event' }, [DeadLetterBehavior, { rethrow: false }])
+ *   async handle(event: UserCreatedEvent) {}
+ * }
+ * ```
+ */
+export class DeadLetterBehavior {
+    transport;
+    static [PIPELINE_BEHAVIOR_CONTRACT] = {
+        validate: (context) => {
+            const options = context.effectiveOptions;
+            if (options?.rethrow !== false || context.requestKind === 'event') {
+                return undefined;
+            }
+            return [
+                {
+                    handlerName: context.handlerName,
+                    behaviorName: DeadLetterBehavior.name,
+                    message: `rethrow: false on a ${context.requestKind} handler would answer its caller with undefined instead of the error`,
+                    fix: 'Remove rethrow: false; swallowing a captured error is allowed on event handlers only.',
+                },
+            ];
+        },
+    };
+    logger;
+    defaults;
+    constructor(transport, defaults, logger) {
+        this.transport = transport;
+        if (typeof transport?.send !== 'function') {
+            throw new TypeError('DeadLetterBehavior requires a dead-letter transport with a send() method, such as a BullMQ, RabbitMQ or PostgreSQL transport.');
+        }
+        this.defaults = defaults ?? {};
+        this.logger = logger ?? console;
+    }
+    async handle(context, next) {
+        try {
+            return await next();
+        }
+        catch (error) {
+            // A redrive records its own attempt on the existing record, and must see
+            // the failure: never capture it again, never swallow it.
+            if (currentRedriveId() !== undefined)
+                throw error;
+            const options = this.resolveOptions(context);
+            const shouldCapture = this.shouldCapture(context, options, error);
+            let recordId;
+            if (shouldCapture) {
+                recordId = await this.capture(context, error, options);
+                setPipelineItem(context, DEAD_LETTER_ITEM_TOKEN, recordId !== undefined);
+            }
+            // Excluding a request kind or ignoring an error means this behavior is inactive
+            // for that failure; it must not silently swallow an error it did not capture.
+            // Only an event's error is ever swallowed: a command or query has a caller.
+            if ((options.rethrow ?? true) ||
+                context.requestKind !== 'event' ||
+                recordId === undefined) {
+                throw error;
+            }
+            this.logger.error?.(`Dead-lettered and swallowed ${context.requestName} ` +
+                `(correlationId: ${context.correlationId}, deadLetterId: ${recordId})`, DeadLetterBehavior.name);
+            return undefined;
+        }
+    }
+    /** Forwards the failed request; returns the record id once the transport has it. */
+    async capture(context, error, options) {
+        try {
+            const record = buildDeadLetterRecord(context, error, options);
+            await this.transport.send(record);
+            this.logger.warn?.(`Dead-lettered ${context.requestKind} ${context.requestName} ` +
+                `(correlationId: ${context.correlationId}, deadLetterId: ${record.id})`, DeadLetterBehavior.name);
+            return record.id;
+        }
+        catch (transportError) {
+            // The sink failing must never hide the real handler error: log and move on.
+            this.logger.error?.(`Failed to dead-letter ${context.requestName}: ` +
+                `${transportError instanceof Error ? transportError.message : transportError}`, DeadLetterBehavior.name);
+            return undefined;
+        }
+    }
+    /** Whether this request kind and error are configured to be captured. */
+    shouldCapture(context, options, error) {
+        const captureKinds = options.captureKinds ?? DEFAULT_CAPTURE_KINDS;
+        if (!captureKinds.includes(context.requestKind)) {
+            return false;
+        }
+        const { ignoreErrors } = options;
+        return !((typeof ignoreErrors === 'function' || Array.isArray(ignoreErrors)) &&
+            matchesIgnoredError(ignoreErrors, error, context));
+    }
+    /** Merges per-handler options over the constructor defaults. */
+    resolveOptions(context) {
+        const handlerOptions = context.getBehaviorOptions(DeadLetterBehavior);
+        if (!handlerOptions)
+            return this.defaults;
+        const merged = {
+            ...this.defaults,
+            ...handlerOptions,
+        };
+        if (this.defaults.ignoreErrors && handlerOptions.ignoreErrors) {
+            if (Array.isArray(this.defaults.ignoreErrors) &&
+                Array.isArray(handlerOptions.ignoreErrors)) {
+                merged.ignoreErrors = [
+                    ...this.defaults.ignoreErrors,
+                    ...handlerOptions.ignoreErrors,
+                ];
+            }
+            else {
+                const defaultFilter = this.defaults.ignoreErrors;
+                const handlerFilter = handlerOptions.ignoreErrors;
+                merged.ignoreErrors = (err, ctx) => matchesIgnoredError(defaultFilter, err, ctx) ||
+                    matchesIgnoredError(handlerFilter, err, ctx);
+            }
+        }
+        if (this.defaults.redactKeys && handlerOptions.redactKeys) {
+            merged.redactKeys = Array.from(new Set([...this.defaults.redactKeys, ...handlerOptions.redactKeys]));
+        }
+        return merged;
+    }
+}
+function matchesIgnoredError(filter, error, context) {
+    if (typeof filter === 'function')
+        return filter(error, context);
+    for (const target of filter) {
+        if (typeof target === 'function' && error instanceof target)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=dead-letter.behavior.js.map

package/dist/dead-letter.behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.behavior.js","sourceRoot":"","sources":["../src/dead-letter.behavior.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,71 @@
+import type { Constructor } from '@cqrs-ddd/pipeline';
+import type { DeadLetterRecord, DeadLetterRequestKind, DeadLetterStore } from './interfaces/dead-letter-transport.interface.js';
+/**
+ * Sends a rebuilt request back for handling. It must settle only when the
+ * handling has finished, and reject when it failed.
+ *
+ * For an event, run only the handler that failed (`record.handlerName`):
+ * publishing the event again would also rerun the handlers that succeeded.
+ */
+export type DeadLetterDispatch = (request: unknown, record: DeadLetterRecord) => Promise<unknown> | unknown;
+/** Options of {@link DeadLetterRedriver}. */
+export interface DeadLetterRedriverOptions {
+    /**
+     * The request classes that may be redriven, matched by class name against
+     * `record.requestName`. A record of any other name is refused.
+     */
+    requestTypes: readonly Constructor[];
+    /** How to dispatch a rebuilt request, per request kind. */
+    dispatch: Partial<Record<DeadLetterRequestKind, DeadLetterDispatch>>;
+    /**
+     * Builds the request from a record. Default: an instance of the registered
+     * class with the stored payload's fields, without running its constructor.
+     * Required to redrive a record whose payload was redacted: it must restore
+     * the redacted values.
+     */
+    rebuild?: (record: DeadLetterRecord, requestType: Constructor) => unknown;
+}
+/** Outcome of a successful {@link DeadLetterRedriver.redrive}. */
+export interface DeadLetterRedriveResult {
+    id: string;
+    /** What the dispatch returned. */
+    response: unknown;
+}
+/**
+ * Redrives dead letters kept by a {@link DeadLetterStore}: rebuilds the
+ * request, dispatches it, then marks the record resolved — or, when the
+ * handling fails again, counts the attempt, keeps its error, and rethrows it.
+ * During a redrive, `DeadLetterBehavior` neither captures the failure again
+ * nor swallows it.
+ *
+ * The application supplies the dispatch functions, one per request kind:
+ *
+ * @example
+ * ```ts
+ * const redriver = new DeadLetterRedriver(store, {
+ *   requestTypes: [SendWelcomeEmailCommand, UserCreatedEvent],
+ *   dispatch: {
+ *     command: (command) => commands.execute(command),
+ *     // Only the failed handler, not every subscriber of the event.
+ *     event: (event, record) => eventHandlers[record.handlerName](event),
+ *   },
+ * });
+ * await redriver.redrive(recordId);
+ * ```
+ */
+export declare class DeadLetterRedriver {
+    private readonly store;
+    private readonly options;
+    private readonly types;
+    constructor(store: DeadLetterStore, options: DeadLetterRedriverOptions);
+    /**
+     * Redrives the dead letter `id`.
+     *
+     * @throws DeadLetterRedriveError when it cannot be redriven; nothing is dispatched.
+     * @throws The handling error when the redrive fails; the attempt is counted.
+     */
+    redrive(id: string): Promise<DeadLetterRedriveResult>;
+    /** Closes the dead letter `id` without replaying it. */
+    resolve(id: string): Promise<void>;
+}
+//# sourceMappingURL=dead-letter.redriver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.redriver.d.ts","sourceRoot":"","sources":["../src/dead-letter.redriver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EAChB,MAAM,iDAAiD,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,gBAAgB,KACrB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACrE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC;CAC3E;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IAEzD,YACmB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,yBAAyB,EAGpD;IAED;;;;;OAKG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA+C1D;IAED,wDAAwD;IACxD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjC;CACF"}

package/dist/dead-letter.redriver.js

@@ -0,0 +1,81 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { DeadLetterRedriveError } from './errors/dead-letter-redrive.error.js';
+import { runAsRedrive } from './helpers/redrive-scope.js';
+/**
+ * Redrives dead letters kept by a {@link DeadLetterStore}: rebuilds the
+ * request, dispatches it, then marks the record resolved — or, when the
+ * handling fails again, counts the attempt, keeps its error, and rethrows it.
+ * During a redrive, `DeadLetterBehavior` neither captures the failure again
+ * nor swallows it.
+ *
+ * The application supplies the dispatch functions, one per request kind:
+ *
+ * @example
+ * ```ts
+ * const redriver = new DeadLetterRedriver(store, {
+ *   requestTypes: [SendWelcomeEmailCommand, UserCreatedEvent],
+ *   dispatch: {
+ *     command: (command) => commands.execute(command),
+ *     // Only the failed handler, not every subscriber of the event.
+ *     event: (event, record) => eventHandlers[record.handlerName](event),
+ *   },
+ * });
+ * await redriver.redrive(recordId);
+ * ```
+ */
+export class DeadLetterRedriver {
+    store;
+    options;
+    types;
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+        this.types = new Map(options.requestTypes.map((type) => [type.name, type]));
+    }
+    /**
+     * Redrives the dead letter `id`.
+     *
+     * @throws DeadLetterRedriveError when it cannot be redriven; nothing is dispatched.
+     * @throws The handling error when the redrive fails; the attempt is counted.
+     */
+    async redrive(id) {
+        const record = await this.store.get(id);
+        if (!record)
+            throw new DeadLetterRedriveError(id, 'no such dead letter');
+        if (record.status === 'resolved') {
+            throw new DeadLetterRedriveError(id, 'it is already resolved');
+        }
+        const requestType = this.types.get(record.requestName);
+        if (!requestType) {
+            throw new DeadLetterRedriveError(id, `request type ${record.requestName} is not registered in requestTypes`);
+        }
+        const dispatch = this.options.dispatch[record.requestKind];
+        if (!dispatch) {
+            throw new DeadLetterRedriveError(id, `no dispatch is configured for ${record.requestKind} requests`);
+        }
+        if (record.payloadRedacted && !this.options.rebuild) {
+            throw new DeadLetterRedriveError(id, 'its payload was redacted; configure rebuild to restore the redacted values');
+        }
+        const request = this.options.rebuild
+            ? this.options.rebuild(record, requestType)
+            : Object.assign(Object.create(requestType.prototype), record.payload);
+        let response;
+        try {
+            response = await runAsRedrive(id, () => dispatch(request, record));
+        }
+        catch (error) {
+            await this.store.recordAttempt(id, {
+                name: error instanceof Error ? error.name : 'unknown',
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        await this.store.markResolved(id);
+        return { id, response };
+    }
+    /** Closes the dead letter `id` without replaying it. */
+    resolve(id) {
+        return this.store.markResolved(id);
+    }
+}
+//# sourceMappingURL=dead-letter.redriver.js.map

package/dist/dead-letter.redriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.redriver.js","sourceRoot":"","sources":["../src/dead-letter.redriver.ts"],"names":[],"mappings":"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"}

package/dist/errors/dead-letter-redrive.error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Raised by `DeadLetterRedriver` when a dead letter cannot be redriven: it does
+ * not exist, is already resolved, has no registered request type or
+ * dispatcher, or its payload was redacted and no `rebuild` is configured.
+ * Nothing is dispatched and the record is unchanged.
+ */
+export declare class DeadLetterRedriveError extends Error {
+    readonly deadLetterId: string;
+    readonly reason: string;
+    readonly name = "DeadLetterRedriveError";
+    constructor(deadLetterId: string, reason: string);
+}
+//# sourceMappingURL=dead-letter-redrive.error.d.ts.map

package/dist/errors/dead-letter-redrive.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-redrive.error.d.ts","sourceRoot":"","sources":["../../src/errors/dead-letter-redrive.error.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAI7B,YAAY,EAAE,MAAM;aACpB,MAAM,EAAE,MAAM;IAJhC,SAAkB,IAAI,4BAA4B;IAElD,YACkB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EAG/B;CACF"}

package/dist/errors/dead-letter-redrive.error.js

@@ -0,0 +1,18 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Raised by `DeadLetterRedriver` when a dead letter cannot be redriven: it does
+ * not exist, is already resolved, has no registered request type or
+ * dispatcher, or its payload was redacted and no `rebuild` is configured.
+ * Nothing is dispatched and the record is unchanged.
+ */
+export class DeadLetterRedriveError extends Error {
+    deadLetterId;
+    reason;
+    name = 'DeadLetterRedriveError';
+    constructor(deadLetterId, reason) {
+        super(`Cannot redrive dead letter ${deadLetterId}: ${reason}`);
+        this.deadLetterId = deadLetterId;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=dead-letter-redrive.error.js.map

package/dist/errors/dead-letter-redrive.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-redrive.error.js","sourceRoot":"","sources":["../../src/errors/dead-letter-redrive.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAI7B,YAAY;IACZ,MAAM;IAJN,IAAI,GAAG,wBAAwB,CAAC;IAElD,YACkB,YAAoB,EACpB,MAAc;QAE9B,KAAK,CAAC,8BAA8B,YAAY,KAAK,MAAM,EAAE,CAAC,CAAC;4BAH/C,YAAY;sBACZ,MAAM;IAGxB,CAAC;CACF"}

package/dist/helpers/build-attributes.d.ts

@@ -0,0 +1,36 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+/**
+ * The dead-letter outcome of one execution as flat attributes:
+ * `{ 'dead_letter.captured': true }` when `DeadLetterBehavior` delivered a
+ * record of the failure, `{}` otherwise — a success, an ignored error, a
+ * delivery that failed, or no dead-letter behavior at all.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `DeadLetterBehavior` ran.
+ * @returns The attributes; empty unless a record was delivered.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildDeadLetterAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildDeadLetterAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export declare function buildDeadLetterAttributes(context: IPipelineContext): Record<string, boolean>;
+//# sourceMappingURL=build-attributes.d.ts.map

package/dist/helpers/build-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB"}

package/dist/helpers/build-attributes.js

@@ -0,0 +1,42 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { getPipelineItem } from '@cqrs-ddd/pipeline';
+import { DEAD_LETTER_ITEM_TOKEN } from '../dead-letter.behavior.js';
+/**
+ * The dead-letter outcome of one execution as flat attributes:
+ * `{ 'dead_letter.captured': true }` when `DeadLetterBehavior` delivered a
+ * record of the failure, `{}` otherwise — a success, an ignored error, a
+ * delivery that failed, or no dead-letter behavior at all.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `DeadLetterBehavior` ran.
+ * @returns The attributes; empty unless a record was delivered.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildDeadLetterAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildDeadLetterAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export function buildDeadLetterAttributes(context) {
+    return getPipelineItem(context, DEAD_LETTER_ITEM_TOKEN) === true
+        ? { 'dead_letter.captured': true }
+        : {};
+}
+//# sourceMappingURL=build-attributes.js.map

package/dist/helpers/build-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.js","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,eAAe,EAAyB,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAyB;IAEzB,OAAO,eAAe,CAAC,OAAO,EAAE,sBAAsB,CAAC,KAAK,IAAI;QAC9D,CAAC,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE;QAClC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/helpers/build-record.d.ts

@@ -0,0 +1,15 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { DeadLetterBehaviorOptions } from '../interfaces/dead-letter-options.interface.js';
+import type { DeadLetterRecord } from '../interfaces/dead-letter-transport.interface.js';
+/**
+ * Build a transport-neutral {@link DeadLetterRecord} from a failed pipeline run.
+ *
+ * Non-`Error` throws are normalized to a record with `name: 'unknown'` so the
+ * transport always receives a well-formed shape.
+ *
+ * @param context - The pipeline context of the failed request.
+ * @param error - The thrown value (any type).
+ * @param options - Effective behavior options (stack inclusion, metadata, redaction).
+ */
+export declare function buildDeadLetterRecord(context: IPipelineContext, error: unknown, options?: DeadLetterBehaviorOptions): DeadLetterRecord;
+//# sourceMappingURL=build-record.d.ts.map

package/dist/helpers/build-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-record.d.ts","sourceRoot":"","sources":["../../src/helpers/build-record.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAO3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gDAAgD,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AA6BzF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,gBAAgB,CA+BlB"}

package/dist/helpers/build-record.js

@@ -0,0 +1,63 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { DEFAULT_REDACT_KEYS, REDACTED, redactValue, } from '@cqrs-ddd/safe-stringify';
+import { uuidv7 } from '@cqrs-ddd/uuidv7';
+/** Redact a payload using a custom redactor or key-based masking. */
+function sanitizePayload(payload, options) {
+    if (options.redact)
+        return options.redact(payload);
+    const keys = options.redactKeys
+        ? [...DEFAULT_REDACT_KEYS, ...options.redactKeys]
+        : DEFAULT_REDACT_KEYS;
+    return redactValue(payload, keys);
+}
+/** Whether key-based redaction masked a value anywhere in `value`. */
+function containsRedacted(value, seen = new WeakSet()) {
+    if (value === REDACTED)
+        return true;
+    if (typeof value !== 'object' || value === null || seen.has(value)) {
+        return false;
+    }
+    seen.add(value);
+    const entries = value instanceof Map ? [...value.values()] : Object.values(value);
+    return entries.some((entry) => containsRedacted(entry, seen));
+}
+/**
+ * Build a transport-neutral {@link DeadLetterRecord} from a failed pipeline run.
+ *
+ * Non-`Error` throws are normalized to a record with `name: 'unknown'` so the
+ * transport always receives a well-formed shape.
+ *
+ * @param context - The pipeline context of the failed request.
+ * @param error - The thrown value (any type).
+ * @param options - Effective behavior options (stack inclusion, metadata, redaction).
+ */
+export function buildDeadLetterRecord(context, error, options = {}) {
+    const isError = error instanceof Error;
+    const userMetadata = options.metadata?.(context);
+    const payload = sanitizePayload(context.request, options);
+    return {
+        id: uuidv7(),
+        correlationId: context.correlationId,
+        tenantId: context.tenantId,
+        requestKind: context.requestKind,
+        requestName: context.requestName,
+        handlerName: context.handlerName,
+        payload,
+        error: {
+            name: isError ? error.name : 'unknown',
+            message: isError ? error.message : String(error),
+            stack: options.includeStack === false || !isError ? undefined : error.stack,
+        },
+        failedAt: new Date().toISOString(),
+        metadata: userMetadata || context.tenantId
+            ? {
+                ...(userMetadata ?? {}),
+                ...(context.tenantId ? { tenantId: context.tenantId } : {}),
+            }
+            : undefined,
+        attempts: 0,
+        status: 'open',
+        payloadRedacted: options.redact !== undefined || containsRedacted(payload),
+    };
+}
+//# sourceMappingURL=build-record.js.map