@drarzter/kafka-client 0.9.3 → 0.10.0

package/dist/client/types/lifecycle.interface.d.ts

@@ -0,0 +1,72 @@
+import type { ClientId, KafkaMetrics } from "./common";
+/** Lifecycle and observability methods of `IKafkaClient`. */
+export interface IKafkaLifecycle {
+    /**
+     * @example
+     * ```ts
+     * const id = kafka.getClientId(); // e.g. 'my-service'
+     * ```
+     */
+    getClientId(): ClientId;
+    /**
+     * Return a snapshot of internal event counters (retry / DLQ / dedup).
+     * - `getMetrics()` — aggregate across all topics.
+     * - `getMetrics(topic)` — counters for a specific topic only; returns all-zero
+     *   if no events have been observed for that topic yet.
+     *
+     * Counters accumulate since client creation or the last `resetMetrics()` call.
+     *
+     * @example
+     * ```ts
+     * const { processedCount, dlqCount, retryCount } = kafka.getMetrics();
+     * console.log(`Processed: ${processedCount}, DLQ: ${dlqCount}`);
+     * ```
+     */
+    getMetrics(topic?: string): Readonly<KafkaMetrics>;
+    /**
+     * Reset internal event counters to zero.
+     * - `resetMetrics()` — reset all topics.
+     * - `resetMetrics(topic)` — reset a single topic only.
+     *
+     * @example
+     * ```ts
+     * kafka.resetMetrics();
+     * kafka.resetMetrics('orders.created');
+     * ```
+     */
+    resetMetrics(topic?: string): void;
+    /**
+     * Connect the producer, recover the Lamport clock (when `clockRecovery` is
+     * configured), and start the lag-throttle poller (when `lagThrottle` is set).
+     * Must be called before any send. NestJS apps call this automatically inside
+     * `KafkaModule.register()` / `registerAsync()`.
+     *
+     * @example
+     * ```ts
+     * await kafka.connectProducer();
+     * ```
+     */
+    connectProducer(): Promise<void>;
+    /**
+     * Drain in-flight handlers, then disconnect all producers, consumers, and admin.
+     * @param drainTimeoutMs Max ms to wait for in-flight handlers (default 30 000).
+     *
+     * @example
+     * ```ts
+     * await kafka.disconnect();
+     * ```
+     */
+    disconnect(drainTimeoutMs?: number): Promise<void>;
+    /**
+     * Register SIGTERM / SIGINT signal handlers that drain in-flight messages before
+     * disconnecting. Call once after constructing the client in non-NestJS apps.
+     * NestJS apps get drain automatically via `onModuleDestroy` → `disconnect()`.
+     *
+     * @example
+     * ```ts
+     * kafka.enableGracefulShutdown(['SIGTERM', 'SIGINT'], 30_000);
+     * ```
+     */
+    enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
+}
+//# sourceMappingURL=lifecycle.interface.d.ts.map

package/dist/client/types/lifecycle.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.interface.d.ts","sourceRoot":"","sources":["../../../src/client/types/lifecycle.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,WAAW,IAAI,QAAQ,CAAC;IAExB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAEnD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;;OAQG;IACH,UAAU,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;;;;;OASG;IACH,sBAAsB,CACpB,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,EAC1B,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI,CAAC;CACT"}

package/dist/client/types/producer.interface.d.ts

