@grupodiariodaregiao/bunstone 0.3.12 → 0.4.0

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();
   }
@@ -117579,7 +117593,51 @@ if (document.readyState === 'loading') {
       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;
+          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 {
+                  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);
+                  }
+                }
+              }, { 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;
+          }
           AppStartup.logger.log(`Registering RabbitMQ consumer for queue: "${queue2}" \u2192 ${providerClass.name}.${descriptor.methodName}()`);
           try {
             const channel = await RabbitMQConnection.getConsumerChannel(queue2);

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

@@ -886,7 +886,76 @@ if (document.readyState === 'loading') {
 				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}()`,
+						);
+
+						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: RabbitMessage = {
+										data,
+										raw,
+										ack: () => channel.ack(raw),
+										nack: (requeue = true) => channel.nack(raw, false, requeue),
+										reject: () => channel.reject(raw, false),
+									};
+
+									try {
+										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;
+					}
+
+					// ── Direct queue mode ──────────────────────────────────────────────
+					if (!queue) {
+						AppStartup.logger.warn(
+							`@RabbitSubscribe on ${providerClass.name}.${descriptor.methodName}() has neither 'queue' nor 'exchange'+'routingKey' – skipping.`,
+						);
+						continue;
+					}
 
 					AppStartup.logger.log(
 						`Registering RabbitMQ consumer for queue: "${queue}" → ${providerClass.name}.${descriptor.methodName}()`,

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.0",
   "homepage": "https://bunstone.diario.one/",
   "repository": {
     "url": "https://github.com/diariodaregiao/bunstone.git",