sentinel-kafka-manager 1.0.0

package/README.md

@@ -0,0 +1,391 @@
+# sentinel-kafka-manager
+
+Reusable Kafka manager for Node.js microservices built on top of `kafkajs`.
+
+This package helps services:
+
+- connect to Kafka with a small shared API
+- create and reuse producers, consumers, and admin clients safely
+- publish JSON messages
+- provision topics if they do not already exist
+- bootstrap from environment variables for both Docker-internal and host-external Kafka access
+
+## Installation
+
+```bash
+npm install sentinel-kafka-manager
+```
+
+For local development in this package:
+
+```bash
+npm install
+npm run build
+```
+
+## Features
+
+- built on `kafkajs`
+- supports direct broker lists or env-driven broker discovery
+- supports internal Docker-network broker routing
+- supports external localhost or host-based broker routing
+- supports optional SSL, SASL, retry, and timeout settings
+- avoids duplicate producer, consumer, and admin connections during concurrent startup
+
+## Exports
+
+```ts
+import { KafkaManager } from 'sentinel-kafka-manager'
+```
+
+## Quick Start
+
+### 1. Create a manager with explicit brokers
+
+```ts
+import { KafkaManager } from 'sentinel-kafka-manager'
+
+const kafkaManager = new KafkaManager({
+  clientId: 'claims-service',
+  brokers: ['localhost:29092', 'localhost:39092', 'localhost:49092'],
+})
+```
+
+### 2. Publish a message
+
+```ts
+await kafkaManager.publish({
+  topic: 'claims.created',
+  key: 'claim-1001',
+  payload: {
+    claimId: 'claim-1001',
+    status: 'created',
+  },
+})
+```
+
+### 3. Provision topics
+
+```ts
+await kafkaManager.provisionTopics([
+  {
+    topic: 'claims.created',
+    numPartitions: 6,
+    replicationFactor: 3,
+  },
+])
+```
+
+### 4. Reuse a connected consumer
+
+```ts
+const consumer = await kafkaManager.getConsumer('claims-service-group')
+
+await consumer.subscribe({
+  topic: 'claims.created',
+  fromBeginning: false,
+})
+```
+
+### 5. Disconnect on shutdown
+
+```ts
+await kafkaManager.disconnect()
+```
+
+## Environment-Based Setup
+
+`KafkaManager.fromEnv()` supports two styles:
+
+1. explicit broker list with `KAFKA_BROKERS`
+2. derived broker list from your Kafka runtime env naming
+
+### Option A: Explicit broker list
+
+```env
+KAFKA_BROKERS=localhost:29092,localhost:39092,localhost:49092
+```
+
+```ts
+import { KafkaManager } from 'sentinel-kafka-manager'
+
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-service',
+})
+```
+
+### Option B: Derived from your current Kafka cluster env
+
+This package supports the env structure you shared for your KRaft cluster.
+
+#### External mode
+
+Use this when your app runs on the host machine or outside the Kafka Docker network.
+
+```env
+KAFKA_EXTERNAL_HOST=localhost
+KAFKA_BROKER_1_EXTERNAL_PORT=29092
+KAFKA_BROKER_2_EXTERNAL_PORT=39092
+KAFKA_BROKER_3_EXTERNAL_PORT=49092
+KAFKA_BROKER_INTERNAL_PORT=9092
+```
+
+```ts
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-service',
+  mode: 'external',
+})
+```
+
+This resolves to:
+
+```text
+localhost:29092
+localhost:39092
+localhost:49092
+```
+
+#### Internal mode
+
+Use this when your app runs inside Docker on the same Kafka network.
+
+```env
+KAFKA_BROKER_INTERNAL_PORT=9092
+```
+
+```ts
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-service',
+  mode: 'internal',
+})
+```
+
+This resolves to:
+
+```text
+broker-1:9092
+broker-2:9092
+broker-3:9092
+```
+
+## Supported Environment Variables
+
+### Minimal variables
+
+- `KAFKA_BROKERS`
+- `KAFKA_EXTERNAL_HOST`
+- `KAFKA_BROKER_1_EXTERNAL_PORT`
+- `KAFKA_BROKER_2_EXTERNAL_PORT`
+- `KAFKA_BROKER_3_EXTERNAL_PORT`
+- `KAFKA_BROKER_INTERNAL_PORT`
+
+### `fromEnv()` options
+
+You can customize the env lookup behavior:
+
+```ts
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-service',
+  mode: 'external',
+  brokerCount: 3,
+  envKey: 'KAFKA_BROKERS',
+  externalHostEnvKey: 'KAFKA_EXTERNAL_HOST',
+  internalPortEnvKey: 'KAFKA_BROKER_INTERNAL_PORT',
+  externalPortEnvKeyPrefix: 'KAFKA_BROKER_',
+  externalPortEnvKeySuffix: '_EXTERNAL_PORT',
+  internalBrokerHostPrefix: 'broker-',
+})
+```
+
+## Advanced Connection Options
+
+### SSL
+
+```ts
+const kafkaManager = new KafkaManager({
+  clientId: 'claims-service',
+  brokers: ['localhost:29092'],
+  ssl: {
+    rejectUnauthorized: true,
+  },
+})
+```
+
+### SASL
+
+```ts
+const kafkaManager = new KafkaManager({
+  clientId: 'claims-service',
+  brokers: ['localhost:29092'],
+  sasl: {
+    mechanism: 'plain',
+    username: 'kafka-user',
+    password: 'secret',
+  },
+})
+```
+
+### Retry and timeout tuning
+
+```ts
+const kafkaManager = new KafkaManager({
+  clientId: 'claims-service',
+  brokers: ['localhost:29092'],
+  connectionTimeout: 5000,
+  requestTimeout: 30000,
+  retry: {
+    initialRetryTime: 300,
+    retries: 10,
+  },
+})
+```
+
+## API
+
+### `new KafkaManager(options)`
+
+Creates a manager from an explicit broker list.
+
+Options:
+
+- `clientId: string`
+- `brokers: string[]`
+- `ssl?: boolean | { rejectUnauthorized?: boolean }`
+- `sasl?: { mechanism, username, password }`
+- `connectionTimeout?: number`
+- `requestTimeout?: number`
+- `retry?: { initialRetryTime?: number; retries?: number }`
+
+### `KafkaManager.fromEnv(options)`
+
+Creates a manager by reading broker information from environment variables.
+
+Options:
+
+- `clientId: string`
+- `envKey?: string`
+- `mode?: 'internal' | 'external'`
+- `brokerCount?: number`
+- `externalHostEnvKey?: string`
+- `internalPortEnvKey?: string`
+- `externalPortEnvKeyPrefix?: string`
+- `externalPortEnvKeySuffix?: string`
+- `internalBrokerHostPrefix?: string`
+- `ssl?: boolean | { rejectUnauthorized?: boolean }`
+- `sasl?: { mechanism, username, password }`
+- `connectionTimeout?: number`
+- `requestTimeout?: number`
+- `retry?: { initialRetryTime?: number; retries?: number }`
+
+### `getProducer()`
+
+Returns a shared connected Kafka producer.
+
+### `getConsumer(groupId)`
+
+Returns a shared connected Kafka consumer for the provided group id.
+
+### `provisionTopics(topics)`
+
+Creates missing topics using the Kafka admin client.
+
+Topic shape:
+
+```ts
+{
+  topic: string
+  numPartitions?: number
+  replicationFactor?: number
+}
+```
+
+### `publish(options)`
+
+Publishes one JSON-encoded message.
+
+Message shape:
+
+```ts
+{
+  topic: string
+  payload: T
+  key?: string
+  headers?: IHeaders
+}
+```
+
+### `disconnect()`
+
+Disconnects the managed producer, admin client, and any connected consumers.
+
+## Example With Your Kafka Cluster
+
+### Host-based app
+
+```ts
+import { KafkaManager } from 'sentinel-kafka-manager'
+
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-api',
+  mode: 'external',
+})
+
+await kafkaManager.publish({
+  topic: 'claims.created',
+  key: 'claim-1001',
+  payload: {
+    claimId: 'claim-1001',
+    source: 'claims-api',
+  },
+})
+```
+
+### Dockerized app on the same network
+
+```ts
+import { KafkaManager } from 'sentinel-kafka-manager'
+
+const kafkaManager = KafkaManager.fromEnv({
+  clientId: 'claims-worker',
+  mode: 'internal',
+})
+```
+
+## Publishing
+
+Build before publishing:
+
+```bash
+npm run build
+```
+
+Publish the package:
+
+```bash
+npm publish
+```
+
+This package already sets `"publishConfig": { "access": "public" }`, so you do not need to pass `--access public` every time.
+
+### Publish Troubleshooting
+
+#### `403` with 2FA or token message
+
+If npm says two-factor authentication or a granular token with bypass 2FA is required, authenticate with an account that can publish or use a publish-capable npm token.
+
+Useful checks:
+
+```bash
+npm whoami
+```
+
+#### `404` or package name unavailable
+
+If npm says the package could not be published, confirm that the package name is available to your npm account and not already owned by someone else.
+
+## Notes
+
+- connect clients only to brokers, not KRaft controller nodes
+- for your current cluster, PLAINTEXT is enough and SSL/SASL is optional
+- if your services use `localhost`, use `mode: 'external'`
+- if your services run in Docker on the Kafka network, use `mode: 'internal'`

