@relab/nestjs-kafka 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 re:lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @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
+
+

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import { INestApplication } from '@nestjs/common';
+import { logLevel } from 'kafkajs';
+
+type KafkaServiceOptions = {
+    clientId?: string;
+    brokers: string[];
+    consumerGroup: string;
+    logLevel?: logLevel;
+    restartTimeout: number;
+    fromBeginning?: boolean;
+};
+
+declare const configureKafkaMicroservice: <T extends INestApplication = INestApplication>(app: T, options: KafkaServiceOptions) => Promise<void>;
+
+export { configureKafkaMicroservice };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { INestApplication } from '@nestjs/common';
+import { logLevel } from 'kafkajs';
+
+type KafkaServiceOptions = {
+    clientId?: string;
+    brokers: string[];
+    consumerGroup: string;
+    logLevel?: logLevel;
+    restartTimeout: number;
+    fromBeginning?: boolean;
+};
+
+declare const configureKafkaMicroservice: <T extends INestApplication = INestApplication>(app: T, options: KafkaServiceOptions) => Promise<void>;
+
+export { configureKafkaMicroservice };

package/dist/index.js

@@ -0,0 +1 @@
+var T=Object.create;var n=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var K=Object.getOwnPropertyNames;var d=Object.getPrototypeOf,v=Object.prototype.hasOwnProperty;var s=(r,e)=>n(r,"name",{value:e,configurable:!0});var I=(r,e)=>{for(var o in e)n(r,o,{get:e[o],enumerable:!0})},l=(r,e,o,a)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of K(e))!v.call(r,t)&&t!==o&&n(r,t,{get:()=>e[t],enumerable:!(a=w(e,t))||a.enumerable});return r};var b=(r,e,o)=>(o=r!=null?T(d(r)):{},l(e||!r||!r.__esModule?n(o,"default",{value:r,enumerable:!0}):o,r)),A=r=>l(n({},"__esModule",{value:!0}),r);var R={};I(R,{configureKafkaMicroservice:()=>L});module.exports=A(R);var u=require("@nestjs/common"),p=require("@nestjs/microservices"),k=b(require("os")),m=require("kafkajs");var c=require("@nestjs/common"),g=require("kafkajs");var i=new c.Logger("Kafka"),f=s(()=>({level:r,log:{timestamp:e,logger:o,message:a,...t}})=>{(r===g.logLevel.DEBUG?i.debug:r===g.logLevel.INFO?i.log:r===g.logLevel.WARN?i.warn:r===g.logLevel.ERROR?i.error:i.log).call(i,a,t)},"kafkaLogger");var L=s(async(r,e)=>{let o=new u.Logger("Kafka");await r.connectMicroservice({transport:p.Transport.KAFKA,options:{postfixId:"",client:{clientId:e.clientId||k.default.hostname(),brokers:e.brokers,logCreator:f,logLevel:e.logLevel??m.logLevel.INFO},consumer:{groupId:e.consumerGroup,sessionTimeout:3e4,heartbeatInterval:3e3,allowAutoTopicCreation:!1,retry:{initialRetryTime:500,maxRetryTime:1e3,multiplier:2,factor:0,retries:5,restartOnFailure:s(async()=>(o.fatal(`Consumer failed to process messages. Sleeping for ${e.restartTimeout/6e4} minutes(s).`),await new Promise(a=>setTimeout(a,e.restartTimeout)),!0),"restartOnFailure")}},producer:{createPartitioner:m.Partitioners.DefaultPartitioner,allowAutoTopicCreation:!1},subscribe:{fromBeginning:e.fromBeginning??!0}}},{inheritAppConfig:!0})},"configureKafkaMicroservice");0&&(module.exports={configureKafkaMicroservice});

package/dist/index.mjs

@@ -0,0 +1 @@
+var m=Object.defineProperty;var t=(e,r)=>m(e,"name",{value:r,configurable:!0});import{Logger as c}from"@nestjs/common";import{Transport as f}from"@nestjs/microservices";import u from"os";import{logLevel as p,Partitioners as k}from"kafkajs";import{Logger as l}from"@nestjs/common";import{logLevel as a}from"kafkajs";var o=new l("Kafka"),s=t(()=>({level:e,log:{timestamp:r,logger:n,message:i,...g}})=>{(e===a.DEBUG?o.debug:e===a.INFO?o.log:e===a.WARN?o.warn:e===a.ERROR?o.error:o.log).call(o,i,g)},"kafkaLogger");var L=t(async(e,r)=>{let n=new c("Kafka");await e.connectMicroservice({transport:f.KAFKA,options:{postfixId:"",client:{clientId:r.clientId||u.hostname(),brokers:r.brokers,logCreator:s,logLevel:r.logLevel??p.INFO},consumer:{groupId:r.consumerGroup,sessionTimeout:3e4,heartbeatInterval:3e3,allowAutoTopicCreation:!1,retry:{initialRetryTime:500,maxRetryTime:1e3,multiplier:2,factor:0,retries:5,restartOnFailure:t(async()=>(n.fatal(`Consumer failed to process messages. Sleeping for ${r.restartTimeout/6e4} minutes(s).`),await new Promise(i=>setTimeout(i,r.restartTimeout)),!0),"restartOnFailure")}},producer:{createPartitioner:k.DefaultPartitioner,allowAutoTopicCreation:!1},subscribe:{fromBeginning:r.fromBeginning??!0}}},{inheritAppConfig:!0})},"configureKafkaMicroservice");export{L as configureKafkaMicroservice};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@relab/nestjs-kafka",
+  "version": "1.0.0",
+  "description": "Kafka helpers for Nest.js",
+  "main": "dist/index.js",
+  "keywords": [
+    "nest.js"
+  ],
+  "author": "Sergey Zwezdin <sergey@zwezdin.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.5",
+    "@nestjs/microservices": "^11.1.5",
+    "kafkajs": "^2.2.4",
+    "rxjs": "^7.8.2",
+    "@relab/nestjs-trace-context": "^3.7.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.5",
+    "@nestjs/microservices": "^11.1.5",
+    "kafkajs": "^2.2.4",
+    "rxjs": "^7.8.2",
+    "tsup": "^8.5.0",
+    "@relab/nestjs-trace-context": "^3.7.0"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format esm,cjs --out-dir dist",
+    "dev": "tsup src/index.ts --dts --format esm,cjs --out-dir dist --watch"
+  }
+}