@drarzter/kafka-client 0.7.0 → 0.7.1

package/dist/index.mjs

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

package/dist/otel.d.mts

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

package/dist/otel.d.ts

@@ -1,4 +1,4 @@
-import { K as KafkaInstrumentation } from './types-DqQ7IXZr.js';
+import { K as KafkaInstrumentation } from './types-BEIGjmV6.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-DqQ7IXZr.mjs';
+import { T as TopicMapConstraint, I as IKafkaClient } from './types-BEIGjmV6.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-DqQ7IXZr.js';
+import { T as TopicMapConstraint, I as IKafkaClient } from './types-BEIGjmV6.js';
 
 /**
  * Fully typed mock of `IKafkaClient<T>` where every method is a mock function.

package/dist/testing.js

@@ -83,6 +83,8 @@ function createMockKafkaClient(mockFactory) {
     replayDlq: resolved({ replayed: 0, skipped: 0 }),
     resetOffsets: resolved(void 0),
     seekToOffset: resolved(void 0),
+    seekToTimestamp: resolved(void 0),
+    getCircuitState: returning(void 0),
     pauseConsumer: mock(),
     resumeConsumer: mock(),
     getMetrics: returning({

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    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":[]}
+{"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    seekToTimestamp: resolved(undefined),\n    getCircuitState: returning(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

@@ -58,6 +58,8 @@ function createMockKafkaClient(mockFactory) {
     replayDlq: resolved({ replayed: 0, skipped: 0 }),
     resetOffsets: resolved(void 0),
     seekToOffset: resolved(void 0),
+    seekToTimestamp: resolved(void 0),
+    getCircuitState: returning(void 0),
     pauseConsumer: mock(),
     resumeConsumer: mock(),
     getMetrics: returning({

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    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":";;;AAcA,SAAS,oBAAiC;AAKxC,MAAI;AACF,QAAI,KAAK,2DAA2D,GAAG;AACrE,aAAO,MAAM,KAAK,WAAW;AAAA,IAC/B;AAAA,EACF,QAAQ;AAAA,EAER;AACA,MAAI;AACF,QAAI,KAAK,uDAAuD,GAAG;AACjE,aAAO,MAAM,KAAK,SAAS;AAAA,IAC7B;AAAA,EACF,QAAQ;AAAA,EAER;AACA,QAAM,IAAI;AAAA,IACR;AAAA,EAEF;AACF;AA4BO,SAAS,sBACd,aACoB;AACpB,QAAM,KAAK,eAAe,kBAAkB;AAE5C,QAAM,OAAO,MAAM,GAAG;AACtB,QAAM,WAAW,CAAC,UAAmB,KAAK,EAAE,kBAAkB,KAAK;AACnE,QAAM,YAAY,CAAC,UAAmB,KAAK,EAAE,gBAAgB,KAAK;AAElE,SAAO;AAAA,IACL,aAAa,SAAS;AAAA,MACpB,QAAQ;AAAA,MACR,UAAU;AAAA,MACV,QAAQ,CAAC;AAAA,IACX,CAAC;AAAA,IACD,gBAAgB,SAAS,CAAC,CAAC;AAAA,IAC3B,aAAa,UAAU,aAAa;AAAA,IACpC,aAAa,SAAS,MAAS;AAAA,IAC/B,WAAW,SAAS,MAAS;AAAA,IAC7B,aAAa,KAAK,EAAE;AAAA,MAClB,OAAO,OAAwD;AAC7D,cAAM,MAAM;AAAA,UACV,MAAM,SAAS,MAAS;AAAA,UACxB,WAAW,SAAS,MAAS;AAAA,QAC/B;AACA,cAAM,GAAG,GAAG;AAAA,MACd;AAAA,IACF;AAAA,IACA,eAAe,SAAS;AAAA,MACtB,SAAS;AAAA,MACT,MAAM,KAAK,EAAE,kBAAkB,MAAS;AAAA,IAC1C,CAAC;AAAA,IACD,oBAAoB,SAAS;AAAA,MAC3B,SAAS;AAAA,MACT,MAAM,KAAK,EAAE,kBAAkB,MAAS;AAAA,IAC1C,CAAC;AAAA,IACD,cAAc,SAAS,MAAS;AAAA,IAChC,SAAS;AAAA,OACN,aAAa;AAAA,MAAC,GAAG;AAAA,IACpB;AAAA,IACA,WAAW,SAAS,EAAE,UAAU,GAAG,SAAS,EAAE,CAAC;AAAA,IAC/C,cAAc,SAAS,MAAS;AAAA,IAChC,cAAc,SAAS,MAAS;AAAA,IAChC,eAAe,KAAK;AAAA,IACpB,gBAAgB,KAAK;AAAA,IACrB,YAAY,UAAU;AAAA,MACpB,gBAAgB;AAAA,MAChB,YAAY;AAAA,MACZ,UAAU;AAAA,MACV,YAAY;AAAA,IACd,CAAC;AAAA,IACD,cAAc,KAAK;AAAA,IACnB,YAAY,SAAS,MAAS;AAAA,IAC9B,wBAAwB,KAAK;AAAA,EAC/B;AACF;;;ACxHA;AAAA,EACE;AAAA,OAEK;AACP,SAAS,eAAe;AACxB,IAAM,EAAE,OAAO,UAAU,cAAc,IAAI;AA4CpC,IAAM,qBAAN,MAAyB;AAAA,EACtB;AAAA,EACS;AAAA,EACA;AAAA,EACA;AAAA,EAIjB,YAAY,SAAqC;AAC/C,SAAK,QAAQ,SAAS,SAAS;AAC/B,SAAK,oBAAoB,SAAS,qBAAqB;AACvD,SAAK,SAAS,SAAS,UAAU,CAAC;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,QAA2B;AAC/B,SAAK,YAAY,MAAM,IAAI,eAAe,KAAK,KAAK,EACjD,UAAU,EACV,iBAAiB,IAAI,EACrB,gBAAgB;AAAA,MACf,gDAAgD;AAAA,MAChD,qCAAqC;AAAA,IACvC,CAAC,EACA,MAAM;AAET,UAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,UAAM,OAAO,KAAK,UAAU,cAAc,IAAI;AAC9C,UAAM,UAAU,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE;AAElC,UAAM,QAAQ,IAAI,MAAM;AAAA,MACtB,SAAS;AAAA,QACP,UAAU;AAAA,QACV;AAAA,QACA,UAAU,cAAc;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,QAAI,KAAK,OAAO,SAAS,GAAG;AAC1B,YAAM,QAAQ,MAAM,MAAM;AAC1B,YAAM,MAAM,QAAQ;AACpB,YAAM,MAAM,aAAa;AAAA,QACvB,QAAQ,KAAK,OAAO;AAAA,UAAI,CAAC,MACvB,OAAO,MAAM,WACT,EAAE,OAAO,GAAG,eAAe,EAAE,IAC7B,EAAE,OAAO,EAAE,OAAO,eAAe,EAAE,iBAAiB,EAAE;AAAA,QAC5D;AAAA,MACF,CAAC;AACD,YAAM,MAAM,WAAW;AAAA,IACzB;AAEA,QAAI,KAAK,mBAAmB;AAC1B,YAAM,cAAc,IAAI,MAAM;AAAA,QAC5B,SAAS;AAAA,UACP,UAAU;AAAA,UACV;AAAA,UACA,UAAU,cAAc;AAAA,QAC1B;AAAA,MACF,CAAC;AACD,YAAM,aAAa,YAAY,SAAS;AAAA,QACtC,SAAS;AAAA,UACP,iBAAiB;AAAA,UACjB,YAAY;AAAA,UACZ,qBAAqB;AAAA,QACvB;AAAA,MACF,CAAC;AACD,YAAM,WAAW,QAAQ;AACzB,YAAM,KAAK,MAAM,WAAW,YAAY;AACxC,YAAM,GAAG,MAAM;AACf,YAAM,WAAW,WAAW;AAAA,IAC9B;AAEA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,OAAsB;AAC1B,UAAM,KAAK,WAAW,KAAK;AAC3B,SAAK,YAAY;AAAA,EACnB;AAAA;AAAA,EAGA,IAAI,UAAoB;AACtB,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI,MAAM,wDAAwD;AAAA,IAC1E;AACA,UAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,UAAM,OAAO,KAAK,UAAU,cAAc,IAAI;AAC9C,WAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE;AAAA,EAC3B;AACF;","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    seekToTimestamp: resolved(undefined),\n    getCircuitState: returning(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-DqQ7IXZr.d.mts → types-BEIGjmV6.d.mts}

@@ -366,7 +366,7 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * 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.
+     * `onTtlExpired` is called. The handler is never invoked for an expired message.
      */
     messageTtlMs?: number;
     /**
@@ -376,6 +376,12 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * See `CircuitBreakerOptions` for the sliding-window semantics.
      */
     circuitBreaker?: CircuitBreakerOptions;
