@jsnw/nestjs-rabbitmq 1.3.6 → 2.0.1

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/lib/rabbitmq-core.module.js

@@ -0,0 +1,97 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var RabbitmqCoreModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqCoreModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rabbitmq_1 = require("./rabbitmq");
+const rabbitmq_consts_1 = require("./rabbitmq.consts");
+const rabbitmq_storage_1 = require("./rabbitmq.storage");
+const rabbitmq_explorer_service_1 = require("./rabbitmq-explorer.service");
+let RabbitmqCoreModule = RabbitmqCoreModule_1 = class RabbitmqCoreModule {
+    rabbit;
+    /**
+     * @param {RabbitmqOptions} options
+     * @return {DynamicModule}
+     */
+    static forRoot(options) {
+        const optionsProvider = this.createOptionsProvider(options), rabbitmqProvider = this.createRabbitmqProvider();
+        return {
+            module: RabbitmqCoreModule_1,
+            imports: [],
+            providers: [
+                optionsProvider,
+                rabbitmqProvider
+            ],
+            exports: [
+                rabbitmqProvider
+            ]
+        };
+    }
+    /**
+     * @param {RabbitmqOptions} options
+     * @return {ValueProvider}
+     * @private
+     */
+    static createOptionsProvider(options) {
+        return {
+            provide: rabbitmq_consts_1.RABBITMQ_OPTIONS_TOKEN,
+            useValue: options
+        };
+    }
+    /**
+     * @return {FactoryProvider}
+     * @private
+     */
+    static createRabbitmqProvider() {
+        return {
+            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_consts_1.RABBITMQ_OPTIONS_TOKEN
+            ]
+        };
+    }
+    /**
+     * @param {Rabbitmq} rabbit
+     */
+    constructor(rabbit) {
+        this.rabbit = rabbit;
+    }
+    /**
+     * @return {Promise<void>}
+     */
+    async onApplicationShutdown() {
+        await this.rabbit.close();
+    }
+};
+exports.RabbitmqCoreModule = RabbitmqCoreModule;
+exports.RabbitmqCoreModule = RabbitmqCoreModule = RabbitmqCoreModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        imports: [
+            core_1.DiscoveryModule
+        ],
+        providers: [
+            core_1.Reflector,
+            rabbitmq_explorer_service_1.RabbitmqExplorerService
+        ]
+    }),
+    __metadata("design:paramtypes", [rabbitmq_1.Rabbitmq])
+], RabbitmqCoreModule);

package/dist/lib/rabbitmq-explorer.service.js

@@ -0,0 +1,89 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqExplorerService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rabbitmq_1 = require("./rabbitmq");
+const rabbitmq_storage_1 = require("./rabbitmq.storage");
+const rabbitmq_consts_1 = require("./rabbitmq.consts");
+let RabbitmqExplorerService = class RabbitmqExplorerService {
+    discoveryService;
+    metadataScanner;
+    reflector;
+    rabbitmq;
+    constructor(discoveryService, metadataScanner, reflector, rabbitmq) {
+        this.discoveryService = discoveryService;
+        this.metadataScanner = metadataScanner;
+        this.reflector = reflector;
+        this.rabbitmq = rabbitmq;
+    }
+    /**
+     * @return {Promise<void>}
+     */
+    async onApplicationBootstrap() {
+        await this.setupInfrastructure();
+        await this.discoverSubscribers();
+    }
+    /**
+     * @return {Promise<void>}
+     * @private
+     */
+    async setupInfrastructure() {
+        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 discoverSubscribers() {
+        const wrappers = [
+            ...this.discoveryService.getProviders(),
+            ...this.discoveryService.getControllers()
+        ];
+        for (const wrapper of wrappers) {
+            const { instance } = wrapper;
+            if (!instance || typeof instance !== 'object')
+                continue;
+            const prototype = Object.getPrototypeOf(instance);
+            if (!prototype)
+                continue;
+            const methodNames = this.metadataScanner.getAllMethodNames(prototype);
+            for (const methodName of methodNames)
+                await this.registerIfSubscriber(instance, methodName);
+        }
+    }
+    /**
+     * @param {any} instance
+     * @param {string} methodName
+     * @return {Promise<void>}
+     * @private
+     */
+    async registerIfSubscriber(instance, methodName) {
+        const methodRef = instance[methodName];
+        const metadata = this.reflector.get(rabbitmq_consts_1.RABBITMQ_SUBSCRIPTION_METADATA, methodRef);
+        if (!metadata)
+            return;
+        await this.rabbitmq.subscribe(metadata, { instance, methodName });
+    }
+};
+exports.RabbitmqExplorerService = RabbitmqExplorerService;
+exports.RabbitmqExplorerService = RabbitmqExplorerService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.MetadataScanner,
+        core_1.Reflector,
+        rabbitmq_1.Rabbitmq])
+], RabbitmqExplorerService);

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;

package/dist/lib/rabbitmq.module.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var RabbitmqModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqModule = void 0;
+const common_1 = require("@nestjs/common");
+const rabbitmq_core_module_1 = require("./rabbitmq-core.module");
+const rabbitmq_storage_1 = require("./rabbitmq.storage");
+let RabbitmqModule = RabbitmqModule_1 = class RabbitmqModule {
+    /**
+     * @param {RabbitmqOptions} options
+     * @return {DynamicModule}
+     */
+    static forRoot(options) {
+        return {
+            module: RabbitmqModule_1,
+            imports: [
+                rabbitmq_core_module_1.RabbitmqCoreModule.forRoot(options)
+            ]
+        };
+    }
+    /**
+     * @param {(RabbitmqExchange | RabbitmqQueue)[] | {exchanges?: RabbitmqExchange[], queues?: RabbitmqQueue[]}} declarations
+     * @return {DynamicModule}
+     */
+    static forFeature(declarations) {
+        if (declarations) {
+            if (Array.isArray(declarations) && declarations.length > 0)
+                rabbitmq_storage_1.RabbitmqStorage.addAny(declarations);
+            if ('exchanges' in declarations && Array.isArray(declarations.exchanges) && declarations.exchanges.length > 0)
+                rabbitmq_storage_1.RabbitmqStorage.addExchanges(declarations.exchanges);
+            if ('queues' in declarations && Array.isArray(declarations.queues) && declarations.queues.length > 0)
+                rabbitmq_storage_1.RabbitmqStorage.addQueues(declarations.queues);
+        }
+        return {
+            module: RabbitmqModule_1,
+            providers: [],
+            exports: []
+        };
+    }
+};
+exports.RabbitmqModule = RabbitmqModule;
+exports.RabbitmqModule = RabbitmqModule = RabbitmqModule_1 = __decorate([
+    (0, common_1.Module)({})
+], RabbitmqModule);