@drarzter/kafka-client 0.2.2 → 0.3.1

package/dist/testing.mjs

@@ -0,0 +1,127 @@
+import "./chunk-EQQGB2QZ.mjs";
+
+// src/testing/mock-client.ts
+function detectMockFactory() {
+  try {
+    const jestFn = eval("typeof jest !== 'undefined' && jest.fn");
+    if (typeof jestFn === "function") return () => eval("jest.fn")();
+  } catch {
+  }
+  try {
+    const viFn = eval("typeof vi !== 'undefined' && vi.fn");
+    if (typeof viFn === "function") return () => eval("vi.fn")();
+  } catch {
+  }
+  throw new Error(
+    "createMockKafkaClient: no mock framework detected (jest/vitest). Pass a custom mockFactory."
+  );
+}
+function createMockKafkaClient(mockFactory) {
+  const fn = mockFactory ?? detectMockFactory();
+  const mock = () => fn();
+  const resolved = (value) => mock().mockResolvedValue(value);
+  const returning = (value) => mock().mockReturnValue(value);
+  return {
+    checkStatus: resolved({ topics: [] }),
+    getClientId: returning("mock-client"),
+    sendMessage: resolved(void 0),
+    sendBatch: resolved(void 0),
+    transaction: mock().mockImplementation(async (cb) => {
+      const ctx = {
+        send: resolved(void 0),
+        sendBatch: resolved(void 0)
+      };
+      await cb(ctx);
+    }),
+    startConsumer: resolved(void 0),
+    startBatchConsumer: resolved(void 0),
+    stopConsumer: resolved(void 0),
+    disconnect: resolved(void 0)
+  };
+}
+
+// src/testing/test-container.ts
+import {
+  KafkaContainer
+} from "@testcontainers/kafka";
+import { Kafka, logLevel as KafkaLogLevel } from "kafkajs";
+var KafkaTestContainer = class {
+  container;
+  image;
+  transactionWarmup;
+  topics;
+  constructor(options) {
+    this.image = options?.image ?? "confluentinc/cp-kafka:7.7.0";
+    this.transactionWarmup = options?.transactionWarmup ?? true;
+    this.topics = options?.topics ?? [];
+  }
+  /**
+   * Start the Kafka container, pre-create topics, and optionally warm up
+   * the transaction coordinator.
+   *
+   * @returns Broker connection strings, e.g. `["localhost:55123"]`.
+   */
+  async start() {
+    this.container = await new KafkaContainer(this.image).withKraft().withExposedPorts(9093).withEnvironment({
+      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1",
+      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
+    }).start();
+    const host = this.container.getHost();
+    const port = this.container.getMappedPort(9093);
+    const brokers = [`${host}:${port}`];
+    const kafka = new Kafka({
+      clientId: "test-container-setup",
+      brokers,
+      logLevel: KafkaLogLevel.NOTHING
+    });
+    if (this.topics.length > 0) {
+      const admin = kafka.admin();
+      await admin.connect();
+      await admin.createTopics({
+        topics: this.topics.map(
+          (t) => typeof t === "string" ? { topic: t, numPartitions: 1 } : { topic: t.topic, numPartitions: t.numPartitions ?? 1 }
+        )
+      });
+      await admin.disconnect();
+    }
+    if (this.transactionWarmup) {
+      const warmupKafka = new Kafka({
+        clientId: "test-container-warmup",
+        brokers,
+        logLevel: KafkaLogLevel.NOTHING,
+        retry: { retries: 30, initialRetryTime: 500, maxRetryTime: 3e4 }
+      });
+      const txProducer = warmupKafka.producer({
+        transactionalId: "test-container-warmup-tx",
+        idempotent: true,
+        maxInFlightRequests: 1
+      });
+      await txProducer.connect();
+      const tx = await txProducer.transaction();
+      await tx.abort();
+      await txProducer.disconnect();
+    }
+    return brokers;
+  }
+  /** Stop and remove the container. */
+  async stop() {
+    await this.container?.stop();
+    this.container = void 0;
+  }
+  /** Broker connection strings. Throws if container is not started. */
+  get brokers() {
+    if (!this.container) {
+      throw new Error(
+        "KafkaTestContainer is not started. Call start() first."
+      );
+    }
+    const host = this.container.getHost();
+    const port = this.container.getMappedPort(9093);
+    return [`${host}:${port}`];
+  }
+};
+export {
+  KafkaTestContainer,
+  createMockKafkaClient
+};
+//# sourceMappingURL=testing.mjs.map

