npm package: @relab/nestjs-rabbit-mq
Description: RabbitMQ helpers for Nest.js
Author: Sergey Zwezdin
Latest version: 6.0.0

# @relab/nestjs-rabbit-mq

## Purpose

This package provides helpers for integrating RabbitMQ with [NestJS](https://nestjs.com/) microservices. It simplifies queue setup, message acknowledgement, error handling, and dead-letter/reprocessing logic, so you can focus on your business logic.

### Key Features

- **Automatic queue setup**: Ensures main, reprocess, and dead-letter queues are created with correct options.
- **Message acknowledgement**: Automatically acknowledges messages on success, nacks on error, and moves messages to DLQ after max attempts.
- **Re-processing logic**: Failed messages are retried via a reprocess queue before being sent to a dead-letter queue.
- **Configurable retry and queue options**.

---

## Installation

```bash
pnpm add @relab/nestjs-rabbit-mq
```

---

## Usage

### Consumer

**main.ts**
```typescript
import { configureRabbitMqMicroservice } from '@relab/nestjs-rabbit-mq'

const app = /* create nestjs app */

await configureRabbitMqMicroservice(app, {
    connectionString: '<connection string>',
    maxAttempts: 3,
    queue: {
        name: '<queue_name>',
        durable: true,
        reprocessTimeout: 30_000,      // optional, ms
        deadLetterTimeout: 48 * 60 * 60 * 1000, // optional, ms
        forceCreate: false,            // optional
    },
})
```

### Producer

**module.ts**
```typescript
import { configureRabbitMqMicroservice } from '@relab/nestjs-rabbit-mq'

@Module({
    providers: [
        {
            provide: 'SMS_SERVICE',
            useFactory: (traceContextService: TraceContextService) => {
                return RabbitMqClientProxyFactory.create({
                  connectionString: 'amqp://user:password@localhost:5672'
                  queueName: 'queue1',
                  traceContextService
                })
            },
        },
    ],
    exports: [],
})
export class Module {}
```

---

## API

### `configureRabbitMqMicroservice(app, options)`

Configures your NestJS app to use RabbitMQ as a microservice transport, sets up the required queues, and installs global message acknowledgement logic.

#### Parameters

- **app**: `INestApplication` — Your NestJS application instance.
- **options**: `object`
  - `connectionString` (`string`, required): RabbitMQ connection string.
  - `maxAttempts` (`number`, optional, default: 3): Max delivery attempts before moving message to DLQ.
  - `queue` (`object`, required):
    - `name` (`string`, required): Name of the main queue.
    - `durable` (`boolean`, optional): Whether the queue survives broker restarts.
    - `reprocessTimeout` (`number`, optional, default: 30000): Time (ms) before a message in the reprocess queue is retried.
    - `deadLetterTimeout` (`number`, optional, default: 48h): Time (ms) before a message in the DLQ is discarded.
    - `forceCreate` (`boolean`, optional): If true, deletes and recreates queues if their options do not match.

---

## How it works

- **Queue Setup**: Three queues are created per logical queue:
  - `<queue_name>`: Main queue.
  - `<queue_name>_rlq`: Reprocess letter queue (for retrying failed messages).
  - `<queue_name>_dlq`: Dead letter queue (for messages that exceeded max attempts).
- **Message Flow**:
  1. On handler success, message is acknowledged.
  2. On handler error, message is nacked. If delivery attempts exceed `maxAttempts`, it is moved to the DLQ.
  3. Messages in the reprocess queue are retried after `reprocessTimeout`.
  4. Messages in the DLQ are retained for `deadLetterTimeout`.

---

## Advanced

You can also use the following exports for custom setups:

- `RabbitMQAckInterceptor`: The interceptor responsible for ack/nack logic.
- `setupQueue(connectionString, queueName, options)`: Manually set up queues.

---

## License

MIT