@drarzter/kafka-client 0.7.1 → 0.7.3

package/dist/core.mjs

@@ -15,7 +15,7 @@ import {
   getEnvelopeContext,
   runWithEnvelopeContext,
   topic
-} from "./chunk-AMEGMOZH.mjs";
+} from "./chunk-XP7LLRGQ.mjs";
 import "./chunk-EQQGB2QZ.mjs";
 export {
   HEADER_CORRELATION_ID,

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { KafkaClient, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.mjs';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-BEIGjmV6.mjs';
-export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as CircuitBreakerOptions, h as ConsumerHandle, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, k as DlqReplayOptions, E as EnvelopeHeaderOptions, l as EventEnvelope, 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, s as KafkaLogger, t as KafkaMetrics, M as MessageHeaders, u as MessageLostContext, R as RetryOptions, v as SchemaParseContext, w as SendOptions, x as SubscribeRetryOptions, y as TTopicMessageMap, z as TopicsFrom, A as TransactionContext, F as TtlExpiredContext, J as buildEnvelopeHeaders, L as decodeHeaders, N as extractEnvelope, O as getEnvelopeContext, P as runWithEnvelopeContext, Q as topic } from './types-BEIGjmV6.mjs';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-4qWrf2aJ.mjs';
+export { B as BatchMessageItem, e as BatchMeta, f as BatchSendOptions, g as BeforeConsumeResult, h as CircuitBreakerOptions, i as CompressionType, j as ConsumerGroupSummary, k as ConsumerHandle, l as ConsumerInterceptor, D as DeduplicationOptions, m as DlqReason, n as DlqReplayOptions, E as EnvelopeHeaderOptions, o as EventEnvelope, 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, v as KafkaLogger, w as KafkaMetrics, M as MessageHeaders, x as MessageLostContext, R as RetryOptions, y as SchemaParseContext, z as SendOptions, A as SubscribeRetryOptions, F as TTopicMessageMap, J as TopicDescription, L as TopicPartitionInfo, N as TopicsFrom, O as TransactionContext, P as TtlExpiredContext, Q as buildEnvelopeHeaders, U as decodeHeaders, V as extractEnvelope, W as getEnvelopeContext, X as runWithEnvelopeContext, Y as topic } from './types-4qWrf2aJ.mjs';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
@@ -55,20 +55,47 @@ declare const KAFKA_CLIENT = "KAFKA_CLIENT";
 /** Returns the DI token for a named (or default) Kafka client instance. */
 declare const getKafkaClientToken: (name?: string) => string;
 
+/** Reflect metadata key used to store `@SubscribeTo` entries on a class constructor. */
 declare const KAFKA_SUBSCRIBER_METADATA = "KAFKA_SUBSCRIBER_METADATA";
+/** Internal shape stored per `@SubscribeTo()` decoration on a class. */
 interface KafkaSubscriberMetadata {
+    /** Resolved topic name strings (descriptors are unwrapped to their `__topic` string). */
     topics: string[];
+    /** Per-topic schema validators extracted from `TopicDescriptor` objects (if any). */
     schemas?: Map<string, SchemaLike>;
+    /** Additional consumer options forwarded to `startConsumer` / `startBatchConsumer`. */
     options?: ConsumerOptions;
+    /** Named client identifier — resolves to `KAFKA_CLIENT_<clientName>` in the DI container. */
     clientName?: string;
+    /** When `true`, routes to `startBatchConsumer` instead of `startConsumer`. */
     batch?: boolean;
+    /** Name of the decorated method on the provider class. */
     methodName?: string | symbol;
 }
 /** Inject a `KafkaClient` instance. Pass a name to target a specific named client. */
 declare const InjectKafkaClient: (name?: string) => ParameterDecorator;
 /**
- * Decorator that auto-subscribes a method to Kafka topics on module init.
- * The decorated method receives `(message, topic)` for each consumed message.
+ * Method decorator that auto-subscribes the decorated method to one or more Kafka topics
+ * when the NestJS module initialises.
+ *
+ * The decorated method receives a fully-decoded `EventEnvelope` for each message
+ * (or an array of envelopes + `BatchMeta` when `batch: true`).
+ *
+ * @param topics One or more topic names or `TopicDescriptor` objects. Schemas embedded in
+ *   descriptors are automatically extracted and forwarded to the consumer.
+ * @param options Consumer and routing options:
+ *   - All `ConsumerOptions` fields (`groupId`, `retry`, `dlq`, `fromBeginning`, …)
+ *   - `clientName` — target a named `KafkaClient` (resolves `KAFKA_CLIENT_<name>` from the DI container)
+ *   - `batch` — use `startBatchConsumer` instead of `startConsumer`
+ *
+ * @example
+ * ```ts
+ * @SubscribeTo('orders.created', { groupId: 'orders-svc', retry: { maxRetries: 3 } })
+ * async handleOrder(envelope: EventEnvelope<Order>) { ... }
+ *
+ * @SubscribeTo(OrdersTopic, { batch: true })
+ * async handleBatch(envelopes: EventEnvelope<Order>[], meta: BatchMeta) { ... }
+ * ```
  */
 declare const SubscribeTo: (topics: string | string[] | TopicDescriptor | TopicDescriptor[] | (string | TopicDescriptor)[], options?: ConsumerOptions & {
     clientName?: string;
@@ -81,6 +108,12 @@ declare class KafkaExplorer implements OnModuleInit {
     private readonly moduleRef;
     private readonly logger;
     constructor(discoveryService: DiscoveryService, moduleRef: ModuleRef);
+    /**
+     * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated
+     * method to its Kafka client via `startConsumer` or `startBatchConsumer`.
+     *
+     * Called automatically by the NestJS lifecycle — do not invoke manually.
+     */
     onModuleInit(): Promise<void>;
 }
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { KafkaClient, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.js';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-BEIGjmV6.js';
-export { B as BatchMessageItem, e as BatchMeta, f as BeforeConsumeResult, g as CircuitBreakerOptions, h as ConsumerHandle, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, k as DlqReplayOptions, E as EnvelopeHeaderOptions, l as EventEnvelope, 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, s as KafkaLogger, t as KafkaMetrics, M as MessageHeaders, u as MessageLostContext, R as RetryOptions, v as SchemaParseContext, w as SendOptions, x as SubscribeRetryOptions, y as TTopicMessageMap, z as TopicsFrom, A as TransactionContext, F as TtlExpiredContext, J as buildEnvelopeHeaders, L as decodeHeaders, N as extractEnvelope, O as getEnvelopeContext, P as runWithEnvelopeContext, Q as topic } from './types-BEIGjmV6.js';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, a as KafkaClientOptions, S as SchemaLike, b as ConsumerOptions, c as TopicDescriptor, I as IKafkaClient, d as KafkaHealthResult } from './types-4qWrf2aJ.js';
+export { B as BatchMessageItem, e as BatchMeta, f as BatchSendOptions, g as BeforeConsumeResult, h as CircuitBreakerOptions, i as CompressionType, j as ConsumerGroupSummary, k as ConsumerHandle, l as ConsumerInterceptor, D as DeduplicationOptions, m as DlqReason, n as DlqReplayOptions, E as EnvelopeHeaderOptions, o as EventEnvelope, 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, v as KafkaLogger, w as KafkaMetrics, M as MessageHeaders, x as MessageLostContext, R as RetryOptions, y as SchemaParseContext, z as SendOptions, A as SubscribeRetryOptions, F as TTopicMessageMap, J as TopicDescription, L as TopicPartitionInfo, N as TopicsFrom, O as TransactionContext, 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';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
@@ -55,20 +55,47 @@ declare const KAFKA_CLIENT = "KAFKA_CLIENT";
 /** Returns the DI token for a named (or default) Kafka client instance. */
 declare const getKafkaClientToken: (name?: string) => string;
 
+/** Reflect metadata key used to store `@SubscribeTo` entries on a class constructor. */
 declare const KAFKA_SUBSCRIBER_METADATA = "KAFKA_SUBSCRIBER_METADATA";
+/** Internal shape stored per `@SubscribeTo()` decoration on a class. */
 interface KafkaSubscriberMetadata {
+    /** Resolved topic name strings (descriptors are unwrapped to their `__topic` string). */
     topics: string[];
+    /** Per-topic schema validators extracted from `TopicDescriptor` objects (if any). */
     schemas?: Map<string, SchemaLike>;
+    /** Additional consumer options forwarded to `startConsumer` / `startBatchConsumer`. */
     options?: ConsumerOptions;
+    /** Named client identifier — resolves to `KAFKA_CLIENT_<clientName>` in the DI container. */
     clientName?: string;
+    /** When `true`, routes to `startBatchConsumer` instead of `startConsumer`. */
     batch?: boolean;
+    /** Name of the decorated method on the provider class. */
     methodName?: string | symbol;
 }
 /** Inject a `KafkaClient` instance. Pass a name to target a specific named client. */
 declare const InjectKafkaClient: (name?: string) => ParameterDecorator;
 /**
- * Decorator that auto-subscribes a method to Kafka topics on module init.
- * The decorated method receives `(message, topic)` for each consumed message.
+ * Method decorator that auto-subscribes the decorated method to one or more Kafka topics
+ * when the NestJS module initialises.
+ *
+ * The decorated method receives a fully-decoded `EventEnvelope` for each message
+ * (or an array of envelopes + `BatchMeta` when `batch: true`).
+ *
+ * @param topics One or more topic names or `TopicDescriptor` objects. Schemas embedded in
+ *   descriptors are automatically extracted and forwarded to the consumer.
+ * @param options Consumer and routing options:
+ *   - All `ConsumerOptions` fields (`groupId`, `retry`, `dlq`, `fromBeginning`, …)
+ *   - `clientName` — target a named `KafkaClient` (resolves `KAFKA_CLIENT_<name>` from the DI container)
+ *   - `batch` — use `startBatchConsumer` instead of `startConsumer`
+ *
+ * @example
+ * ```ts
+ * @SubscribeTo('orders.created', { groupId: 'orders-svc', retry: { maxRetries: 3 } })
+ * async handleOrder(envelope: EventEnvelope<Order>) { ... }
+ *
+ * @SubscribeTo(OrdersTopic, { batch: true })
+ * async handleBatch(envelopes: EventEnvelope<Order>[], meta: BatchMeta) { ... }
+ * ```
  */
 declare const SubscribeTo: (topics: string | string[] | TopicDescriptor | TopicDescriptor[] | (string | TopicDescriptor)[], options?: ConsumerOptions & {
     clientName?: string;
@@ -81,6 +108,12 @@ declare class KafkaExplorer implements OnModuleInit {
     private readonly moduleRef;
     private readonly logger;
     constructor(discoveryService: DiscoveryService, moduleRef: ModuleRef);
+    /**
+     * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated
+     * method to its Kafka client via `startConsumer` or `startBatchConsumer`.
+     *
+     * Called automatically by the NestJS lifecycle — do not invoke manually.
+     */
     onModuleInit(): Promise<void>;
 }