@drarzter/kafka-client 0.2.0 → 0.2.2

package/README.md

@@ -331,6 +331,13 @@ await kafka.startConsumer(['orders'], auditHandler, { groupId: 'orders-audit' })
 async auditOrders(message) { ... }
 ```
 
+**Important:** You cannot mix `eachMessage` and `eachBatch` consumers on the same `groupId`. The library throws a clear error if you try:
+
+```text
+Cannot use eachBatch on consumer group "my-group" — it is already running with eachMessage.
+Use a different groupId for this consumer.
+```
+
 ### Named clients
 
 Register multiple named clients for different bounded contexts:
@@ -529,6 +536,8 @@ Options for `sendMessage()` — the third argument:
 | `dlq` | `false` | Send to `{topic}.dlq` after all retries exhausted |
 | `interceptors` | `[]` | Array of before/after/onError hooks |
 | `batch` | `false` | (decorator only) Use `startBatchConsumer` instead of `startConsumer` |
+| `subscribeRetry.retries` | `5` | Max attempts for `consumer.subscribe()` when topic doesn't exist yet |
+| `subscribeRetry.backoffMs` | `5000` | Delay between subscribe retry attempts (ms) |
 
 ### Module options
 
@@ -541,7 +550,8 @@ Passed to `KafkaModule.register()` or returned from `registerAsync()` factory:
 | `brokers` | — | Array of broker addresses (required) |
 | `name` | — | Named client identifier for multi-client setups |
 | `isGlobal` | `false` | Make the client available in all modules without re-importing |
-| `autoCreateTopics` | `false` | Auto-create topics on first send/consume (dev only) |
+| `autoCreateTopics` | `false` | Auto-create topics on first send (dev only) |
+| `strictSchemas` | `true` | Validate string topic keys against schemas registered via TopicDescriptor |
 
 **Module-scoped** (default) — import `KafkaModule` in each module that needs it:
 
@@ -676,6 +686,20 @@ async handleOrder(message) {
 }
 ```
 
+### Strict schema mode
+
+By default (`strictSchemas: true`), once a schema is registered via a TopicDescriptor, string topic keys are also validated against it:
+
+```typescript
+// First call registers the schema in the internal registry
+await kafka.sendMessage(OrderCreated, { orderId: '1', userId: '2', amount: 100 });
+
+// Now this is ALSO validated — throws if data doesn't match OrderCreated's schema
+await kafka.sendMessage('order.created', { orderId: 123, userId: null, amount: -5 });
+```
+
+Disable with `strictSchemas: false` in `KafkaModule.register()` options if you want the old behavior (string topics bypass validation).
+
 ### Bring your own validator
 
 Any object with `parse(data: unknown): T` works:

package/dist/index.d.mts

@@ -139,6 +139,8 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     interceptors?: ConsumerInterceptor<T>[];
     /** @internal Schema map populated by @SubscribeTo when descriptors have schemas. */
     schemas?: Map<string, SchemaLike>;
+    /** Retry config for `consumer.subscribe()` when the topic doesn't exist yet. */
+    subscribeRetry?: SubscribeRetryOptions;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -196,8 +198,17 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
 }
 /** Options for `KafkaClient` constructor. */
 interface KafkaClientOptions {
-    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, `transaction`, or `startConsumer` for each topic. Useful for development — not recommended in production. */
+    /** 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;
+}
+/** Options for consumer subscribe retry when topic doesn't exist yet. */
+interface SubscribeRetryOptions {
+    /** Maximum number of subscribe attempts. Default: `5`. */
+    retries?: number;
+    /** Delay between retries in ms. Default: `5000`. */
+    backoffMs?: number;
 }
 
 /**
@@ -213,15 +224,14 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly admin;
     private readonly logger;
     private readonly autoCreateTopicsEnabled;
+    private readonly strictSchemasEnabled;
     private readonly ensuredTopics;
     private readonly defaultGroupId;
+    private readonly schemaRegistry;
+    private readonly runningConsumers;
     private isAdminConnected;
     readonly clientId: ClientId;
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
-    private getOrCreateConsumer;
-    private resolveTopicName;
-    private ensureTopic;
-    private validateMessage;
     /** Send a single typed message. Accepts a topic key or a TopicDescriptor. */
     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>;
@@ -255,9 +265,36 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     getClientId(): ClientId;
     /** Gracefully disconnect producer, all consumers, and admin. */
     disconnect(): Promise<void>;
+    private getOrCreateConsumer;
+    private resolveTopicName;
+    private ensureTopic;
+    /** Register schema from descriptor into global registry (side-effect). */
+    private registerSchema;
+    /** Validate message against schema. Pure — no side-effects on registry. */
+    private validateMessage;
+    /**
+     * Build a kafkajs-ready send payload.
+     * Handles: topic resolution, schema registration, validation, JSON serialization.
+     */
+    private buildSendPayload;
+    /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
+    private setupConsumer;
     private buildSchemaMap;
-    private processMessage;
+    /** Parse raw message as JSON. Returns null on failure (logs error). */
+    private parseJsonMessage;
+    /**
+     * Validate a parsed message against the schema map.
+     * On failure: logs error, sends to DLQ if enabled, calls interceptor.onError.
+     * Returns validated message or null.
+     */
+    private validateWithSchema;
+    /**
+     * Execute a handler with retry, interceptors, and DLQ support.
+     * Used by both single-message and batch consumers.
+     */
+    private executeWithRetry;
     private sendToDlq;
+    private subscribeWithRetry;
     private sleep;
 }
 
