@cqrs-ddd/pipeline-deadletter 0.5.0

package/dist/transports/rabbitmq.transport.d.ts

@@ -0,0 +1,56 @@
+import type { DeadLetterRecord, DeadLetterTransport } from '../interfaces/dead-letter-transport.interface.js';
+/**
+ * Minimal structural shape of an `amqplib` `ConfirmChannel`. Declared locally
+ * so this package does not hard-depend on `amqplib`. Add it in your app with
+ * `pnpm add amqplib` and create it via `connection.createConfirmChannel()`.
+ */
+export interface RabbitMqConfirmChannelLike {
+    publish(exchange: string, routingKey: string, content: Buffer, options?: unknown): boolean;
+    /** Waits until the broker acknowledges or rejects all outstanding publishes. */
+    waitForConfirms(): Promise<void>;
+    /** EventEmitter lifecycle hook exposed by real amqplib channels. */
+    once?(event: 'drain' | 'close' | 'error', listener: (error?: Error) => void): unknown;
+    /** Removes lifecycle listeners after the backpressure wait settles. */
+    removeListener?(event: 'drain' | 'close' | 'error', listener: (error?: Error) => void): unknown;
+}
+/** Options for {@link RabbitMqDeadLetterTransport}. */
+export interface RabbitMqDeadLetterTransportOptions {
+    /**
+     * Exchange to publish to. Default `''` (the AMQP default exchange), in which
+     * case `routingKey` is treated as the destination queue name.
+     */
+    exchange?: string;
+    /** Routing key (or queue name with the default exchange). Default `'dead-letter'`. */
+    routingKey?: string;
+    /**
+     * Extra `amqplib` publish options, merged over the defaults
+     * `{ persistent: true, contentType: 'application/json', correlationId }`.
+     */
+    publishOptions?: Record<string, unknown>;
+}
+/**
+ * {@link DeadLetterTransport} backed by **RabbitMQ** (`amqplib`).
+ *
+ * Publishes each dead letter as a persistent JSON message and waits for a
+ * broker publisher-confirm acknowledgement before reporting success. Make sure
+ * the target exchange/queue exists (`channel.assertQueue(...)`) before use.
+ *
+ * @example
+ * ```ts
+ * const conn = await amqp.connect(process.env.AMQP_URL);
+ * const channel = await conn.createConfirmChannel();
+ * await channel.assertQueue('dead-letters', { durable: true });
+ * const transport = new RabbitMqDeadLetterTransport(channel, { routingKey: 'dead-letters' });
+ * ```
+ */
+export declare class RabbitMqDeadLetterTransport implements DeadLetterTransport {
+    private readonly channel;
+    private readonly exchange;
+    private readonly routingKey;
+    private readonly publishOptions;
+    constructor(channel: RabbitMqConfirmChannelLike, options?: RabbitMqDeadLetterTransportOptions);
+    send(record: DeadLetterRecord): Promise<void>;
+    /** Waits for flow control to recover, rejecting if the channel dies first. */
+    private waitForDrain;
+}
+//# sourceMappingURL=rabbitmq.transport.d.ts.map

package/dist/transports/rabbitmq.transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rabbitmq.transport.d.ts","sourceRoot":"","sources":["../../src/transports/rabbitmq.transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kDAAkD,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC;IACX,gFAAgF;IAChF,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,oEAAoE;IACpE,IAAI,CAAC,CACH,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,EAClC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,GAChC,OAAO,CAAC;IACX,uEAAuE;IACvE,cAAc,CAAC,CACb,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,EAClC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,GAChC,OAAO,CAAC;CACZ;AAED,uDAAuD;AACvD,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,2BAA4B,YAAW,mBAAmB;IAMnE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IAEzD,YACmB,OAAO,EAAE,0BAA0B,EACpD,OAAO,GAAE,kCAAuC,EAUjD;IAEK,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBlD;IAED,8EAA8E;YAChE,YAAY;CA2C3B"}

package/dist/transports/rabbitmq.transport.js

@@ -0,0 +1,82 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * {@link DeadLetterTransport} backed by **RabbitMQ** (`amqplib`).
+ *
+ * Publishes each dead letter as a persistent JSON message and waits for a
+ * broker publisher-confirm acknowledgement before reporting success. Make sure
+ * the target exchange/queue exists (`channel.assertQueue(...)`) before use.
+ *
+ * @example
+ * ```ts
+ * const conn = await amqp.connect(process.env.AMQP_URL);
+ * const channel = await conn.createConfirmChannel();
+ * await channel.assertQueue('dead-letters', { durable: true });
+ * const transport = new RabbitMqDeadLetterTransport(channel, { routingKey: 'dead-letters' });
+ * ```
+ */
+export class RabbitMqDeadLetterTransport {
+    channel;
+    exchange;
+    routingKey;
+    publishOptions;
+    constructor(channel, options = {}) {
+        this.channel = channel;
+        if (typeof channel.waitForConfirms !== 'function') {
+            throw new TypeError('RabbitMqDeadLetterTransport requires an amqplib ConfirmChannel.');
+        }
+        this.exchange = options.exchange ?? '';
+        this.routingKey = options.routingKey ?? 'dead-letter';
+        this.publishOptions = options.publishOptions ?? {};
+    }
+    async send(record) {
+        const content = Buffer.from(JSON.stringify(record));
+        const options = {
+            persistent: true,
+            contentType: 'application/json',
+            correlationId: record.correlationId,
+            ...this.publishOptions,
+        };
+        const writable = this.channel.publish(this.exchange, this.routingKey, content, options);
+        // amqplib models publish() after stream.Writable: false means the message
+        // was buffered successfully but callers should stop writing until `drain`.
+        // It is not a publish failure and must not be surfaced as one.
+        if (!writable) {
+            await Promise.all([this.waitForDrain(), this.channel.waitForConfirms()]);
+            return;
+        }
+        await this.channel.waitForConfirms();
+    }
+    /** Waits for flow control to recover, rejecting if the channel dies first. */
+    async waitForDrain() {
+        const { once, removeListener } = this.channel;
+        if (!once || !removeListener) {
+            throw new Error('RabbitMQ channel reported backpressure but does not expose EventEmitter lifecycle methods.');
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                removeListener.call(this.channel, 'drain', onDrain);
+                removeListener.call(this.channel, 'close', onClose);
+                removeListener.call(this.channel, 'error', onError);
+            };
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const onDrain = () => finish();
+            const onClose = () => finish(new Error('RabbitMQ channel closed while waiting for publish backpressure to drain.'));
+            const onError = (error) => finish(error ??
+                new Error('RabbitMQ channel failed while waiting for publish backpressure to drain.'));
+            once.call(this.channel, 'drain', onDrain);
+            once.call(this.channel, 'close', onClose);
+            once.call(this.channel, 'error', onError);
+        });
+    }
+}
+//# sourceMappingURL=rabbitmq.transport.js.map

package/dist/transports/rabbitmq.transport.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@cqrs-ddd/pipeline-deadletter",
+  "version": "0.5.0",
+  "description": "Dead letters for @cqrs-ddd/pipeline: captures failed commands and events with their context to a queue or table, and redrives them",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "dead-letter",
+    "dlq",
+    "redrive",
+    "bullmq",
+    "rabbitmq",
+    "postgres",
+    "retry",
+    "resilience",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-deadletter"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-deadletter/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "dependencies": {
+    "@cqrs-ddd/uuidv7": "^0.5.0",
+    "@cqrs-ddd/safe-stringify": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}