@drarzter/kafka-client 0.7.1 → 0.7.2

package/dist/index.js

@@ -57,7 +57,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client/kafka.client/index.ts
-var import_kafka_javascript = require("@confluentinc/kafka-javascript");
+var import_kafka_javascript2 = require("@confluentinc/kafka-javascript");
 
 // src/client/message/envelope.ts
 var import_node_async_hooks = require("async_hooks");
@@ -198,7 +198,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) => {
@@ -228,11 +228,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) {
+var import_kafka_javascript = require("@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);
@@ -244,8 +245,11 @@ function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps) {
     return consumers.get(groupId);
   }
   consumerCreationOptions.set(groupId, { fromBeginning, autoCommit });
+  const assigners = [
+    partitionAssigner === "roundrobin" ? import_kafka_javascript.KafkaJS.PartitionAssigners.roundRobin : partitionAssigner === "range" ? import_kafka_javascript.KafkaJS.PartitionAssigners.range : import_kafka_javascript.KafkaJS.PartitionAssigners.cooperativeSticky
+  ];
   const config = {
-    kafkaJS: { groupId, fromBeginning, autoCommit }
+    kafkaJS: { groupId, fromBeginning, autoCommit, partitionAssigners: assigners }
   };
   if (onRebalance) {
     const cb = onRebalance;
@@ -790,7 +794,8 @@ async function handleEachMessage(payload, opts, deps) {
         });
         deps.onDlq?.(envelope, "ttl-expired");
       } else {
-        await deps.onTtlExpired?.({
+        const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+        await ttlHandler?.({
           topic: topic2,
           ageMs,
           messageTtlMs: opts.messageTtlMs,
@@ -917,7 +922,8 @@ async function handleEachBatch(payload, opts, deps) {
           });
           deps.onDlq?.(envelope, "ttl-expired");
         } else {
-          await deps.onTtlExpired?.({
+          const ttlHandler = opts.onTtlExpired ?? deps.onTtlExpired;
+          await ttlHandler?.({
             topic: batch.topic,
             ageMs,
             messageTtlMs: opts.messageTtlMs,
@@ -963,6 +969,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 });
@@ -972,7 +979,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);
     }
@@ -1234,7 +1241,7 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 }
 
 // src/client/kafka.client/index.ts
-var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript.KafkaJS;
+var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript2.KafkaJS;
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
 var AsyncQueue = class {
   constructor(highWaterMark = Infinity, onFull = () => {
@@ -1358,21 +1365,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);
   }
@@ -1420,6 +1460,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);
@@ -1462,6 +1509,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)
@@ -1493,6 +1546,7 @@ var KafkaClient = class _KafkaClient {
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
             messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
             eosMainContext
           },
           deps
@@ -1525,6 +1579,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?.(
@@ -1548,6 +1608,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,
@@ -1562,6 +1632,7 @@ var KafkaClient = class _KafkaClient {
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
             deduplication,
             messageTtlMs: options.messageTtlMs,
+            onTtlExpired: options.onTtlExpired,
             eosMainContext
           },
           deps
@@ -1608,6 +1679,11 @@ var KafkaClient = class _KafkaClient {
    * }
    */
   consume(topic2, options) {
+    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,
@@ -1636,6 +1712,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);
@@ -1729,6 +1813,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);
@@ -1742,6 +1832,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);
@@ -1781,6 +1877,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();
@@ -1909,6 +2016,14 @@ 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)) {
@@ -1942,6 +2057,17 @@ var KafkaClient = class _KafkaClient {
       );
     }
   }
+  /**
+   * 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}`);
@@ -1999,9 +2125,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);
@@ -2021,6 +2200,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);
@@ -2092,6 +2276,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(() => {
@@ -2101,6 +2292,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) => {
@@ -2121,12 +2318,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;
@@ -2139,6 +2343,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) {
@@ -2147,12 +2357,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) {
@@ -2214,12 +2436,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) {
@@ -2362,6 +2598,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);
@@ -2387,6 +2632,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";
@@ -2405,15 +2653,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);
     }
@@ -2421,7 +2674,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);
       }
     }
@@ -2431,21 +2684,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) {
@@ -2456,6 +2710,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,
@@ -2465,6 +2728,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,
@@ -2488,6 +2760,21 @@ var KafkaClient = class _KafkaClient {
       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,
@@ -2574,6 +2861,12 @@ var KafkaExplorer = class {
     this.moduleRef = moduleRef;
   }
   logger = new import_common2.Logger(KafkaExplorer.name);
+  /**
+   * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated
+   * method to its Kafka client via `startConsumer` or `startBatchConsumer`.
+   *
+   * Called automatically by the NestJS lifecycle — do not invoke manually.
+   */
   async onModuleInit() {
     const providers = this.discoveryService.getProviders();
     for (const wrapper of providers) {