@drarzter/kafka-client 0.7.2 → 0.7.3

package/dist/core.d.mts

@@ -16,7 +16,6 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     /** Maps transactionalId → Producer for each active retry level consumer. */
     private readonly retryTxProducers;
     private readonly consumers;
-    private readonly admin;
     private readonly logger;
     private readonly autoCreateTopicsEnabled;
     private readonly strictSchemasEnabled;
@@ -36,20 +35,20 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly onRebalance;
     /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
     private readonly txId;
-    /** Per-topic event counters, lazily created on first event. Aggregated by `getMetrics()`. */
-    private readonly _topicMetrics;
     /** Monotonically increasing Lamport clock stamped on every outgoing message. */
     private _lamportClock;
     /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
     private readonly dedupStates;
-    /** Circuit breaker state per `"${gid}:${topic}:${partition}"` key. */
-    private readonly circuitStates;
-    /** Circuit breaker config per groupId, set at startConsumer/startBatchConsumer time. */
-    private readonly circuitConfigs;
-    private isAdminConnected;
-    private inFlightTotal;
-    private readonly drainResolvers;
+    private readonly circuitBreaker;
+    private readonly adminOps;
+    private readonly metrics;
+    private readonly inFlight;
     readonly clientId: ClientId;
+    private readonly _producerOpsDeps;
+    private readonly _consumerOpsDeps;
+    private readonly _retryTopicDeps;
+    /** DLQ header keys added by the pipeline — stripped before re-publishing. */
+    private static readonly DLQ_HEADER_KEYS;
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
     /**
      * Send a single typed message. Accepts a topic key or a `TopicDescriptor`.
@@ -170,8 +169,6 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private pauseTopicAllPartitions;
     /** Resume all assigned partitions of a topic for a consumer group (used for queue backpressure). */
     private resumeTopicAllPartitions;
-    /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
-    private static readonly DLQ_HEADER_KEYS;
     /**
      * Re-publish messages from a dead letter queue back to the original topic.
      *
@@ -295,95 +292,12 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * NestJS apps get drain for free via `onModuleDestroy` → `disconnect()`.
      */
     enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
-    /**
-     * 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.
-     */
-    private trackInFlight;
-    /**
-     * 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
-     */
-    private waitForDrain;
-    /**
-     * 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
-     */
     private preparePayload;
-    private notifyAfterSend;
-    /**
-     * 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
-     */
-    private metricsFor;
-    /**
-     * 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.
-     */
-    private notifyRetry;
-    /**
-     * 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.
-     */
-    private notifyDlq;
-    /**
-     * 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.
-     */
-    private notifyDuplicate;
-    /**
-     * 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.
-     */
-    private notifyMessage;
     /**
      * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
      * The handler itself is not cancelled — the warning is diagnostic only.
      */
     private wrapWithTimeoutWarning;
-    /**
-     * When `retryTopics: true` and `autoCreateTopics: false`, verify that every
-     * `<topic>.retry.<level>` topic already exists. Throws a clear error at startup
-     * rather than silently discovering missing topics on the first handler failure.
-     */
-    private validateRetryTopicsExist;
-    /**
-     * When `autoCreateTopics` is disabled, verify that `<topic>.dlq` exists for every
-     * consumed topic. Throws a clear error at startup rather than silently discovering
-     * missing DLQ topics on the first handler failure.
-     */
-    private validateDlqTopicsExist;
-    /**
-     * When `deduplication.strategy: 'topic'` and `autoCreateTopics: false`, verify
-     * that every `<topic>.duplicates` destination topic already exists. Throws a
-     * clear error at startup rather than silently dropping duplicates on first hit.
-     */
-    private validateDuplicatesTopicsExist;
-    /**
-     * Connect the admin client if not already connected.
-     * The flag is only set to `true` after a successful connect — if `admin.connect()`
-     * throws the flag remains `false` so the next call will retry the connection.
-     */
-    private ensureAdminConnected;
     /**
      * Create and connect a transactional producer for EOS retry routing.
      * Each retry level consumer gets its own producer with a unique `transactionalId`
@@ -392,56 +306,24 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private createRetryTxProducer;
     /**
      * 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.
+     * If `autoCreateTopics` is disabled, returns immediately.
+     * Concurrent calls for the same topic are deduplicated.
      */
     private ensureTopic;
     /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
     private setupConsumer;
     /** Create or retrieve the deduplication context for a consumer group. */
     private resolveDeduplicationContext;
-    /**
-     * 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.
-     */
-    private get producerOpsDeps();
-    /**
-     * 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.
-     */
-    private get consumerOpsDeps();
+    /** Guard checks shared by startConsumer and startBatchConsumer. */
+    private validateTopicConsumerOpts;
+    /** Create EOS transactional producer context for atomic main → retry.1 routing. */
+    private makeEosMainContext;
+    /** Start companion retry-level consumers and register them under the main groupId. */
+    private launchRetryChain;
     /** Build MessageHandlerDeps with circuit breaker callbacks bound to the given groupId. */
     private messageDepsFor;
-    /**
-     * 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.
-     */
-    private get retryTopicDeps();
+    /** Build the deps object passed to retry topic consumers. */
+    private buildRetryTopicDeps;
 }
 
 /** Error thrown when a consumer message handler fails. */