package/dist/testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing/mock-client.ts","../src/testing/test-container.ts"],"sourcesContent":["import type { IKafkaClient, TopicMapConstraint } from \"../client/types\";\n\n/**\n * Fully typed mock of `IKafkaClient<T>` where every method is a mock function.\n * Compatible with Jest, Vitest, or any framework whose `fn()` returns\n * an object with `.mock`, `.mockResolvedValue`, etc.\n */\nexport type MockKafkaClient<T extends TopicMapConstraint<T>> = {\n  [K in keyof IKafkaClient<T>]: IKafkaClient<T>[K] & Record<string, any>;\n};\n\n/** Factory that creates a no-op mock function (e.g. `() => jest.fn()`). */\nexport type MockFactory = () => (...args: any[]) => any;\n\nfunction detectMockFactory(): MockFactory {\n   \n  // Jest and Vitest inject globals into the test environment scope,\n  // which may not be on `globalThis`. Use eval to check the actual scope.\n  try {\n    const jestFn = eval(\"typeof jest !== 'undefined' && jest.fn\");\n    if (typeof jestFn === \"function\") return () => (eval(\"jest.fn\") as () => (...args: any[]) => any)();\n  } catch { /* not available */ }\n  try {\n    const viFn = eval(\"typeof vi !== 'undefined' && vi.fn\");\n    if (typeof viFn === \"function\") return () => (eval(\"vi.fn\") as () => (...args: any[]) => any)();\n  } catch { /* not available */ }\n   \n\n  throw new Error(\n    \"createMockKafkaClient: no mock framework detected (jest/vitest). \" +\n      \"Pass a custom mockFactory.\",\n  );\n}\n\n/**\n * Create a fully typed mock implementing every `IKafkaClient<T>` method.\n * Useful for unit-testing services that depend on `KafkaClient` without\n * touching a real broker.\n *\n * Auto-detects Jest (`jest.fn()`) or Vitest (`vi.fn()`). Pass a custom\n * `mockFactory` for other frameworks.\n *\n * All methods resolve to sensible defaults:\n * - `checkStatus()` → `{ topics: [] }`\n * - `getClientId()` → `\"mock-client\"`\n * - void methods → `undefined`\n *\n * @example\n * ```ts\n * const kafka = createMockKafkaClient<MyTopics>();\n *\n * const service = new OrdersService(kafka);\n * await service.createOrder();\n *\n * expect(kafka.sendMessage).toHaveBeenCalledWith(\n *   'order.created',\n *   expect.objectContaining({ orderId: '123' }),\n * );\n * ```\n */\nexport function createMockKafkaClient<T extends TopicMapConstraint<T>>(\n  mockFactory?: MockFactory,\n): MockKafkaClient<T> {\n  const fn = mockFactory ?? detectMockFactory();\n\n  const mock = () => fn() as any;\n  const resolved = (value: unknown) => mock().mockResolvedValue(value);\n  const returning = (value: unknown) => mock().mockReturnValue(value);\n\n  return {\n    checkStatus: resolved({ topics: [] }),\n    getClientId: returning(\"mock-client\"),\n    sendMessage: resolved(undefined),\n    sendBatch: resolved(undefined),\n    transaction: mock().mockImplementation(async (cb: (ctx: Record<string, unknown>) => Promise<void>) => {\n      const ctx = {\n        send: resolved(undefined),\n        sendBatch: resolved(undefined),\n      };\n      await cb(ctx);\n    }),\n    startConsumer: resolved(undefined),\n    startBatchConsumer: resolved(undefined),\n    stopConsumer: resolved(undefined),\n    disconnect: resolved(undefined),\n  } as unknown as MockKafkaClient<T>;\n}\n","import {\n  KafkaContainer,\n  type StartedKafkaContainer,\n} from \"@testcontainers/kafka\";\nimport { Kafka, logLevel as KafkaLogLevel } from \"kafkajs\";\n\n/** Options for `KafkaTestContainer`. */\nexport interface KafkaTestContainerOptions {\n  /** Docker image. Default: `\"confluentinc/cp-kafka:7.7.0\"`. */\n  image?: string;\n  /** Warm up the transactional coordinator on start. Default: `true`. */\n  transactionWarmup?: boolean;\n  /** Topics to pre-create. Each entry can be a string (1 partition) or `{ topic, numPartitions }`. */\n  topics?: Array<string | { topic: string; numPartitions?: number }>;\n}\n\n/**\n * Thin wrapper around `@testcontainers/kafka` that starts a single-node\n * KRaft Kafka container and exposes `brokers` for use with `KafkaClient`.\n *\n * Handles common setup pain points:\n * - Transaction coordinator warmup (avoids transactional producer hangs)\n * - Topic pre-creation (avoids race conditions)\n *\n * @example\n * ```ts\n * const container = new KafkaTestContainer({ topics: ['orders', 'payments'] });\n * const brokers = await container.start();\n *\n * const kafka = new KafkaClient('test', 'test-group', brokers);\n * // ... run tests ...\n *\n * await container.stop();\n * ```\n *\n * @example Jest lifecycle\n * ```ts\n * let container: KafkaTestContainer;\n * let brokers: string[];\n *\n * beforeAll(async () => {\n *   container = new KafkaTestContainer({ topics: ['orders'] });\n *   brokers = await container.start();\n * }, 120_000);\n *\n * afterAll(() => container.stop());\n * ```\n */\nexport class KafkaTestContainer {\n  private container: StartedKafkaContainer | undefined;\n  private readonly image: string;\n  private readonly transactionWarmup: boolean;\n  private readonly topics: Array<\n    string | { topic: string; numPartitions?: number }\n  >;\n\n  constructor(options?: KafkaTestContainerOptions) {\n    this.image = options?.image ?? \"confluentinc/cp-kafka:7.7.0\";\n    this.transactionWarmup = options?.transactionWarmup ?? true;\n    this.topics = options?.topics ?? [];\n  }\n\n  /**\n   * Start the Kafka container, pre-create topics, and optionally warm up\n   * the transaction coordinator.\n   *\n   * @returns Broker connection strings, e.g. `[\"localhost:55123\"]`.\n   */\n  async start(): Promise<string[]> {\n    this.container = await new KafkaContainer(this.image)\n      .withKraft()\n      .withExposedPorts(9093)\n      .withEnvironment({\n        KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: \"1\",\n        KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: \"1\",\n      })\n      .start();\n\n    const host = this.container.getHost();\n    const port = this.container.getMappedPort(9093);\n    const brokers = [`${host}:${port}`];\n\n    const kafka = new Kafka({\n      clientId: \"test-container-setup\",\n      brokers,\n      logLevel: KafkaLogLevel.NOTHING,\n    });\n\n    if (this.topics.length > 0) {\n      const admin = kafka.admin();\n      await admin.connect();\n      await admin.createTopics({\n        topics: this.topics.map((t) =>\n          typeof t === \"string\"\n            ? { topic: t, numPartitions: 1 }\n            : { topic: t.topic, numPartitions: t.numPartitions ?? 1 },\n        ),\n      });\n      await admin.disconnect();\n    }\n\n    if (this.transactionWarmup) {\n      const warmupKafka = new Kafka({\n        clientId: \"test-container-warmup\",\n        brokers,\n        logLevel: KafkaLogLevel.NOTHING,\n        retry: { retries: 30, initialRetryTime: 500, maxRetryTime: 30000 },\n      });\n      const txProducer = warmupKafka.producer({\n        transactionalId: \"test-container-warmup-tx\",\n        idempotent: true,\n        maxInFlightRequests: 1,\n      });\n      await txProducer.connect();\n      const tx = await txProducer.transaction();\n      await tx.abort();\n      await txProducer.disconnect();\n    }\n\n    return brokers;\n  }\n\n  /** Stop and remove the container. */\n  async stop(): Promise<void> {\n    await this.container?.stop();\n    this.container = undefined;\n  }\n\n  /** Broker connection strings. Throws if container is not started. */\n  get brokers(): string[] {\n    if (!this.container) {\n      throw new Error(\n        \"KafkaTestContainer is not started. Call start() first.\",\n      );\n    }\n    const host = this.container.getHost();\n    const port = this.container.getMappedPort(9093);\n    return [`${host}:${port}`];\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types-CtwJihJ3.d.mts