+    /**
+     * Max number of messages buffered in the `consume()` iterator queue before
+     * the partition is paused. The partition resumes when the queue drains below 50%.
+     * Only applies to `consume()`. Default: unbounded.
+     */
+    queueHighWaterMark?: number;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -497,6 +503,12 @@ interface KafkaInstrumentation {
      * Fires for both single-message and batch consumers (once per envelope).
      */
     onMessage?(envelope: EventEnvelope<any>): void;
+    /** Called when a partition circuit opens (consumer paused due to DLQ failures). */
+    onCircuitOpen?(topic: string, partition: number): void;
+    /** Called when the circuit moves to half-open (partition resumed for a probe). */
+    onCircuitHalfOpen?(topic: string, partition: number): void;
+    /** Called when the circuit closes (normal operation restored). */
+    onCircuitClose?(topic: string, partition: number): void;
 }
 /** Context passed to the `transaction()` callback with type-safe send methods. */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
@@ -606,6 +618,36 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
         partition: number;
         offset: string;
     }>): Promise<void>;
+    /**
+     * Seek specific partitions to the offset nearest to a given Unix timestamp (ms).
+     * Uses `admin.fetchTopicOffsetsByTime` under the hood. Falls back to `-1` (end of
+     * topic) when no offset exists at the requested timestamp (e.g. empty partition or
+     * future timestamp).
+     *
+     * The consumer group must be inactive. Call `stopConsumer(groupId)` first.
+     *
+     * @param groupId Consumer group to seek. Defaults to the client's default groupId.
+     * @param assignments Array of `{ topic, partition, timestamp }` tuples (Unix ms).
+     */
+    seekToTimestamp(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        timestamp: number;
+    }>): Promise<void>;
+    /**
+     * Returns the current circuit breaker state for a specific topic partition.
+     * Returns `undefined` when no circuit state exists — either `circuitBreaker` is not
+     * configured for the group, or the circuit has never been tripped.
+     *
+     * @param topic Topic name.
+     * @param partition Partition index.
+     * @param groupId Consumer group. Defaults to the client's default groupId.
+     */
+    getCircuitState(topic: string, partition: number, groupId?: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
     /**
      * Consume messages as an async iterator. Useful for scripts, migrations, and
      * one-off processing where the full `startConsumer` lifecycle is unnecessary.
@@ -667,6 +709,20 @@ interface KafkaLogger {
     error(message: string, ...args: any[]): void;
     debug?(message: string, ...args: any[]): void;
 }
+/**
+ * Context passed to `onTtlExpired` when a message is dropped because it
+ * exceeded `messageTtlMs` and `dlq` is not enabled.
+ */
+interface TtlExpiredContext {
+    /** Topic the message was consumed from. */
+    topic: string;
+    /** Actual age of the message in ms at the time it was dropped. */
+    ageMs: number;
+    /** The configured TTL threshold (`messageTtlMs`). */
+    messageTtlMs: number;
+    /** Original Kafka message headers (correlationId, traceparent, etc.). */
+    headers: MessageHeaders;
+}
 /**
  * Context passed to `onMessageLost` when a message is silently dropped
  * (handler threw and `dlq` is not enabled).
@@ -710,6 +766,12 @@ interface KafkaClientOptions {
      * Use this to alert, log to external systems, or trigger fallback logic.
      */
     onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
+     * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
+     * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
     /**
      * Called whenever a consumer group rebalance occurs.
      * - `'assign'` — new partitions were granted to this instance.
@@ -731,4 +793,4 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-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 };
+export { type TransactionContext as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, type TtlExpiredContext as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, buildEnvelopeHeaders as J, type KafkaInstrumentation as K, decodeHeaders as L, type MessageHeaders as M, extractEnvelope as N, getEnvelopeContext as O, runWithEnvelopeContext as P, topic as Q, 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-DqQ7IXZr.d.ts → types-BEIGjmV6.d.ts}

@@ -366,7 +366,7 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * 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.
+     * `onTtlExpired` is called. The handler is never invoked for an expired message.
      */
     messageTtlMs?: number;
     /**
@@ -376,6 +376,12 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * See `CircuitBreakerOptions` for the sliding-window semantics.
      */
     circuitBreaker?: CircuitBreakerOptions;
+    /**
+     * Max number of messages buffered in the `consume()` iterator queue before
+     * the partition is paused. The partition resumes when the queue drains below 50%.
+     * Only applies to `consume()`. Default: unbounded.
+     */
+    queueHighWaterMark?: number;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -497,6 +503,12 @@ interface KafkaInstrumentation {
      * Fires for both single-message and batch consumers (once per envelope).
      */
     onMessage?(envelope: EventEnvelope<any>): void;
+    /** Called when a partition circuit opens (consumer paused due to DLQ failures). */
+    onCircuitOpen?(topic: string, partition: number): void;
+    /** Called when the circuit moves to half-open (partition resumed for a probe). */
+    onCircuitHalfOpen?(topic: string, partition: number): void;
+    /** Called when the circuit closes (normal operation restored). */
+    onCircuitClose?(topic: string, partition: number): void;
 }
 /** Context passed to the `transaction()` callback with type-safe send methods. */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
@@ -606,6 +618,36 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
         partition: number;
         offset: string;
     }>): Promise<void>;