package/dist/index.d.mts

@@ -0,0 +1,77 @@
+import { SASLOptions, Consumer, IHeaders, Producer } from 'kafkajs';
+
+type KafkaConnectionMode = 'internal' | 'external';
+interface KafkaRetryOptions {
+    initialRetryTime?: number;
+    retries?: number;
+}
+interface KafkaSslOptions {
+    rejectUnauthorized?: boolean;
+}
+type KafkaSaslOptions = SASLOptions;
+interface KafkaTopicConfig {
+    topic: string;
+    numPartitions?: number;
+    replicationFactor?: number;
+}
+interface PublishMessageOptions<T> {
+    topic: string;
+    payload: T;
+    key?: string;
+    headers?: IHeaders;
+}
+interface KafkaManagerOptions {
+    clientId: string;
+    brokers: string[];
+    ssl?: boolean | KafkaSslOptions;
+    sasl?: KafkaSaslOptions;
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    retry?: KafkaRetryOptions;
+}
+interface KafkaConnectionOptions {
+    clientId: string;
+    envKey?: string;
+    mode?: KafkaConnectionMode;
+    brokerCount?: number;
+    externalHostEnvKey?: string;
+    internalPortEnvKey?: string;
+    externalPortEnvKeyPrefix?: string;
+    externalPortEnvKeySuffix?: string;
+    internalBrokerHostPrefix?: string;
+    ssl?: boolean | KafkaSslOptions;
+    sasl?: KafkaSaslOptions;
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    retry?: KafkaRetryOptions;
+}
+interface KafkaConsumers {
+    [groupId: string]: Consumer;
+}
+type KafkaProducer = Producer;
+type KafkaConsumer = Consumer;
+
+declare class KafkaManager {
+    private kafka;
+    private producer;
+    private producerPromise;
+    private admin;
+    private adminPromise;
+    private consumers;
+    private consumerPromises;
+    constructor(options: KafkaManagerOptions);
+    static fromEnv(options: KafkaConnectionOptions): KafkaManager;
+    getProducer(): Promise<Producer>;
+    getConsumer(groupId: string): Promise<Consumer>;
+    provisionTopics(topics: KafkaTopicConfig[]): Promise<void>;
+    publish<T>(options: PublishMessageOptions<T>): Promise<void>;
+    disconnect(): Promise<void>;
+    private static parseBrokerList;
+    private static buildBrokersFromRuntime;
+    private connectProducer;
+    private connectConsumer;
+    private getAdmin;
+    private connectAdmin;
+}
+
+export { type KafkaConnectionMode, type KafkaConnectionOptions, type KafkaConsumer, type KafkaConsumers, KafkaManager, type KafkaManagerOptions, type KafkaProducer, type KafkaRetryOptions, type KafkaSaslOptions, type KafkaSslOptions, type KafkaTopicConfig, type PublishMessageOptions };

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { SASLOptions, Consumer, IHeaders, Producer } from 'kafkajs';
+
+type KafkaConnectionMode = 'internal' | 'external';
+interface KafkaRetryOptions {
+    initialRetryTime?: number;
+    retries?: number;
+}
+interface KafkaSslOptions {
+    rejectUnauthorized?: boolean;
+}
+type KafkaSaslOptions = SASLOptions;
+interface KafkaTopicConfig {
+    topic: string;
+    numPartitions?: number;
+    replicationFactor?: number;
+}
+interface PublishMessageOptions<T> {
+    topic: string;
+    payload: T;
+    key?: string;
+    headers?: IHeaders;
+}
+interface KafkaManagerOptions {
+    clientId: string;
+    brokers: string[];
+    ssl?: boolean | KafkaSslOptions;
+    sasl?: KafkaSaslOptions;
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    retry?: KafkaRetryOptions;
+}
+interface KafkaConnectionOptions {
+    clientId: string;
+    envKey?: string;
+    mode?: KafkaConnectionMode;
+    brokerCount?: number;
+    externalHostEnvKey?: string;
+    internalPortEnvKey?: string;
+    externalPortEnvKeyPrefix?: string;
+    externalPortEnvKeySuffix?: string;
+    internalBrokerHostPrefix?: string;
+    ssl?: boolean | KafkaSslOptions;
+    sasl?: KafkaSaslOptions;
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    retry?: KafkaRetryOptions;
+}
+interface KafkaConsumers {
+    [groupId: string]: Consumer;
+}
+type KafkaProducer = Producer;
+type KafkaConsumer = Consumer;
+
+declare class KafkaManager {
+    private kafka;
+    private producer;
+    private producerPromise;
+    private admin;
+    private adminPromise;
+    private consumers;
+    private consumerPromises;
+    constructor(options: KafkaManagerOptions);
+    static fromEnv(options: KafkaConnectionOptions): KafkaManager;
+    getProducer(): Promise<Producer>;
+    getConsumer(groupId: string): Promise<Consumer>;
+    provisionTopics(topics: KafkaTopicConfig[]): Promise<void>;
+    publish<T>(options: PublishMessageOptions<T>): Promise<void>;
+    disconnect(): Promise<void>;
+    private static parseBrokerList;
+    private static buildBrokersFromRuntime;
+    private connectProducer;
+    private connectConsumer;
+    private getAdmin;
+    private connectAdmin;
+}
+
+export { type KafkaConnectionMode, type KafkaConnectionOptions, type KafkaConsumer, type KafkaConsumers, KafkaManager, type KafkaManagerOptions, type KafkaProducer, type KafkaRetryOptions, type KafkaSaslOptions, type KafkaSslOptions, type KafkaTopicConfig, type PublishMessageOptions };

