npm package: @relab/nestjs-kafka
Description: Kafka helpers for Nest.js
Author: Sergey Zwezdin
Latest version: 1.1.0

# @relab/nestjs-kafka

## Purpose

This package provides helpers for integrating Kafka with [NestJS](https://nestjs.com/) microservices. It simplifies Kafka client/consumer/producer configuration, resilient consumer restart strategy, and subscription behavior, so you can focus on your business logic.

### Key Features

- **Simple setup**: One call to configure a Kafka microservice transport in your NestJS app.
- **Resilient consumption**: Automatic consumer restart with backoff after failures.
- **Configurable logging**: Uses `kafkajs` log levels and a structured log creator.
- **Producer defaults**: Sensible producer defaults (default partitioner, no auto topic creation).

---

## Installation

```bash
pnpm add @relab/nestjs-kafka
```

---

## Usage

### Consumer

**main.ts**
```typescript
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'
import { configureKafkaMicroservice } from '@relab/nestjs-kafka'

async function bootstrap() {
    const app = await NestFactory.create(AppModule)

    await configureKafkaMicroservice(app, {
        clientId: 'my-service',
        brokers: ['localhost:9092'],
        consumerGroup: 'my-service-consumers',
        restartTimeout: 60_000,     // ms
        fromBeginning: true,        // optional
    })

    await app.startAllMicroservices()
    await app.listen(3000)
}

bootstrap()
```

### Producer

Use NestJS `ClientKafka` or your own `kafkajs` producer as needed. This package focuses on configuring the microservice transport for consumers; it does not provide a custom producer factory.

---

## API

### `configureKafkaMicroservice(app, options)`

Configures your NestJS app to use Kafka as a microservice transport and applies resilient consumer restart behavior and sensible defaults.

#### Parameters

- **app**: `INestApplication` — Your NestJS application instance.
- **options**: `object`
  - `clientId` (`string`, optional): Kafka client ID (defaults to host name).
  - `brokers` (`string[]`, required): Kafka broker addresses, e.g. `['localhost:9092']`.
  - `consumerGroup` (`string`, required): Kafka consumer group ID.
  - `logLevel` (`KafkaLogLevel`, optional): `kafkajs` log level (default: `INFO`).
  - `restartTimeout` (`number`, required): Pause (ms) before restarting the consumer after a failure.
  - `fromBeginning` (`boolean`, optional, default: `true`): Subscribe from the beginning on first subscription.

---

## How it works

- **Kafka client setup**: Configures client ID, brokers, structured logging, and log level.
- **Consumer config**: Sets group, session/heartbeat timeouts, disables auto topic creation, and enables a retry strategy with automatic restart after failures (waiting `restartTimeout`).
- **Producer config**: Uses the default partitioner and disables auto topic creation.
- **Subscription**: Subscribes with `fromBeginning` on first subscription by default.

---

## Advanced

You can import the following for custom setups:

- `configureKafkaMicroservice`: Helper to attach a Kafka microservice transport to your NestJS app with resilient defaults.

---

## License

MIT