@jsnw/nestjs-rabbitmq 1.0.0

package/README.md

@@ -0,0 +1,194 @@
+# @jsnw/nestjs-rabbitmq
+
+NestJS module for RabbitMQ integration using [rabbitmq-client](https://www.npmjs.com/package/rabbitmq-client).
+
+## Installation
+
+```bash
+npm i -s @jsnw/nestjs-rabbitmq
+```
+
+Additionally, you can install `zod` and `rabbitmq-client`
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { RabbitmqModule, 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
+});
+
+const ordersQueue = new RabbitmqQueue({
+  name: 'order.created',
+  durable: true,
+  bindings: [
+    { exchange: ordersExchange, routingKeys: ['order.created'] }
+  ]
+});
+
+RabbitmqModule.forRoot({
+  name: 'main',
+  hostname: 'localhost',
+  port: 5672,
+  username: 'guest',
+  password: 'guest',
+  exchanges: [ordersExchange],
+  queues: [ordersQueue]
+})
+```
+
+## Publishing Messages
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRabbitmq, Rabbitmq } 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'
+    });
+  }
+}
+```
+
+To inject a specific instance by name:
+
+```typescript
+@InjectRabbitmq('main')
+private readonly rabbitmq: Rabbitmq
+```
+
+## Subscribing to Queues
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RabbitmqSubscribe, type AsyncMessage } 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'
+  }
+}
+```
+
+### 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
+
+## Message Validation
+
+Use Zod schemas to validate incoming messages:
+
+```typescript
+import { z } from 'zod';
+
+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'
+})
+```
+
+## License
+
+MIT
+
+## Author
+
+Pavlo Baliuk (jsnow0177@gmail.com)

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+__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/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqQueue = exports.RabbitmqExchange = exports.Rabbitmq = void 0;
+var rabbitmq_1 = require("./rabbitmq");
+Object.defineProperty(exports, "Rabbitmq", { enumerable: true, get: function () { return rabbitmq_1.Rabbitmq; } });
+var rabbitmq_exchange_1 = require("./rabbitmq-exchange");
+Object.defineProperty(exports, "RabbitmqExchange", { enumerable: true, get: function () { return rabbitmq_exchange_1.RabbitmqExchange; } });
+var rabbitmq_queue_1 = require("./rabbitmq-queue");
+Object.defineProperty(exports, "RabbitmqQueue", { enumerable: true, get: function () { return rabbitmq_queue_1.RabbitmqQueue; } });

package/dist/rabbitmq/rabbitmq-exchange.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqExchange = void 0;
+class RabbitmqExchange {
+    _$type = 'exchange';
+    name;
+    type;
+    durable;
+    autoDelete;
+    /**
+     * @param {RabbitmqExchangeDeclaration} declaration
+     */
+    constructor(declaration) {
+        this.name = declaration.name;
+        this.type = declaration.type;
+        this.durable = !!declaration.durable;
+        this.autoDelete = !!declaration.autoDelete;
+    }
+}
+exports.RabbitmqExchange = RabbitmqExchange;

package/dist/rabbitmq/rabbitmq-queue.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqQueue = void 0;
+class RabbitmqQueue {
+    _$type = 'queue';
+    name;
+    arguments;
+    durable;
+    autoDelete;
+    exclusive;
+    /** https://www.rabbitmq.com/dlx.html */
+    deadLetterExchange;
+    /** https://www.rabbitmq.com/dlx.html */
+    deadLetterRoutingKey;
+    _bindings;
+    get bindings() {
+        return this._bindings.map(binding => ({
+            exchange: binding.exchange,
+            routingKeys: (binding.routingKeys ?? []).map(key => key)
+        }));
+    }
+    /**
+     * @param {RabbitmqQueueDeclaration} declaration
+     */
+    constructor(declaration) {
+        this.name = declaration.name;
+        this.arguments = Object.assign({}, declaration.arguments ?? {});
+        this.durable = !!declaration.durable;
+        this.autoDelete = !!declaration.autoDelete;
+        this.exclusive = !!declaration.exclusive;
+        this.deadLetterExchange = declaration.deadLetterExchange ?? null;
+        this.deadLetterRoutingKey = declaration.deadLetterRoutingKey ?? null;
+        this._bindings = declaration.bindings ?? [];
+    }
+}
+exports.RabbitmqQueue = RabbitmqQueue;

package/dist/rabbitmq/rabbitmq.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rabbitmq = void 0;
+const rabbitmq_client_1 = require("rabbitmq-client");
+const common_1 = require("@nestjs/common");
+class Rabbitmq {
+    name;
+    logger;
+    connection;
+    exchanges = new Map();
+    queues = new Map();
+    consumers = new Set;
+    consumersById = new Map();
+    publisher = null;
+    /**
+     * @param {string | RabbitmqConstructorParams} arg1
+     * @param {Connection} arg2
+     */
+    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
+            });
+    }
+    /**
+     * @param {RabbitmqExchange} exchange
+     * @returns {Promise<boolean>}
+     */
+    async declareExchange(exchange) {
+        if (this.exchanges.has(exchange.name))
+            return false;
+        this.exchanges.set(exchange.name, exchange);
+        await this.connection.exchangeDeclare({
+            exchange: exchange.name,
+            type: exchange.type,
+            durable: exchange.durable,
+            autoDelete: exchange.autoDelete
+        });
+        return true;
+    }
+    /**
+     * @param {RabbitmqQueue} queue
+     * @returns {Promise<boolean>}
+     */
+    async declareQueue(queue) {
+        if (this.queues.has(queue.name))
+            return false;
+        // Auto-declare dead-letter exchange if any
+        if (queue.deadLetterExchange)
+            await this.declareExchange(queue.deadLetterExchange);
+        this.queues.set(queue.name, queue);
+        await this.connection.queueDeclare({
+            queue: queue.name,
+            durable: queue.durable,
+            autoDelete: queue.autoDelete,
+            arguments: {
+                ...queue.arguments,
+                'x-dead-letter-exchange': queue.deadLetterExchange?.name ?? undefined,
+                'x-dead-letter-routing-key': queue.deadLetterRoutingKey ?? undefined
+            },
+            exclusive: queue.exclusive
+        });
+        // Auto-declare bound exchanges
+        await this.setupQueueBindings(queue);
+        return true;
+    }
+    /**
+     * @param {RabbitmqQueue} queue
+     * @returns {Promise<void>}
+     * @protected
+     */
+    async setupQueueBindings(queue) {
+        const bindings = queue.bindings;
+        for (const binding of bindings) {
+            // Try to declare (or re-declare) an exchange to make sure that it exists before binding a queue to it
+            await this.declareExchange(binding.exchange);
+            if (binding.routingKeys.length === 0 || binding.routingKeys.length === 1) {
+                await this.connection.queueBind({
+                    queue: queue.name,
+                    exchange: binding.exchange.name,
+                    routingKey: binding.routingKeys.length === 0 ? undefined : binding.routingKeys[0]
+                });
+            }
+            else {
+                await Promise.all(binding.routingKeys.map(routingKey => this.connection.queueBind({
+                    queue: queue.name,
+                    exchange: binding.exchange.name,
+                    routingKey: routingKey
+                })));
+            }
+        }
+    }
+    /**
+     * @param {RabbitmqSubscribeParams} params
+     * @param {RabbitmqSubscriber} subscriber
+     * @returns {Promise<void>}
+     */
+    async subscribe(params, subscriber) {
+        await this.declareQueue(params.queue);
+        const consumer = this.connection.createConsumer({
+            queue: params.queue.name,
+            requeue: !!params.requeue,
+            qos: {
+                prefetchSize: params.prefetchSize ?? 0,
+                prefetchCount: params.prefetchCount ?? 1
+            },
+            concurrency: params.concurrency ?? 1,
+            lazy: !!params.autoStart
+        }, this.internalConsumer.bind(this, params, subscriber));
+        this.consumers.add(consumer);
+        if (params.id)
+            this.consumersById.set(params.id, { isStarted: !!params.autoStart, consumer: consumer });
+    }
+    /**
+     * @param {string} id
+     * @returns {void}
+     */
+    startSubscriber(id) {
+        const consumer = this.consumersById.get(id);
+        if (!consumer)
+            throw new Error(`Subscriber ${id} not found for connection ${this.name}`);
+        if (consumer.isStarted)
+            return;
+        consumer.isStarted = true;
+        consumer.consumer.start();
+    }
+    /**
+     * @returns {void}
+     */
+    startPendingSubscribers() {
+        for (const consumer of this.consumersById.values()) {
+            if (consumer.isStarted)
+                continue;
+            consumer.isStarted = true;
+            consumer.consumer.start();
+        }
+    }
+    /**
+     * @param {RabbitmqSubscribeParams} params
+     * @param {RabbitmqSubscriber} subscriber
+     * @param {AsyncMessage} message
+     * @returns {Promise<ConsumerStatus>}
+     * @private
+     */
+    async internalConsumer(params, subscriber, message) {
+        if (!message.body || (typeof message.body !== 'string' && !Buffer.isBuffer(message.body)))
+            return rabbitmq_client_1.ConsumerStatus.DROP;
+        const messageBody = Buffer.isBuffer(message.body)
+            ? message.body.toString('utf-8')
+            : typeof message.body === 'string'
+                ? message.body
+                : null;
+        if (!messageBody)
+            return rabbitmq_client_1.ConsumerStatus.DROP;
+        const isJSON = message.contentType === 'application/json';
+        let data;
+        try {
+            data = isJSON ? JSON.parse(messageBody) : messageBody;
+        }
+        catch (e) {
+            this.logger.error(`Failed to parse message body as JSON`);
+            return rabbitmq_client_1.ConsumerStatus.DROP;
+        }
+        if (!!params.validation?.schema) {
+            const { data: parsed, error, success } = params.validation.schema.safeParse(data);
+            if (error || !success)
+                return this.mapRabbitmqResponseToConsumerStatus(params.validation.onFail ?? 'drop');
+            data = parsed;
+        }
+        const subscriberName = typeof subscriber === 'function'
+            ? subscriber.name ?? 'anonymous function'
+            : `${subscriber.instance.constructor.name}.${subscriber.methodName}`;
+        try {
+            const response = await (typeof subscriber === 'function'
+                ? subscriber(data, message)
+                : subscriber.instance[subscriber.methodName](data, message));
+            return this.mapRabbitmqResponseToConsumerStatus(response);
+        }
+        catch (e) {
+            this.logger.error(`Error in subscriber ${subscriberName} (connection: ${this.name}). Error: ${e.constructor.name}(${e.message ?? ''})`);
+            return !!params.requeue ? rabbitmq_client_1.ConsumerStatus.REQUEUE : rabbitmq_client_1.ConsumerStatus.DROP;
+        }
+    }
+    /**
+     * @param {RabbitmqPublishOptions} options
+     * @return {Promise<void>}
+     */
+    publish(options) {
+        if (!this.publisher)
+            this.publisher = this.connection.createPublisher();
+        return this.publisher.send({
+            exchange: options.exchange.name,
+            routingKey: options.routingKey,
+            durable: options.durable !== undefined ? options.durable : options.exchange.durable,
+            contentType: options.type === 'json' ? 'application/json' : undefined,
+            expiration: options.ttlMs?.toString() ?? undefined
+        }, options.type === 'json' ? JSON.stringify(options.message) : options.message);
+    }
+    /**
+     * @param {RabbitmqResponse | string} response
+     * @return {ConsumerStatus}
+     * @protected
+     */
+    mapRabbitmqResponseToConsumerStatus(response) {
+        response = response.toLowerCase();
+        switch (response) {
+            case 'ack': return rabbitmq_client_1.ConsumerStatus.ACK;
+            case 'requeue': return rabbitmq_client_1.ConsumerStatus.REQUEUE;
+            case 'drop': return rabbitmq_client_1.ConsumerStatus.DROP;
+        }
+        return rabbitmq_client_1.ConsumerStatus.DROP;
+    }
+    /**
+     * @return {Promise<void>}
+     */
+    async close() {
+        const promises = [];
+        for (const consumer of this.consumers.values())
+            promises.push(consumer.close());
+        promises.push(this.connection.close());
+        await Promise.allSettled(promises);
+    }
+}
+exports.Rabbitmq = Rabbitmq;

package/dist/rabbitmq-core.module.js

@@ -0,0 +1,116 @@
+"use strict";
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitmqCoreModule = void 0;
+const common_1 = require("@nestjs/common");
+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_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 _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var RabbitmqCoreModule = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            RabbitmqCoreModule = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        /**
+         * @param {RabbitmqForRootParams} params
+         * @return {DynamicModule}
+         */
+        static forRoot(params) {
+            const providers = [];
+            const instanceProvider = this.createInstanceProvider(params);
+            providers.push(instanceProvider);
+            if (params.isDefault)
+                providers.push({
+                    provide: rabbitmq_consts_1.RABBITMQ_INSTANCE_DEFAULT_NAME,
+                    useExisting: (0, rabbitmq_helpers_1.getInstanceToken)(params)
+                });
+            return {
+                module: RabbitmqCoreModule,
+                providers: providers,
+                exports: providers
+            };
+        }
+        /**
+         * @param {RabbitmqForRootParams} params
+         * @return {FactoryProvider}
+         * @private
+         */
+        static createInstanceProvider(params) {
+            const instanceToken = (0, rabbitmq_helpers_1.getInstanceToken)(params);
+            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;
+                },
+                inject: [
+                    rabbitmq_instances_manager_1.RabbitmqInstancesManager
+                ]
+            };
+        }
+    };
+    return RabbitmqCoreModule = _classThis;
+})();
+exports.RabbitmqCoreModule = RabbitmqCoreModule;