@drarzter/kafka-client 0.7.0 → 0.7.2

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, a as KafkaClientOptions, c as TopicDescriptor, w as SendOptions, B as BatchMessageItem, A as TransactionContext, l as EventEnvelope, b as ConsumerOptions, h as ConsumerHandle, e as BatchMeta, k as DlqReplayOptions, d as KafkaHealthResult, t as KafkaMetrics } from './types-DqQ7IXZr.js';
-export { f as BeforeConsumeResult, g as CircuitBreakerOptions, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, m as HEADER_EVENT_ID, n as HEADER_LAMPORT_CLOCK, o as HEADER_SCHEMA_VERSION, p as HEADER_TIMESTAMP, q as HEADER_TRACEPARENT, r as InferSchema, K as KafkaInstrumentation, s as KafkaLogger, M as MessageHeaders, u as MessageLostContext, R as RetryOptions, S as SchemaLike, v as SchemaParseContext, x as SubscribeRetryOptions, y as TTopicMessageMap, z as TopicsFrom, F as buildEnvelopeHeaders, J as decodeHeaders, L as extractEnvelope, N as getEnvelopeContext, O as runWithEnvelopeContext, P as topic } from './types-DqQ7IXZr.js';
+import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, a as KafkaClientOptions, c as TopicDescriptor, z as SendOptions, M as MessageHeaders, B as BatchMessageItem, f as BatchSendOptions, O as TransactionContext, o as EventEnvelope, b as ConsumerOptions, k as ConsumerHandle, e as BatchMeta, n as DlqReplayOptions, d as KafkaHealthResult, j as ConsumerGroupSummary, J as TopicDescription, w as KafkaMetrics } from './types-4qWrf2aJ.js';
+export { g as BeforeConsumeResult, h as CircuitBreakerOptions, i as CompressionType, l as ConsumerInterceptor, D as DeduplicationOptions, m as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, p as HEADER_EVENT_ID, q as HEADER_LAMPORT_CLOCK, r as HEADER_SCHEMA_VERSION, s as HEADER_TIMESTAMP, t as HEADER_TRACEPARENT, u as InferSchema, K as KafkaInstrumentation, v as KafkaLogger, x as MessageLostContext, R as RetryOptions, S as SchemaLike, y as SchemaParseContext, A as SubscribeRetryOptions, F as TTopicMessageMap, L as TopicPartitionInfo, N as TopicsFrom, P as TtlExpiredContext, Q as buildEnvelopeHeaders, U as decodeHeaders, V as extractEnvelope, W as getEnvelopeContext, X as runWithEnvelopeContext, Y as topic } from './types-4qWrf2aJ.js';
 
 /**
  * Type-safe Kafka client.
@@ -32,6 +32,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly companionGroupIds;
     private readonly instrumentation;
     private readonly onMessageLost;
+    private readonly onTtlExpired;
     private readonly onRebalance;
     /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
     private readonly txId;
@@ -50,12 +51,39 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly drainResolvers;
     readonly clientId: ClientId;
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
-    /** Send a single typed message. Accepts a topic key or a TopicDescriptor. */
+    /**
+     * Send a single typed message. Accepts a topic key or a `TopicDescriptor`.
+     *
+     * @param topic Topic key from the `TopicMessageMap` or a `TopicDescriptor` object.
+     * @param message Message payload — validated against the topic schema when one is registered.
+     * @param options Optional per-send settings: `key`, `headers`, `correlationId`, `compression`, etc.
+     */
     sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
-    /** Send multiple typed messages in one call. Accepts a topic key or a TopicDescriptor. */
-    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>): Promise<void>;
-    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>): Promise<void>;
+    /**
+     * 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.
+     */
+    sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
+    /**
+     * Send multiple typed messages in a single Kafka produce request. Accepts a topic key or a `TopicDescriptor`.
+     *
+     * Each item in `messages` can carry its own `key`, `headers`, `correlationId`, and `schemaVersion`.
+     * The `key` is used for partition routing — messages with the same key always land on the same partition.
+     *
+     * @param topic Topic key from the `TopicMessageMap` or a `TopicDescriptor` object.
+     * @param messages Array of messages to send.
+     * @param options Optional batch-level settings: `compression` codec.
+     */
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
     /** Execute multiple sends atomically. Commits on success, aborts on error. */
     transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
     /**
@@ -67,10 +95,36 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
      */
     disconnectProducer(): Promise<void>;
