@drarzter/kafka-client 0.7.0 → 0.7.2

package/dist/{chunk-MJ342P4R.mjs → chunk-MADAJD2F.mjs}

@@ -1,5 +1,5 @@
 // src/client/kafka.client/index.ts
-import { KafkaJS } from "@confluentinc/kafka-javascript";
+import { KafkaJS as KafkaJS2 } from "@confluentinc/kafka-javascript";
 
 // src/client/message/envelope.ts
 import { AsyncLocalStorage } from "async_hooks";
@@ -140,7 +140,7 @@ async function validateMessage(topicOrDesc, message, deps, ctx) {
   }
   return message;
 }
-async function buildSendPayload(topicOrDesc, messages, deps) {
+async function buildSendPayload(topicOrDesc, messages, deps, compression) {
   const topic2 = resolveTopicName(topicOrDesc);
   const builtMessages = await Promise.all(
     messages.map(async (m) => {
@@ -170,11 +170,12 @@ async function buildSendPayload(topicOrDesc, messages, deps) {
       };
     })
   );
-  return { topic: topic2, messages: builtMessages };
+  return { topic: topic2, messages: builtMessages, ...compression && { compression } };
 }
 
 // src/client/kafka.client/consumer-ops.ts
-function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner) {
   const { consumers, consumerCreationOptions, kafka, onRebalance, logger } = deps;
   if (consumers.has(groupId)) {
     const prev = consumerCreationOptions.get(groupId);
@@ -186,8 +187,11 @@ function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
     return consumers.get(groupId);
   }
   consumerCreationOptions.set(groupId, { fromBeginning, autoCommit });
+  const assigners = [
+    partitionAssigner === "roundrobin" ? KafkaJS.PartitionAssigners.roundRobin : partitionAssigner === "range" ? KafkaJS.PartitionAssigners.range : KafkaJS.PartitionAssigners.cooperativeSticky
+  ];
   const config = {
-    kafkaJS: { groupId, fromBeginning, autoCommit }
+    kafkaJS: { groupId, fromBeginning, autoCommit, partitionAssigners: assigners }
   };
   if (onRebalance) {
     const cb = onRebalance;
@@ -732,10 +736,11 @@ async function handleEachMessage(payload, opts, deps) {
         });
         deps.onDlq?.(envelope, "ttl-expired");
       } else {
-        await deps.onMessageLost?.({
+        const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+        await ttlHandler?.({
           topic: topic2,
-          error: new Error(`TTL expired: ${ageMs}ms`),
-          attempt: 0,
+          ageMs,
+          messageTtlMs: opts.messageTtlMs,
           headers: envelope.headers
         });
       }
@@ -859,10 +864,11 @@ async function handleEachBatch(payload, opts, deps) {
           });
           deps.onDlq?.(envelope, "ttl-expired");
         } else {
-          await deps.onMessageLost?.({
+          const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+          await ttlHandler?.({
             topic: batch.topic,
-            error: new Error(`TTL expired: ${ageMs}ms`),
-            attempt: 0,
+            ageMs,
+            messageTtlMs: opts.messageTtlMs,
             headers: envelope.headers
           });
         }
@@ -905,6 +911,7 @@ async function handleEachBatch(payload, opts, deps) {
 async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   const maxAttempts = retryOpts?.retries ?? 5;
   const backoffMs = retryOpts?.backoffMs ?? 5e3;
+  const displayTopics = topics.map((t) => t instanceof RegExp ? t.toString() : t).join(", ");
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       await consumer.subscribe({ topics });
@@ -914,7 +921,7 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
       const msg = toError(error).message;
       const delay = Math.floor(Math.random() * backoffMs);
       logger.warn(
-        `Failed to subscribe to [${topics.join(", ")}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${delay}ms...`
+        `Failed to subscribe to [${displayTopics}] (attempt ${attempt}/${maxAttempts}): ${msg}. Retrying in ${delay}ms...`
       );
       await sleep(delay);
     }
@@ -1176,31 +1183,54 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 }
 
 // src/client/kafka.client/index.ts
-var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS;
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = KafkaJS2;
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
 var AsyncQueue = class {
+  constructor(highWaterMark = Infinity, onFull = () => {
+  }, onDrained = () => {
+  }) {
+    this.highWaterMark = highWaterMark;
+    this.onFull = onFull;
+    this.onDrained = onDrained;
+  }
   items = [];
   waiting = [];
   closed = false;
+  error;
+  paused = false;
   push(item) {
     if (this.waiting.length > 0) {
-      this.waiting.shift()({ value: item, done: false });
+      this.waiting.shift().resolve({ value: item, done: false });
     } else {
       this.items.push(item);
+      if (!this.paused && this.items.length >= this.highWaterMark) {
+        this.paused = true;
+        this.onFull();
+      }
     }
   }
+  fail(err) {
+    this.closed = true;
+    this.error = err;
+    for (const { reject } of this.waiting.splice(0)) reject(err);
+  }
   close() {
     this.closed = true;
-    for (const r of this.waiting.splice(0)) {
-      r({ value: void 0, done: true });
-    }
+    for (const { resolve } of this.waiting.splice(0))
+      resolve({ value: void 0, done: true });
   }
   next() {
-    if (this.items.length > 0)
-      return Promise.resolve({ value: this.items.shift(), done: false });
-    if (this.closed)
-      return Promise.resolve({ value: void 0, done: true });
-    return new Promise((r) => this.waiting.push(r));
+    if (this.error) return Promise.reject(this.error);
+    if (this.items.length > 0) {
+      const value = this.items.shift();
+      if (this.paused && this.items.length <= Math.floor(this.highWaterMark / 2)) {
+        this.paused = false;
+        this.onDrained();
+      }
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.closed) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
   }
 };
 var KafkaClient = class _KafkaClient {
@@ -1227,6 +1257,7 @@ var KafkaClient = class _KafkaClient {
   companionGroupIds = /* @__PURE__ */ new Map();
   instrumentation;
   onMessageLost;
+  onTtlExpired;
   onRebalance;
   /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
   txId;
@@ -1258,6 +1289,7 @@ var KafkaClient = class _KafkaClient {
     this.numPartitions = options?.numPartitions ?? 1;
     this.instrumentation = options?.instrumentation ?? [];
     this.onMessageLost = options?.onMessageLost;
+    this.onTtlExpired = options?.onTtlExpired;
     this.onRebalance = options?.onRebalance;
     this.txId = options?.transactionalId ?? `${clientId}-tx`;
     this.kafka = new KafkaClass({
@@ -1275,21 +1307,54 @@ var KafkaClient = class _KafkaClient {
     this.admin = this.kafka.admin();
   }
   async sendMessage(topicOrDesc, message, options = {}) {
-    const payload = await this.preparePayload(topicOrDesc, [
-      {
-        value: message,
-        key: options.key,
-        headers: options.headers,
-        correlationId: options.correlationId,
-        schemaVersion: options.schemaVersion,
-        eventId: options.eventId
-      }
-    ]);
+    const payload = await this.preparePayload(
+      topicOrDesc,
+      [
+        {
+          value: message,
+          key: options.key,
+          headers: options.headers,
+          correlationId: options.correlationId,
+          schemaVersion: options.schemaVersion,
+          eventId: options.eventId
+        }
+      ],
+      options.compression
+    );
     await this.producer.send(payload);
     this.notifyAfterSend(payload.topic, payload.messages.length);
   }
-  async sendBatch(topicOrDesc, messages) {
-    const payload = await this.preparePayload(topicOrDesc, messages);
+  /**
+   * Send a null-value (tombstone) message. Used with log-compacted topics to signal
+   * that a key's record should be removed during the next compaction cycle.
+   *
+   * Tombstones skip envelope headers, schema validation, and Lamport clock stamping.
+   * Both `beforeSend` and `afterSend` instrumentation hooks are still called so tracing works correctly.
+   *
+   * @param topic Topic name.
+   * @param key Partition key identifying the record to tombstone.
+   * @param headers Optional custom Kafka headers.
+   */
+  async sendTombstone(topic2, key, headers) {
+    const hdrs = { ...headers };
+    for (const inst of this.instrumentation) {
+      inst.beforeSend?.(topic2, hdrs);
+    }
+    await this.ensureTopic(topic2);
+    await this.producer.send({
+      topic: topic2,
+      messages: [{ value: null, key, headers: hdrs }]
+    });
+    for (const inst of this.instrumentation) {
+      inst.afterSend?.(topic2);
+    }
+  }
+  async sendBatch(topicOrDesc, messages, options) {
+    const payload = await this.preparePayload(
+      topicOrDesc,
+      messages,
+      options?.compression
+    );
     await this.producer.send(payload);
     this.notifyAfterSend(payload.topic, payload.messages.length);
   }
@@ -1337,6 +1402,13 @@ var KafkaClient = class _KafkaClient {
           await tx.send(payload);
           this.notifyAfterSend(payload.topic, payload.messages.length);
         },
+        /**
+         * Send multiple messages in a single call to the topic.
+         * All messages in the batch will be sent atomically.
+         * If any message fails to send, the entire batch will be aborted.
+         * @param topicOrDesc - topic name or TopicDescriptor
+         * @param messages - array of messages to send with optional key, headers, correlationId, schemaVersion, and eventId
+         */
         sendBatch: async (topicOrDesc, messages) => {
           const payload = await this.preparePayload(topicOrDesc, messages);
           await tx.send(payload);
@@ -1379,6 +1451,12 @@ var KafkaClient = class _KafkaClient {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
+    const hasRegexTopics = topics.some((t) => t instanceof RegExp);
+    if (options.retryTopics && hasRegexTopics) {
+      throw new Error(
+        "retryTopics is incompatible with regex topic patterns \u2014 retry topics require a fixed topic name to build the retry chain."
+      );
+    }
     const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
     const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
     if (options.circuitBreaker)
@@ -1410,6 +1488,7 @@ var KafkaClient = class _KafkaClient {
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
             messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
             eosMainContext
           },
           deps
@@ -1442,6 +1521,12 @@ var KafkaClient = class _KafkaClient {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
+    const hasRegexTopics = topics.some((t) => t instanceof RegExp);
+    if (options.retryTopics && hasRegexTopics) {
+      throw new Error(
+        "retryTopics is incompatible with regex topic patterns \u2014 retry topics require a fixed topic name to build the retry chain."
+      );
+    }
     if (options.retryTopics) {
     } else if (options.autoCommit !== false) {
       this.logger.debug?.(
@@ -1465,6 +1550,16 @@ var KafkaClient = class _KafkaClient {
       eosMainContext = { txProducer, consumer };
     }
     await consumer.run({
+      /**
+       * eachBatch: called by the consumer for each batch of messages.
+       * Called with the `payload` argument, which is an object containing the
+       * batch of messages and a `BatchMeta` object with offset management controls.
+       *
+       * The function is wrapped with `trackInFlight` and `handleEachBatch` to provide
+       * error handling and offset management.
+       *
+       * @param payload - an object containing the batch of messages and a `BatchMeta` object.
+       */
       eachBatch: (payload) => this.trackInFlight(
         () => handleEachBatch(
           payload,
@@ -1479,6 +1574,7 @@ var KafkaClient = class _KafkaClient {
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
             messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
             eosMainContext
           },
           deps
@@ -1525,7 +1621,17 @@ var KafkaClient = class _KafkaClient {
    * }
    */
   consume(topic2, options) {
-    const queue = new AsyncQueue();
+    if (options?.retryTopics) {
+      throw new Error(
+        "consume() does not support retryTopics (EOS retry chains). Use startConsumer() with retryTopics: true for guaranteed retry delivery."
+      );
+    }
+    const gid = options?.groupId ?? this.defaultGroupId;
+    const queue = new AsyncQueue(
+      options?.queueHighWaterMark,
+      () => this.pauseTopicAllPartitions(gid, topic2),
+      () => this.resumeTopicAllPartitions(gid, topic2)
+    );
     const handlePromise = this.startConsumer(
       [topic2],
       async (envelope) => {
@@ -1533,6 +1639,7 @@ var KafkaClient = class _KafkaClient {
       },
       options
     );
+    handlePromise.catch((err) => queue.fail(err));
     return {
       [Symbol.asyncIterator]() {
         return this;
@@ -1547,6 +1654,14 @@ var KafkaClient = class _KafkaClient {
     };
   }
   // ── Consumer lifecycle ───────────────────────────────────────────
+  /**
+   * Stop all consumers or a specific group.
+   *
+   * If `groupId` is unspecified, all active consumers are stopped.
+   * If `groupId` is specified, only the consumer with that group ID is stopped.
+   *
+   * @throws {Error} if the consumer fails to disconnect.
+   */
   async stopConsumer(groupId) {
     if (groupId !== void 0) {
       const consumer = this.consumers.get(groupId);
@@ -1640,6 +1755,12 @@ var KafkaClient = class _KafkaClient {
       this.logger.log("All consumers disconnected");
     }
   }
+  /**
+   * Temporarily stop delivering messages from specific partitions without disconnecting the consumer.
+   *
+   * @param groupId Consumer group to pause. Defaults to the client's default groupId.
+   * @param assignments Topic-partition pairs to pause.
+   */
   pauseConsumer(groupId, assignments) {
     const gid = groupId ?? this.defaultGroupId;
     const consumer = this.consumers.get(gid);
@@ -1653,6 +1774,12 @@ var KafkaClient = class _KafkaClient {
       )
     );
   }
+  /**
+   * Resume message delivery for previously paused topic-partitions.
+   *
+   * @param {string|undefined} groupId Consumer group to resume. Defaults to the client's default groupId.
+   * @param {Array<{ topic: string; partitions: number[] }>} assignments Topic-partition pairs to resume.
+   */
   resumeConsumer(groupId, assignments) {
     const gid = groupId ?? this.defaultGroupId;
     const consumer = this.consumers.get(gid);
@@ -1666,6 +1793,24 @@ var KafkaClient = class _KafkaClient {
       )
     );
   }
+  /** Pause all assigned partitions of a topic for a consumer group (used for queue backpressure). */
+  pauseTopicAllPartitions(gid, topic2) {
+    const consumer = this.consumers.get(gid);
+    if (!consumer) return;
+    const assignment = consumer.assignment?.() ?? [];
+    const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+    if (partitions.length > 0)
+      consumer.pause(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+  }
+  /** Resume all assigned partitions of a topic for a consumer group (used for queue backpressure). */
+  resumeTopicAllPartitions(gid, topic2) {
+    const consumer = this.consumers.get(gid);
+    if (!consumer) return;
+    const assignment = consumer.assignment?.() ?? [];
+    const partitions = assignment.filter((a) => a.topic === topic2).map((a) => a.partition);
+    if (partitions.length > 0)
+      consumer.resume(partitions.map((p) => ({ topic: topic2, partitions: [p] })));
+  }
   /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
   static DLQ_HEADER_KEYS = /* @__PURE__ */ new Set([
     "x-dlq-original-topic",
@@ -1674,6 +1819,17 @@ var KafkaClient = class _KafkaClient {
     "x-dlq-error-stack",
     "x-dlq-attempt-count"
   ]);
+  /**
+   * Re-publish messages from a dead letter queue back to the original topic.
+   *
+   * Messages are consumed from `<topic>.dlq` and re-published to `<topic>`.
+   * The original topic is determined by the `x-dlq-original-topic` header.
+   * The `x-dlq-*` headers are stripped before re-publishing.
+   *
+   * @param topic - The topic to replay from `<topic>.dlq`
+   * @param options - Options for replay
+   * @returns { replayed: number; skipped: number } - counts of re-published vs skipped messages
+   */
   async replayDlq(topic2, options = {}) {
     const dlqTopic = `${topic2}.dlq`;
     await this.ensureAdminConnected();
@@ -1802,6 +1958,68 @@ var KafkaClient = class _KafkaClient {
       );
     }
   }
+  /**
+   * Seek specific topic-partition pairs to the offset nearest to a given timestamp
+   * (in milliseconds) for a stopped consumer group.
+   * Throws if the group is still running — call `stopConsumer(groupId)` first.
+   * Assignments are grouped by topic and committed via `admin.setOffsets`.
+   * If no offset exists at the requested timestamp (e.g. empty partition or
+   * future timestamp), the partition falls back to `-1` (end of topic — new messages only).
+   */
+  async seekToTimestamp(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (this.runningConsumers.has(gid)) {
+      throw new Error(
+        `seekToTimestamp: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before seeking offsets.`
+      );
+    }
+    await this.ensureAdminConnected();
+    const byTopic = /* @__PURE__ */ new Map();
+    for (const { topic: topic2, partition, timestamp } of assignments) {
+      const list = byTopic.get(topic2) ?? [];
+      list.push({ partition, timestamp });
+      byTopic.set(topic2, list);
+    }
+    for (const [topic2, parts] of byTopic) {
+      const offsets = await Promise.all(
+        parts.map(async ({ partition, timestamp }) => {
+          const results = await this.admin.fetchTopicOffsetsByTime(
+            topic2,
+            timestamp
+          );
+          const found = results.find(
+            (r) => r.partition === partition
+          );
+          return { partition, offset: found?.offset ?? "-1" };
+        })
+      );
+      await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions: offsets });
+      this.logger.log(
+        `Offsets set by timestamp for group "${gid}" on "${topic2}": ${JSON.stringify(offsets)}`
+      );
+    }
+  }
+  /**
+   * 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.
+   *
+   * @returns `{ status, failures, windowSize }` snapshot for a given partition or `undefined` if no state exists.
+   */
+  getCircuitState(topic2, partition, groupId) {
+    const gid = groupId ?? this.defaultGroupId;
+    const state = this.circuitStates.get(`${gid}:${topic2}:${partition}`);
+    if (!state) return void 0;
+    return {
+      status: state.status,
+      failures: state.window.filter((v) => !v).length,
+      windowSize: state.window.length
+    };
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1849,9 +2067,62 @@ var KafkaClient = class _KafkaClient {
       };
     }
   }
+  /**
+   * List all consumer groups known to the broker.
+   * Useful for monitoring which groups are active and their current state.
+   */
+  async listConsumerGroups() {
+    await this.ensureAdminConnected();
+    const result = await this.admin.listGroups();
+    return result.groups.map((g) => ({
+      groupId: g.groupId,
+      state: g.state ?? "Unknown"
+    }));
+  }
+  /**
+   * Describe topics — returns partition layout, leader, replicas, and ISR.
+   * @param topics Topic names to describe. Omit to describe all topics.
+   */
+  async describeTopics(topics) {
+    await this.ensureAdminConnected();
+    const result = await this.admin.fetchTopicMetadata(
+      topics ? { topics } : void 0
+    );
+    return result.topics.map((t) => ({
+      name: t.name,
+      partitions: t.partitions.map((p) => ({
+        partition: p.partitionId ?? p.partition,
+        leader: p.leader,
+        replicas: p.replicas.map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        ),
+        isr: p.isr.map(
+          (r) => typeof r === "number" ? r : r.nodeId
+        )
+      }))
+    }));
+  }
+  /**
+   * Delete records from a topic up to (but not including) the given offsets.
+   * All messages with offsets **before** the given offset are deleted.
+   */
+  async deleteRecords(topic2, partitions) {
+    await this.ensureAdminConnected();
+    await this.admin.deleteTopicRecords({ topic: topic2, partitions });
+  }
+  /** Return the client ID provided during `KafkaClient` construction. */
   getClientId() {
     return this.clientId;
   }
+  /**
+   * Return a snapshot of internal event counters accumulated since client creation
+   * (or since the last `resetMetrics()` call).
+   *
+   * @param topic Topic name to scope the snapshot to. When omitted, counters are
+   *   aggregated across all topics. If the topic has no recorded events yet, returns
+   *   a zero-valued snapshot.
+   * @returns Read-only `KafkaMetrics` snapshot: `processedCount`, `retryCount`, `dlqCount`, `dedupCount`.
+   */
   getMetrics(topic2) {
     if (topic2 !== void 0) {
       const m = this._topicMetrics.get(topic2);
@@ -1871,6 +2142,11 @@ var KafkaClient = class _KafkaClient {
     }
     return agg;
   }
+  /**
+   * Reset internal event counters to zero.
+   *
+   * @param topic Topic name to reset. When omitted, all topics are reset.
+   */
   resetMetrics(topic2) {
     if (topic2 !== void 0) {
       this._topicMetrics.delete(topic2);
@@ -1942,6 +2218,13 @@ var KafkaClient = class _KafkaClient {
       process.once(signal, handler);
     }
   }
+  /**
+   * Increment the in-flight handler count and return a promise that calls the given handler.
+   * When the promise resolves or rejects, decrement the in flight handler count.
+   * If the in flight handler count reaches 0, call all previously registered drain resolvers.
+   * @param fn The handler to call when the promise is resolved or rejected.
+   * @returns A promise that resolves or rejects with the result of calling the handler.
+   */
   trackInFlight(fn) {
     this.inFlightTotal++;
     return fn().finally(() => {
@@ -1951,6 +2234,12 @@ var KafkaClient = class _KafkaClient {
       }
     });
   }
+  /**
+   * Waits for all in-flight handlers to complete or for a given timeout, whichever comes first.
+   * @param timeoutMs Maximum time to wait in milliseconds.
+   * @returns A promise that resolves when all handlers have completed or the timeout is reached.
+   * @private
+   */
   waitForDrain(timeoutMs) {
     if (this.inFlightTotal === 0) return Promise.resolve();
     return new Promise((resolve) => {
@@ -1971,12 +2260,19 @@ var KafkaClient = class _KafkaClient {
     });
   }
   // ── Private helpers ──────────────────────────────────────────────
-  async preparePayload(topicOrDesc, messages) {
+  /**
+   * Prepare a send payload by registering the topic's schema and then building the payload.
+   * @param topicOrDesc - topic name or topic descriptor
+   * @param messages - batch of messages to send
+   * @returns - prepared payload
+   */
+  async preparePayload(topicOrDesc, messages, compression) {
     registerSchema(topicOrDesc, this.schemaRegistry, this.logger);
     const payload = await buildSendPayload(
       topicOrDesc,
       messages,
-      this.producerOpsDeps
+      this.producerOpsDeps,
+      compression
     );
     await this.ensureTopic(payload.topic);
     return payload;
@@ -1989,6 +2285,12 @@ var KafkaClient = class _KafkaClient {
       }
     }
   }
+  /**
+   * Returns the KafkaMetrics for a given topic.
+   * If the topic hasn't seen any events, initializes a zero-valued snapshot.
+   * @param topic - name of the topic to get the metrics for
+   * @returns - KafkaMetrics for the given topic
+   */
   metricsFor(topic2) {
     let m = this._topicMetrics.get(topic2);
     if (!m) {
@@ -1997,12 +2299,24 @@ var KafkaClient = class _KafkaClient {
     }
     return m;
   }
+  /**
+   * Notifies instrumentation hooks of a retry event.
+   * @param envelope The original message envelope that triggered the retry.
+   * @param attempt The current retry attempt (1-indexed).
+   * @param maxRetries The maximum number of retries configured for this topic.
+   */
   notifyRetry(envelope, attempt, maxRetries) {
     this.metricsFor(envelope.topic).retryCount++;
     for (const inst of this.instrumentation) {
       inst.onRetry?.(envelope, attempt, maxRetries);
     }
   }
+  /**
+   * Called whenever a message is routed to the dead letter queue.
+   * @param envelope The original message envelope.
+   * @param reason The reason for routing to the dead letter queue.
+   * @param gid The group ID of the consumer that triggered the circuit breaker, if any.
+   */
   notifyDlq(envelope, reason, gid) {
     this.metricsFor(envelope.topic).dlqCount++;
     for (const inst of this.instrumentation) {
@@ -2022,6 +2336,11 @@ var KafkaClient = class _KafkaClient {
     if (state.status === "open") return;
     const openCircuit = () => {
       state.status = "open";
+      state.window = [];
+      state.successes = 0;
+      clearTimeout(state.timer);
+      for (const inst of this.instrumentation)
+        inst.onCircuitOpen?.(envelope.topic, envelope.partition);
       this.pauseConsumer(gid, [
         { topic: envelope.topic, partitions: [envelope.partition] }
       ]);
@@ -2031,6 +2350,8 @@ var KafkaClient = class _KafkaClient {
         this.logger.log(
           `[CircuitBreaker] HALF-OPEN \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
         );
+        for (const inst of this.instrumentation)
+          inst.onCircuitHalfOpen?.(envelope.topic, envelope.partition);
         this.resumeConsumer(gid, [
           { topic: envelope.topic, partitions: [envelope.partition] }
         ]);
@@ -2057,12 +2378,26 @@ var KafkaClient = class _KafkaClient {
       openCircuit();
     }
   }
+  /**
+   * Notify all instrumentation hooks about a duplicate message detection.
+   * Invoked by the consumer after a message has been successfully processed
+   * and the Lamport clock detected a duplicate.
+   * @param envelope The processed message envelope.
+   * @param strategy The duplicate detection strategy used.
+   */
   notifyDuplicate(envelope, strategy) {
     this.metricsFor(envelope.topic).dedupCount++;
     for (const inst of this.instrumentation) {
       inst.onDuplicate?.(envelope, strategy);
     }
   }
+  /**
+   * Notify all instrumentation hooks about a successfully processed message.
+   * Invoked by the consumer after a message has been successfully processed
+   * by the handler.
+   * @param envelope The processed message envelope.
+   * @param gid The optional consumer group ID.
+   */
   notifyMessage(envelope, gid) {
     this.metricsFor(envelope.topic).processedCount++;
     for (const inst of this.instrumentation) {
@@ -2086,6 +2421,8 @@ var KafkaClient = class _KafkaClient {
         this.logger.log(
           `[CircuitBreaker] CLOSED \u2014 group="${gid}" topic="${envelope.topic}" partition=${envelope.partition}`
         );
+        for (const inst of this.instrumentation)
+          inst.onCircuitClose?.(envelope.topic, envelope.partition);
       }
     } else if (state.status === "closed") {
       const threshold = cfg.threshold ?? 5;
@@ -2203,6 +2540,15 @@ var KafkaClient = class _KafkaClient {
     this.retryTxProducers.set(transactionalId, p);
     return p;
   }
+  /**
+   * Ensure that a topic exists by creating it if it doesn't already exist.
+   * If `autoCreateTopics` is disabled, this method will not create the topic and
+   * will return immediately.
+   * If multiple concurrent calls are made to `ensureTopic` for the same topic,
+   * they are deduplicated to prevent multiple calls to `admin.createTopics()`.
+   * @param topic - The topic to ensure exists.
+   * @returns A promise that resolves when the topic has been created or already exists.
+   */
   async ensureTopic(topic2) {
     if (!this.autoCreateTopicsEnabled || this.ensuredTopics.has(topic2)) return;
     let p = this.ensureTopicPromises.get(topic2);
@@ -2228,6 +2574,9 @@ var KafkaClient = class _KafkaClient {
       interceptors = [],
       schemas: optionSchemas
     } = options;
+    const stringTopics = topics.filter((t) => !(t instanceof RegExp));
+    const regexTopics = topics.filter((t) => t instanceof RegExp);
+    const hasRegex = regexTopics.length > 0;
     const gid = optGroupId || this.defaultGroupId;
     const existingMode = this.runningConsumers.get(gid);
     const oppositeMode = mode === "eachMessage" ? "eachBatch" : "eachMessage";
@@ -2246,15 +2595,20 @@ var KafkaClient = class _KafkaClient {
       gid,
       fromBeginning,
       options.autoCommit ?? true,
-      this.consumerOpsDeps
+      this.consumerOpsDeps,
+      options.partitionAssigner
     );
     const schemaMap = buildSchemaMap(
-      topics,
+      stringTopics,
       this.schemaRegistry,
       optionSchemas,
       this.logger
     );
-    const topicNames = topics.map((t) => resolveTopicName(t));
+    const topicNames = stringTopics.map((t) => resolveTopicName(t));
+    const subscribeTopics = [
+      ...topicNames,
+      ...regexTopics
+    ];
     for (const t of topicNames) {
       await this.ensureTopic(t);
     }
@@ -2262,7 +2616,7 @@ var KafkaClient = class _KafkaClient {
       for (const t of topicNames) {
         await this.ensureTopic(`${t}.dlq`);
       }
-      if (!this.autoCreateTopicsEnabled) {
+      if (!this.autoCreateTopicsEnabled && topicNames.length > 0) {
         await this.validateDlqTopicsExist(topicNames);
       }
     }
@@ -2272,21 +2626,22 @@ var KafkaClient = class _KafkaClient {
         for (const t of topicNames) {
           await this.ensureTopic(dest ?? `${t}.duplicates`);
         }
-      } else {
+      } else if (topicNames.length > 0) {
         await this.validateDuplicatesTopicsExist(topicNames, dest);
       }
     }
     await consumer.connect();
     await subscribeWithRetry(
       consumer,
-      topicNames,
+      subscribeTopics,
       this.logger,
       options.subscribeRetry
     );
+    const displayTopics = subscribeTopics.map((t) => t instanceof RegExp ? t.toString() : t).join(", ");
     this.logger.log(
-      `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${topicNames.join(", ")}`
+      `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${displayTopics}`
     );
-    return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry };
+    return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, hasRegex };
   }
   /** Create or retrieve the deduplication context for a consumer group. */
   resolveDeduplicationContext(groupId, options) {
@@ -2297,6 +2652,15 @@ var KafkaClient = class _KafkaClient {
     return { options, state: this.dedupStates.get(groupId) };
   }
   // ── Deps object getters ──────────────────────────────────────────
+  /**
+   * An object containing the necessary dependencies for building a send payload.
+   *
+   * @property {Map<string, SchemaLike>} schemaRegistry - A map of topic names to their schemas.
+   * @property {boolean} strictSchemasEnabled - Whether strict schema validation is enabled.
+   * @property {KafkaInstrumentation} instrumentation - An object for creating a span for instrumentation.
+   * @property {KafkaLogger} logger - A logger for logging messages.
+   * @property {() => number} nextLamportClock - A function that returns the next value of the logical clock.
+   */
   get producerOpsDeps() {
     return {
       schemaRegistry: this.schemaRegistry,
@@ -2306,6 +2670,15 @@ var KafkaClient = class _KafkaClient {
       nextLamportClock: () => ++this._lamportClock
     };
   }
+  /**
+   * ConsumerOpsDeps object properties:
+   *
+   * @property {Map<string, Consumer>} consumers - A map of consumer group IDs to their corresponding consumer instances.
+   * @property {Map<string, { fromBeginning: boolean; autoCommit: boolean }>} consumerCreationOptions - A map of consumer group IDs to their creation options.
+   * @property {Kafka} kafka - The Kafka client instance.
+   * @property {function(string, Partition[]): void} onRebalance - An optional callback function called when a consumer group is rebalanced.
+   * @property {KafkaLogger} logger - The logger instance used for logging consumer operations.
+   */
   get consumerOpsDeps() {
     return {
       consumers: this.consumers,
@@ -2322,12 +2695,28 @@ var KafkaClient = class _KafkaClient {
       producer: this.producer,
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
+      onTtlExpired: this.onTtlExpired,
       onRetry: this.notifyRetry.bind(this),
       onDlq: (envelope, reason) => this.notifyDlq(envelope, reason, gid),
       onDuplicate: this.notifyDuplicate.bind(this),
       onMessage: (envelope) => this.notifyMessage(envelope, gid)
     };
   }
+  /**
+   * The dependencies object passed to the retry topic consumers.
+   *
+   * `logger`: The logger instance passed to the retry topic consumers.
+   * `producer`: The producer instance passed to the retry topic consumers.
+   * `instrumentation`: The instrumentation instance passed to the retry topic consumers.
+   * `onMessageLost`: The callback function passed to the retry topic consumers for tracking lost messages.
+   * `onRetry`: The callback function passed to the retry topic consumers for tracking retry attempts.
+   * `onDlq`: The callback function passed to the retry topic consumers for tracking dead-letter queue routing.
+   * `onMessage`: The callback function passed to the retry topic consumers for tracking message delivery.
+   * `ensureTopic`: A function that ensures a topic exists before subscribing to it.
+   * `getOrCreateConsumer`: A function that creates or retrieves a consumer instance.
+   * `runningConsumers`: A map of consumer group IDs to their corresponding consumer instances.
+   * `createRetryTxProducer`: A function that creates a retry transactional producer instance.
+   */
   get retryTopicDeps() {
     return {
       logger: this.logger,
@@ -2379,4 +2768,4 @@ export {
   KafkaClient,
   topic
 };
-//# sourceMappingURL=chunk-MJ342P4R.mjs.map
+//# sourceMappingURL=chunk-MADAJD2F.mjs.map