@drarzter/kafka-client 0.6.7 → 0.7.0

package/dist/index.mjs

@@ -15,7 +15,7 @@ import {
   getEnvelopeContext,
   runWithEnvelopeContext,
   topic
-} from "./chunk-ISYOEX4W.mjs";
+} from "./chunk-MJ342P4R.mjs";
 import {
   __decorateClass,
   __decorateParam

package/dist/otel.d.mts

@@ -1,4 +1,4 @@
-import { K as KafkaInstrumentation } from './types-CqjRm-Cd.mjs';
+import { K as KafkaInstrumentation } from './types-DqQ7IXZr.mjs';
 
 /**
  * Create a `KafkaInstrumentation` that automatically propagates

package/dist/otel.d.ts

@@ -1,4 +1,4 @@
-import { K as KafkaInstrumentation } from './types-CqjRm-Cd.js';
+import { K as KafkaInstrumentation } from './types-DqQ7IXZr.js';
 
 /**
  * Create a `KafkaInstrumentation` that automatically propagates

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { T as TopicMapConstraint, I as IKafkaClient } from './types-CqjRm-Cd.mjs';
+import { T as TopicMapConstraint, I as IKafkaClient } from './types-DqQ7IXZr.mjs';
 
 /**
  * Fully typed mock of `IKafkaClient<T>` where every method is a mock function.

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { T as TopicMapConstraint, I as IKafkaClient } from './types-CqjRm-Cd.js';
+import { T as TopicMapConstraint, I as IKafkaClient } from './types-DqQ7IXZr.js';
 
 /**
  * Fully typed mock of `IKafkaClient<T>` where every method is a mock function.

package/dist/testing.js

@@ -76,6 +76,22 @@ function createMockKafkaClient(mockFactory) {
       stop: mock().mockResolvedValue(void 0)
     }),
     stopConsumer: resolved(void 0),
+    consume: returning(
+      (function* () {
+      })()
+    ),
+    replayDlq: resolved({ replayed: 0, skipped: 0 }),
+    resetOffsets: resolved(void 0),
+    seekToOffset: resolved(void 0),
+    pauseConsumer: mock(),
+    resumeConsumer: mock(),
+    getMetrics: returning({
+      processedCount: 0,
+      retryCount: 0,
+      dlqCount: 0,
+      dedupCount: 0
+    }),
+    resetMetrics: mock(),
     disconnect: resolved(void 0),
     enableGracefulShutdown: mock()
   };

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/testing.ts","../src/testing/mock-client.ts","../src/testing/test-container.ts"],"sourcesContent":["export * from \"./testing/index\";\n","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  // Jest and Vitest inject their globals (`jest` / `vi`) as module-scope\n  // bindings, not as properties of `globalThis`. The only reliable way to\n  // detect them without a hard import is via `eval`, which evaluates in the\n  // current module scope where those bindings are available.\n  try {\n    if (eval(\"typeof jest === 'object' && typeof jest.fn === 'function'\")) {\n      return () => eval(\"jest.fn()\");\n    }\n  } catch {\n    /* not available */\n  }\n  try {\n    if (eval(\"typeof vi === 'object' && typeof vi.fn === 'function'\")) {\n      return () => eval(\"vi.fn()\");\n    }\n  } catch {\n    /* not available */\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()` → `{ status: 'up', clientId: 'mock-client', 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({\n      status: \"up\",\n      clientId: \"mock-client\",\n      topics: [],\n    }),\n    getConsumerLag: resolved([]),\n    getClientId: returning(\"mock-client\"),\n    sendMessage: resolved(undefined),\n    sendBatch: resolved(undefined),\n    transaction: mock().mockImplementation(\n      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    ),\n    startConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    startBatchConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    stopConsumer: resolved(undefined),\n    disconnect: resolved(undefined),\n    enableGracefulShutdown: mock(),\n  } as unknown as MockKafkaClient<T>;\n}\n","import {\n  KafkaContainer,\n  type StartedKafkaContainer,\n} from \"@testcontainers/kafka\";\nimport { KafkaJS } from \"@confluentinc/kafka-javascript\";\nconst { Kafka, logLevel: KafkaLogLevel } = 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      kafkaJS: {\n        clientId: \"test-container-setup\",\n        brokers,\n        logLevel: KafkaLogLevel.NOTHING,\n      },\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        kafkaJS: {\n          clientId: \"test-container-warmup\",\n          brokers,\n          logLevel: KafkaLogLevel.NOTHING,\n        },\n      });\n      const txProducer = warmupKafka.producer({\n        kafkaJS: {\n          transactionalId: \"test-container-warmup-tx\",\n          idempotent: true,\n          maxInFlightRequests: 1,\n        },\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(\"KafkaTestContainer is not started. Call start() first.\");\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":[]}
+{"version":3,"sources":["../src/testing.ts","../src/testing/mock-client.ts","../src/testing/test-container.ts"],"sourcesContent":["export * from \"./testing/index\";\n","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  // Jest and Vitest inject their globals (`jest` / `vi`) as module-scope\n  // bindings, not as properties of `globalThis`. The only reliable way to\n  // detect them without a hard import is via `eval`, which evaluates in the\n  // current module scope where those bindings are available.\n  try {\n    if (eval(\"typeof jest === 'object' && typeof jest.fn === 'function'\")) {\n      return () => eval(\"jest.fn()\");\n    }\n  } catch {\n    /* not available */\n  }\n  try {\n    if (eval(\"typeof vi === 'object' && typeof vi.fn === 'function'\")) {\n      return () => eval(\"vi.fn()\");\n    }\n  } catch {\n    /* not available */\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()` → `{ status: 'up', clientId: 'mock-client', 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({\n      status: \"up\",\n      clientId: \"mock-client\",\n      topics: [],\n    }),\n    getConsumerLag: resolved([]),\n    getClientId: returning(\"mock-client\"),\n    sendMessage: resolved(undefined),\n    sendBatch: resolved(undefined),\n    transaction: mock().mockImplementation(\n      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    ),\n    startConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    startBatchConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    stopConsumer: resolved(undefined),\n    consume: returning(\n      (function* () {})() as unknown as AsyncIterableIterator<any>,\n    ),\n    replayDlq: resolved({ replayed: 0, skipped: 0 }),\n    resetOffsets: resolved(undefined),\n    seekToOffset: resolved(undefined),\n    pauseConsumer: mock(),\n    resumeConsumer: mock(),\n    getMetrics: returning({\n      processedCount: 0,\n      retryCount: 0,\n      dlqCount: 0,\n      dedupCount: 0,\n    }),\n    resetMetrics: mock(),\n    disconnect: resolved(undefined),\n    enableGracefulShutdown: mock(),\n  } as unknown as MockKafkaClient<T>;\n}\n","import {\n  KafkaContainer,\n  type StartedKafkaContainer,\n} from \"@testcontainers/kafka\";\nimport { KafkaJS } from \"@confluentinc/kafka-javascript\";\nconst { Kafka, logLevel: KafkaLogLevel } = 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      kafkaJS: {\n        clientId: \"test-container-setup\",\n        brokers,\n        logLevel: KafkaLogLevel.NOTHING,\n      },\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        kafkaJS: {\n          clientId: \"test-container-warmup\",\n          brokers,\n          logLevel: KafkaLogLevel.NOTHING,\n        },\n      });\n      const txProducer = warmupKafka.producer({\n        kafkaJS: {\n          transactionalId: \"test-container-warmup-tx\",\n          idempotent: true,\n          maxInFlightRequests: 1,\n        },\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(\"KafkaTestContainer is not started. Call start() first.\");\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/testing.mjs

@@ -51,6 +51,22 @@ function createMockKafkaClient(mockFactory) {
       stop: mock().mockResolvedValue(void 0)
     }),
     stopConsumer: resolved(void 0),
+    consume: returning(
+      (function* () {
+      })()
+    ),
+    replayDlq: resolved({ replayed: 0, skipped: 0 }),
+    resetOffsets: resolved(void 0),
+    seekToOffset: resolved(void 0),
+    pauseConsumer: mock(),
+    resumeConsumer: mock(),
+    getMetrics: returning({
+      processedCount: 0,
+      retryCount: 0,
+      dlqCount: 0,
+      dedupCount: 0
+    }),
+    resetMetrics: mock(),
     disconnect: resolved(void 0),
     enableGracefulShutdown: mock()
   };

package/dist/testing.mjs.map

@@ -1 +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  // Jest and Vitest inject their globals (`jest` / `vi`) as module-scope\n  // bindings, not as properties of `globalThis`. The only reliable way to\n  // detect them without a hard import is via `eval`, which evaluates in the\n  // current module scope where those bindings are available.\n  try {\n    if (eval(\"typeof jest === 'object' && typeof jest.fn === 'function'\")) {\n      return () => eval(\"jest.fn()\");\n    }\n  } catch {\n    /* not available */\n  }\n  try {\n    if (eval(\"typeof vi === 'object' && typeof vi.fn === 'function'\")) {\n      return () => eval(\"vi.fn()\");\n    }\n  } catch {\n    /* not available */\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()` → `{ status: 'up', clientId: 'mock-client', 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({\n      status: \"up\",\n      clientId: \"mock-client\",\n      topics: [],\n    }),\n    getConsumerLag: resolved([]),\n    getClientId: returning(\"mock-client\"),\n    sendMessage: resolved(undefined),\n    sendBatch: resolved(undefined),\n    transaction: mock().mockImplementation(\n      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    ),\n    startConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    startBatchConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    stopConsumer: resolved(undefined),\n    disconnect: resolved(undefined),\n    enableGracefulShutdown: mock(),\n  } as unknown as MockKafkaClient<T>;\n}\n","import {\n  KafkaContainer,\n  type StartedKafkaContainer,\n} from \"@testcontainers/kafka\";\nimport { KafkaJS } from \"@confluentinc/kafka-javascript\";\nconst { Kafka, logLevel: KafkaLogLevel } = 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      kafkaJS: {\n        clientId: \"test-container-setup\",\n        brokers,\n        logLevel: KafkaLogLevel.NOTHING,\n      },\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        kafkaJS: {\n          clientId: \"test-container-warmup\",\n          brokers,\n          logLevel: KafkaLogLevel.NOTHING,\n        },\n      });\n      const txProducer = warmupKafka.producer({\n        kafkaJS: {\n          transactionalId: \"test-container-warmup-tx\",\n          idempotent: true,\n          maxInFlightRequests: 1,\n        },\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(\"KafkaTestContainer is not started. Call start() first.\");\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":[]}
+{"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  // Jest and Vitest inject their globals (`jest` / `vi`) as module-scope\n  // bindings, not as properties of `globalThis`. The only reliable way to\n  // detect them without a hard import is via `eval`, which evaluates in the\n  // current module scope where those bindings are available.\n  try {\n    if (eval(\"typeof jest === 'object' && typeof jest.fn === 'function'\")) {\n      return () => eval(\"jest.fn()\");\n    }\n  } catch {\n    /* not available */\n  }\n  try {\n    if (eval(\"typeof vi === 'object' && typeof vi.fn === 'function'\")) {\n      return () => eval(\"vi.fn()\");\n    }\n  } catch {\n    /* not available */\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()` → `{ status: 'up', clientId: 'mock-client', 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({\n      status: \"up\",\n      clientId: \"mock-client\",\n      topics: [],\n    }),\n    getConsumerLag: resolved([]),\n    getClientId: returning(\"mock-client\"),\n    sendMessage: resolved(undefined),\n    sendBatch: resolved(undefined),\n    transaction: mock().mockImplementation(\n      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    ),\n    startConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    startBatchConsumer: resolved({\n      groupId: \"mock-group\",\n      stop: mock().mockResolvedValue(undefined),\n    }),\n    stopConsumer: resolved(undefined),\n    consume: returning(\n      (function* () {})() as unknown as AsyncIterableIterator<any>,\n    ),\n    replayDlq: resolved({ replayed: 0, skipped: 0 }),\n    resetOffsets: resolved(undefined),\n    seekToOffset: resolved(undefined),\n    pauseConsumer: mock(),\n    resumeConsumer: mock(),\n    getMetrics: returning({\n      processedCount: 0,\n      retryCount: 0,\n      dlqCount: 0,\n      dedupCount: 0,\n    }),\n    resetMetrics: mock(),\n    disconnect: resolved(undefined),\n    enableGracefulShutdown: mock(),\n  } as unknown as MockKafkaClient<T>;\n}\n","import {\n  KafkaContainer,\n  type StartedKafkaContainer,\n} from \"@testcontainers/kafka\";\nimport { KafkaJS } from \"@confluentinc/kafka-javascript\";\nconst { Kafka, logLevel: KafkaLogLevel } = 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      kafkaJS: {\n        clientId: \"test-container-setup\",\n        brokers,\n        logLevel: KafkaLogLevel.NOTHING,\n      },\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        kafkaJS: {\n          clientId: \"test-container-warmup\",\n          brokers,\n          logLevel: KafkaLogLevel.NOTHING,\n        },\n      });\n      const txProducer = warmupKafka.producer({\n        kafkaJS: {\n          transactionalId: \"test-container-warmup-tx\",\n          idempotent: true,\n          maxInFlightRequests: 1,\n        },\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(\"KafkaTestContainer is not started. Call start() first.\");\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-CqjRm-Cd.d.mts → types-DqQ7IXZr.d.mts}

@@ -277,6 +277,41 @@ interface DeduplicationOptions {
      */
     duplicatesTopic?: string;
 }
+/**
+ * Options for the per-partition circuit breaker.
+ *
+ * The circuit breaker tracks recent message outcomes in a **sliding window** and
+ * opens (pauses the partition) when too many failures accumulate:
+ *
+ * - **CLOSED** — normal operation. Each DLQ route or successful delivery is recorded
+ *   in the window. When `failuresInWindow >= threshold` the circuit opens.
+ * - **OPEN** — the partition is paused. After `recoveryMs` the circuit moves to HALF-OPEN.
+ * - **HALF-OPEN** — the partition is resumed. If the next `halfOpenSuccesses` messages
+ *   succeed the circuit closes; a new failure immediately re-opens it.
+ */
+interface CircuitBreakerOptions {
+    /**
+     * Number of failures within the sliding window required to open the circuit.
+     * A failure is any message that ends up in the DLQ.
+     * Default: `5`.
+     */
+    threshold?: number;
+    /**
+     * Time (ms) to keep the circuit OPEN before attempting recovery (HALF_OPEN).
+     * Default: `30_000` (30 s).
+     */
+    recoveryMs?: number;
+    /**
+     * Number of outcomes (successes + failures) to keep in the sliding window.
+     * Default: `threshold * 2` (minimum `10`).
+     */
+    windowSize?: number;
+    /**
+     * Number of consecutive successes in HALF-OPEN state required to close the
+     * circuit. Default: `1`.
+     */
+    halfOpenSuccesses?: number;
+}
 /** Options for configuring a Kafka consumer. */
 interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     /** Override the default consumer group ID from the constructor. */
@@ -326,6 +361,21 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * Messages without the header are passed through unchanged.
      */
     deduplication?: DeduplicationOptions;
+    /**
+     * Drop messages older than this threshold, measured in milliseconds from
+     * the `x-timestamp` header set by the producer.
+     *
+     * Expired messages are routed to `{topic}.dlq` when `dlq: true`, otherwise
+     * `onMessageLost` is called. The handler is never invoked for an expired message.
+     */
+    messageTtlMs?: number;
+    /**
+     * Automatically pause a partition when it accumulates too many consecutive
+     * failures, then resume after a recovery window.
+     *
+     * See `CircuitBreakerOptions` for the sliding-window semantics.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -372,8 +422,28 @@ type BeforeConsumeResult = (() => void) | {
  * - `'validation-error'` — schema validation failed before the handler ran.
  * - `'lamport-clock-duplicate'` — message was identified as a Lamport-clock duplicate
  *   and `deduplication.strategy` is `'dlq'`.
+ * - `'ttl-expired'` — message age exceeded `messageTtlMs` before the handler ran.
  */
-type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate";
+type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate" | "ttl-expired";
+/** Options for `replayDlq`. */
+interface DlqReplayOptions {
+    /**
+     * Override the target topic to re-publish to.
+     * Default: reads the `x-dlq-original-topic` header from each DLQ message.
+     */
+    targetTopic?: string;
+    /**
+     * Dry-run mode — log what would be replayed without actually sending.
+     * Increments the `replayed` counter so you can see what would happen.
+     */
+    dryRun?: boolean;
+    /**
+     * Optional filter — return `false` to skip a message.
+     * @param headers All headers on the DLQ message (including `x-dlq-*` metadata).
+     * @param value Raw message value (JSON string).
+     */
+    filter?: (headers: MessageHeaders, value: string) => boolean;
+}
 /**
  * Snapshot of internal event counters accumulated since client creation
  * (or since the last `resetMetrics()` call).
@@ -482,11 +552,97 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
     getClientId(): ClientId;
     /**
      * Return a snapshot of internal event counters (retry / DLQ / dedup).
+     * - `getMetrics()` — aggregate across all topics.
+     * - `getMetrics(topic)` — counters for a specific topic only; returns all-zero
+     *   if no events have been observed for that topic yet.
+     *
      * Counters accumulate since client creation or the last `resetMetrics()` call.
      */
-    getMetrics(): Readonly<KafkaMetrics>;
-    /** Reset all internal event counters to zero. */
-    resetMetrics(): void;
+    getMetrics(topic?: string): Readonly<KafkaMetrics>;
+    /**
+     * Reset internal event counters to zero.
+     * - `resetMetrics()` — reset all topics.
+     * - `resetMetrics(topic)` — reset a single topic only.
+     */
+    resetMetrics(topic?: string): void;
+    /**
+     * Consume all messages currently in `{topic}.dlq`, strip the `x-dlq-*` metadata
+     * headers, and re-publish each message to its original topic (or `options.targetTopic`).
+     *
+     * A temporary consumer group is created and torn down automatically. The DLQ topic
+     * itself is not modified — messages remain there after replay.
+     *
+     * @returns `{ replayed, skipped }` — counts of re-published vs skipped messages.
+     */
+    replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
+        replayed: number;
+        skipped: number;
+    }>;
+    /**
+     * Reset committed offsets for a consumer group to the earliest or latest position.
+     *
+     * The consumer group must be inactive (no running consumers) — Kafka does not
+     * allow offset resets while members are actively consuming. Call
+     * `stopConsumer(groupId)` first.
+     *
+     * @param groupId Consumer group to reset. Defaults to the client's default groupId.
+     * @param topic Topic to reset.
+     * @param position `'earliest'` seeks to the first available offset; `'latest'`
+     *   seeks past the last message (consumer will only see new messages).
+     */
+    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
+    /**
+     * Seek specific partitions to explicit offsets.
+     * More granular than `resetOffsets` — each partition can target a different offset.
+     *
+     * The consumer group must be inactive. Assignments for different topics are batched
+     * into one admin call per topic.
+     *
+     * @param groupId Consumer group to seek. Defaults to the client's default groupId.
+     * @param assignments Array of `{ topic, partition, offset }` tuples.
+     */
+    seekToOffset(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /**
+     * Consume messages as an async iterator. Useful for scripts, migrations, and
+     * one-off processing where the full `startConsumer` lifecycle is unnecessary.
+     *
+     * Breaking out of the loop (or calling `return()` on the iterator) stops the
+     * underlying consumer automatically.
+     *
+     * @example
+     * ```ts
+     * for await (const envelope of kafka.consume('orders')) {
+     *   await process(envelope);
+     * }
+     * ```
+     */
+    consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /**
+     * Pause message delivery for specific topic-partitions on a consumer group.
+     * The consumer remains connected and its committed offsets are preserved —
+     * only polling is suspended. Call `resumeConsumer` to restart delivery.
+     *
+     * @param groupId Consumer group to pause. Defaults to the client's default groupId.
+     * @param assignments Topic-partition pairs to pause.
+     */
+    pauseConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+    /**
+     * Resume message delivery for previously paused topic-partitions.
+     *
+     * @param groupId Consumer group to resume. Defaults to the client's default groupId.
+     * @param assignments Topic-partition pairs to resume.
+     */
+    resumeConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
     /**
      * Drain in-flight handlers, then disconnect all producers, consumers, and admin.
      * @param drainTimeoutMs Max ms to wait for in-flight handlers (default 30 000).
@@ -575,4 +731,4 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-export { decodeHeaders as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, extractEnvelope as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, getEnvelopeContext as J, type KafkaInstrumentation as K, runWithEnvelopeContext as L, type MessageHeaders as M, topic as N, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type BeforeConsumeResult as f, type ConsumerHandle as g, type ConsumerInterceptor as h, type DlqReason as i, type EventEnvelope as j, HEADER_EVENT_ID as k, HEADER_LAMPORT_CLOCK as l, HEADER_SCHEMA_VERSION as m, HEADER_TIMESTAMP as n, HEADER_TRACEPARENT as o, type InferSchema as p, type KafkaLogger as q, type KafkaMetrics as r, type MessageLostContext as s, type SchemaParseContext as t, type SendOptions as u, type SubscribeRetryOptions as v, type TTopicMessageMap as w, type TopicsFrom as x, type TransactionContext as y, buildEnvelopeHeaders as z };
+export { type TransactionContext as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, buildEnvelopeHeaders as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, decodeHeaders as J, type KafkaInstrumentation as K, extractEnvelope as L, type MessageHeaders as M, getEnvelopeContext as N, runWithEnvelopeContext as O, topic as P, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type BeforeConsumeResult as f, type CircuitBreakerOptions as g, type ConsumerHandle as h, type ConsumerInterceptor as i, type DlqReason as j, type DlqReplayOptions as k, type EventEnvelope as l, HEADER_EVENT_ID as m, HEADER_LAMPORT_CLOCK as n, HEADER_SCHEMA_VERSION as o, HEADER_TIMESTAMP as p, HEADER_TRACEPARENT as q, type InferSchema as r, type KafkaLogger as s, type KafkaMetrics as t, type MessageLostContext as u, type SchemaParseContext as v, type SendOptions as w, type SubscribeRetryOptions as x, type TTopicMessageMap as y, type TopicsFrom as z };

package/dist/{types-CqjRm-Cd.d.ts → types-DqQ7IXZr.d.ts}

@@ -277,6 +277,41 @@ interface DeduplicationOptions {
      */
     duplicatesTopic?: string;
 }
+/**
+ * Options for the per-partition circuit breaker.
+ *
+ * The circuit breaker tracks recent message outcomes in a **sliding window** and
+ * opens (pauses the partition) when too many failures accumulate:
+ *
+ * - **CLOSED** — normal operation. Each DLQ route or successful delivery is recorded
+ *   in the window. When `failuresInWindow >= threshold` the circuit opens.
+ * - **OPEN** — the partition is paused. After `recoveryMs` the circuit moves to HALF-OPEN.
+ * - **HALF-OPEN** — the partition is resumed. If the next `halfOpenSuccesses` messages
+ *   succeed the circuit closes; a new failure immediately re-opens it.
+ */
+interface CircuitBreakerOptions {
+    /**
+     * Number of failures within the sliding window required to open the circuit.
+     * A failure is any message that ends up in the DLQ.
+     * Default: `5`.
+     */
+    threshold?: number;
+    /**
+     * Time (ms) to keep the circuit OPEN before attempting recovery (HALF_OPEN).
+     * Default: `30_000` (30 s).
+     */
+    recoveryMs?: number;
+    /**
+     * Number of outcomes (successes + failures) to keep in the sliding window.
+     * Default: `threshold * 2` (minimum `10`).
+     */
+    windowSize?: number;
+    /**
+     * Number of consecutive successes in HALF-OPEN state required to close the
+     * circuit. Default: `1`.
+     */
+    halfOpenSuccesses?: number;
+}
 /** Options for configuring a Kafka consumer. */
 interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     /** Override the default consumer group ID from the constructor. */
@@ -326,6 +361,21 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * Messages without the header are passed through unchanged.
      */
     deduplication?: DeduplicationOptions;
+    /**
+     * Drop messages older than this threshold, measured in milliseconds from
+     * the `x-timestamp` header set by the producer.
+     *
+     * Expired messages are routed to `{topic}.dlq` when `dlq: true`, otherwise
+     * `onMessageLost` is called. The handler is never invoked for an expired message.
+     */
+    messageTtlMs?: number;
+    /**
+     * Automatically pause a partition when it accumulates too many consecutive
+     * failures, then resume after a recovery window.
+     *
+     * See `CircuitBreakerOptions` for the sliding-window semantics.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -372,8 +422,28 @@ type BeforeConsumeResult = (() => void) | {
  * - `'validation-error'` — schema validation failed before the handler ran.
  * - `'lamport-clock-duplicate'` — message was identified as a Lamport-clock duplicate
  *   and `deduplication.strategy` is `'dlq'`.
+ * - `'ttl-expired'` — message age exceeded `messageTtlMs` before the handler ran.
  */
-type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate";
+type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate" | "ttl-expired";
+/** Options for `replayDlq`. */
+interface DlqReplayOptions {
+    /**
+     * Override the target topic to re-publish to.
+     * Default: reads the `x-dlq-original-topic` header from each DLQ message.
+     */
+    targetTopic?: string;
+    /**
+     * Dry-run mode — log what would be replayed without actually sending.
+     * Increments the `replayed` counter so you can see what would happen.
+     */
+    dryRun?: boolean;
+    /**
+     * Optional filter — return `false` to skip a message.
+     * @param headers All headers on the DLQ message (including `x-dlq-*` metadata).
+     * @param value Raw message value (JSON string).
+     */
+    filter?: (headers: MessageHeaders, value: string) => boolean;
+}
 /**
  * Snapshot of internal event counters accumulated since client creation
  * (or since the last `resetMetrics()` call).
@@ -482,11 +552,97 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
     getClientId(): ClientId;
     /**
      * Return a snapshot of internal event counters (retry / DLQ / dedup).
+     * - `getMetrics()` — aggregate across all topics.
+     * - `getMetrics(topic)` — counters for a specific topic only; returns all-zero
+     *   if no events have been observed for that topic yet.
+     *
      * Counters accumulate since client creation or the last `resetMetrics()` call.
      */
-    getMetrics(): Readonly<KafkaMetrics>;
-    /** Reset all internal event counters to zero. */
-    resetMetrics(): void;
+    getMetrics(topic?: string): Readonly<KafkaMetrics>;
+    /**
+     * Reset internal event counters to zero.
+     * - `resetMetrics()` — reset all topics.
+     * - `resetMetrics(topic)` — reset a single topic only.
+     */
+    resetMetrics(topic?: string): void;
+    /**
+     * Consume all messages currently in `{topic}.dlq`, strip the `x-dlq-*` metadata
+     * headers, and re-publish each message to its original topic (or `options.targetTopic`).
+     *
+     * A temporary consumer group is created and torn down automatically. The DLQ topic
+     * itself is not modified — messages remain there after replay.
+     *
+     * @returns `{ replayed, skipped }` — counts of re-published vs skipped messages.
+     */
+    replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
+        replayed: number;
+        skipped: number;
+    }>;
+    /**
+     * Reset committed offsets for a consumer group to the earliest or latest position.
+     *
+     * The consumer group must be inactive (no running consumers) — Kafka does not
+     * allow offset resets while members are actively consuming. Call
+     * `stopConsumer(groupId)` first.
+     *
+     * @param groupId Consumer group to reset. Defaults to the client's default groupId.
+     * @param topic Topic to reset.
+     * @param position `'earliest'` seeks to the first available offset; `'latest'`
+     *   seeks past the last message (consumer will only see new messages).
+     */
+    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
+    /**
+     * Seek specific partitions to explicit offsets.
+     * More granular than `resetOffsets` — each partition can target a different offset.
+     *
+     * The consumer group must be inactive. Assignments for different topics are batched
+     * into one admin call per topic.
+     *
+     * @param groupId Consumer group to seek. Defaults to the client's default groupId.
+     * @param assignments Array of `{ topic, partition, offset }` tuples.
+     */
+    seekToOffset(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /**
+     * Consume messages as an async iterator. Useful for scripts, migrations, and
+     * one-off processing where the full `startConsumer` lifecycle is unnecessary.
+     *
+     * Breaking out of the loop (or calling `return()` on the iterator) stops the
+     * underlying consumer automatically.
+     *
+     * @example
+     * ```ts
+     * for await (const envelope of kafka.consume('orders')) {
+     *   await process(envelope);
+     * }
+     * ```
+     */
+    consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /**
+     * Pause message delivery for specific topic-partitions on a consumer group.
+     * The consumer remains connected and its committed offsets are preserved —
+     * only polling is suspended. Call `resumeConsumer` to restart delivery.
+     *
+     * @param groupId Consumer group to pause. Defaults to the client's default groupId.
+     * @param assignments Topic-partition pairs to pause.
+     */
+    pauseConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+    /**
+     * Resume message delivery for previously paused topic-partitions.
+     *
+     * @param groupId Consumer group to resume. Defaults to the client's default groupId.
+     * @param assignments Topic-partition pairs to resume.
+     */
+    resumeConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
     /**
      * Drain in-flight handlers, then disconnect all producers, consumers, and admin.
      * @param drainTimeoutMs Max ms to wait for in-flight handlers (default 30 000).
@@ -575,4 +731,4 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-export { decodeHeaders as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, extractEnvelope as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, getEnvelopeContext as J, type KafkaInstrumentation as K, runWithEnvelopeContext as L, type MessageHeaders as M, topic as N, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type BeforeConsumeResult as f, type ConsumerHandle as g, type ConsumerInterceptor as h, type DlqReason as i, type EventEnvelope as j, HEADER_EVENT_ID as k, HEADER_LAMPORT_CLOCK as l, HEADER_SCHEMA_VERSION as m, HEADER_TIMESTAMP as n, HEADER_TRACEPARENT as o, type InferSchema as p, type KafkaLogger as q, type KafkaMetrics as r, type MessageLostContext as s, type SchemaParseContext as t, type SendOptions as u, type SubscribeRetryOptions as v, type TTopicMessageMap as w, type TopicsFrom as x, type TransactionContext as y, buildEnvelopeHeaders as z };
+export { type TransactionContext as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, buildEnvelopeHeaders as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, decodeHeaders as J, type KafkaInstrumentation as K, extractEnvelope as L, type MessageHeaders as M, getEnvelopeContext as N, runWithEnvelopeContext as O, topic as P, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type BeforeConsumeResult as f, type CircuitBreakerOptions as g, type ConsumerHandle as h, type ConsumerInterceptor as i, type DlqReason as j, type DlqReplayOptions as k, type EventEnvelope as l, HEADER_EVENT_ID as m, HEADER_LAMPORT_CLOCK as n, HEADER_SCHEMA_VERSION as o, HEADER_TIMESTAMP as p, HEADER_TRACEPARENT as q, type InferSchema as r, type KafkaLogger as s, type KafkaMetrics as t, type MessageLostContext as u, type SchemaParseContext as v, type SendOptions as w, type SubscribeRetryOptions as x, type TTopicMessageMap as y, type TopicsFrom as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drarzter/kafka-client",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Type-safe Kafka client wrapper for NestJS with typed topic-message maps",
   "license": "MIT",
   "main": "./dist/index.js",