@grupodiariodaregiao/bunstone 0.3.8 → 0.3.9

package/dist/index.d.ts

@@ -39,6 +39,7 @@ export * from "./lib/bullmq/decorators/processor.decorator";
 export * from "./lib/bullmq/decorators/process.decorator";
 export { RabbitMQModule } from "./lib/rabbitmq/rabbitmq-module";
 export { RabbitMQService } from "./lib/rabbitmq/rabbitmq.service";
+export { RabbitMQDeadLetterService } from "./lib/rabbitmq/dead-letter.service";
 export { RabbitMQConnection } from "./lib/rabbitmq/rabbitmq-connection";
 export * from "./lib/rabbitmq/decorators/consumer.decorator";
 export * from "./lib/rabbitmq/decorators/subscribe.decorator";

package/dist/index.js

@@ -32209,7 +32209,7 @@ var require_node_cron = __commonJS((exports) => {
 });
 
 // index.ts
-var import_reflect_metadata28 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata29 = __toESM(require_Reflect(), 1);
 
 // lib/adapters/cache-adapter.ts
 var {RedisClient, redis } = globalThis.Bun;
@@ -116845,6 +116845,23 @@ class RabbitMQConnection {
           await channel.bindQueue(q4.name, binding.exchange, binding.routingKey ?? "", binding.arguments);
           logger2.log(`Queue "${q4.name}" bound to exchange "${binding.exchange}" with key "${binding.routingKey ?? ""}"`);
         }
+        if (q4.deadLetterQueue && q4.deadLetterExchange) {
+          const dlxType = q4.deadLetterExchangeType ?? "direct";
+          await channel.assertExchange(q4.deadLetterExchange, dlxType, {
+            durable: true,
+            autoDelete: false
+          });
+          logger2.log(`Dead letter exchange asserted: [${dlxType}] ${q4.deadLetterExchange}`);
+          await channel.assertQueue(q4.deadLetterQueue, {
+            durable: true,
+            exclusive: false,
+            autoDelete: false
+          });
+          logger2.log(`Dead letter queue asserted: ${q4.deadLetterQueue}`);
+          const dlxBindingKey = q4.deadLetterRoutingKey ?? "";
+          await channel.bindQueue(q4.deadLetterQueue, q4.deadLetterExchange, dlxBindingKey);
+          logger2.log(`DLQ "${q4.deadLetterQueue}" bound to DLX "${q4.deadLetterExchange}" with key "${dlxBindingKey}"`);
+        }
       }
     } finally {
       await channel.close().catch(() => {});
@@ -117880,8 +117897,144 @@ function Process(name3) {
     Reflect.defineMetadata(BULLMQ_PROCESS_METADATA, { name: name3 }, target2, propertyKey);
   };
 }
-// lib/rabbitmq/rabbitmq.service.ts
+// lib/rabbitmq/dead-letter.service.ts
 var import_reflect_metadata20 = __toESM(require_Reflect(), 1);