@@ -0,0 +1,52 @@
+import type { TopicMapConstraint, MessageHeaders } from "./common";
+import type { SendOptions, BatchMessageItem, BatchSendOptions } from "./producer.types";
+import type { TransactionContext } from "./consumer.types";
+import type { TopicDescriptor } from "../message/topic";
+/** Producer methods of `IKafkaClient`. */
+export interface IKafkaProducer<T extends TopicMapConstraint<T>> {
+    /**
+     * @example
+     * ```ts
+     * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 });
+     * ```
+     */
+    sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    /**
+     * Send a null-value (tombstone) message to a topic.
+     * Tombstones are used with log-compacted topics to signal that a key's record
+     * should be removed during the next compaction cycle.
+     *
+     * Unlike `sendMessage`, tombstones carry no payload, no envelope headers, and
+     * skip schema validation. Only the partition `key` and optional custom `headers`
+     * are forwarded to Kafka.
+     *
+     * @example
+     * ```ts
+     * await kafka.sendTombstone('users.state', 'user-42');
+     * ```
+     */
+    sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.sendBatch('orders.created', [
+     *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+     *   { value: { orderId: '2', amount: 20 }, key: 'order-2' },
+     * ]);
+     * ```
+     */
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.transaction(async (tx) => {
+     *   await tx.send('orders.created',    { orderId: '123', amount: 99 });
+     *   await tx.send('inventory.reserved', { itemId: 'a',  qty: 1 });
+     * });
+     * ```
+     */
+    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=producer.interface.d.ts.map

package/dist/client/types/producer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.interface.d.ts","sourceRoot":"","sources":["../../../src/client/types/producer.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,0CAA0C;AAC1C,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,WAAW,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EAC1E,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,aAAa,CACX,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,EACzB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,SAAS,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EACxE,UAAU,EAAE,CAAC,EACb,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC9C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E"}

package/dist/client/types/producer.types.d.ts

@@ -0,0 +1,90 @@
+import type { CompressionType, MessageHeaders } from "./common";
+/**
+ * Options for sending a single message.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 }, {
+ *   key: 'order-123',
+ *   headers: { 'x-source': 'checkout-service' },
+ *   compression: 'snappy',
+ * });
+ * ```
+ */
+export interface SendOptions {
+    /** Partition key for message routing. */
+    key?: string;
+    /** Custom headers attached to the message (merged with auto-generated envelope headers). */
+    headers?: MessageHeaders;
+    /** Override the auto-propagated correlation ID (default: inherited from ALS context or new UUID). */
+    correlationId?: string;
+    /** Schema version for the payload. Default: `1`. */
+    schemaVersion?: number;
+    /** Override the auto-generated event ID (UUID v4). */
+    eventId?: string;
+    /**
+     * Compression codec for this message.
+     * Applied at the producer record level — all messages in a single `send` call share the same codec.
+     * Default: `'none'`.
+     */
+    compression?: CompressionType;
+    /**
+     * Delay delivery by at least this many milliseconds.
+     *
+     * The message is produced to the `<topic>.delayed` staging topic with
+     * `x-delayed-until` / `x-delayed-target` headers instead of the target
+     * topic. A relay started via `startDelayedRelay()` holds it until the
+     * deadline, then forwards it to the target topic.
+     *
+     * Delivery time is a lower bound (at-least semantics) — actual delivery
+     * depends on the relay being up and partition-level head-of-line waits.
+     */
+    deliverAfterMs?: number;
+}
+/**
+ * Shape of each item in a `sendBatch` call.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('orders.created', [
+ *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+ *   { value: { orderId: '2', amount: 20 }, key: 'order-2', headers: { 'x-priority': 'high' } },
+ * ]);
+ * ```
+ */
+export interface BatchMessageItem<V> {
+    value: V;
+    /**
+     * Kafka partition key for this message.
+     * Kafka hashes the key to deterministically route the message to a partition.
+     * Messages with the same key always land on the same partition — use this to
+     * guarantee ordering per entity (e.g. `userId`, `orderId`).
+     */
+    key?: string;
+    headers?: MessageHeaders;
+    correlationId?: string;
+    schemaVersion?: number;
+    eventId?: string;
+}
+/**
+ * Options for a `sendBatch` call (applies to all messages in the batch).
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('metrics', messages, { compression: 'zstd' });
+ * ```
+ */
+export interface BatchSendOptions {
+    /**
+     * Compression codec for this batch.
+     * Applied at the producer record level — all messages in the batch share the same codec.
+     * Default: `'none'`.
+     */
+    compression?: CompressionType;
+    /**
+     * Delay delivery of the whole batch by at least this many milliseconds.
+     * See `SendOptions.deliverAfterMs` for semantics.
+     */
+    deliverAfterMs?: number;
+}
+//# sourceMappingURL=producer.types.d.ts.map

package/dist/client/types/producer.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.types.d.ts","sourceRoot":"","sources":["../../../src/client/types/producer.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,CAAC;IACT;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/client/types.d.ts

@@ -0,0 +1,8 @@
+export * from "./types/common";
+export * from "./types/producer.types";
+export * from "./types/dedup.types";
+export * from "./types/consumer.types";
+export * from "./types/admin.types";
+export * from "./types/config.types";
+export * from "./types/client";
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAEA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/core.d.ts

@@ -1,314 +1,10 @@
-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-CBBUDDtu.js';
-export { C as CheckpointEntry, v as IKafkaAdmin, w as IKafkaConsumer, x as IKafkaLifecycle, y as IKafkaProducer, A as TopicPartitionInfo } from './client-CBBUDDtu.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.
- * Wraps @confluentinc/kafka-javascript (librdkafka) with JSON serialization,
- * retries, DLQ, transactions, and interceptors.
- *
- * @typeParam T - Topic-to-message type mapping for compile-time safety.
- */
-declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClient<T> {
-    readonly clientId: ClientId;
-    private readonly ctx;
-    /**
-     * Create a new KafkaClient.
-     * @param clientId Unique client identifier (used in Kafka metadata and logs).
-     * @param groupId Default consumer group ID for this client.
-     * @param brokers Array of broker addresses, e.g. `['localhost:9092']`.
-     * @param options Optional client-wide configuration.
-     * @example
-     * ```ts
-     * const kafka = new KafkaClient('my-service', 'my-service-group', ['localhost:9092'], {
-     *   lagThrottle: { maxLag: 10_000 },
-     *   onMessageLost: (ctx) => logger.error('Message lost', ctx),
-     * });
-     * await kafka.connectProducer();
-     * ```
-     */
-    constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
-    /** @inheritDoc */
-    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>;
-    /** @inheritDoc */
-    sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
-    /** @inheritDoc */
-    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>;
-    /** @inheritDoc */
-    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
-    /** @inheritDoc */
-    connectProducer(): Promise<void>;
-    /** @internal */
-    disconnectProducer(): Promise<void>;
-    /** @inheritDoc */
-    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>;
-    /** @inheritDoc */
-    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>;
-    /** @inheritDoc */
-    consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
-    /** @inheritDoc */
-    startWindowConsumer<K extends keyof T & string>(topic: K, handler: (envelopes: EventEnvelope<T[K]>[], meta: WindowMeta) => Promise<void>, options: WindowConsumerOptions<T>): Promise<ConsumerHandle>;
-    /** @inheritDoc */
-    startRoutedConsumer<K extends Array<keyof T>>(topics: K, routing: RoutingOptions<T[K[number]]>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
-    /** @inheritDoc */
-    startTransactionalConsumer<K extends Array<keyof T>>(topics: K, handler: (envelope: EventEnvelope<T[K[number]]>, tx: TransactionalHandlerContext<T>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
-    /** @inheritDoc */
-    stopConsumer(groupId?: string): Promise<void>;
-    /** @inheritDoc */
-    pauseConsumer(groupId: string | undefined, assignments: Array<{
-        topic: string;
-        partitions: number[];
-    }>): void;
-    /** @inheritDoc */
-    resumeConsumer(groupId: string | undefined, assignments: Array<{
-        topic: string;
-        partitions: number[];
-    }>): void;
-    /** @inheritDoc */
-    replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
-        replayed: number;
-        skipped: number;
-    }>;
-    /** @inheritDoc */
-    readSnapshot<K extends keyof T & string>(topic: K, options?: ReadSnapshotOptions): Promise<Map<string, EventEnvelope<T[K]>>>;
-    /** @inheritDoc */
-    checkpointOffsets(groupId: string | undefined, checkpointTopic: string): Promise<CheckpointResult>;
-    /** @inheritDoc */
-    restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
-    /** @inheritDoc */
-    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
-    /** @inheritDoc */
-    seekToOffset(groupId: string | undefined, assignments: Array<{
-        topic: string;
-        partition: number;
-        offset: string;
-    }>): Promise<void>;
-    /** @inheritDoc */
-    seekToTimestamp(groupId: string | undefined, assignments: Array<{
-        topic: string;
-        partition: number;
-        timestamp: number;
-    }>): Promise<void>;
-    /** @inheritDoc */
-    getConsumerLag(groupId?: string): Promise<Array<{
-        topic: string;
-        partition: number;
-        lag: number;
-    }>>;
-    /** @inheritDoc */
-    checkStatus(): Promise<KafkaHealthResult>;
-    /** @inheritDoc */
-    listConsumerGroups(): Promise<ConsumerGroupSummary[]>;
-    /** @inheritDoc */
-    describeTopics(topics?: string[]): Promise<TopicDescription[]>;
-    /** @inheritDoc */
-    deleteRecords(topic: string, partitions: Array<{
-        partition: number;
-        offset: string;
-    }>): Promise<void>;
-    /** @inheritDoc */
-    getCircuitState(topic: string, partition: number, groupId?: string): {
-        status: "closed" | "open" | "half-open";
-        failures: number;
-        windowSize: number;
-    } | undefined;
-    /** @inheritDoc */
-    getMetrics(topic?: string): Readonly<KafkaMetrics>;
-    /** @inheritDoc */
-    resetMetrics(topic?: string): void;
-    getClientId(): ClientId;
-    /** @inheritDoc */
-    disconnect(drainTimeoutMs?: number): Promise<void>;
-    /** NestJS lifecycle hook — called automatically on module teardown. */
-    onModuleDestroy(): Promise<void>;
-    /** @inheritDoc */
-    enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
-}
-
-/**
- * Error thrown when a consumer message handler fails.
- * @example
- * ```ts
- * await kafka.startConsumer(['orders'], async (envelope) => {
- *   try { await process(envelope); }
- *   catch (err) {
- *     if (err instanceof KafkaProcessingError) {
- *       console.error(err.topic, err.originalMessage);
- *     }
- *   }
- * });
- * ```
- */
-declare class KafkaProcessingError extends Error {
-    readonly topic: string;
-    readonly originalMessage: unknown;
-    readonly cause?: Error;
-    constructor(message: string, topic: string, originalMessage: unknown, options?: {
-        cause?: Error;
-    });
-}
-/**
- * Error thrown when schema validation fails on send or consume.
- * @example
- * ```ts
- * try { await kafka.sendMessage('orders.created', invalidPayload); }
- * catch (err) {
- *   if (err instanceof KafkaValidationError) {
- *     console.error('Validation failed for topic:', err.topic);
- *   }
- * }
- * ```
- */
-declare class KafkaValidationError extends Error {
-    readonly topic: string;
-    readonly originalMessage: unknown;
-    readonly cause?: Error;
-    constructor(topic: string, originalMessage: unknown, options?: {
-        cause?: Error;
-    });
-}
-/**
- * Error thrown when all retry attempts are exhausted for a message.
- * @example
- * ```ts
- * const kafka = new KafkaClient(config, groupId, { onMessageLost: (ctx) => {
- *   if (ctx.error instanceof KafkaRetryExhaustedError) {
- *     console.error(`Exhausted after ${ctx.error.attempts} attempts on ${ctx.error.topic}`);
- *   }
- * }});
- * ```
- */
-declare class KafkaRetryExhaustedError extends KafkaProcessingError {
-    readonly attempts: number;
-    constructor(topic: string, originalMessage: unknown, attempts: number, options?: {
-        cause?: Error;
-    });
-}
-
-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 };
+export * from "./client/kafka.client";
+export * from "./client/message/topic";
+export * from "./client/message/versioned-schema";
+export * from "./client/message/schema-registry";
+export * from "./client/errors";
+export * from "./client/message/envelope";
+export * from "./client/outbox";
+export * from "./client/security";
+export * from "./client/config";
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}