@grupodiariodaregiao/bunstone 0.3.12 → 0.4.1

package/dist/index.js

@@ -116733,6 +116733,20 @@ class RabbitMQConnection {
     RabbitMQConnection.consumerChannels.set(queue2, channel);
     return channel;
   }
+  static async createRoutingKeyConsumerChannel(exchange, routingKey) {
+    const connection2 = await RabbitMQConnection.getConnection();
+    const channel = await connection2.createChannel();
+    const prefetch = RabbitMQConnection.options?.prefetch ?? 10;
+    await channel.prefetch(prefetch);
+    const { queue: queueName } = await channel.assertQueue("", {
+      exclusive: true,
+      autoDelete: true,
+      durable: false
+    });
+    await channel.bindQueue(queueName, exchange, routingKey);
+    logger2.log(`Routing-key consumer queue "${queueName}" bound to exchange "${exchange}" with key "${routingKey}"`);
+    return { channel, queueName };
+  }
   static async initialise() {
     await RabbitMQConnection.getConnection();
   }
@@ -117576,42 +117590,114 @@ if (document.readyState === 'loading') {
         AppStartup.logger.error(`RabbitMQ initialisation failed: ${err.message}`);
         return;
       }
+      const queueMap = new Map;
       for (const [providerClass, descriptors] of providersRabbitMQ.entries()) {
         const instance = injectables?.get(providerClass) ?? new providerClass;
         for (const descriptor of descriptors) {
-          const { queue: queue2, noAck = false } = descriptor.options;
-          AppStartup.logger.log(`Registering RabbitMQ consumer for queue: "${queue2}" \u2192 ${providerClass.name}.${descriptor.methodName}()`);
-          try {
-            const channel = await RabbitMQConnection.getConsumerChannel(queue2);
-            await channel.consume(queue2, async (raw) => {
-              if (!raw)
-                return;
-              const data = (() => {
+          const {
+            queue: queue2,
+            exchange,
+            routingKey,
+            noAck = false
+          } = descriptor.options;
+          if (exchange && routingKey) {
+            AppStartup.logger.log(`Registering RabbitMQ consumer for exchange: "${exchange}" routingKey: "${routingKey}" \u2192 ${providerClass.name}.${descriptor.methodName}()`);
+            try {
+              const { channel, queueName } = await RabbitMQConnection.createRoutingKeyConsumerChannel(exchange, routingKey);
+              await channel.consume(queueName, async (raw) => {
+                if (!raw)
+                  return;
+                const data = (() => {
+                  try {
+                    return JSON.parse(raw.content.toString());
+                  } catch {
+                    return raw.content.toString();
+                  }
+                })();
+                const msg = {
+                  data,
+                  raw,
+                  ack: () => channel.ack(raw),
+                  nack: (requeue = true) => channel.nack(raw, false, requeue),
+                  reject: () => channel.reject(raw, false)
+                };
                 try {
-                  return JSON.parse(raw.content.toString());
-                } catch {
-                  return raw.content.toString();
+                  await instance[descriptor.methodName](msg);
+                } catch (err) {
+                  AppStartup.logger.error(`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on exchange "${exchange}" routingKey "${routingKey}": ${err.message}`);
+                  if (!noAck) {
+                    channel.nack(raw, false, true);
+                  }
                 }
-              })();
-              const msg = {
-                data,
-                raw,
-                ack: () => channel.ack(raw),
-                nack: (requeue = true) => channel.nack(raw, false, requeue),
-                reject: () => channel.reject(raw, false)
-              };
+              }, { noAck });
+            } catch (err) {
+              AppStartup.logger.error(`Failed to register consumer for exchange "${exchange}" routingKey "${routingKey}": ${err.message}`);
+            }
+            continue;
+          }
+          if (!queue2) {
+            AppStartup.logger.warn(`@RabbitSubscribe on ${providerClass.name}.${descriptor.methodName}() has neither 'queue' nor 'exchange'+'routingKey' \u2013 skipping.`);
+            continue;
+          }
+          if (!queueMap.has(queue2))
+            queueMap.set(queue2, []);
+          const queueHandlers = queueMap.get(queue2);
+          queueHandlers.push({
+            instance,
+            descriptor,
+            noAck,
+            providerName: providerClass.name
+          });
+        }
+      }
+      for (const [queue2, handlers] of queueMap.entries()) {
+        const noAck = handlers.every((h3) => h3.noAck);
+        const handlerList = handlers.map((h3) => `${h3.providerName}.${h3.descriptor.methodName}()`).join(", ");
+        AppStartup.logger.log(`Registering RabbitMQ consumer for queue: "${queue2}" \u2192 [${handlerList}]`);
+        try {
+          const channel = await RabbitMQConnection.getConsumerChannel(queue2);
+          await channel.consume(queue2, async (raw) => {
+            if (!raw)
+              return;
+            const data = (() => {
+              try {
+                return JSON.parse(raw.content.toString());
+              } catch {
+                return raw.content.toString();
+              }
+            })();
+            let settled = false;
+            const settle = (fn3) => {
+              if (!settled) {
+                settled = true;
+                fn3();
+              }
+            };
+            const msg = {
+              data,
+              raw,
+              ack: () => settle(() => channel.ack(raw)),
+              nack: (requeue = true) => settle(() => channel.nack(raw, false, requeue)),
+              reject: () => settle(() => channel.reject(raw, false))
+            };
+            for (const {
+              instance,
+              descriptor,
+              noAck: handlerNoAck,
+              providerName
+            } of handlers) {
               try {
                 await instance[descriptor.methodName](msg);
               } catch (err) {
-                AppStartup.logger.error(`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on queue "${queue2}": ${err.message}`);
-                if (!noAck) {
-                  channel.nack(raw, false, true);
+                AppStartup.logger.error(`Unhandled error in RabbitMQ handler ${providerName}.${descriptor.methodName}() on queue "${queue2}": ${err.message}`);
+                if (!handlerNoAck && !settled) {
+                  settle(() => channel.nack(raw, false, true));
                 }
               }
-            }, { noAck });
-          } catch (err) {
-            AppStartup.logger.error(`Failed to register consumer for queue "${queue2}": ${err.message}`);
-          }
+            }
+          }, { noAck });
+        } catch (err) {
+          AppStartup.logger.error(`Failed to register consumer for queue "${queue2}": ${err.message}`);
         }
       }
     })();