+class RabbitMQDeadLetterService {
+  logger = new Logger(RabbitMQDeadLetterService.name);
+  async inspect(queue2, count = 10) {
+    const pubCh = await RabbitMQConnection.getPublisherChannel();
+    const ch = await RabbitMQConnection.getConsumerChannel(`__dlq_inspect_${queue2}`);
+    const results = [];
+    for (let i = 0;i < count; i++) {
+      const raw = await ch.get(queue2, { noAck: false });
+      if (!raw)
+        break;
+      const data = this.parsePayload(raw);
+      const deathInfo = this.extractDeathInfo(raw);
+      results.push(this.buildWrapper(ch, raw, data, deathInfo, pubCh));
+      ch.nack(raw, false, true);
+    }
+    await ch.close().catch(() => {});
+    return results;
+  }
+  async requeueMessages(options) {
+    const { fromQueue, toExchange, routingKey, count, publishOptions } = options;
+    const ch = await RabbitMQConnection.getConsumerChannel(`__dlq_requeue_${fromQueue}`);
+    const pubCh = await RabbitMQConnection.getPublisherChannel();
+    let requeued = 0;
+    const max = count ?? Number.POSITIVE_INFINITY;
+    while (requeued < max) {
+      const raw = await ch.get(fromQueue, { noAck: false });
+      if (!raw)
+        break;
+      try {
+        const pubOpts = this.buildPublishOpts(raw, publishOptions);
+        await new Promise((resolve2, reject) => {
+          pubCh.publish(toExchange, routingKey, raw.content, pubOpts, (err) => {
+            if (err)
+              reject(err);
+            else
+              resolve2();
+          });
+        });
+        ch.ack(raw);
+        requeued++;
+      } catch (err) {
+        ch.nack(raw, false, true);
+        this.logger.error(`Failed to republish message from "${fromQueue}" to "${toExchange}/${routingKey}": ${err.message}`);
+        break;
+      }
+    }
+    await ch.close().catch(() => {});
+    this.logger.log(`Requeued ${requeued} message(s) from "${fromQueue}" to exchange "${toExchange}" (key: "${routingKey}")`);
+    return requeued;
+  }
+  async discardMessages(queue2, count) {
+    const ch = await RabbitMQConnection.getConsumerChannel(`__dlq_discard_${queue2}`);
+    let discarded = 0;
+    const max = count ?? Number.POSITIVE_INFINITY;
+    while (discarded < max) {
+      const raw = await ch.get(queue2, { noAck: false });
+      if (!raw)
+        break;
+      ch.ack(raw);
+      discarded++;
+    }
+    await ch.close().catch(() => {});
+    this.logger.log(`Discarded ${discarded} message(s) from queue "${queue2}"`);
+    return discarded;
+  }
+  async messageCount(queue2) {
+    const ch = await RabbitMQConnection.getConsumerChannel(`__dlq_count_${queue2}`);
+    const info = await ch.checkQueue(queue2);
+    await ch.close().catch(() => {});
+    return info.messageCount;
+  }
+  parsePayload(raw) {
+    try {
+      return JSON.parse(raw.content.toString("utf-8"));
+    } catch {
+      return raw.content.toString("utf-8");
+    }
+  }
+  extractDeathInfo(raw) {
+    const xDeath = raw.properties.headers?.["x-death"];
+    if (!Array.isArray(xDeath) || xDeath.length === 0)
+      return null;
+    const record2 = xDeath[0];
+    return {
+      queue: String(record2["queue"] ?? ""),
+      exchange: String(record2["exchange"] ?? ""),
+      routingKeys: Array.isArray(record2["routing-keys"]) ? record2["routing-keys"].map(String) : [],
+      count: Number(record2["count"] ?? 1),
+      reason: String(record2["reason"] ?? "rejected"),
+      time: record2["time"] instanceof Date ? record2["time"] : new Date(String(record2["time"] ?? Date.now()))
+    };
+  }
+  buildPublishOpts(raw, overrides) {
+    return {
+      persistent: overrides?.persistent ?? raw.properties.deliveryMode === 2,
+      contentType: overrides?.contentType ?? raw.properties.contentType ?? "application/json",
+      contentEncoding: overrides?.contentEncoding ?? raw.properties.contentEncoding ?? "utf-8",
+      headers: {
+        ...raw.properties.headers,
+        ...overrides?.headers,
+        "x-dlq-requeued": Number(raw.properties.headers?.["x-dlq-requeued"] ?? 0) + 1
+      },
+      correlationId: overrides?.correlationId ?? raw.properties.correlationId,
+      messageId: overrides?.messageId ?? raw.properties.messageId,
+      priority: overrides?.priority ?? raw.properties.priority,
+      expiration: overrides?.expiration !== undefined ? String(overrides.expiration) : undefined
+    };
+  }
+  buildWrapper(ch, raw, data, deathInfo, pubCh) {
+    const asMsg = raw;
+    return {
+      data,
+      raw: asMsg,
+      deathInfo,
+      ack: () => ch.ack(raw),
+      nack: (requeue = false) => ch.nack(raw, false, requeue),
+      republish: async (exchange, routingKey, options) => {
+        const pubOpts = this.buildPublishOpts(raw, options);
+        await new Promise((resolve2, reject) => {
+          pubCh.publish(exchange, routingKey, raw.content, pubOpts, (err) => {
+            if (err)
+              reject(err);
+            else
+              resolve2();
+          });
+        });
+      }
+    };
+  }
+}
+RabbitMQDeadLetterService = __legacyDecorateClassTS([
+  Injectable()
+], RabbitMQDeadLetterService);
+
+// lib/rabbitmq/rabbitmq.service.ts
+var import_reflect_metadata21 = __toESM(require_Reflect(), 1);
 class RabbitMQService {
   logger = new Logger(RabbitMQService.name);
   async publish(exchange, routingKey, data, options) {
@@ -117948,13 +118101,13 @@ class RabbitMQModule {
 }
 RabbitMQModule = __legacyDecorateClassTS([
   Module({
-    providers: [RabbitMQService],
-    exports: [RabbitMQService],
+    providers: [RabbitMQService, RabbitMQDeadLetterService],
+    exports: [RabbitMQService, RabbitMQDeadLetterService],
     global: true
   })
 ], RabbitMQModule);
 // lib/rabbitmq/decorators/consumer.decorator.ts
-var import_reflect_metadata21 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata22 = __toESM(require_Reflect(), 1);
 function RabbitConsumer() {
   return (target2) => {
     Reflect.defineMetadata(RABBITMQ_CONSUMER_METADATA, true, target2);
@@ -117962,7 +118115,7 @@ function RabbitConsumer() {
   };
 }
 // lib/rabbitmq/decorators/subscribe.decorator.ts
-var import_reflect_metadata22 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata23 = __toESM(require_Reflect(), 1);
 function RabbitSubscribe(options) {
   return (target2, propertyKey) => {
     const existing = target2[RABBITMQ_SUBSCRIBE_SYMBOL] ?? [];
@@ -117976,7 +118129,7 @@ function RabbitSubscribe(options) {
   };
 }
 // lib/guard.ts
-var import_reflect_metadata23 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata24 = __toESM(require_Reflect(), 1);
 
 // lib/utils/is-class.ts
 function isClass(fn3) {
@@ -118048,7 +118201,7 @@ function Jwt() {
   };
 }
 // lib/jwt/jwt-module.ts
-var import_reflect_metadata24 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata25 = __toESM(require_Reflect(), 1);
 
 class JwtModule {
   static options;
@@ -118064,7 +118217,7 @@ class JwtModule {
   }
 }
 // lib/schedule/cron/cron.ts
-var import_reflect_metadata25 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata26 = __toESM(require_Reflect(), 1);
 function Cron(expression) {
   if (!expression) {
     throw new Error("Invalid cron expression.");
@@ -118084,7 +118237,7 @@ function Cron(expression) {
   };
 }
 // lib/schedule/timeout/timeout.ts
-var import_reflect_metadata26 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata27 = __toESM(require_Reflect(), 1);
 function Timeout(delay2) {
   if (!delay2 || delay2 < 0) {
     throw new Error("Delay must be a positive number.");
@@ -118104,7 +118257,7 @@ function Timeout(delay2) {
   };
 }
 // lib/testing/testing-module-builder.ts
-var import_reflect_metadata27 = __toESM(require_Reflect(), 1);
+var import_reflect_metadata28 = __toESM(require_Reflect(), 1);
 
 // lib/testing/test-app.ts
 class TestApp {
@@ -118266,6 +118419,7 @@ export {
   RabbitSubscribe,
   RabbitMQService,
   RabbitMQModule,
+  RabbitMQDeadLetterService,
   RabbitMQConnection,
   RabbitConsumer,
   RENDER_METADATA,

package/dist/lib/rabbitmq/dead-letter.service.d.ts

@@ -0,0 +1,103 @@
+import "reflect-metadata";
+import type { DeadLetterMessage, RequeueOptions } from "./interfaces/rabbitmq-message.interface";
+/**
+ * Service for inspecting and reprocessing messages in Dead Letter Queues.
+ *
+ * Inject `RabbitMQDeadLetterService` wherever you need to manage failed messages –
+ * in controllers (for admin REST endpoints), scheduled tasks, or one-off scripts.
+ *
+ * @example
+ * ```typescript
+ * // Requeue all stuck orders
+ * @Get('/admin/dlq/requeue')
+ * async requeueOrders() {
+ *   const count = await this.dlq.requeueMessages({
+ *     fromQueue:  'orders.dlq',
+ *     toExchange: 'events',
+ *     routingKey: 'orders.created',
+ *   });
+ *   return { requeued: count };
+ * }
+ * ```
+ */
+export declare class RabbitMQDeadLetterService {
+    private readonly logger;
+    /**
+     * Peek at messages in a Dead Letter Queue **without permanently consuming them**.
+     *
+     * Internally uses `basic.get` + `nack(requeue=true)` so every inspected message
+     * is put back at the tail of the queue after inspection.
+     *
+     * > **Note:** Because AMQP has no native "peek" operation, there is a small
+     * > window where another consumer could receive the message between the `get`
+     * > and the `nack`. Use a dedicated DLQ that is only consumed by this service
+     * > (or consumed manually) to avoid race conditions.
+     *
+     * @param queue - Name of the dead letter queue to inspect
+     * @param count - Maximum number of messages to return. Default: `10`
+     * @returns Array of `DeadLetterMessage` wrappers with death metadata
+     *
+     * @example
+     * ```typescript
+     * const messages = await this.dlq.inspect<OrderPayload>('orders.dlq', 5);
+     * for (const msg of messages) {
+     *   console.log(msg.deathInfo?.reason, msg.data);
+     * }
+     * ```
+     */
+    inspect<T = unknown>(queue: string, count?: number): Promise<DeadLetterMessage<T>[]>;
+    /**
+     * Move messages from a Dead Letter Queue back to an exchange for reprocessing.
+     *
+     * Each message is `ack`-ed from the DLQ only **after** it is successfully
+     * republished, so no messages are lost even if publishing fails mid-batch.
+     *
+     * @param options - Source queue, target exchange/routing-key, optional count cap
+     * @returns Number of messages successfully requeued
+     *
+     * @example
+     * ```typescript
+     * // Requeue up to 50 messages back to the original exchange
+     * const n = await this.dlq.requeueMessages({
+     *   fromQueue:  'orders.dlq',
+     *   toExchange: 'events',
+     *   routingKey: 'orders.created',
+     *   count: 50,
+     * });
+     * console.log(`Requeued ${n} messages`);
+     * ```
+     */
+    requeueMessages(options: RequeueOptions): Promise<number>;
+    /**
+     * Permanently discard messages from a Dead Letter Queue by acknowledging them
+     * without republishing.
+     *
+     * @param queue - Dead letter queue name
+     * @param count - Number of messages to discard. Omit to discard **all**.
+     * @returns Number of messages discarded
+     *
+     * @example
+     * ```typescript
+     * await this.dlq.discardMessages('orders.dlq');     // purge all
+     * await this.dlq.discardMessages('orders.dlq', 10); // discard first 10
+     * ```
+     */
+    discardMessages(queue: string, count?: number): Promise<number>;
+    /**
+     * Returns the number of messages currently in a queue (including DLQs).
+     *
+     * @param queue - Queue name to check
+     * @returns Message count
+     *
+     * @example
+     * ```typescript
+     * const pending = await this.dlq.messageCount('orders.dlq');
+     * console.log(`${pending} failed orders waiting`);
+     * ```
+     */
+    messageCount(queue: string): Promise<number>;
+    private parsePayload;
+    private extractDeathInfo;
+    private buildPublishOpts;
+    private buildWrapper;
+}

package/dist/lib/rabbitmq/interfaces/rabbitmq-message.interface.d.ts

@@ -1,4 +1,76 @@
 import type { ConsumeMessage } from "amqplib";
+/**
+ * Information extracted from the `x-death` header that RabbitMQ automatically
+ * attaches to every dead-lettered message.
+ */
+export interface DeadLetterDeathInfo {
+    /** Queue where the message was dead-lettered */
+    queue: string;
+    /** Exchange where the message was originally published */
+    exchange: string;
+    /** Routing keys the message was published with */
+    routingKeys: string[];
+    /** How many times this message has been dead-lettered */
+    count: number;
+    /** Reason for dead-lettering */
+    reason: "rejected" | "expired" | "maxlen" | "delivery-limit";
+    /** Timestamp when the message was dead-lettered */
+    time: Date;
+}
+/**
+ * A message consumed from a Dead Letter Queue with extra context and
+ * a `republish()` helper for reprocessing.
+ *
+ * @example
+ * ```typescript
+ * @RabbitConsumer()
+ * export class OrderDLQConsumer {
+ *   constructor(private readonly dlq: RabbitMQDeadLetterService) {}
+ *
+ *   @RabbitSubscribe({ queue: 'orders.dlq' })
+ *   async handle(msg: DeadLetterMessage<OrderPayload>) {
+ *     console.log('Failed', msg.deathInfo?.reason, msg.data);
+ *     await msg.republish('events', 'orders.created'); // retry
+ *     msg.ack();
+ *   }
+ * }
+ * ```
+ */
+export interface DeadLetterMessage<T = unknown> {
+    /** Deserialized message payload */
+    data: T;
+    /** Raw amqplib ConsumeMessage */
+    raw: ConsumeMessage;
+    /**
+     * Death metadata provided by RabbitMQ via `x-death` headers.
+     * `null` if the message was not dead-lettered by the broker.
+     */
+    deathInfo: DeadLetterDeathInfo | null;
+    /** Acknowledge and remove the message from the DLQ */
+    ack: () => void;
+    /** Negative-ack (optionally requeue back to DLQ). Default requeue: false */
+    nack: (requeue?: boolean) => void;
+    /**
+     * Republish the message to an exchange for reprocessing.
+     * The original payload is preserved as-is.
+     */
+    republish: (exchange: string, routingKey: string, options?: RabbitPublishOptions) => Promise<void>;
+}
+/**
+ * Options for `RabbitMQDeadLetterService.requeueMessages()`.
+ */
+export interface RequeueOptions {
+    /** Dead letter queue to consume from */
+    fromQueue: string;
+    /** Exchange to republish the messages to */
+    toExchange: string;
+    /** Routing key for the republished messages */
+    routingKey: string;
+    /** Maximum number of messages to requeue. Omit to requeue all. */
+    count?: number;
+    /** Additional publish options applied during requeue */
+    publishOptions?: RabbitPublishOptions;
+}
 /**
  * A typed RabbitMQ message received by a `@RabbitSubscribe` handler.
  *

package/dist/lib/rabbitmq/interfaces/rabbitmq-options.interface.d.ts

@@ -42,6 +42,21 @@ export interface RabbitMQQueueConfig {
     deadLetterExchange?: string;
     /** Dead letter routing key */
     deadLetterRoutingKey?: string;
+    /**
+     * When provided, the lib will automatically:
+     * 1. Assert the `deadLetterExchange` (type controlled by `deadLetterExchangeType`)
+     * 2. Assert a queue with this name
+     * 3. Bind that queue to the DLX using `deadLetterRoutingKey` (or `""`)
+     *
+     * This removes the need to manually declare the DLX exchange + queue in your
+     * `exchanges` and `queues` arrays.
+     */
+    deadLetterQueue?: string;
+    /**
+     * Exchange type used when auto-asserting the dead letter exchange.
+     * Only used when `deadLetterQueue` is set. Default: `"direct"`.
+     */
+    deadLetterExchangeType?: "direct" | "topic" | "fanout";
     /** Maximum time (ms) a message can remain in the queue undelivered */
     messageTtl?: number;
     /** Maximum number of messages the queue can hold */

package/lib/rabbitmq/dead-letter.service.ts

@@ -0,0 +1,324 @@
+import "reflect-metadata";
+import type { GetMessage, Message, Options } from "amqplib";
+import { Injectable } from "../injectable";
+import { Logger } from "../utils/logger";
+import type {
+	DeadLetterDeathInfo,
+	DeadLetterMessage,
+	RabbitPublishOptions,
+	RequeueOptions,
+} from "./interfaces/rabbitmq-message.interface";
+import { RabbitMQConnection } from "./rabbitmq-connection";
+
+/**
+ * Service for inspecting and reprocessing messages in Dead Letter Queues.
+ *
+ * Inject `RabbitMQDeadLetterService` wherever you need to manage failed messages –
+ * in controllers (for admin REST endpoints), scheduled tasks, or one-off scripts.
+ *
+ * @example
+ * ```typescript
+ * // Requeue all stuck orders
+ * @Get('/admin/dlq/requeue')
+ * async requeueOrders() {
+ *   const count = await this.dlq.requeueMessages({
+ *     fromQueue:  'orders.dlq',
+ *     toExchange: 'events',
+ *     routingKey: 'orders.created',
+ *   });
+ *   return { requeued: count };
+ * }
+ * ```
+ */
+@Injectable()
+export class RabbitMQDeadLetterService {
+	private readonly logger = new Logger(RabbitMQDeadLetterService.name);
+
+	// ─── Inspect ────────────────────────────────────────────────────────────────
+
+	/**
+	 * Peek at messages in a Dead Letter Queue **without permanently consuming them**.
+	 *
+	 * Internally uses `basic.get` + `nack(requeue=true)` so every inspected message
+	 * is put back at the tail of the queue after inspection.
+	 *
+	 * > **Note:** Because AMQP has no native "peek" operation, there is a small
+	 * > window where another consumer could receive the message between the `get`
+	 * > and the `nack`. Use a dedicated DLQ that is only consumed by this service
+	 * > (or consumed manually) to avoid race conditions.
+	 *
+	 * @param queue - Name of the dead letter queue to inspect
+	 * @param count - Maximum number of messages to return. Default: `10`
+	 * @returns Array of `DeadLetterMessage` wrappers with death metadata
+	 *
+	 * @example
+	 * ```typescript
+	 * const messages = await this.dlq.inspect<OrderPayload>('orders.dlq', 5);
+	 * for (const msg of messages) {
+	 *   console.log(msg.deathInfo?.reason, msg.data);
+	 * }
+	 * ```
+	 */
+	async inspect<T = unknown>(
+		queue: string,
+		count = 10,
+	): Promise<DeadLetterMessage<T>[]> {
+		const pubCh = await RabbitMQConnection.getPublisherChannel();
+		const ch = await RabbitMQConnection.getConsumerChannel(
+			`__dlq_inspect_${queue}`,
+		);
+
+		const results: DeadLetterMessage<T>[] = [];
+
+		for (let i = 0; i < count; i++) {
+			const raw = await ch.get(queue, { noAck: false });
+			if (!raw) break;
+
+			const data = this.parsePayload<T>(raw);
+			const deathInfo = this.extractDeathInfo(raw);
+
+			results.push(this.buildWrapper<T>(ch, raw, data, deathInfo, pubCh));
+
+			// Put message back so it is not permanently consumed
+			ch.nack(raw, false, true);
+		}
+
+		// Release the inspection channel slot
+		await ch.close().catch(() => {});
+
+		return results;
+	}
+
+	// ─── Requeue ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Move messages from a Dead Letter Queue back to an exchange for reprocessing.
+	 *
+	 * Each message is `ack`-ed from the DLQ only **after** it is successfully
+	 * republished, so no messages are lost even if publishing fails mid-batch.
+	 *
+	 * @param options - Source queue, target exchange/routing-key, optional count cap
+	 * @returns Number of messages successfully requeued
+	 *
+	 * @example
+	 * ```typescript
+	 * // Requeue up to 50 messages back to the original exchange
+	 * const n = await this.dlq.requeueMessages({
+	 *   fromQueue:  'orders.dlq',
+	 *   toExchange: 'events',
+	 *   routingKey: 'orders.created',
+	 *   count: 50,
+	 * });
+	 * console.log(`Requeued ${n} messages`);
+	 * ```
+	 */
+	async requeueMessages(options: RequeueOptions): Promise<number> {
+		const { fromQueue, toExchange, routingKey, count, publishOptions } =
+			options;
+
+		const ch = await RabbitMQConnection.getConsumerChannel(
+			`__dlq_requeue_${fromQueue}`,
+		);
+		const pubCh = await RabbitMQConnection.getPublisherChannel();
+
+		let requeued = 0;
+		const max = count ?? Number.POSITIVE_INFINITY;
+
+		while (requeued < max) {
+			const raw = await ch.get(fromQueue, { noAck: false });
+			if (!raw) break;
+
+			try {
+				const pubOpts = this.buildPublishOpts(raw, publishOptions);
+
+				await new Promise<void>((resolve, reject) => {
+					pubCh.publish(toExchange, routingKey, raw.content, pubOpts, (err) => {
+						if (err) reject(err);
+						else resolve();
+					});
+				});
+
+				ch.ack(raw);
+				requeued++;
+			} catch (err: any) {
+				// Put the message back so it is not lost
+				ch.nack(raw, false, true);
+				this.logger.error(
+					`Failed to republish message from "${fromQueue}" to "${toExchange}/${routingKey}": ${err.message}`,
+				);
+				break;
+			}
+		}
+
+		await ch.close().catch(() => {});
+
+		this.logger.log(
+			`Requeued ${requeued} message(s) from "${fromQueue}" to exchange "${toExchange}" (key: "${routingKey}")`,
+		);
+
+		return requeued;
+	}
+
+	// ─── Discard ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Permanently discard messages from a Dead Letter Queue by acknowledging them
+	 * without republishing.
+	 *
+	 * @param queue - Dead letter queue name
+	 * @param count - Number of messages to discard. Omit to discard **all**.
+	 * @returns Number of messages discarded
+	 *
+	 * @example
+	 * ```typescript
+	 * await this.dlq.discardMessages('orders.dlq');     // purge all
+	 * await this.dlq.discardMessages('orders.dlq', 10); // discard first 10
+	 * ```
+	 */
+	async discardMessages(queue: string, count?: number): Promise<number> {
+		const ch = await RabbitMQConnection.getConsumerChannel(
+			`__dlq_discard_${queue}`,
+		);
+
+		let discarded = 0;
+		const max = count ?? Number.POSITIVE_INFINITY;
+
+		while (discarded < max) {
+			const raw = await ch.get(queue, { noAck: false });
+			if (!raw) break;
+
+			ch.ack(raw);
+			discarded++;
+		}
+
+		await ch.close().catch(() => {});
+
+		this.logger.log(`Discarded ${discarded} message(s) from queue "${queue}"`);
+		return discarded;
+	}
+
+	// ─── Count ───────────────────────────────────────────────────────────────
+
+	/**
+	 * Returns the number of messages currently in a queue (including DLQs).
+	 *
+	 * @param queue - Queue name to check
+	 * @returns Message count
+	 *
+	 * @example
+	 * ```typescript
+	 * const pending = await this.dlq.messageCount('orders.dlq');
+	 * console.log(`${pending} failed orders waiting`);
+	 * ```
+	 */
+	async messageCount(queue: string): Promise<number> {
+		const ch = await RabbitMQConnection.getConsumerChannel(
+			`__dlq_count_${queue}`,
+		);
+
+		const info = await ch.checkQueue(queue);
+		await ch.close().catch(() => {});
+		return info.messageCount;
+	}
+
+	// ─── Private helpers ──────────────────────────────────────────────────────
+
+	private parsePayload<T>(raw: GetMessage): T {
+		try {
+			return JSON.parse(raw.content.toString("utf-8")) as T;
+		} catch {
+			return raw.content.toString("utf-8") as unknown as T;
+		}
+	}
+
+	private extractDeathInfo(raw: GetMessage): DeadLetterDeathInfo | null {
+		const xDeath = raw.properties.headers?.["x-death"];
+		if (!Array.isArray(xDeath) || xDeath.length === 0) return null;
+
+		// The most recent death record is the first entry
+		const record = xDeath[0] as unknown as Record<string, unknown>;
+
+		return {
+			queue: String(record["queue"] ?? ""),
+			exchange: String(record["exchange"] ?? ""),
+			routingKeys: Array.isArray(record["routing-keys"])
+				? (record["routing-keys"] as any[]).map(String)
+				: [],
+			count: Number(record["count"] ?? 1),
+			reason: String(
+				record["reason"] ?? "rejected",
+			) as DeadLetterDeathInfo["reason"],
+			time:
+				record["time"] instanceof Date
+					? record["time"]
+					: new Date(String(record["time"] ?? Date.now())),
+		};
+	}
+
+	private buildPublishOpts(
+		raw: GetMessage,
+		overrides?: RabbitPublishOptions,
+	): Options.Publish {
+		return {
+			persistent: overrides?.persistent ?? raw.properties.deliveryMode === 2,
+			contentType:
+				overrides?.contentType ??
+				raw.properties.contentType ??
+				"application/json",
+			contentEncoding:
+				overrides?.contentEncoding ?? raw.properties.contentEncoding ?? "utf-8",
+			headers: {
+				...raw.properties.headers,
+				...overrides?.headers,
+				// Track how many times this message has been manually requeued from a DLQ
+				"x-dlq-requeued":
+					Number(raw.properties.headers?.["x-dlq-requeued"] ?? 0) + 1,
+			},
+			correlationId: overrides?.correlationId ?? raw.properties.correlationId,
+			messageId: overrides?.messageId ?? raw.properties.messageId,
+			priority: overrides?.priority ?? raw.properties.priority,
+			expiration:
+				overrides?.expiration !== undefined
+					? String(overrides.expiration)
+					: undefined,
+		};
+	}
+
+	private buildWrapper<T>(
+		ch: any,
+		raw: GetMessage,
+		data: T,
+		deathInfo: DeadLetterDeathInfo | null,
+		pubCh: any,
+	): DeadLetterMessage<T> {
+		// GetMessage and ConsumeMessage share the same structure except for the
+		// consumerTag field in fields. Cast here for interface compatibility.
+		const asMsg = raw as unknown as Message;
+		return {
+			data,
+			raw: asMsg as any,
+			deathInfo,
+			ack: () => ch.ack(raw),
+			nack: (requeue = false) => ch.nack(raw, false, requeue),
+			republish: async (
+				exchange: string,
+				routingKey: string,
+				options?: RabbitPublishOptions,
+			) => {
+				const pubOpts = this.buildPublishOpts(raw, options);
+				await new Promise<void>((resolve, reject) => {
+					pubCh.publish(
+						exchange,
+						routingKey,
+						raw.content,
+						pubOpts,
+						(err: Error | null) => {
+							if (err) reject(err);
+							else resolve();
+						},
+					);
+				});
+			},
+		};
+	}
+}

package/lib/rabbitmq/interfaces/rabbitmq-message.interface.ts

@@ -1,5 +1,88 @@
 import type { ConsumeMessage } from "amqplib";
 
+// ─── Dead Letter types ──────────────────────────────────────────────────────
+
+/**
+ * Information extracted from the `x-death` header that RabbitMQ automatically
+ * attaches to every dead-lettered message.
+ */
+export interface DeadLetterDeathInfo {
+	/** Queue where the message was dead-lettered */
+	queue: string;
+	/** Exchange where the message was originally published */
+	exchange: string;
+	/** Routing keys the message was published with */
+	routingKeys: string[];
+	/** How many times this message has been dead-lettered */
+	count: number;
+	/** Reason for dead-lettering */
+	reason: "rejected" | "expired" | "maxlen" | "delivery-limit";
+	/** Timestamp when the message was dead-lettered */
+	time: Date;
+}
+
+/**
+ * A message consumed from a Dead Letter Queue with extra context and
+ * a `republish()` helper for reprocessing.
+ *
+ * @example
+ * ```typescript
+ * @RabbitConsumer()
+ * export class OrderDLQConsumer {
+ *   constructor(private readonly dlq: RabbitMQDeadLetterService) {}
+ *
+ *   @RabbitSubscribe({ queue: 'orders.dlq' })
+ *   async handle(msg: DeadLetterMessage<OrderPayload>) {
+ *     console.log('Failed', msg.deathInfo?.reason, msg.data);
+ *     await msg.republish('events', 'orders.created'); // retry
+ *     msg.ack();
+ *   }
+ * }
+ * ```
+ */
+export interface DeadLetterMessage<T = unknown> {
+	/** Deserialized message payload */
+	data: T;
+	/** Raw amqplib ConsumeMessage */
+	raw: ConsumeMessage;
+	/**
+	 * Death metadata provided by RabbitMQ via `x-death` headers.
+	 * `null` if the message was not dead-lettered by the broker.
+	 */
+	deathInfo: DeadLetterDeathInfo | null;
+	/** Acknowledge and remove the message from the DLQ */
+	ack: () => void;
+	/** Negative-ack (optionally requeue back to DLQ). Default requeue: false */
+	nack: (requeue?: boolean) => void;
+	/**
+	 * Republish the message to an exchange for reprocessing.
+	 * The original payload is preserved as-is.
+	 */
+	republish: (
+		exchange: string,
+		routingKey: string,
+		options?: RabbitPublishOptions,
+	) => Promise<void>;
+}
+
+/**
+ * Options for `RabbitMQDeadLetterService.requeueMessages()`.
+ */
+export interface RequeueOptions {
+	/** Dead letter queue to consume from */
+	fromQueue: string;
+	/** Exchange to republish the messages to */
+	toExchange: string;
+	/** Routing key for the republished messages */
+	routingKey: string;
+	/** Maximum number of messages to requeue. Omit to requeue all. */
+	count?: number;
+	/** Additional publish options applied during requeue */
+	publishOptions?: RabbitPublishOptions;
+}
+
+// ─── Standard message ───────────────────────────────────────────────────────
+
 /**
  * A typed RabbitMQ message received by a `@RabbitSubscribe` handler.
  *

package/lib/rabbitmq/interfaces/rabbitmq-options.interface.ts

@@ -44,6 +44,21 @@ export interface RabbitMQQueueConfig {
 	deadLetterExchange?: string;
 	/** Dead letter routing key */
 	deadLetterRoutingKey?: string;
+	/**
+	 * When provided, the lib will automatically:
+	 * 1. Assert the `deadLetterExchange` (type controlled by `deadLetterExchangeType`)
+	 * 2. Assert a queue with this name
+	 * 3. Bind that queue to the DLX using `deadLetterRoutingKey` (or `""`)
+	 *
+	 * This removes the need to manually declare the DLX exchange + queue in your
+	 * `exchanges` and `queues` arrays.
+	 */
+	deadLetterQueue?: string;
+	/**
+	 * Exchange type used when auto-asserting the dead letter exchange.
+	 * Only used when `deadLetterQueue` is set. Default: `"direct"`.
+	 */
+	deadLetterExchangeType?: "direct" | "topic" | "fanout";
 	/** Maximum time (ms) a message can remain in the queue undelivered */
 	messageTtl?: number;
 	/** Maximum number of messages the queue can hold */

package/lib/rabbitmq/rabbitmq-connection.ts

@@ -243,6 +243,38 @@ export class RabbitMQConnection {
 						`Queue "${q.name}" bound to exchange "${binding.exchange}" with key "${binding.routingKey ?? ""}"`,
 					);
 				}
+
+				// ── Auto Dead Letter topology ──────────────────────────────────
+				// When `deadLetterQueue` + `deadLetterExchange` are both set, the lib
+				// automatically asserts the DLX exchange, the DLQ queue, and their binding.
+				// This removes the need to declare them manually in exchanges/queues arrays.
+				if (q.deadLetterQueue && q.deadLetterExchange) {
+					const dlxType = q.deadLetterExchangeType ?? "direct";
+					await channel.assertExchange(q.deadLetterExchange, dlxType, {
+						durable: true,
+						autoDelete: false,
+					});
+					logger.log(
+						`Dead letter exchange asserted: [${dlxType}] ${q.deadLetterExchange}`,
+					);
+
+					await channel.assertQueue(q.deadLetterQueue, {
+						durable: true,
+						exclusive: false,
+						autoDelete: false,
+					});
+					logger.log(`Dead letter queue asserted: ${q.deadLetterQueue}`);
+
+					const dlxBindingKey = q.deadLetterRoutingKey ?? "";
+					await channel.bindQueue(
+						q.deadLetterQueue,
+						q.deadLetterExchange,
+						dlxBindingKey,
+					);
+					logger.log(
+						`DLQ "${q.deadLetterQueue}" bound to DLX "${q.deadLetterExchange}" with key "${dlxBindingKey}"`,
+					);
+				}
 			}
 		} finally {
 			await channel.close().catch(() => {});

package/lib/rabbitmq/rabbitmq-module.ts

@@ -1,4 +1,5 @@
 import { Module } from "../module";
+import { RabbitMQDeadLetterService } from "./dead-letter.service";
 import type { RabbitMQModuleOptions } from "./interfaces/rabbitmq-options.interface";
 import { RabbitMQService } from "./rabbitmq.service";
 import { RabbitMQConnection } from "./rabbitmq-connection";
@@ -33,8 +34,8 @@ import { RabbitMQConnection } from "./rabbitmq-connection";
  * ```
  */
 @Module({
-	providers: [RabbitMQService],
-	exports: [RabbitMQService],
+	providers: [RabbitMQService, RabbitMQDeadLetterService],
+	exports: [RabbitMQService, RabbitMQDeadLetterService],
 	global: true,
 })
 export class RabbitMQModule {

package/package.json

@@ -13,7 +13,7 @@
       "types": "./dist/*.d.ts"
     }
   },
-  "version": "0.3.8",
+  "version": "0.3.9",
   "homepage": "https://bunstone.diario.one/",
   "repository": {
     "url": "https://github.com/diariodaregiao/bunstone.git",