@@ -0,0 +1,224 @@
+/**
+ * Any validation library with a `.parse()` method.
+ * Works with Zod, Valibot, ArkType, or any custom validator.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * const schema: SchemaLike<{ id: string }> = z.object({ id: z.string() });
+ * ```
+ */
+interface SchemaLike<T = any> {
+    parse(data: unknown): T;
+}
+/** Infer the output type from a SchemaLike. */
+type InferSchema<S extends SchemaLike> = S extends SchemaLike<infer T> ? T : never;
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+    /** Runtime schema validator. Present only when created via `topic().schema()`. */
+    readonly __schema?: SchemaLike<M>;
+}
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * // Without schema — type provided explicitly:
+ * const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
+ *
+ * // With schema — type inferred from schema:
+ * const OrderCreated = topic('order.created').schema(z.object({
+ *   orderId: z.string(),
+ *   amount: z.number(),
+ * }));
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+declare function topic<N extends string>(name: N): {
+    <M extends Record<string, any>>(): TopicDescriptor<N, M>;
+    schema<S extends SchemaLike<Record<string, any>>>(schema: S): TopicDescriptor<N, InferSchema<S>>;
+};
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+
+/**
+ * Mapping of topic names to their message types.
+ * Define this interface to get type-safe publish/subscribe across your app.
+ *
+ * @example
+ * ```ts
+ * // with explicit extends (IDE hints for values)
+ * interface MyTopics extends TTopicMessageMap {
+ *   "orders.created": { orderId: string; amount: number };
+ *   "users.updated": { userId: string; name: string };
+ * }
+ *
+ * // or plain interface / type — works the same
+ * interface MyTopics {
+ *   "orders.created": { orderId: string; amount: number };
+ * }
+ * ```
+ */
+type TTopicMessageMap = {
+    [topic: string]: Record<string, any>;
+};
+/**
+ * Generic constraint for topic-message maps.
+ * Works with both `type` aliases and `interface` declarations.
+ */
+type TopicMapConstraint<T> = {
+    [K in keyof T]: Record<string, any>;
+};
+type ClientId = string;
+type GroupId = string;
+type MessageHeaders = Record<string, string>;
+/** Options for sending a single message. */
+interface SendOptions {
+    /** Partition key for message routing. */
+    key?: string;
+    /** Custom headers attached to the message. */
+    headers?: MessageHeaders;
+}
+/** Metadata exposed to batch consumer handlers. */
+interface BatchMeta {
+    /** Partition number for this batch. */
+    partition: number;
+    /** Highest offset available on the broker for this partition. */
+    highWatermark: string;
+    /** Send a heartbeat to the broker to prevent session timeout. */
+    heartbeat(): Promise<void>;
+    /** Mark an offset as processed (for manual offset management). */
+    resolveOffset(offset: string): void;
+    /** Commit offsets if the auto-commit threshold has been reached. */
+    commitOffsetsIfNecessary(): Promise<void>;
+}
+/** Options for configuring a Kafka consumer. */
+interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Override the default consumer group ID from the constructor. */
+    groupId?: string;
+    /** Start reading from earliest offset. Default: `false`. */
+    fromBeginning?: boolean;
+    /** Automatically commit offsets. Default: `true`. */
+    autoCommit?: boolean;
+    /** Retry policy for failed message processing. */
+    retry?: RetryOptions;
+    /** Send failed messages to a Dead Letter Queue (`<topic>.dlq`). */
+    dlq?: boolean;
+    /** Interceptors called before/after each message. */
+    interceptors?: ConsumerInterceptor<T>[];
+    /** @internal Schema map populated by @SubscribeTo when descriptors have schemas. */
+    schemas?: Map<string, SchemaLike>;
+    /** Retry config for `consumer.subscribe()` when the topic doesn't exist yet. */
+    subscribeRetry?: SubscribeRetryOptions;
+}
+/** Configuration for consumer retry behavior. */
+interface RetryOptions {
+    /** Maximum number of retry attempts before giving up. */
+    maxRetries: number;
+    /** Base delay between retries in ms (multiplied by attempt number). Default: `1000`. */
+    backoffMs?: number;
+}
+/**
+ * Interceptor hooks for consumer message processing.
+ * All methods are optional — implement only what you need.
+ */
+interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Called before the message handler. */
+    before?(message: T[keyof T], topic: string): Promise<void> | void;
+    /** Called after the message handler succeeds. */
+    after?(message: T[keyof T], topic: string): Promise<void> | void;
+    /** Called when the message handler throws. */
+    onError?(message: T[keyof T], topic: string, error: Error): Promise<void> | void;
+}
+/** Context passed to the `transaction()` callback with type-safe send methods. */
+interface TransactionContext<T extends TopicMapConstraint<T>> {
+    send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<{
+        value: T[K];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+}
+/** Interface describing all public methods of the Kafka client. */
+interface IKafkaClient<T extends TopicMapConstraint<T>> {
+    checkStatus(): Promise<{
+        topics: string[];
+    }>;
+    startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (messages: T[K[number]][], topic: K[number], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (messages: D["__type"][], topic: D["__topic"], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    stopConsumer(): Promise<void>;
+    sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<{
+        value: T[K];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+    getClientId: () => ClientId;
+    disconnect(): Promise<void>;
+}
+/**
+ * Logger interface for KafkaClient.
+ * Compatible with NestJS Logger, console, winston, pino, or any custom logger.
+ */
+interface KafkaLogger {
+    log(message: string): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/** Options for `KafkaClient` constructor. */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
+    logger?: KafkaLogger;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+}
+/** Options for consumer subscribe retry when topic doesn't exist yet. */
+interface SubscribeRetryOptions {
+    /** Maximum number of subscribe attempts. Default: `5`. */
+    retries?: number;
+    /** Delay between retries in ms. Default: `5000`. */
+    backoffMs?: number;
+}
+
+export { type BatchMeta as B, type ClientId as C, type GroupId as G, type IKafkaClient as I, type KafkaClientOptions as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type ConsumerInterceptor as c, type InferSchema as d, type KafkaLogger as e, type SendOptions as f, type SubscribeRetryOptions as g, type TTopicMessageMap as h, type TopicsFrom as i, type TransactionContext as j, topic as t };

package/dist/types-CtwJihJ3.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Any validation library with a `.parse()` method.
+ * Works with Zod, Valibot, ArkType, or any custom validator.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * const schema: SchemaLike<{ id: string }> = z.object({ id: z.string() });
+ * ```
+ */
+interface SchemaLike<T = any> {
+    parse(data: unknown): T;
+}
+/** Infer the output type from a SchemaLike. */
+type InferSchema<S extends SchemaLike> = S extends SchemaLike<infer T> ? T : never;
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+    /** Runtime schema validator. Present only when created via `topic().schema()`. */
+    readonly __schema?: SchemaLike<M>;
+}
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * // Without schema — type provided explicitly:
+ * const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
+ *
+ * // With schema — type inferred from schema:
+ * const OrderCreated = topic('order.created').schema(z.object({
+ *   orderId: z.string(),
+ *   amount: z.number(),
+ * }));
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+declare function topic<N extends string>(name: N): {
+    <M extends Record<string, any>>(): TopicDescriptor<N, M>;
+    schema<S extends SchemaLike<Record<string, any>>>(schema: S): TopicDescriptor<N, InferSchema<S>>;
+};
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+
+/**
+ * Mapping of topic names to their message types.
+ * Define this interface to get type-safe publish/subscribe across your app.
+ *
+ * @example
+ * ```ts
+ * // with explicit extends (IDE hints for values)
+ * interface MyTopics extends TTopicMessageMap {
+ *   "orders.created": { orderId: string; amount: number };
+ *   "users.updated": { userId: string; name: string };
+ * }
+ *
+ * // or plain interface / type — works the same
+ * interface MyTopics {
+ *   "orders.created": { orderId: string; amount: number };
+ * }
+ * ```
+ */
+type TTopicMessageMap = {
+    [topic: string]: Record<string, any>;
+};
+/**
+ * Generic constraint for topic-message maps.
+ * Works with both `type` aliases and `interface` declarations.
+ */
+type TopicMapConstraint<T> = {
+    [K in keyof T]: Record<string, any>;
+};
+type ClientId = string;
+type GroupId = string;
+type MessageHeaders = Record<string, string>;
+/** Options for sending a single message. */
+interface SendOptions {
+    /** Partition key for message routing. */
+    key?: string;
+    /** Custom headers attached to the message. */
+    headers?: MessageHeaders;
+}
+/** Metadata exposed to batch consumer handlers. */
+interface BatchMeta {
+    /** Partition number for this batch. */
+    partition: number;
+    /** Highest offset available on the broker for this partition. */
+    highWatermark: string;
+    /** Send a heartbeat to the broker to prevent session timeout. */
+    heartbeat(): Promise<void>;
+    /** Mark an offset as processed (for manual offset management). */
+    resolveOffset(offset: string): void;
+    /** Commit offsets if the auto-commit threshold has been reached. */
+    commitOffsetsIfNecessary(): Promise<void>;
+}
+/** Options for configuring a Kafka consumer. */
+interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Override the default consumer group ID from the constructor. */
+    groupId?: string;
+    /** Start reading from earliest offset. Default: `false`. */
+    fromBeginning?: boolean;
+    /** Automatically commit offsets. Default: `true`. */
+    autoCommit?: boolean;
+    /** Retry policy for failed message processing. */
+    retry?: RetryOptions;
+    /** Send failed messages to a Dead Letter Queue (`<topic>.dlq`). */
+    dlq?: boolean;
+    /** Interceptors called before/after each message. */
+    interceptors?: ConsumerInterceptor<T>[];
+    /** @internal Schema map populated by @SubscribeTo when descriptors have schemas. */
+    schemas?: Map<string, SchemaLike>;
+    /** Retry config for `consumer.subscribe()` when the topic doesn't exist yet. */
+    subscribeRetry?: SubscribeRetryOptions;
+}
+/** Configuration for consumer retry behavior. */
+interface RetryOptions {
+    /** Maximum number of retry attempts before giving up. */
+    maxRetries: number;
+    /** Base delay between retries in ms (multiplied by attempt number). Default: `1000`. */
+    backoffMs?: number;
+}
+/**
+ * Interceptor hooks for consumer message processing.
+ * All methods are optional — implement only what you need.
+ */
+interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Called before the message handler. */
+    before?(message: T[keyof T], topic: string): Promise<void> | void;
+    /** Called after the message handler succeeds. */
+    after?(message: T[keyof T], topic: string): Promise<void> | void;
+    /** Called when the message handler throws. */
+    onError?(message: T[keyof T], topic: string, error: Error): Promise<void> | void;
+}
+/** Context passed to the `transaction()` callback with type-safe send methods. */
+interface TransactionContext<T extends TopicMapConstraint<T>> {
+    send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<{
+        value: T[K];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+}
+/** Interface describing all public methods of the Kafka client. */
+interface IKafkaClient<T extends TopicMapConstraint<T>> {
+    checkStatus(): Promise<{
+        topics: string[];
+    }>;
+    startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (messages: T[K[number]][], topic: K[number], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (messages: D["__type"][], topic: D["__topic"], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    stopConsumer(): Promise<void>;
+    sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<{
+        value: T[K];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
+    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+    getClientId: () => ClientId;
+    disconnect(): Promise<void>;
+}
+/**
+ * Logger interface for KafkaClient.
+ * Compatible with NestJS Logger, console, winston, pino, or any custom logger.
+ */
+interface KafkaLogger {
+    log(message: string): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/** Options for `KafkaClient` constructor. */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
+    logger?: KafkaLogger;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+}
+/** Options for consumer subscribe retry when topic doesn't exist yet. */
+interface SubscribeRetryOptions {
+    /** Maximum number of subscribe attempts. Default: `5`. */
+    retries?: number;
+    /** Delay between retries in ms. Default: `5000`. */
+    backoffMs?: number;
+}
+
+export { type BatchMeta as B, type ClientId as C, type GroupId as G, type IKafkaClient as I, type KafkaClientOptions as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type ConsumerInterceptor as c, type InferSchema as d, type KafkaLogger as e, type SendOptions as f, type SubscribeRetryOptions as g, type TTopicMessageMap as h, type TopicsFrom as i, type TransactionContext as j, topic as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drarzter/kafka-client",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Type-safe Kafka client wrapper for NestJS with typed topic-message maps",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -11,6 +11,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "core": ["./dist/core.d.ts"],
+      "testing": ["./dist/testing.d.ts"]
     }
   },
   "files": [
@@ -45,6 +61,12 @@
     "reflect-metadata": ">=0.1.13",
     "rxjs": ">=7.0.0"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/common": { "optional": true },
+    "@nestjs/core": { "optional": true },
+    "reflect-metadata": { "optional": true },
+    "rxjs": { "optional": true }
+  },
   "devDependencies": {
     "@nestjs/common": "^11.1.13",
     "@nestjs/core": "^11.1.13",