@jsnw/nestjs-rabbitmq 1.3.5 → 2.0.0

package/README.md

@@ -1,194 +1,134 @@
 # @jsnw/nestjs-rabbitmq
 
-NestJS module for RabbitMQ integration using [rabbitmq-client](https://www.npmjs.com/package/rabbitmq-client).
+**A lightweight, strictly typed, and predictable RabbitMQ module for NestJS**
+
+## Key features
+- [rabbitmq-client](https://www.npmjs.com/package/rabbitmq-client) inside
+- Full validation for both incoming and outgoing messages using [zod](https://www.npmjs.com/package/zod)
+- Single connection
+- Type-Safe publishing: You cannot publish an invalid payload
+- Exchanges and queues are automatically declared upon application bootstrap
+- No AI. The code is written by human, not a machine
 
 ## Installation
 
 ```bash
-npm i -s @jsnw/nestjs-rabbitmq
+npm i -s @jsnw/nestjs-rabbitmq @nestjs/core@11 @nestjs/common@11
 ```
 
-Additionally, you can install `zod` and `rabbitmq-client`
+Optionally, you can install `zod` and `rabbitmq-client`
 
 ## Quick Start
+### 1. Define exchanges and queues
 
-```typescript
-import { Module } from '@nestjs/common';
-import { RabbitmqModule, RabbitmqExchange, RabbitmqQueue } from '@jsnw/nestjs-rabbitmq';
+```ts
+import {RabbitmqExchange, RabbitmqQueue} from '@jsnw/nestjs-rabbitmq';
 
-@Module({
-  imports: [
-    RabbitmqModule.forRoot({
-      name: 'main',
-      hostname: 'localhost',
-      port: 5672,
-      username: 'guest',
-      password: 'guest',
-      isDefault: true
-    })
-  ]
-})
-export class AppModule {}
-```
-
-## Declaring Exchanges and Queues
-
-```typescript
-const ordersExchange = new RabbitmqExchange({
-  name: 'orders',
-  type: 'topic',
-  durable: true
+export const MY_EXCHANGE = new RabbitmqExchange({
+    name: 'my_exchange',
+    type: 'direct',
+    durable: true,
+    autoDelete: false
 });
 
-const ordersQueue = new RabbitmqQueue({
-  name: 'order.created',
-  durable: true,
-  bindings: [
-    { exchange: ordersExchange, routingKeys: ['order.created'] }
-  ]
+export const MY_QUEUE = new RabbitmqQueue({
+    name: 'my_queue',
+    durable: true,
+    autoDelete: false,
+    bindings: [
+        {exchange: MY_EXCHANGE, routingKeys: ['user.created']}
+    ]
 });
 
-RabbitmqModule.forRoot({
-  name: 'main',
-  hostname: 'localhost',
-  port: 5672,
-  username: 'guest',
-  password: 'guest',
-  exchanges: [ordersExchange],
-  queues: [ordersQueue]
-})
 ```
 
-## Publishing Messages
+### 2. Register the module
 
-```typescript
-import { Injectable } from '@nestjs/common';
-import { InjectRabbitmq, Rabbitmq } from '@jsnw/nestjs-rabbitmq';
+```ts
+// app.module.ts
+import {Module} from '@nestjs/common';
+import {RabbitmqModule} from '@jsnw/nestjs-rabbitmq';
 
-@Injectable()
-export class OrderService {
-  constructor(
-    @InjectRabbitmq() // injects default instance
-    private readonly rabbitmq: Rabbitmq
-  ) {}
-
-  async createOrder(data: any) {
-    await this.rabbitmq.publish({
-      type: 'json',
-      message: data,
-      exchange: ordersExchange,
-      routingKey: 'order.created'
-    });
-  }
-}
+@Module({
+    imports: [
+        RabbitmqModule.forRoot({
+            hostname: 'localhost',
+            port: 5672,
+            username: 'guest',
+            password: 'guest',
+            exchanges: [MY_EXCHANGE],
+            queues: [MY_QUEUE]
+        })
+    ]
+})
+export class AppModule {}
 ```
 
-To inject a specific instance by name:
+### 3. Define a Message Contract
 
-```typescript
-@InjectRabbitmq('main')
-private readonly rabbitmq: Rabbitmq
-```
+```ts
+import {z} from 'zod';
+import {RabbitmqMessage} from '@jsnw/nestjs-rabbitmq';
 
-## Subscribing to Queues
+export const USER_CREATED_EVENT = RabbitmqMessage.template({
+    type: 'json',
+    exchange: MY_EXCHANGE,
+    durable: true,
+    routingKey: 'user.created',
+    schema: z.object({
+        id: z.number(),
+        email: z.string().email()
+    })
+});
+```
 
-```typescript
-import { Injectable } from '@nestjs/common';
-import { RabbitmqSubscribe, type AsyncMessage } from '@jsnw/nestjs-rabbitmq';
+### 4. Publishing messages
+```ts
+import {Injectable} from '@nestjs/common';
+import {Rabbitmq} from '@jsnw/nestjs-rabbitmq';
 
 @Injectable()
-export class OrderConsumer {
-  @RabbitmqSubscribe({
-    queue: ordersQueue,
-    concurrency: 5
-  })
-  async handleOrderCreated(data: any, message: AsyncMessage) {
-    console.log('Order created:', data);
-    return 'ack'; // or 'drop', 'requeue'
-  }
+export class UserService {
+
+    constructor(private readonly rabbit: Rabbitmq){}
+    
+    async create(dto: any){
+        await this.rabbit.publish(
+            USER_CREATED_EVENT.make({
+                id: 1, 
+                email: 'example@example.com'
+            })
+        );
+    }
+
 }
 ```
 
-### Subscriber Options
-
-- `instanceName`: RabbitMQ instance name
-- `queue` (required): Queue to subscribe to
-- `concurrency`: Number of concurrent message handlers (default: 1)
-- `prefetchCount`: Number of messages to prefetch (default: 1)
-- `prefetchSize`: Size of messages to prefetch in bytes (default: 0)
-- `requeue`: Whether to requeue failed messages (default: false)
-- `autoStart`: Auto-start consumer on boot (default: true)
-- `id`: Unique identifier for manual start control
+### 5. Subscribing to messages
 
-## Message Validation
+```ts
+import {Injectable} from '@nestjs/common';
+import {RabbitmqSubscribe, type AsyncMessage} from '@jsnw/nestjs-rabbitmq';
 
-Use Zod schemas to validate incoming messages:
-
-```typescript
-import { z } from 'zod';
+@Injectable()
+export class NotificationsService {
+
+    @RabbitmqSubscribe({
+        queue: MY_QUEUE,
+        validation: {
+            schema: USER_CREATED_EVENT.schema,
+            onFail: 'drop'
+        }
+    })
+    async onUserCreated(data: z.infer<typeof USER_CREATED_EVENT.schema>, message: AsyncMessage) {
 
-const orderSchema = z.object({
-  orderId: z.string(),
-  amount: z.number()
-});
+    }
 
-@RabbitmqSubscribe({
-  instanceName: 'main',
-  queue: ordersQueue,
-  validation: {
-    schema: orderSchema,
-    onFail: 'drop' // or 'ack', 'requeue'
-  }
-})
-async handleOrderCreated(data: z.infer<typeof orderSchema>) {
-  // data is typed and validated
-  return 'ack';
 }
 ```
 
-## Dead Letter Exchanges
-
-```typescript
-const dlxExchange = new RabbitmqExchange({
-  name: 'orders.dlx',
-  type: 'topic',
-  durable: true
-});
-
-const queueWithDlx = new RabbitmqQueue({
-  name: 'order.created',
-  durable: true,
-  deadLetterExchange: dlxExchange,
-  deadLetterRoutingKey: 'order.failed',
-  bindings: [{ exchange: ordersExchange, routingKeys: ['order.created'] }]
-});
-```
-
-## Multiple Instances
-
-```typescript
-RabbitmqModule.forRoot({
-  name: 'instance1',
-  hostname: 'localhost',
-  port: 5672,
-  username: 'guest',
-  password: 'guest',
-  isDefault: true
-})
-
-RabbitmqModule.forRoot({
-  name: 'instance2',
-  hostname: 'other-host',
-  port: 5672,
-  username: 'guest',
-  password: 'guest'
-})
-```
+## Author
+Pavlo Baliuk (jsnow0177@gmail.com)
 
 ## License
-
 MIT
-
-## Author
-
-Pavlo Baliuk (jsnow0177@gmail.com)

package/dist/{index.js → lib/index.js}

@@ -14,10 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InjectRabbitmq = exports.RabbitmqSubscribe = exports.RabbitmqModule = void 0;
+exports.RabbitmqSubscribe = exports.RabbitmqModule = void 0;
 __exportStar(require("./rabbitmq"), exports);
 var rabbitmq_module_1 = require("./rabbitmq.module");
 Object.defineProperty(exports, "RabbitmqModule", { enumerable: true, get: function () { return rabbitmq_module_1.RabbitmqModule; } });
 var rabbitmq_decorators_1 = require("./rabbitmq.decorators");
 Object.defineProperty(exports, "RabbitmqSubscribe", { enumerable: true, get: function () { return rabbitmq_decorators_1.RabbitmqSubscribe; } });
-Object.defineProperty(exports, "InjectRabbitmq", { enumerable: true, get: function () { return rabbitmq_decorators_1.InjectRabbitmq; } });

package/dist/{rabbitmq → lib/rabbitmq}/rabbitmq-message.js

@@ -25,7 +25,7 @@ class RabbitmqMessage {
         this._template = template;
     }
     /**
-     * @param {Prettify<InputData<T>>} data
+     * @param {InputData<T>} data
      * @return {RabbitmqPublishOptions}
      */
     make(data) {

package/dist/{rabbitmq → lib/rabbitmq}/rabbitmq.js

@@ -5,7 +5,6 @@ const rabbitmq_client_1 = require("rabbitmq-client");
 const common_1 = require("@nestjs/common");
 const rabbitmq_subscriber_1 = require("./rabbitmq-subscriber");
 class Rabbitmq {
-    name;
     logger;
     connection;
     exchanges = new Map();
@@ -13,25 +12,11 @@ class Rabbitmq {
     subscribers = new Map;
     publisher = null;
     /**
-     * @param {string | RabbitmqConstructorParams} arg1
-     * @param {Connection} arg2
+     * @param {Connection | RabbitmqConstructorParams} arg
      */
-    constructor(arg1, arg2) {
-        if (typeof arg1 === 'string' && !arg2)
-            throw new TypeError(`Invalid second argument passed to the constructor of ${Rabbitmq.name}`);
-        this.name = typeof arg1 === 'string' ? arg1 : arg1.name;
-        this.logger = new common_1.Logger(Rabbitmq.name + `(${this.name})`);
-        this.connection = typeof arg1 === 'string'
-            ? arg2
-            : new rabbitmq_client_1.Connection({
-                connectionName: arg1.connectionName ?? arg1.name,
-                hostname: arg1.hostname,
-                port: arg1.port,
-                username: arg1.username,
-                password: arg1.password,
-                vhost: arg1.vhost ?? '/',
-                connectionTimeout: arg1.connectionTimeout ?? 10_000
-            });
+    constructor(arg) {
+        this.logger = new common_1.Logger(this.constructor.name);
+        this.connection = arg instanceof rabbitmq_client_1.Connection ? arg : new rabbitmq_client_1.Connection(arg);
     }
     /**
      * @param {RabbitmqExchange} exchange
@@ -157,7 +142,7 @@ class Rabbitmq {
     startSubscriber(id) {
         const subscriber = this.subscribers.get(id);
         if (!subscriber)
-            throw new Error(`Subscriber ${id} not found for connection ${this.name}`);
+            throw new Error(`Subscriber ${id} not found`);
         subscriber.start();
     }
     /**
@@ -167,7 +152,7 @@ class Rabbitmq {
     async stopSubscriber(id) {
         const subscriber = this.subscribers.get(id);
         if (!subscriber)
-            throw new Error(`Subscriber ${id} not found for connection ${this.name}`);
+            throw new Error(`Subscriber ${id} not found`);
         await subscriber.stop();
     }
     /**
@@ -200,6 +185,8 @@ class Rabbitmq {
         const promises = [];
         for (const subscriber of this.subscribers.values())
             promises.push(subscriber.stop());
+        if (this.publisher)
+            promises.push(this.publisher.close());
         promises.push(this.connection.close());
         await Promise.allSettled(promises);
     }

package/dist/{rabbitmq-core.module.js → lib/rabbitmq-core.module.js}

@@ -36,18 +36,12 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RabbitmqCoreModule = void 0;
 const common_1 = require("@nestjs/common");
+const rabbitmq_1 = require("./rabbitmq");
 const rabbitmq_consts_1 = require("./rabbitmq.consts");
-const rabbitmq_helpers_1 = require("./rabbitmq.helpers");
-const rabbitmq_instances_manager_1 = require("./rabbitmq-instances-manager");
+const rabbitmq_storage_1 = require("./rabbitmq.storage");
 const rabbitmq_explorer_service_1 = require("./rabbitmq-explorer.service");
-const rabbitmq_1 = require("./rabbitmq");
 let RabbitmqCoreModule = (() => {
-    let _classDecorators = [(0, common_1.Global)(), (0, common_1.Module)({
-            providers: [
-                rabbitmq_instances_manager_1.RabbitmqInstancesManager,
-                rabbitmq_explorer_service_1.RabbitmqExplorerService
-            ]
-        })];
+    let _classDecorators = [(0, common_1.Global)(), (0, common_1.Module)({})];
     let _classDescriptor;
     let _classExtraInitializers = [];
     let _classThis;
@@ -60,56 +54,68 @@ let RabbitmqCoreModule = (() => {
             if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
             __runInitializers(_classThis, _classExtraInitializers);
         }
+        rabbit;
         /**
-         * @param {RabbitmqForRootParams} params
+         * @param {RabbitmqOptions} options
          * @return {DynamicModule}
          */
-        static forRoot(params) {
-            const providers = [];
-            const instanceProvider = this.createInstanceProvider(params);
-            providers.push(instanceProvider);
-            if (params.isDefault)
-                providers.push({
-                    provide: (0, rabbitmq_helpers_1.getInstanceToken)(rabbitmq_consts_1.RABBITMQ_INSTANCE_DEFAULT_NAME),
-                    useExisting: (0, rabbitmq_helpers_1.getInstanceToken)(params)
-                });
+        static forRoot(options) {
+            const optionsProvider = this.createOptionsProvider(options), rabbitmqProvider = this.createRabbitmqProvider();
             return {
                 module: RabbitmqCoreModule,
-                providers: providers,
-                exports: providers
+                providers: [
+                    optionsProvider,
+                    rabbitmqProvider,
+                    rabbitmq_explorer_service_1.RabbitmqExplorerService
+                ],
+                exports: [
+                    rabbitmqProvider
+                ]
+            };
+        }
+        /**
+         * @param {RabbitmqOptions} options
+         * @return {ValueProvider}
+         * @private
+         */
+        static createOptionsProvider(options) {
+            return {
+                provide: rabbitmq_consts_1.RABBITMQ_OPTIONS_TOKEN,
+                useValue: options
             };
         }
         /**
-         * @param {RabbitmqForRootParams} params
          * @return {FactoryProvider}
          * @private
          */
-        static createInstanceProvider(params) {
-            const instanceToken = (0, rabbitmq_helpers_1.getInstanceToken)(params);
+        static createRabbitmqProvider() {
             return {
-                provide: instanceToken,
-                useFactory: (im) => {
-                    const existingInstance = im.getInstance(instanceToken);
-                    if (existingInstance)
-                        return existingInstance;
-                    const instance = new rabbitmq_1.Rabbitmq({
-                        name: params.name,
-                        connectionName: params.connectionName,
-                        hostname: params.hostname,
-                        port: params.port,
-                        username: params.username,
-                        password: params.password,
-                        vhost: params.vhost,
-                        connectionTimeout: params.connectionTimeout
-                    });
-                    im.addInstance(instanceToken, instance);
-                    return instance;
+                provide: rabbitmq_1.Rabbitmq,
+                useFactory: (options) => {
+                    const rabbitmq = new rabbitmq_1.Rabbitmq(options);
+                    if (options.exchanges && options.exchanges.length > 0)
+                        rabbitmq_storage_1.RabbitmqStorage.addExchanges(options.exchanges);
+                    if (options.queues && options.queues.length > 0)
+                        rabbitmq_storage_1.RabbitmqStorage.addQueues(options.queues);
+                    return rabbitmq;
                 },
                 inject: [
-                    rabbitmq_instances_manager_1.RabbitmqInstancesManager
+                    rabbitmq_consts_1.RABBITMQ_OPTIONS_TOKEN
                 ]
             };
         }
+        /**
+         * @param {Rabbitmq} rabbit
+         */
+        constructor(rabbit) {
+            this.rabbit = rabbit;
+        }
+        /**
+         * @return {Promise<void>}
+         */
+        async onApplicationShutdown() {
+            await this.rabbit.close();
+        }
     };
     return RabbitmqCoreModule = _classThis;
 })();

package/dist/{rabbitmq-explorer.service.js → lib/rabbitmq-explorer.service.js}

@@ -36,8 +36,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RabbitmqExplorerService = void 0;
 const common_1 = require("@nestjs/common");
-const rabbitmq_metadata_storage_1 = require("./rabbitmq-metadata-storage");
-const rabbitmq_helpers_1 = require("./rabbitmq.helpers");
+const rabbitmq_storage_1 = require("./rabbitmq.storage");
 const rabbitmq_consts_1 = require("./rabbitmq.consts");
 let RabbitmqExplorerService = (() => {
     let _classDecorators = [(0, common_1.Injectable)()];
@@ -56,43 +55,36 @@ let RabbitmqExplorerService = (() => {
         discoveryService;
         metadataScanner;
         reflector;
-        instancesManager;
-        logger = new common_1.Logger(RabbitmqExplorerService.name);
-        constructor(discoveryService, metadataScanner, reflector, instancesManager) {
+        rabbitmq;
+        constructor(discoveryService, metadataScanner, reflector, rabbitmq) {
             this.discoveryService = discoveryService;
             this.metadataScanner = metadataScanner;
             this.reflector = reflector;
-            this.instancesManager = instancesManager;
+            this.rabbitmq = rabbitmq;
         }
         /**
          * @return {Promise<void>}
          */
         async onApplicationBootstrap() {
             await this.setupInfrastructure();
-            await this.setupSubscribers();
+            await this.discoverSubscribers();
         }
         /**
          * @return {Promise<void>}
          * @private
          */
         async setupInfrastructure() {
-            const instances = this.instancesManager.getAllInstances();
-            for (const instance of instances) {
-                const metadata = rabbitmq_metadata_storage_1.RabbitmqMetadataStorage.getMetadata((0, rabbitmq_helpers_1.getInstanceToken)(instance.name));
-                if (!metadata || (metadata.exchanges.size === 0 && metadata.queues.size === 0))
-                    continue;
-                const exchanges = Array.from(metadata.exchanges), queues = Array.from(metadata.queues);
-                if (exchanges.length > 0)
-                    await Promise.all(exchanges.map(exchange => instance.declareExchange(exchange)));
-                if (queues.length > 0)
-                    await Promise.all(queues.map(queue => instance.declareQueue(queue)));
-            }
+            const exchanges = rabbitmq_storage_1.RabbitmqStorage.getExchanges(), queues = rabbitmq_storage_1.RabbitmqStorage.getQueues();
+            if (exchanges.length > 0)
+                await Promise.all(exchanges.map(exchange => this.rabbitmq.declareExchange(exchange)));
+            if (queues.length > 0)
+                await Promise.all(queues.map(queue => this.rabbitmq.declareQueue(queue)));
         }
         /**
          * @return {Promise<void>}
          * @private
          */
-        async setupSubscribers() {
+        async discoverSubscribers() {
             const wrappers = [
                 ...this.discoveryService.getProviders(),
                 ...this.discoveryService.getControllers()
@@ -106,7 +98,7 @@ let RabbitmqExplorerService = (() => {
                     continue;
                 const methodNames = this.metadataScanner.getAllMethodNames(prototype);
                 for (const methodName of methodNames)
-                    await this.tryRegisterSubscriber(instance, methodName);
+                    await this.registerIfSubscriber(instance, methodName);
             }
         }
         /**
@@ -115,27 +107,12 @@ let RabbitmqExplorerService = (() => {
          * @return {Promise<void>}
          * @private
          */
-        async tryRegisterSubscriber(instance, methodName) {
+        async registerIfSubscriber(instance, methodName) {
             const methodRef = instance[methodName];
-            const subscriptionMetadata = this.reflector.get(rabbitmq_consts_1.RABBITMQ_SUBSCRIBE_METADATA_KEY, methodRef);
-            if (!subscriptionMetadata)
+            const metadata = this.reflector.get(rabbitmq_consts_1.RABBITMQ_SUBSCRIPTION_METADATA, methodRef);
+            if (!metadata)
                 return;
-            const rabbitmqInstance = this.instancesManager.getInstance(subscriptionMetadata.instanceToken);
-            if (!rabbitmqInstance) {
-                this.logger.error(`Instance ${subscriptionMetadata.instanceName}" not found for subscriber ${instance.constructor.name}.${methodName}`);
-                return;
-            }
-            this.logger.log(`Registering subscriber: ${instance.constructor.name}.${methodName} -> ${subscriptionMetadata.queue.name}`);
-            await rabbitmqInstance.subscribe({
-                id: subscriptionMetadata.id,
-                queue: subscriptionMetadata.queue,
-                requeue: subscriptionMetadata.requeue,
-                concurrency: subscriptionMetadata.concurrency,
-                prefetchSize: subscriptionMetadata.prefetchSize,
-                prefetchCount: subscriptionMetadata.prefetchCount,
-                autoStart: subscriptionMetadata.autoStart,
-                validation: subscriptionMetadata.validation
-            }, { instance: instance, methodName: methodName });
+            await this.rabbitmq.subscribe(metadata, { instance, methodName });
         }
     };
     return RabbitmqExplorerService = _classThis;

package/dist/lib/rabbitmq.consts.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RABBITMQ_SUBSCRIPTION_METADATA = exports.RABBITMQ_OPTIONS_TOKEN = void 0;
+exports.RABBITMQ_OPTIONS_TOKEN = Symbol('RABBITMQ_OPTIONS');
+exports.RABBITMQ_SUBSCRIPTION_METADATA = Symbol('RABBITMQ_SUBSCRIPTION_METADATA');

package/dist/lib/rabbitmq.decorators.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqSubscribe = void 0;
+const common_1 = require("@nestjs/common");
+const rabbitmq_consts_1 = require("./rabbitmq.consts");
+/**
+ * @param {RabbitmqSubscribeParams} subscription
+ * @return {MethodDecorator}
+ * @constructor
+ */
+const RabbitmqSubscribe = (subscription) => {
+    return (target, key, descriptor) => {
+        (0, common_1.SetMetadata)(rabbitmq_consts_1.RABBITMQ_SUBSCRIPTION_METADATA, subscription)(target, key, descriptor);
+        return descriptor;
+    };
+};
+exports.RabbitmqSubscribe = RabbitmqSubscribe;