@@ -370,4 +407,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { type BatchMeta, type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, type InferSchema, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, KafkaValidationError, type MessageHeaders, type RetryOptions, type SchemaLike, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };
+export { type BatchMeta, type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, type InferSchema, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, KafkaValidationError, type MessageHeaders, type RetryOptions, type SchemaLike, type SendOptions, type SubscribeRetryOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };

package/dist/index.d.ts

@@ -139,6 +139,8 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     interceptors?: ConsumerInterceptor<T>[];
     /** @internal Schema map populated by @SubscribeTo when descriptors have schemas. */
     schemas?: Map<string, SchemaLike>;
+    /** Retry config for `consumer.subscribe()` when the topic doesn't exist yet. */
+    subscribeRetry?: SubscribeRetryOptions;
 }
 /** Configuration for consumer retry behavior. */
 interface RetryOptions {
@@ -196,8 +198,17 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
 }
 /** Options for `KafkaClient` constructor. */
 interface KafkaClientOptions {
-    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, `transaction`, or `startConsumer` for each topic. Useful for development — not recommended in production. */
+    /** 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;
+}
+/** Options for consumer subscribe retry when topic doesn't exist yet. */
+interface SubscribeRetryOptions {
+    /** Maximum number of subscribe attempts. Default: `5`. */
+    retries?: number;
+    /** Delay between retries in ms. Default: `5000`. */
+    backoffMs?: number;
 }
 
 /**
@@ -213,15 +224,14 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly admin;
     private readonly logger;
     private readonly autoCreateTopicsEnabled;
+    private readonly strictSchemasEnabled;
     private readonly ensuredTopics;
     private readonly defaultGroupId;
+    private readonly schemaRegistry;
+    private readonly runningConsumers;
     private isAdminConnected;
     readonly clientId: ClientId;
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
-    private getOrCreateConsumer;
-    private resolveTopicName;
-    private ensureTopic;
-    private validateMessage;
     /** Send a single typed message. Accepts a topic key or a TopicDescriptor. */
     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>;
@@ -255,9 +265,36 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     getClientId(): ClientId;
     /** Gracefully disconnect producer, all consumers, and admin. */
     disconnect(): Promise<void>;
+    private getOrCreateConsumer;
+    private resolveTopicName;
+    private ensureTopic;
+    /** Register schema from descriptor into global registry (side-effect). */
+    private registerSchema;
+    /** Validate message against schema. Pure — no side-effects on registry. */
+    private validateMessage;
+    /**
+     * Build a kafkajs-ready send payload.
+     * Handles: topic resolution, schema registration, validation, JSON serialization.
+     */
+    private buildSendPayload;
+    /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
+    private setupConsumer;
     private buildSchemaMap;
-    private processMessage;
+    /** Parse raw message as JSON. Returns null on failure (logs error). */
+    private parseJsonMessage;
+    /**
+     * Validate a parsed message against the schema map.
+     * On failure: logs error, sends to DLQ if enabled, calls interceptor.onError.
+     * Returns validated message or null.
+     */
+    private validateWithSchema;
+    /**
+     * Execute a handler with retry, interceptors, and DLQ support.
+     * Used by both single-message and batch consumers.
+     */
+    private executeWithRetry;
     private sendToDlq;
+    private subscribeWithRetry;
     private sleep;
 }
 
@@ -370,4 +407,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { type BatchMeta, type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, type InferSchema, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, KafkaValidationError, type MessageHeaders, type RetryOptions, type SchemaLike, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };
+export { type BatchMeta, type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, type InferSchema, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, KafkaValidationError, type MessageHeaders, type RetryOptions, type SchemaLike, type SendOptions, type SubscribeRetryOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };