@drarzter/kafka-client 0.9.2 → 0.9.4

package/dist/core.d.mts

@@ -1,5 +1,128 @@
-import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, s as KafkaClientOptions, u as TopicDescriptor, a7 as SendOptions, a0 as MessageHeaders, B as BatchMessageItem, x as BatchSendOptions, ad as TransactionContext, Q as EventEnvelope, t as ConsumerOptions, J as ConsumerHandle, w as BatchMeta, ah as WindowMeta, ag as WindowConsumerOptions, a5 as RoutingOptions, ae as TransactionalHandlerContext, O as DlqReplayOptions, a2 as ReadSnapshotOptions, D as CheckpointResult, a3 as RestoreCheckpointOptions, A as CheckpointRestoreResult, v as KafkaHealthResult, H as ConsumerGroupSummary, aa as TopicDescription, $ as KafkaMetrics } from './types-4XNxkici.mjs';
-export { y as BeforeConsumeResult, z as CheckpointEntry, E as CircuitBreakerOptions, F as CompressionType, L as ConsumerInterceptor, M as DeduplicationOptions, N as DlqReason, P as EnvelopeHeaderOptions, R as HEADER_CORRELATION_ID, U as HEADER_EVENT_ID, V as HEADER_LAMPORT_CLOCK, W as HEADER_SCHEMA_VERSION, X as HEADER_TIMESTAMP, Y as HEADER_TRACEPARENT, Z as InferSchema, K as KafkaInstrumentation, _ as KafkaLogger, a1 as MessageLostContext, a4 as RetryOptions, S as SchemaLike, a6 as SchemaParseContext, a8 as SubscribeRetryOptions, a9 as TTopicMessageMap, ab as TopicPartitionInfo, ac as TopicsFrom, af as TtlExpiredContext, ai as buildEnvelopeHeaders, aj as decodeHeaders, ak as extractEnvelope, al as getEnvelopeContext, am as runWithEnvelopeContext, an as topic } from './types-4XNxkici.mjs';
+import { q as KafkaLogger, K as KafkaInstrumentation, s as MessageLostContext, F as TtlExpiredContext, T as TopicMapConstraint, C as ClientId, G as GroupId, b as TopicDescriptor, v as SendOptions, M as MessageHeaders, B as BatchMessageItem, d as BatchSendOptions, z as TransactionContext, k as EventEnvelope, a as ConsumerOptions, h as ConsumerHandle, c as BatchMeta, J as WindowMeta, W as WindowConsumerOptions, t as RoutingOptions, A as TransactionalHandlerContext, r as KafkaMetrics } from './consumer.types-fFCag3VJ.mjs';
+export { e as BeforeConsumeResult, f as CircuitBreakerOptions, g as CompressionType, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, l as HEADER_EVENT_ID, m as HEADER_LAMPORT_CLOCK, n as HEADER_SCHEMA_VERSION, o as HEADER_TIMESTAMP, p as HEADER_TRACEPARENT, I as InferSchema, R as RetryOptions, S as SchemaLike, u as SchemaParseContext, w as SubscribeRetryOptions, x as TTopicMessageMap, y as TopicsFrom, L as buildEnvelopeHeaders, N as decodeHeaders, O as extractEnvelope, P as getEnvelopeContext, Q as runWithEnvelopeContext, U as topic } from './consumer.types-fFCag3VJ.mjs';
+import { K as KafkaTransport, I as IKafkaClient, D as DlqReplayOptions, R as ReadSnapshotOptions, t as CheckpointResult, z as RestoreCheckpointOptions, s as CheckpointRestoreResult, r as KafkaHealthResult, u as ConsumerGroupSummary, T as TopicDescription } from './client-1irhGEu0.mjs';
+export { C as CheckpointEntry, v as IKafkaAdmin, w as IKafkaConsumer, x as IKafkaLifecycle, y as IKafkaProducer, A as TopicPartitionInfo } from './client-1irhGEu0.mjs';
+
+/**
+ * Options for `KafkaClient` constructor.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(kafkaConfig, 'my-service', {
+ *   transactionalId: `my-service-tx-${replicaIndex}`,
+ *   lagThrottle: { maxLag: 10_000, pollIntervalMs: 3_000 },
+ *   clockRecovery: { topics: ['orders.created'] },
+ *   onMessageLost: (ctx) => alerting.fire('kafka.message-lost', ctx),
+ *   instrumentation: [otelInstrumentation()],
+ * });
+ * ```
+ */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
+    logger?: KafkaLogger;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
+    /**
+     * Override the transactional producer ID used by `transaction()`.
+     * Defaults to `${clientId}-tx`.
+     *
+     * The transactional ID must be **unique per producer instance** across the
+     * entire Kafka cluster. Two `KafkaClient` instances with the same ID will
+     * cause Kafka to fence one of the producers — the fenced producer will fail
+     * on the next `transaction()` call. Set a distinct value per replica when
+     * running multiple instances of the same service.
+     */
+    transactionalId?: string;
+    /**
+     * Called when a message is dropped without being sent to a DLQ.
+     * Fires when the handler throws after all retries, or schema validation fails — and `dlq` is not enabled.
+     * Use this to alert, log to external systems, or trigger fallback logic.
+     */
+    onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
+     * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
+     * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
+     *
+     * **Client-wide fallback**: if `ConsumerOptions.onTtlExpired` is set on the consumer,
+     * it takes precedence over this client-level callback.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
+    /**
+     * Called whenever a consumer group rebalance occurs.
+     * - `'assign'` — new partitions were granted to this instance.
+     * - `'revoke'` — partitions were taken away (e.g. another consumer joined).
+     *
+     * Applied to every consumer created by this client. If you need per-consumer
+     * rebalance handling, use separate `KafkaClient` instances.
+     */
+    onRebalance?: (type: "assign" | "revoke", partitions: Array<{
+        topic: string;
+        partition: number;
+    }>) => void;
+    /**
+     * Recover the Lamport clock from the last message in the given topics on `connectProducer()`.
+     *
+     * On startup the producer creates a short-lived consumer, seeks each partition to its
+     * last message (`highWatermark − 1`), reads the `x-lamport-clock` header, then
+     * initialises `_lamportClock` to the maximum value found. This guarantees monotonic
+     * clock values across restarts without an external store.
+     *
+     * Topics that do not exist or are empty are silently skipped.
+     */
+    clockRecovery?: {
+        /** Topic names to scan for the highest Lamport clock. */
+        topics: string[];
+    };
+    /**
+     * Delay `sendMessage` / `sendBatch` / `sendTombstone` when the observed lag of a
+     * consumer group exceeds `maxLag`. Resumes immediately when lag drops below the threshold.
+     *
+     * Lag is polled via `getConsumerLag()` every `pollIntervalMs` in the background;
+     * no admin call is made on each individual send.
+     *
+     * When `maxWaitMs` is exceeded the send is unblocked with a warning — this is
+     * best-effort throttling, not hard back-pressure.
+     *
+     * Requires `connectProducer()` to have been called to start the polling loop.
+     */
+    lagThrottle?: {
+        /** Consumer group whose lag is monitored. Defaults to the client's default group. */
+        groupId?: string;
+        /** Lag threshold (number of messages) above which sends are delayed. */
+        maxLag: number;
+        /** How often to poll `getConsumerLag()`. Default: `5000` ms. */
+        pollIntervalMs?: number;
+        /**
+         * Maximum time (ms) a send will wait while throttled before proceeding anyway.
+         * Default: `30_000` ms.
+         */
+        maxWaitMs?: number;
+    };
+    /**
+     * Custom transport implementation.
+     *
+     * By default `KafkaClient` uses `ConfluentTransport` which wraps
+     * `@confluentinc/kafka-javascript` (librdkafka). Inject a different
+     * `KafkaTransport` to target an alternative broker library, or to supply
+     * a deterministic fake in unit tests without mocking the confluentinc module.
+     *
+     * @example
+     * ```ts
+     * // In tests — no jest.mock() needed
+     * const kafka = new KafkaClient('svc', 'grp', [], {
+     *   transport: new FakeTransport(),
+     * });
+     * ```
+     */
+    transport?: KafkaTransport;
+}
 
 /**
  * Type-safe Kafka client.
@@ -188,4 +311,4 @@ declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     });
 }
 
-export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, WindowConsumerOptions, WindowMeta };
+export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, type KafkaClientOptions, KafkaHealthResult, KafkaInstrumentation, KafkaLogger, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, MessageLostContext, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, TtlExpiredContext, WindowConsumerOptions, WindowMeta };

package/dist/core.d.ts

@@ -1,5 +1,128 @@
-import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, s as KafkaClientOptions, u as TopicDescriptor, a7 as SendOptions, a0 as MessageHeaders, B as BatchMessageItem, x as BatchSendOptions, ad as TransactionContext, Q as EventEnvelope, t as ConsumerOptions, J as ConsumerHandle, w as BatchMeta, ah as WindowMeta, ag as WindowConsumerOptions, a5 as RoutingOptions, ae as TransactionalHandlerContext, O as DlqReplayOptions, a2 as ReadSnapshotOptions, D as CheckpointResult, a3 as RestoreCheckpointOptions, A as CheckpointRestoreResult, v as KafkaHealthResult, H as ConsumerGroupSummary, aa as TopicDescription, $ as KafkaMetrics } from './types-4XNxkici.js';
-export { y as BeforeConsumeResult, z as CheckpointEntry, E as CircuitBreakerOptions, F as CompressionType, L as ConsumerInterceptor, M as DeduplicationOptions, N as DlqReason, P as EnvelopeHeaderOptions, R as HEADER_CORRELATION_ID, U as HEADER_EVENT_ID, V as HEADER_LAMPORT_CLOCK, W as HEADER_SCHEMA_VERSION, X as HEADER_TIMESTAMP, Y as HEADER_TRACEPARENT, Z as InferSchema, K as KafkaInstrumentation, _ as KafkaLogger, a1 as MessageLostContext, a4 as RetryOptions, S as SchemaLike, a6 as SchemaParseContext, a8 as SubscribeRetryOptions, a9 as TTopicMessageMap, ab as TopicPartitionInfo, ac as TopicsFrom, af as TtlExpiredContext, ai as buildEnvelopeHeaders, aj as decodeHeaders, ak as extractEnvelope, al as getEnvelopeContext, am as runWithEnvelopeContext, an as topic } from './types-4XNxkici.js';
+import { q as KafkaLogger, K as KafkaInstrumentation, s as MessageLostContext, F as TtlExpiredContext, T as TopicMapConstraint, C as ClientId, G as GroupId, b as TopicDescriptor, v as SendOptions, M as MessageHeaders, B as BatchMessageItem, d as BatchSendOptions, z as TransactionContext, k as EventEnvelope, a as ConsumerOptions, h as ConsumerHandle, c as BatchMeta, J as WindowMeta, W as WindowConsumerOptions, t as RoutingOptions, A as TransactionalHandlerContext, r as KafkaMetrics } from './consumer.types-fFCag3VJ.js';
+export { e as BeforeConsumeResult, f as CircuitBreakerOptions, g as CompressionType, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, l as HEADER_EVENT_ID, m as HEADER_LAMPORT_CLOCK, n as HEADER_SCHEMA_VERSION, o as HEADER_TIMESTAMP, p as HEADER_TRACEPARENT, I as InferSchema, R as RetryOptions, S as SchemaLike, u as SchemaParseContext, w as SubscribeRetryOptions, x as TTopicMessageMap, y as TopicsFrom, L as buildEnvelopeHeaders, N as decodeHeaders, O as extractEnvelope, P as getEnvelopeContext, Q as runWithEnvelopeContext, U as topic } from './consumer.types-fFCag3VJ.js';
+import { K as KafkaTransport, I as IKafkaClient, D as DlqReplayOptions, R as ReadSnapshotOptions, t as CheckpointResult, z as RestoreCheckpointOptions, s as CheckpointRestoreResult, r as KafkaHealthResult, u as ConsumerGroupSummary, T as TopicDescription } from './client-BpFjkHhr.js';
+export { C as CheckpointEntry, v as IKafkaAdmin, w as IKafkaConsumer, x as IKafkaLifecycle, y as IKafkaProducer, A as TopicPartitionInfo } from './client-BpFjkHhr.js';
+
+/**
+ * Options for `KafkaClient` constructor.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(kafkaConfig, 'my-service', {
+ *   transactionalId: `my-service-tx-${replicaIndex}`,
+ *   lagThrottle: { maxLag: 10_000, pollIntervalMs: 3_000 },
+ *   clockRecovery: { topics: ['orders.created'] },
+ *   onMessageLost: (ctx) => alerting.fire('kafka.message-lost', ctx),
+ *   instrumentation: [otelInstrumentation()],
+ * });
+ * ```
+ */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
+    logger?: KafkaLogger;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
+    /**
+     * Override the transactional producer ID used by `transaction()`.
+     * Defaults to `${clientId}-tx`.
+     *
+     * The transactional ID must be **unique per producer instance** across the
+     * entire Kafka cluster. Two `KafkaClient` instances with the same ID will
+     * cause Kafka to fence one of the producers — the fenced producer will fail
+     * on the next `transaction()` call. Set a distinct value per replica when
+     * running multiple instances of the same service.
+     */
+    transactionalId?: string;
+    /**
+     * Called when a message is dropped without being sent to a DLQ.
+     * Fires when the handler throws after all retries, or schema validation fails — and `dlq` is not enabled.
+     * Use this to alert, log to external systems, or trigger fallback logic.
+     */
+    onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
+     * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
+     * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
+     *
+     * **Client-wide fallback**: if `ConsumerOptions.onTtlExpired` is set on the consumer,
+     * it takes precedence over this client-level callback.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
+    /**
+     * Called whenever a consumer group rebalance occurs.
+     * - `'assign'` — new partitions were granted to this instance.
+     * - `'revoke'` — partitions were taken away (e.g. another consumer joined).
+     *
+     * Applied to every consumer created by this client. If you need per-consumer
+     * rebalance handling, use separate `KafkaClient` instances.
+     */
+    onRebalance?: (type: "assign" | "revoke", partitions: Array<{
+        topic: string;
+        partition: number;
+    }>) => void;
+    /**
+     * Recover the Lamport clock from the last message in the given topics on `connectProducer()`.
+     *
+     * On startup the producer creates a short-lived consumer, seeks each partition to its
+     * last message (`highWatermark − 1`), reads the `x-lamport-clock` header, then
+     * initialises `_lamportClock` to the maximum value found. This guarantees monotonic
+     * clock values across restarts without an external store.
+     *
+     * Topics that do not exist or are empty are silently skipped.
+     */
+    clockRecovery?: {
+        /** Topic names to scan for the highest Lamport clock. */
+        topics: string[];
+    };
+    /**
+     * Delay `sendMessage` / `sendBatch` / `sendTombstone` when the observed lag of a
+     * consumer group exceeds `maxLag`. Resumes immediately when lag drops below the threshold.
+     *
+     * Lag is polled via `getConsumerLag()` every `pollIntervalMs` in the background;
+     * no admin call is made on each individual send.
+     *
+     * When `maxWaitMs` is exceeded the send is unblocked with a warning — this is
+     * best-effort throttling, not hard back-pressure.
+     *
+     * Requires `connectProducer()` to have been called to start the polling loop.
+     */
+    lagThrottle?: {
+        /** Consumer group whose lag is monitored. Defaults to the client's default group. */
+        groupId?: string;
+        /** Lag threshold (number of messages) above which sends are delayed. */
+        maxLag: number;
+        /** How often to poll `getConsumerLag()`. Default: `5000` ms. */
+        pollIntervalMs?: number;
+        /**
+         * Maximum time (ms) a send will wait while throttled before proceeding anyway.
+         * Default: `30_000` ms.
+         */
+        maxWaitMs?: number;
+    };
+    /**
+     * Custom transport implementation.
+     *
+     * By default `KafkaClient` uses `ConfluentTransport` which wraps
+     * `@confluentinc/kafka-javascript` (librdkafka). Inject a different
+     * `KafkaTransport` to target an alternative broker library, or to supply
+     * a deterministic fake in unit tests without mocking the confluentinc module.
+     *
+     * @example
+     * ```ts
+     * // In tests — no jest.mock() needed
+     * const kafka = new KafkaClient('svc', 'grp', [], {
+     *   transport: new FakeTransport(),
+     * });
+     * ```
+     */
+    transport?: KafkaTransport;
+}
 
 /**
  * Type-safe Kafka client.
@@ -188,4 +311,4 @@ declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     });
 }
 
-export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, WindowConsumerOptions, WindowMeta };
+export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, type KafkaClientOptions, KafkaHealthResult, KafkaInstrumentation, KafkaLogger, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, MessageLostContext, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, TtlExpiredContext, WindowConsumerOptions, WindowMeta };

package/dist/core.js

@@ -647,8 +647,8 @@ var AdminOps = class {
     return result.topics.map((t) => ({
       name: t.name,
       partitions: t.partitions.map((p) => ({
-        partition: p.partitionId ?? p.partition,
-        leader: p.leader,
+        partition: p.partitionId ?? p.partition ?? 0,
+        leader: p.leader ?? 0,
         replicas: (p.replicas ?? []).map(
           (r) => typeof r === "number" ? r : r.nodeId
         ),
@@ -1164,7 +1164,7 @@ async function replayDlqTopic(topic2, deps, options = {}) {
   return { replayed, skipped };
 }
 
-// src/client/kafka.client/infra/metrics-manager.ts
+// src/client/kafka.client/infra/metrics.manager.ts
 var MetricsManager = class {
   constructor(deps) {
     this.deps = deps;
@@ -1257,7 +1257,7 @@ var MetricsManager = class {
   }
 };
 
-// src/client/kafka.client/infra/inflight-tracker.ts
+// src/client/kafka.client/infra/inflight.tracker.ts
 var InFlightTracker = class {
   constructor(warn) {
     this.warn = warn;
@@ -1304,7 +1304,7 @@ var InFlightTracker = class {
   }
 };
 
-// src/client/kafka.client/infra/circuit-breaker.ts
+// src/client/kafka.client/infra/circuit-breaker.manager.ts
 var CircuitBreakerManager = class {
   constructor(deps) {
     this.deps = deps;