package/dist/index.js

@@ -0,0 +1,219 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KafkaManager: () => KafkaManager
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/kafka-manager.ts
+var import_kafkajs = require("kafkajs");
+var KafkaManager = class _KafkaManager {
+  constructor(options) {
+    this.producer = null;
+    // Share the same in-flight connection across concurrent callers.
+    this.producerPromise = null;
+    this.admin = null;
+    // Admin access is reused so topic provisioning does not race on startup.
+    this.adminPromise = null;
+    this.consumers = /* @__PURE__ */ new Map();
+    // Consumers are cached per group id to avoid duplicate group members.
+    this.consumerPromises = /* @__PURE__ */ new Map();
+    if (!options.brokers.length) {
+      throw new Error("Kafka brokers are required.");
+    }
+    this.kafka = new import_kafkajs.Kafka({
+      clientId: options.clientId,
+      brokers: options.brokers,
+      ssl: options.ssl,
+      sasl: options.sasl,
+      connectionTimeout: options.connectionTimeout,
+      requestTimeout: options.requestTimeout,
+      retry: options.retry ?? {
+        initialRetryTime: 300,
+        retries: 10
+      }
+    });
+  }
+  static fromEnv(options) {
+    const brokerString = options.envKey ? process.env[options.envKey] : process.env.KAFKA_BROKERS;
+    const brokers = brokerString ? _KafkaManager.parseBrokerList(brokerString) : _KafkaManager.buildBrokersFromRuntime(options);
+    if (!brokers.length) {
+      throw new Error("Kafka brokers are not configured.");
+    }
+    return new _KafkaManager({
+      clientId: options.clientId,
+      brokers,
+      ssl: options.ssl,
+      sasl: options.sasl,
+      connectionTimeout: options.connectionTimeout,
+      requestTimeout: options.requestTimeout,
+      retry: options.retry
+    });
+  }
+  async getProducer() {
+    if (this.producer) {
+      return this.producer;
+    }
+    if (!this.producerPromise) {
+      this.producerPromise = this.connectProducer();
+    }
+    return this.producerPromise;
+  }
+  async getConsumer(groupId) {
+    const existingConsumer = this.consumers.get(groupId);
+    if (existingConsumer) {
+      return existingConsumer;
+    }
+    const existingPromise = this.consumerPromises.get(groupId);
+    if (existingPromise) {
+      return existingPromise;
+    }
+    const consumerPromise = this.connectConsumer(groupId);
+    this.consumerPromises.set(groupId, consumerPromise);
+    return consumerPromise;
+  }
+  async provisionTopics(topics) {
+    const admin = await this.getAdmin();
+    const existingTopics = await admin.listTopics();
+    const topicsToCreate = topics.filter((topic) => !existingTopics.includes(topic.topic)).map((topic) => ({
+      topic: topic.topic,
+      numPartitions: topic.numPartitions ?? 3,
+      replicationFactor: topic.replicationFactor ?? 1
+    }));
+    if (!topicsToCreate.length) {
+      return;
+    }
+    await admin.createTopics({
+      topics: topicsToCreate
+    });
+  }
+  async publish(options) {
+    const producer = await this.getProducer();
+    await producer.send({
+      topic: options.topic,
+      messages: [
+        {
+          key: options.key,
+          value: JSON.stringify(options.payload),
+          headers: options.headers
+        }
+      ]
+    });
+  }
+  async disconnect() {
+    this.producerPromise = null;
+    if (this.producer) {
+      await this.producer.disconnect();
+      this.producer = null;
+    }
+    this.consumerPromises.clear();
+    for (const consumer of this.consumers.values()) {
+      await consumer.disconnect();
+    }
+    this.consumers.clear();
+    this.adminPromise = null;
+    if (this.admin) {
+      await this.admin.disconnect().catch(() => void 0);
+      this.admin = null;
+    }
+  }
+  static parseBrokerList(brokerString) {
+    return brokerString.split(",").map((broker) => broker.trim()).filter(Boolean);
+  }
+  static buildBrokersFromRuntime(options) {
+    const mode = options.mode ?? "external";
+    const brokerCount = options.brokerCount ?? 3;
+    if (mode === "internal") {
+      const internalPortEnvKey = options.internalPortEnvKey ?? "KAFKA_BROKER_INTERNAL_PORT";
+      const internalPort = process.env[internalPortEnvKey];
+      const hostPrefix = options.internalBrokerHostPrefix ?? "broker-";
+      if (!internalPort) {
+        throw new Error(`${internalPortEnvKey} is not configured.`);
+      }
+      return Array.from({ length: brokerCount }, (_, index) => `${hostPrefix}${index + 1}:${internalPort}`);
+    }
+    const externalHostEnvKey = options.externalHostEnvKey ?? "KAFKA_EXTERNAL_HOST";
+    const externalHost = process.env[externalHostEnvKey];
+    const externalPortEnvKeyPrefix = options.externalPortEnvKeyPrefix ?? "KAFKA_BROKER_";
+    const externalPortEnvKeySuffix = options.externalPortEnvKeySuffix ?? "_EXTERNAL_PORT";
+    if (!externalHost) {
+      throw new Error(`${externalHostEnvKey} is not configured.`);
+    }
+    return Array.from({ length: brokerCount }, (_, index) => {
+      const brokerNumber = index + 1;
+      const portEnvKey = `${externalPortEnvKeyPrefix}${brokerNumber}${externalPortEnvKeySuffix}`;
+      const port = process.env[portEnvKey];
+      if (!port) {
+        throw new Error(`${portEnvKey} is not configured.`);
+      }
+      return `${externalHost}:${port}`;
+    });
+  }
+  async connectProducer() {
+    const producer = this.kafka.producer();
+    try {
+      await producer.connect();
+      this.producer = producer;
+      return producer;
+    } catch (error) {
+      this.producerPromise = null;
+      throw error;
+    }
+  }
+  async connectConsumer(groupId) {
+    const consumer = this.kafka.consumer({
+      groupId
+    });
+    try {
+      await consumer.connect();
+      this.consumers.set(groupId, consumer);
+      return consumer;
+    } catch (error) {
+      this.consumerPromises.delete(groupId);
+      throw error;
+    }
+  }
+  async getAdmin() {
+    if (this.admin) {
+      return this.admin;
+    }
+    if (!this.adminPromise) {
+      this.adminPromise = this.connectAdmin();
+    }
+    return this.adminPromise;
+  }
+  async connectAdmin() {
+    const admin = this.kafka.admin();
+    try {
+      await admin.connect();
+      this.admin = admin;
+      return admin;
+    } catch (error) {
+      this.adminPromise = null;
+      throw error;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KafkaManager
+});

package/dist/index.mjs

@@ -0,0 +1,194 @@
+// src/kafka-manager.ts
+import {
+  Kafka
+} from "kafkajs";
+var KafkaManager = class _KafkaManager {
+  constructor(options) {
+    this.producer = null;
+    // Share the same in-flight connection across concurrent callers.
+    this.producerPromise = null;
+    this.admin = null;
+    // Admin access is reused so topic provisioning does not race on startup.
+    this.adminPromise = null;
+    this.consumers = /* @__PURE__ */ new Map();
+    // Consumers are cached per group id to avoid duplicate group members.
+    this.consumerPromises = /* @__PURE__ */ new Map();
+    if (!options.brokers.length) {
+      throw new Error("Kafka brokers are required.");
+    }
+    this.kafka = new Kafka({
+      clientId: options.clientId,
+      brokers: options.brokers,
+      ssl: options.ssl,
+      sasl: options.sasl,
+      connectionTimeout: options.connectionTimeout,
+      requestTimeout: options.requestTimeout,
+      retry: options.retry ?? {
+        initialRetryTime: 300,
+        retries: 10
+      }
+    });
+  }
+  static fromEnv(options) {
+    const brokerString = options.envKey ? process.env[options.envKey] : process.env.KAFKA_BROKERS;
+    const brokers = brokerString ? _KafkaManager.parseBrokerList(brokerString) : _KafkaManager.buildBrokersFromRuntime(options);
+    if (!brokers.length) {
+      throw new Error("Kafka brokers are not configured.");
+    }
+    return new _KafkaManager({
+      clientId: options.clientId,
+      brokers,
+      ssl: options.ssl,
+      sasl: options.sasl,
+      connectionTimeout: options.connectionTimeout,
+      requestTimeout: options.requestTimeout,
+      retry: options.retry
+    });
+  }
+  async getProducer() {
+    if (this.producer) {
+      return this.producer;
+    }
+    if (!this.producerPromise) {
+      this.producerPromise = this.connectProducer();
+    }
+    return this.producerPromise;
+  }
+  async getConsumer(groupId) {
+    const existingConsumer = this.consumers.get(groupId);
+    if (existingConsumer) {
+      return existingConsumer;
+    }
+    const existingPromise = this.consumerPromises.get(groupId);
+    if (existingPromise) {
+      return existingPromise;
+    }
+    const consumerPromise = this.connectConsumer(groupId);
+    this.consumerPromises.set(groupId, consumerPromise);
+    return consumerPromise;
+  }
+  async provisionTopics(topics) {
+    const admin = await this.getAdmin();
+    const existingTopics = await admin.listTopics();
+    const topicsToCreate = topics.filter((topic) => !existingTopics.includes(topic.topic)).map((topic) => ({
+      topic: topic.topic,
+      numPartitions: topic.numPartitions ?? 3,
+      replicationFactor: topic.replicationFactor ?? 1
+    }));
+    if (!topicsToCreate.length) {
+      return;
+    }
+    await admin.createTopics({
+      topics: topicsToCreate
+    });
+  }
+  async publish(options) {
+    const producer = await this.getProducer();
+    await producer.send({
+      topic: options.topic,
+      messages: [
+        {
+          key: options.key,
+          value: JSON.stringify(options.payload),
+          headers: options.headers
+        }
+      ]
+    });
+  }
+  async disconnect() {
+    this.producerPromise = null;
+    if (this.producer) {
+      await this.producer.disconnect();
+      this.producer = null;
+    }
+    this.consumerPromises.clear();
+    for (const consumer of this.consumers.values()) {
+      await consumer.disconnect();
+    }
+    this.consumers.clear();
+    this.adminPromise = null;
+    if (this.admin) {
+      await this.admin.disconnect().catch(() => void 0);
+      this.admin = null;
+    }
+  }
+  static parseBrokerList(brokerString) {
+    return brokerString.split(",").map((broker) => broker.trim()).filter(Boolean);
+  }
+  static buildBrokersFromRuntime(options) {
+    const mode = options.mode ?? "external";
+    const brokerCount = options.brokerCount ?? 3;
+    if (mode === "internal") {
+      const internalPortEnvKey = options.internalPortEnvKey ?? "KAFKA_BROKER_INTERNAL_PORT";
+      const internalPort = process.env[internalPortEnvKey];
+      const hostPrefix = options.internalBrokerHostPrefix ?? "broker-";
+      if (!internalPort) {
+        throw new Error(`${internalPortEnvKey} is not configured.`);
+      }
+      return Array.from({ length: brokerCount }, (_, index) => `${hostPrefix}${index + 1}:${internalPort}`);
+    }
+    const externalHostEnvKey = options.externalHostEnvKey ?? "KAFKA_EXTERNAL_HOST";
+    const externalHost = process.env[externalHostEnvKey];
+    const externalPortEnvKeyPrefix = options.externalPortEnvKeyPrefix ?? "KAFKA_BROKER_";
+    const externalPortEnvKeySuffix = options.externalPortEnvKeySuffix ?? "_EXTERNAL_PORT";
+    if (!externalHost) {
+      throw new Error(`${externalHostEnvKey} is not configured.`);
+    }
+    return Array.from({ length: brokerCount }, (_, index) => {
+      const brokerNumber = index + 1;
+      const portEnvKey = `${externalPortEnvKeyPrefix}${brokerNumber}${externalPortEnvKeySuffix}`;
+      const port = process.env[portEnvKey];
+      if (!port) {
+        throw new Error(`${portEnvKey} is not configured.`);
+      }
+      return `${externalHost}:${port}`;
+    });
+  }
+  async connectProducer() {
+    const producer = this.kafka.producer();
+    try {
+      await producer.connect();
+      this.producer = producer;
+      return producer;
+    } catch (error) {
+      this.producerPromise = null;
+      throw error;
+    }
+  }
+  async connectConsumer(groupId) {
+    const consumer = this.kafka.consumer({
+      groupId
+    });
+    try {
+      await consumer.connect();
+      this.consumers.set(groupId, consumer);
+      return consumer;
+    } catch (error) {
+      this.consumerPromises.delete(groupId);
+      throw error;
+    }
+  }
+  async getAdmin() {
+    if (this.admin) {
+      return this.admin;
+    }
+    if (!this.adminPromise) {
+      this.adminPromise = this.connectAdmin();
+    }
+    return this.adminPromise;
+  }
+  async connectAdmin() {
+    const admin = this.kafka.admin();
+    try {
+      await admin.connect();
+      this.admin = admin;
+      return admin;
+    } catch (error) {
+      this.adminPromise = null;
+      throw error;
+    }
+  }
+};
+export {
+  KafkaManager
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "sentinel-kafka-manager",
+  "version": "1.0.0",
+  "description": "Reusable Kafka manager for Node.js microservices",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "kafka",
+    "kafkajs",
+    "nodejs",
+    "microservice"
+  ],
+  "author": "Ngen Claims",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "kafkajs": "^2.2.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}