package/dist/core.d.ts

@@ -16,7 +16,6 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     /** Maps transactionalId → Producer for each active retry level consumer. */
     private readonly retryTxProducers;
     private readonly consumers;
-    private readonly admin;
     private readonly logger;
     private readonly autoCreateTopicsEnabled;
     private readonly strictSchemasEnabled;
@@ -36,20 +35,20 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly onRebalance;
     /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
     private readonly txId;
-    /** Per-topic event counters, lazily created on first event. Aggregated by `getMetrics()`. */
-    private readonly _topicMetrics;
     /** Monotonically increasing Lamport clock stamped on every outgoing message. */
     private _lamportClock;
     /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
     private readonly dedupStates;
-    /** Circuit breaker state per `"${gid}:${topic}:${partition}"` key. */
-    private readonly circuitStates;
-    /** Circuit breaker config per groupId, set at startConsumer/startBatchConsumer time. */
-    private readonly circuitConfigs;
-    private isAdminConnected;
-    private inFlightTotal;
-    private readonly drainResolvers;
+    private readonly circuitBreaker;
+    private readonly adminOps;
+    private readonly metrics;
+    private readonly inFlight;
     readonly clientId: ClientId;
+    private readonly _producerOpsDeps;
+    private readonly _consumerOpsDeps;
+    private readonly _retryTopicDeps;
+    /** DLQ header keys added by the pipeline — stripped before re-publishing. */
+    private static readonly DLQ_HEADER_KEYS;
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
     /**
      * Send a single typed message. Accepts a topic key or a `TopicDescriptor`.
@@ -170,8 +169,6 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private pauseTopicAllPartitions;
     /** Resume all assigned partitions of a topic for a consumer group (used for queue backpressure). */
     private resumeTopicAllPartitions;
-    /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
-    private static readonly DLQ_HEADER_KEYS;
     /**
      * Re-publish messages from a dead letter queue back to the original topic.
      *
@@ -295,95 +292,12 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * NestJS apps get drain for free via `onModuleDestroy` → `disconnect()`.
      */
     enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
-    /**
-     * 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.
-     */
-    private trackInFlight;
-    /**
-     * 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
-     */
-    private waitForDrain;
-    /**
-     * 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
-     */
     private preparePayload;
-    private notifyAfterSend;
-    /**
-     * 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
-     */
-    private metricsFor;
-    /**
-     * 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.
-     */
-    private notifyRetry;
-    /**
-     * 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.
-     */
-    private notifyDlq;
-    /**
-     * 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.
-     */
-    private notifyDuplicate;
-    /**
-     * 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.
-     */
-    private notifyMessage;
     /**
      * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
      * The handler itself is not cancelled — the warning is diagnostic only.
      */
     private wrapWithTimeoutWarning;
-    /**
-     * When `retryTopics: true` and `autoCreateTopics: false`, verify that every
-     * `<topic>.retry.<level>` topic already exists. Throws a clear error at startup
-     * rather than silently discovering missing topics on the first handler failure.
-     */
-    private validateRetryTopicsExist;
-    /**
-     * When `autoCreateTopics` is disabled, verify that `<topic>.dlq` exists for every
-     * consumed topic. Throws a clear error at startup rather than silently discovering
-     * missing DLQ topics on the first handler failure.
-     */
-    private validateDlqTopicsExist;
-    /**
-     * When `deduplication.strategy: 'topic'` and `autoCreateTopics: false`, verify
-     * that every `<topic>.duplicates` destination topic already exists. Throws a
-     * clear error at startup rather than silently dropping duplicates on first hit.
-     */
-    private validateDuplicatesTopicsExist;
-    /**
-     * Connect the admin client if not already connected.
-     * The flag is only set to `true` after a successful connect — if `admin.connect()`
-     * throws the flag remains `false` so the next call will retry the connection.
-     */
-    private ensureAdminConnected;
     /**
      * Create and connect a transactional producer for EOS retry routing.
      * Each retry level consumer gets its own producer with a unique `transactionalId`
@@ -392,56 +306,24 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private createRetryTxProducer;
     /**
      * 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.
+     * If `autoCreateTopics` is disabled, returns immediately.
+     * Concurrent calls for the same topic are deduplicated.
      */
     private ensureTopic;
     /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
     private setupConsumer;
     /** Create or retrieve the deduplication context for a consumer group. */
     private resolveDeduplicationContext;
-    /**
-     * 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.
-     */
-    private get producerOpsDeps();
-    /**
-     * 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.
-     */
-    private get consumerOpsDeps();
+    /** Guard checks shared by startConsumer and startBatchConsumer. */
+    private validateTopicConsumerOpts;
+    /** Create EOS transactional producer context for atomic main → retry.1 routing. */
+    private makeEosMainContext;
+    /** Start companion retry-level consumers and register them under the main groupId. */
+    private launchRetryChain;
     /** Build MessageHandlerDeps with circuit breaker callbacks bound to the given groupId. */
     private messageDepsFor;
-    /**
-     * 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.
-     */
-    private get retryTopicDeps();
+    /** Build the deps object passed to retry topic consumers. */
+    private buildRetryTopicDeps;
 }
 
 /** Error thrown when a consumer message handler fails. */