+    /**
+     * Seek specific partitions to the offset nearest to a given Unix timestamp (ms).
+     * Uses `admin.fetchTopicOffsetsByTime` under the hood. Falls back to `-1` (end of
+     * topic) when no offset exists at the requested timestamp (e.g. empty partition or
+     * future timestamp).
+     *
+     * The consumer group must be inactive. Call `stopConsumer(groupId)` first.
+     *
+     * @param groupId Consumer group to seek. Defaults to the client's default groupId.
+     * @param assignments Array of `{ topic, partition, timestamp }` tuples (Unix ms).
+     */
+    seekToTimestamp(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        timestamp: number;
+    }>): Promise<void>;
+    /**
+     * Returns the current circuit breaker state for a specific topic partition.
+     * Returns `undefined` when no circuit state exists — either `circuitBreaker` is not
+     * configured for the group, or the circuit has never been tripped.
+     *
+     * @param topic Topic name.
+     * @param partition Partition index.
+     * @param groupId Consumer group. Defaults to the client's default groupId.
+     */
+    getCircuitState(topic: string, partition: number, groupId?: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
     /**
      * Consume messages as an async iterator. Useful for scripts, migrations, and
      * one-off processing where the full `startConsumer` lifecycle is unnecessary.
@@ -667,6 +709,20 @@ interface KafkaLogger {
     error(message: string, ...args: any[]): void;
     debug?(message: string, ...args: any[]): void;
 }
+/**
+ * Context passed to `onTtlExpired` when a message is dropped because it
+ * exceeded `messageTtlMs` and `dlq` is not enabled.
+ */
+interface TtlExpiredContext {
+    /** Topic the message was consumed from. */
+    topic: string;
+    /** Actual age of the message in ms at the time it was dropped. */
+    ageMs: number;
+    /** The configured TTL threshold (`messageTtlMs`). */
+    messageTtlMs: number;
+    /** Original Kafka message headers (correlationId, traceparent, etc.). */
+    headers: MessageHeaders;
+}
 /**
  * Context passed to `onMessageLost` when a message is silently dropped
  * (handler threw and `dlq` is not enabled).
@@ -710,6 +766,12 @@ interface KafkaClientOptions {
      * Use this to alert, log to external systems, or trigger fallback logic.
      */
     onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
+     * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
+     * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
     /**
      * Called whenever a consumer group rebalance occurs.
      * - `'assign'` — new partitions were granted to this instance.
@@ -731,4 +793,4 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-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 };
+export { type TransactionContext as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, type TtlExpiredContext as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, buildEnvelopeHeaders as J, type KafkaInstrumentation as K, decodeHeaders as L, type MessageHeaders as M, extractEnvelope as N, getEnvelopeContext as O, runWithEnvelopeContext as P, topic as Q, 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.7.0",
+  "version": "0.7.1",
   "description": "Type-safe Kafka client wrapper for NestJS with typed topic-message maps",
   "license": "MIT",
   "main": "./dist/index.js",