package/dist/lib/app-startup.d.ts

@@ -80,6 +80,14 @@ export declare class AppStartup {
     /**
      * Sets up RabbitMQ consumers for every provider that has `@RabbitSubscribe`
      * methods registered in the given module.
+     *
+     * Queue mode (fan-out): all handlers subscribed to the same named queue share a
+     * single AMQP consumer. Every message is delivered to ALL handlers in declaration
+     * order. A "settle guard" ensures ack/nack/reject is called only once per message
+     * regardless of how many handlers invoke it.
+     *
+     * Routing-key mode: each handler gets its own exclusive auto-delete queue bound
+     * to the exchange, so the broker itself handles fan-out.
      */
     private static registerRabbitMQConsumers;
     private static registerCqrsHandlers;

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

@@ -120,13 +120,51 @@ export interface RabbitPublishOptions {
 }
 /**
  * Options for the `@RabbitSubscribe` method decorator.
+ *
+ * Two usage modes:
+ *
+ * 1. **Direct queue** – set `queue` to consume from a named queue.
+ * 2. **Routing key** – set `exchange` + `routingKey` to subscribe to a topic/direct
+ *    exchange with a specific routing key pattern. The lib creates an exclusive
+ *    auto-delete queue per handler, so **every** handler bound to the same routing
+ *    key receives its own copy of the message (fan-out per key).
+ *
+ * @example Queue mode
+ * ```typescript
+ * @RabbitSubscribe({ queue: 'orders.created' })
+ * async handle(msg: RabbitMessage<Order>) { msg.ack(); }
+ * ```
+ *
+ * @example Routing key mode
+ * ```typescript
+ * @RabbitSubscribe({ exchange: 'events', routingKey: 'article.published' })
+ * async onPublished(msg: RabbitMessage<Article>) { msg.ack(); }
+ * ```
  */
 export interface RabbitSubscribeOptions {
     /**
      * Queue to consume messages from.
      * The queue must be declared either via `RabbitMQModule.register({ queues: [...] })` or by the broker.
+     * Mutually exclusive with `exchange` + `routingKey`.
      */
-    queue: string;
+    queue?: string;
+    /**
+     * Exchange name to bind to. Must be used together with `routingKey`.
+     * The lib automatically creates an exclusive auto-delete queue for each handler
+     * and binds it to this exchange, so all handlers for the same routing key
+     * receive a copy of every published message.
+     */
+    exchange?: string;
+    /**
+     * Routing key to subscribe to. Supports wildcards for topic exchanges:
+     * - `*` matches exactly one word
+     * - `#` matches zero or more words
+     *
+     * Examples: `article.published`, `article.*`, `article.#`
+     *
+     * Must be used together with `exchange`.
+     */
+    routingKey?: string;
     /**
      * When `true`, messages are automatically acknowledged as soon as they are delivered.
      * When `false` (default), you must call `msg.ack()` / `msg.nack()` manually.

package/dist/lib/rabbitmq/rabbitmq-connection.d.ts

@@ -27,6 +27,20 @@ export declare class RabbitMQConnection {
      * Each queue gets its own channel so that prefetch applies per-queue.
      */
     static getConsumerChannel(queue: string): Promise<Channel>;
+    /**
+     * Creates a **new** channel with an exclusive, auto-delete server-named queue
+     * bound to `exchange` with `routingKey`.
+     *
+     * Because each call creates an independent queue, every handler that subscribes
+     * to the same exchange + routing key receives its own copy of the message
+     * (fan-out behaviour per routing key).
+     *
+     * The channel and queue are **not** cached – each call returns a fresh pair.
+     */
+    static createRoutingKeyConsumerChannel(exchange: string, routingKey: string): Promise<{
+        channel: Channel;
+        queueName: string;
+    }>;
     /**
      * Initialises the connection, asserts all configured exchanges and queues,
      * then resolves. Safe to call multiple times – returns the same promise.

package/lib/app-startup.ts

@@ -857,6 +857,14 @@ if (document.readyState === 'loading') {
 	/**
 	 * Sets up RabbitMQ consumers for every provider that has `@RabbitSubscribe`
 	 * methods registered in the given module.
+	 *
+	 * Queue mode (fan-out): all handlers subscribed to the same named queue share a
+	 * single AMQP consumer. Every message is delivered to ALL handlers in declaration
+	 * order. A "settle guard" ensures ack/nack/reject is called only once per message
+	 * regardless of how many handlers invoke it.
+	 *
+	 * Routing-key mode: each handler gets its own exclusive auto-delete queue bound
+	 * to the exchange, so the broker itself handles fan-out.
 	 */
 	private static registerRabbitMQConsumers(module: any): void {
 		const providersRabbitMQ: Map<any, RabbitMQMethodDescriptor[]> | undefined =
@@ -871,6 +879,13 @@ if (document.readyState === 'loading') {
 			module,
 		);
 
+		type QueueHandler = {
+			instance: any;
+			descriptor: RabbitMQMethodDescriptor;
+			noAck: boolean;
+			providerName: string;
+		};
+
 		// Fire-and-forget – connect asynchronously so startup is never blocked
 		(async () => {
 			try {
@@ -882,59 +897,170 @@ if (document.readyState === 'loading') {
 				return;
 			}
 
+			// ── Step 1: separate routing-key handlers from named-queue handlers ──
+			// Named-queue handlers are grouped by queue name so that a single AMQP
+			// consumer is created per queue and every message is fanned-out to all
+			// registered handlers in-process.
+			const queueMap = new Map<string, QueueHandler[]>();
+
 			for (const [providerClass, descriptors] of providersRabbitMQ.entries()) {
 				const instance = injectables?.get(providerClass) ?? new providerClass();
 
 				for (const descriptor of descriptors) {
-					const { queue, noAck = false } = descriptor.options;
+					const {
+						queue,
+						exchange,
+						routingKey,
+						noAck = false,
+					} = descriptor.options;
+
+					// ── Routing-key mode: exchange + routingKey ─────────────────────
+					if (exchange && routingKey) {
+						AppStartup.logger.log(
+							`Registering RabbitMQ consumer for exchange: "${exchange}" routingKey: "${routingKey}" → ${providerClass.name}.${descriptor.methodName}()`,
+						);
 
-					AppStartup.logger.log(
-						`Registering RabbitMQ consumer for queue: "${queue}" → ${providerClass.name}.${descriptor.methodName}()`,
-					);
+						try {
+							const { channel, queueName } =
+								await RabbitMQConnection.createRoutingKeyConsumerChannel(
+									exchange,
+									routingKey,
+								);
 
-					try {
-						const channel = await RabbitMQConnection.getConsumerChannel(queue);
+							await channel.consume(
+								queueName,
+								async (raw) => {
+									if (!raw) return;
 
-						await channel.consume(
-							queue,
-							async (raw) => {
-								if (!raw) return; // consumer cancelled
+									const data = (() => {
+										try {
+											return JSON.parse(raw.content.toString());
+										} catch {
+											return raw.content.toString();
+										}
+									})();
+
+									const msg: RabbitMessage = {
+										data,
+										raw,
+										ack: () => channel.ack(raw),
+										nack: (requeue = true) => channel.nack(raw, false, requeue),
+										reject: () => channel.reject(raw, false),
+									};
 
-								const data = (() => {
 									try {
-										return JSON.parse(raw.content.toString());
-									} catch {
-										return raw.content.toString();
+										await instance[descriptor.methodName](msg);
+									} catch (err: any) {
+										AppStartup.logger.error(
+											`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on exchange "${exchange}" routingKey "${routingKey}": ${err.message}`,
+										);
+										if (!noAck) {
+											channel.nack(raw, false, true);
+										}
 									}
-								})();
+								},
+								{ noAck },
+							);
+						} catch (err: any) {
+							AppStartup.logger.error(
+								`Failed to register consumer for exchange "${exchange}" routingKey "${routingKey}": ${err.message}`,
+							);
+						}
+
+						continue;
+					}
+
+					// ── Queue mode: collect and group by queue name ─────────────────
+					if (!queue) {
+						AppStartup.logger.warn(
+							`@RabbitSubscribe on ${providerClass.name}.${descriptor.methodName}() has neither 'queue' nor 'exchange'+'routingKey' – skipping.`,
+						);
+						continue;
+					}
+
+					if (!queueMap.has(queue)) queueMap.set(queue, []);
+					const queueHandlers = queueMap.get(queue) as QueueHandler[];
+					queueHandlers.push({
+						instance,
+						descriptor,
+						noAck,
+						providerName: providerClass.name,
+					});
+				}
+			}
 
-								const msg: RabbitMessage = {
-									data,
-									raw,
-									ack: () => channel.ack(raw),
-									nack: (requeue = true) => channel.nack(raw, false, requeue),
-									reject: () => channel.reject(raw, false),
-								};
+			// ── Step 2: one AMQP consumer per unique queue, fan-out in-process ──
+			for (const [queue, handlers] of queueMap.entries()) {
+				// Use noAck only when every handler opts in; otherwise manual ack.
+				const noAck = handlers.every((h) => h.noAck);
 
+				const handlerList = handlers
+					.map((h) => `${h.providerName}.${h.descriptor.methodName}()`)
+					.join(", ");
+
+				AppStartup.logger.log(
+					`Registering RabbitMQ consumer for queue: "${queue}" → [${handlerList}]`,
+				);
+
+				try {
+					const channel = await RabbitMQConnection.getConsumerChannel(queue);
+
+					await channel.consume(
+						queue,
+						async (raw) => {
+							if (!raw) return; // consumer cancelled
+
+							const data = (() => {
+								try {
+									return JSON.parse(raw.content.toString());
+								} catch {
+									return raw.content.toString();
+								}
+							})();
+
+							// Settle guard: ack/nack/reject may only be called once per
+							// delivery tag regardless of how many handlers invoke it.
+							let settled = false;
+							const settle = (fn: () => void) => {
+								if (!settled) {
+									settled = true;
+									fn();
+								}
+							};
+
+							const msg: RabbitMessage = {
+								data,
+								raw,
+								ack: () => settle(() => channel.ack(raw)),
+								nack: (requeue = true) =>
+									settle(() => channel.nack(raw, false, requeue)),
+								reject: () => settle(() => channel.reject(raw, false)),
+							};
+
+							for (const {
+								instance,
+								descriptor,
+								noAck: handlerNoAck,
+								providerName,
+							} of handlers) {
 								try {
 									await instance[descriptor.methodName](msg);
 								} catch (err: any) {
 									AppStartup.logger.error(
-										`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on queue "${queue}": ${err.message}`,
+										`Unhandled error in RabbitMQ handler ${providerName}.${descriptor.methodName}() on queue "${queue}": ${err.message}`,
 									);
-									if (!noAck) {
-										// Nack and requeue by default so the message isn't lost
-										channel.nack(raw, false, true);
+									if (!handlerNoAck && !settled) {
+										settle(() => channel.nack(raw, false, true));
 									}
 								}
-							},
-							{ noAck },
-						);
-					} catch (err: any) {
-						AppStartup.logger.error(
-							`Failed to register consumer for queue "${queue}": ${err.message}`,
-						);
-					}
+							}
+						},
+						{ noAck },
+					);
+				} catch (err: any) {
+					AppStartup.logger.error(
+						`Failed to register consumer for queue "${queue}": ${err.message}`,
+					);
 				}
 			}
 		})();

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

@@ -134,13 +134,51 @@ export interface RabbitPublishOptions {
 
 /**
  * Options for the `@RabbitSubscribe` method decorator.
+ *
+ * Two usage modes:
+ *
+ * 1. **Direct queue** – set `queue` to consume from a named queue.
+ * 2. **Routing key** – set `exchange` + `routingKey` to subscribe to a topic/direct
+ *    exchange with a specific routing key pattern. The lib creates an exclusive
+ *    auto-delete queue per handler, so **every** handler bound to the same routing
+ *    key receives its own copy of the message (fan-out per key).
+ *
+ * @example Queue mode
+ * ```typescript
+ * @RabbitSubscribe({ queue: 'orders.created' })
+ * async handle(msg: RabbitMessage<Order>) { msg.ack(); }
+ * ```
+ *
+ * @example Routing key mode
+ * ```typescript
+ * @RabbitSubscribe({ exchange: 'events', routingKey: 'article.published' })
+ * async onPublished(msg: RabbitMessage<Article>) { msg.ack(); }
+ * ```
  */
 export interface RabbitSubscribeOptions {
 	/**
 	 * Queue to consume messages from.
 	 * The queue must be declared either via `RabbitMQModule.register({ queues: [...] })` or by the broker.
+	 * Mutually exclusive with `exchange` + `routingKey`.
 	 */
-	queue: string;
+	queue?: string;
+	/**
+	 * Exchange name to bind to. Must be used together with `routingKey`.
+	 * The lib automatically creates an exclusive auto-delete queue for each handler
+	 * and binds it to this exchange, so all handlers for the same routing key
+	 * receive a copy of every published message.
+	 */
+	exchange?: string;
+	/**
+	 * Routing key to subscribe to. Supports wildcards for topic exchanges:
+	 * - `*` matches exactly one word
+	 * - `#` matches zero or more words
+	 *
+	 * Examples: `article.published`, `article.*`, `article.#`
+	 *
+	 * Must be used together with `exchange`.
+	 */
+	routingKey?: string;
 	/**
 	 * When `true`, messages are automatically acknowledged as soon as they are delivered.
 	 * When `false` (default), you must call `msg.ack()` / `msg.nack()` manually.

package/lib/rabbitmq/rabbitmq-connection.ts

@@ -70,6 +70,42 @@ export class RabbitMQConnection {
 		return channel;
 	}
 
+	/**
+	 * Creates a **new** channel with an exclusive, auto-delete server-named queue
+	 * bound to `exchange` with `routingKey`.
+	 *
+	 * Because each call creates an independent queue, every handler that subscribes
+	 * to the same exchange + routing key receives its own copy of the message
+	 * (fan-out behaviour per routing key).
+	 *
+	 * The channel and queue are **not** cached – each call returns a fresh pair.
+	 */
+	static async createRoutingKeyConsumerChannel(
+		exchange: string,
+		routingKey: string,
+	): Promise<{ channel: Channel; queueName: string }> {
+		const connection = await RabbitMQConnection.getConnection();
+		const channel = await connection.createChannel();
+
+		const prefetch = RabbitMQConnection.options?.prefetch ?? 10;
+		await channel.prefetch(prefetch);
+
+		// Server-generated name, exclusive so only this consumer uses it,
+		// autoDelete so it disappears when the consumer disconnects.
+		const { queue: queueName } = await channel.assertQueue("", {
+			exclusive: true,
+			autoDelete: true,
+			durable: false,
+		});
+
+		await channel.bindQueue(queueName, exchange, routingKey);
+		logger.log(
+			`Routing-key consumer queue "${queueName}" bound to exchange "${exchange}" with key "${routingKey}"`,
+		);
+
+		return { channel, queueName };
+	}
+
 	/**
 	 * Initialises the connection, asserts all configured exchanges and queues,
 	 * then resolves. Safe to call multiple times – returns the same promise.

package/package.json

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