-    /** Subscribe to topics and start consuming messages with the given handler. */
+    /**
+     * Subscribe to one or more topics and start consuming messages one at a time.
+     *
+     * Each message is delivered to `handleMessage` as a fully-decoded `EventEnvelope`.
+     * The call blocks until the consumer is connected and the subscription is set up,
+     * then returns a `ConsumerHandle` with a `stop()` method for clean shutdown.
+     *
+     * @param topics Array of topic keys, `TopicDescriptor` objects, or `RegExp` patterns.
+     *   Regex patterns cannot be combined with `retryTopics: true`.
+     * @param handleMessage Async handler called for every message. Throw to trigger retries.
+     * @param options Consumer configuration — `groupId`, `retry`, `dlq`, `circuitBreaker`, etc.
+     * @returns A handle with `{ groupId, stop() }` for managing the consumer lifecycle.
+     */
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (envelope: EventEnvelope<T[K[number]]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (envelope: EventEnvelope<D["__type"]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
-    /** Subscribe to topics and consume messages in batches. */
+    /**
+     * Subscribe to one or more topics and consume messages in batches.
+     *
+     * `handleBatch` receives an array of decoded `EventEnvelope` objects together with
+     * batch metadata (topic, partition, high-watermark offset). Prefer this over
+     * `startConsumer` when throughput matters more than per-message latency.
+     *
+     * Set `autoCommit: false` in options when the handler calls `resolveOffset()` or
+     * `commitOffsetsIfNecessary()` directly, to avoid offset conflicts.
+     *
+     * @param topics Array of topic keys, `TopicDescriptor` objects, or `RegExp` patterns.
+     * @param handleBatch Async handler called with each batch of decoded messages.
+     * @param options Consumer configuration — `groupId`, `retry`, `dlq`, `autoCommit`, etc.
+     * @returns A handle with `{ groupId, stop() }` for managing the consumer lifecycle.
+     */
     startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (envelopes: EventEnvelope<T[K[number]]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (envelopes: EventEnvelope<D["__type"]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     /**
@@ -83,17 +137,52 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * }
      */
     consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /**
+     * 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.
+     */
     stopConsumer(groupId?: string): Promise<void>;
+    /**
+     * 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: string | undefined, assignments: Array<{
         topic: string;
         partitions: number[];
     }>): void;
+    /**
+     * 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: string | undefined, assignments: Array<{
         topic: string;
         partitions: number[];
     }>): void;
+    /** Pause all assigned partitions of a topic for a consumer group (used for queue backpressure). */
+    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.
+     *
+     * 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
+     */
     replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
         replayed: number;
         skipped: number;
@@ -109,6 +198,35 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
         partition: number;
         offset: string;
     }>): Promise<void>;
+    /**
+     * 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).
+     */
+    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.
+     *
+     * @returns `{ status, failures, windowSize }` snapshot for a given partition or `undefined` if no state exists.
+     */
+    getCircuitState(topic: string, partition: number, groupId?: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
     /**
      * Query consumer group lag per partition.
      * Lag = broker high-watermark − last committed offset.
@@ -127,8 +245,41 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     }>>;
     /** Check broker connectivity. Never throws — returns a discriminated union. */
     checkStatus(): Promise<KafkaHealthResult>;
+    /**
+     * List all consumer groups known to the broker.
+     * Useful for monitoring which groups are active and their current state.
+     */
+    listConsumerGroups(): Promise<ConsumerGroupSummary[]>;
+    /**
+     * Describe topics — returns partition layout, leader, replicas, and ISR.
+     * @param topics Topic names to describe. Omit to describe all topics.
+     */
+    describeTopics(topics?: string[]): Promise<TopicDescription[]>;
+    /**
+     * Delete records from a topic up to (but not including) the given offsets.
+     * All messages with offsets **before** the given offset are deleted.
+     */
+    deleteRecords(topic: string, partitions: Array<{
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /** Return the client ID provided during `KafkaClient` construction. */
     getClientId(): 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(topic?: string): Readonly<KafkaMetrics>;
+    /**
+     * Reset internal event counters to zero.
+     *
+     * @param topic Topic name to reset. When omitted, all topics are reset.
+     */
     resetMetrics(topic?: string): void;
     /** Gracefully disconnect producer, all consumers, and admin. */
     disconnect(drainTimeoutMs?: number): Promise<void>;
@@ -144,14 +295,65 @@ 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`.
@@ -188,15 +390,57 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * so Kafka can fence stale producers on restart without affecting other levels.
      */
     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.
+     */
     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();
     /** 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();
 }
 
@@ -226,4 +470,4 @@ declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     });
 }
 
-export { BatchMessageItem, BatchMeta, ClientId, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, SendOptions, TopicDescriptor, TopicMapConstraint, TransactionContext };
+export { BatchMessageItem, BatchMeta, BatchSendOptions, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext };