@woovi/kafka 0.1.6 → 0.1.7

package/dist/index.cjs

@@ -109,13 +109,25 @@ function registerGracefulShutdown() {
 function onShutdown(callback) {
     shutdownCallbacks.push(callback);
 }
-let mockKafkaForTestMode = null;
+const WOOVI_KAFKA_MOCK_KEY = '__woovi_kafka_mock__';
+function getGlobalState() {
+    const g = globalThis;
+    if (!g[WOOVI_KAFKA_MOCK_KEY]) g[WOOVI_KAFKA_MOCK_KEY] = {
+        mock: null,
+        testMode: false
+    };
+    return g[WOOVI_KAFKA_MOCK_KEY];
+}
 function setMockKafkaForTestMode(mock) {
-    mockKafkaForTestMode = mock;
+    const state = getGlobalState();
+    state.mock = mock;
+    state.testMode = true;
     testMode = true;
 }
 function getKafka() {
-    if (testMode && mockKafkaForTestMode) return mockKafkaForTestMode;
+    const state = getGlobalState();
+    if (state.testMode && state.mock) return state.mock;
+    if (testMode && kafkaInstance) return kafkaInstance;
     if (!kafkaInstance) throw new Error('Kafka not initialized. Call createKafka() first.');
     return kafkaInstance;
 }

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import type { CompressionTypes } from 'kafkajs';
+import type { Consumer } from 'kafkajs';
+import type { ConsumerConfig } from 'kafkajs';
+import type { ConsumerSubscribeTopics } from 'kafkajs';
+import { Counter } from 'prom-client';
+import type { EachBatchPayload } from 'kafkajs';
+import type { EachMessagePayload } from 'kafkajs';
+import { Gauge } from 'prom-client';
+import { Histogram } from 'prom-client';
+import { Kafka } from 'kafkajs';
+import type { KafkaConfig as KafkaConfig_2 } from 'kafkajs';
+import { logLevel } from 'kafkajs';
+import type { Message } from 'kafkajs';
+import type { Producer } from 'kafkajs';
+import type { ProducerConfig } from 'kafkajs';
+import type { RecordMetadata } from 'kafkajs';
+import { Registry } from 'prom-client';
+
+export declare interface BatchHandler {
+    (payload: EachBatchPayload): Promise<void>;
+}
+
+export declare const batchProcessingDuration: Histogram<"topic" | "group_id" | "partition">;
+
+export declare const batchSize: Histogram<"topic" | "group_id" | "partition">;
+
+export declare const consumerLag: Gauge<"topic" | "group_id" | "partition">;
+
+export declare function createConsumer(config: WooviConsumerConfig): WooviConsumer;
+
+export declare function createKafka(config: KafkaConfig): Kafka;
+
+export declare function createKafkaFromEnv(clientId: string): Kafka;
+
+export declare function createProducer(config?: WooviProducerConfig): WooviProducer;
+
+/**
+ * Disable test mode and reset the Kafka instance.
+ */
+export declare function disableTestMode(): void;
+
+export { EachBatchPayload }
+
+export { EachMessagePayload }
+
+export declare function enableDefaultMetrics(): void;
+
+/**
+ * Enable test mode with a mock Kafka instance.
+ * This allows tests to bypass the real Kafka connection.
+ */
+export declare function enableTestMode(mockKafka?: Kafka): void;
+
+export declare interface ErrorHandler {
+    (error: Error, payload: EachMessagePayload): Promise<void>;
+}
+
+export declare function getKafka(): Kafka;
+
+export declare function getMessageHeaders(payload: EachMessagePayload): Record<string, string>;
+
+export declare function getMetrics(): Promise<string>;
+
+export declare function getMetricsContentType(): string;
+
+export declare function healthCheck(): Promise<{
+    healthy: boolean;
+    error?: string;
+}>;
+
+/**
+ * Check if test mode is enabled.
+ */
+export declare function isTestMode(): boolean;
+
+export { Kafka }
+
+export declare interface KafkaConfig {
+    brokers: string[];
+    clientId: string;
+    ssl?: KafkaConfig_2['ssl'];
+    sasl?: KafkaConfig_2['sasl'];
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    retry?: KafkaConfig_2['retry'];
+}
+
+export declare const kafkaRegistry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+
+export declare const lastMessageTimestamp: Gauge<"topic" | "group_id" | "partition">;
+
+export { logLevel }
+
+export { Message }
+
+export declare interface MessageHandler {
+    (payload: EachMessagePayload): Promise<void>;
+}
+
+export declare const messageProcessingDuration: Histogram<"topic" | "group_id" | "partition">;
+
+export declare const messagesFailedTotal: Counter<"topic" | "group_id" | "partition" | "error_type">;
+
+export declare const messagesProcessedTotal: Counter<"topic" | "group_id" | "partition" | "status">;
+
+export declare const messagesProducedTotal: Counter<"topic" | "status">;
+
+export declare function onShutdown(callback: () => Promise<void>): void;
+
+export declare function parseMessage<T>(payload: EachMessagePayload): T | null;
+
+export declare const produceLatency: Histogram<"topic">;
+
+export declare interface PublishArgs<T = unknown> {
+    data: T;
+    topic?: string;
+    key?: string;
+    partition?: number;
+    headers?: Record<string, string>;
+    timestamp?: string;
+    compression?: CompressionTypes;
+}
+
+export declare interface PublishBatchArgs<T = unknown> {
+    messages: Array<{
+        data: T;
+        key?: string;
+        partition?: number;
+        headers?: Record<string, string>;
+        timestamp?: string;
+    }>;
+    topic?: string;
+    compression?: CompressionTypes;
+}
+
+export declare interface PublishMultiTopicArgs<T = unknown> {
+    messages: Array<{
+        topic: string;
+        data: T;
+        key?: string;
+        partition?: number;
+        headers?: Record<string, string>;
+        timestamp?: string;
+    }>;
+}
+
+export { RecordMetadata }
+
+export declare function resetMetrics(): void;
+
+export declare function setMockKafkaForTestMode(mock: Kafka): void;
+
+export declare class WooviConsumer {
+    private consumer;
+    private topics;
+    private fromBeginning;
+    private connected;
+    private subscribed;
+    private groupId;
+    private onError?;
+    constructor(config: WooviConsumerConfig);
+    connect(): Promise<void>;
+    subscribe(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    run(handler: MessageHandler): Promise<void>;
+    runBatch(handler: BatchHandler): Promise<void>;
+    pause(topics?: string[]): Promise<void>;
+    resume(topics?: string[]): Promise<void>;
+    getConsumer(): Consumer;
+}
+
+export declare interface WooviConsumerConfig extends ConsumerConfig {
+    topics: ConsumerSubscribeTopics['topics'];
+    fromBeginning?: boolean;
+    onError?: ErrorHandler;
+}
+
+export declare class WooviProducer {
+    private producer;
+    private defaultTopic?;
+    private connected;
+    constructor(config?: WooviProducerConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    publish<T>(args: PublishArgs<T>): Promise<RecordMetadata[]>;
+    publishBatch<T>(args: PublishBatchArgs<T>): Promise<RecordMetadata[]>;
+    publishToMultipleTopics<T>(args: PublishMultiTopicArgs<T>): Promise<RecordMetadata[]>;
+    getProducer(): Producer;
+}
+
+export declare interface WooviProducerConfig extends ProducerConfig {
+    defaultTopic?: string;
+}
+
+export { }

package/dist/index.js

@@ -52,13 +52,25 @@ function registerGracefulShutdown() {
 function onShutdown(callback) {
     shutdownCallbacks.push(callback);
 }
-let mockKafkaForTestMode = null;
+const WOOVI_KAFKA_MOCK_KEY = '__woovi_kafka_mock__';
+function getGlobalState() {
+    const g = globalThis;
+    if (!g[WOOVI_KAFKA_MOCK_KEY]) g[WOOVI_KAFKA_MOCK_KEY] = {
+        mock: null,
+        testMode: false
+    };
+    return g[WOOVI_KAFKA_MOCK_KEY];
+}
 function setMockKafkaForTestMode(mock) {
-    mockKafkaForTestMode = mock;
+    const state = getGlobalState();
+    state.mock = mock;
+    state.testMode = true;
     testMode = true;
 }
 function getKafka() {
-    if (testMode && mockKafkaForTestMode) return mockKafkaForTestMode;
+    const state = getGlobalState();
+    if (state.testMode && state.mock) return state.mock;
+    if (testMode && kafkaInstance) return kafkaInstance;
     if (!kafkaInstance) throw new Error('Kafka not initialized. Call createKafka() first.');
     return kafkaInstance;
 }

package/dist/test-utils.cjs

@@ -37,6 +37,7 @@ __webpack_require__.d(__webpack_exports__, {
     mockProducerSend: ()=>mockProducerSend,
     mockTransaction: ()=>mockTransaction,
     mockTransactionSend: ()=>mockTransactionSend,
+    setupKafkaTest: ()=>setupKafkaTest,
     KafkaJSNonRetriableError: ()=>KafkaJSNonRetriableError,
     CompressionTypes: ()=>CompressionTypes,
     mockProducer: ()=>mockProducer
@@ -204,12 +205,20 @@ const kafkaAssertLength = (args)=>{
     }
 };
 function createMockKafka() {
-    return Kafka({
-        clientId: 'test',
-        brokers: [
-            'localhost:9092'
-        ]
-    });
+    return Kafka();
+}
+const WOOVI_KAFKA_MOCK_KEY = '__woovi_kafka_mock__';
+function setupKafkaTest() {
+    const mockKafkaInstance = {
+        producer: mockProducer,
+        consumer: mockConsumer,
+        admin: mockAdmin
+    };
+    const g = globalThis;
+    g[WOOVI_KAFKA_MOCK_KEY] = {
+        mock: mockKafkaInstance,
+        testMode: true
+    };
 }
 exports.CompressionTypes = __webpack_exports__.CompressionTypes;
 exports.Kafka = __webpack_exports__.Kafka;
@@ -227,6 +236,7 @@ exports.mockProducer = __webpack_exports__.mockProducer;
 exports.mockProducerSend = __webpack_exports__.mockProducerSend;
 exports.mockTransaction = __webpack_exports__.mockTransaction;
 exports.mockTransactionSend = __webpack_exports__.mockTransactionSend;
+exports.setupKafkaTest = __webpack_exports__.setupKafkaTest;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "CompressionTypes",
     "Kafka",
@@ -243,7 +253,8 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "mockProducer",
     "mockProducerSend",
     "mockTransaction",
-    "mockTransactionSend"
+    "mockTransactionSend",
+    "setupKafkaTest"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/test-utils.d.ts

@@ -0,0 +1,110 @@
+export declare const clearAllMocks: () => void;
+
+export declare const CompressionTypes: {
+    None: number;
+    GZIP: number;
+    Snappy: number;
+    LZ4: number;
+    ZSTD: number;
+};
+
+/**
+ * Create a mock Kafka instance for testing.
+ * Use this with setMockKafkaForTestMode from @woovi/kafka.
+ *
+ * @example
+ * import { setMockKafkaForTestMode } from '@woovi/kafka';
+ * import { createMockKafka } from '@woovi/kafka/test-utils';
+ *
+ * beforeAll(() => {
+ *   setMockKafkaForTestMode(createMockKafka());
+ * });
+ */
+export declare function createMockKafka(): any;
+
+export declare const getKafkaMessages: () => KafkaMessage[];
+
+export declare const Kafka: MockFn;
+
+export declare const kafkaAssert: (args: KafkaAssertArgs) => void;
+
+declare type KafkaAssertArgs = {
+    topic: string;
+    message: Record<string, unknown>;
+};
+
+export declare const kafkaAssertLength: (args: KafkaAssertLengthArgs) => void;
+
+declare type KafkaAssertLengthArgs = {
+    topic: string;
+    length: number;
+};
+
+export declare class KafkaJSNonRetriableError extends Error {
+    constructor(message: string);
+}
+
+export declare class KafkaJSProtocolError extends Error {
+    type: string;
+    constructor(message: string, type: string);
+}
+
+export declare type KafkaMessage = {
+    topic: string;
+    messages: Array<{
+        key?: string;
+        value: string;
+        headers?: Record<string, string>;
+    }>;
+};
+
+export declare const logLevel: {
+    NOTHING: number;
+    ERROR: number;
+    WARN: number;
+    INFO: number;
+    DEBUG: number;
+};
+
+export declare const mockAdmin: MockFn;
+
+export declare const mockConsumer: MockFn;
+
+declare type MockFn = {
+    (): any;
+    mock: {
+        calls: any[][];
+    };
+    mockClear: () => void;
+    mockReset: () => void;
+    mockImplementation: (fn: (...args: any[]) => any) => MockFn;
+    mockReturnValue: (value: any) => MockFn;
+    mockResolvedValue: (value: any) => MockFn;
+};
+
+export declare const mockProducer: MockFn;
+
+export declare const mockProducerSend: MockFn;
+
+export declare const mockTransaction: MockFn;
+
+export declare const mockTransactionSend: MockFn;
+
+/**
+ * Set up Kafka for testing with a mock instance.
+ * This creates a mock Kafka that records messages for kafkaAssert.
+ *
+ * @example
+ * import { setupKafkaTest, clearAllMocks } from '@woovi/kafka/test-utils';
+ *
+ * beforeAll(() => {
+ *   setupKafkaTest();
+ * });
+ *
+ * beforeEach(() => {
+ *   clearAllMocks();
+ * });
+ */
+export declare function setupKafkaTest(): void;
+
+export { }

package/dist/test-utils.js

@@ -161,11 +161,19 @@ const kafkaAssertLength = (args)=>{
     }
 };
 function createMockKafka() {
-    return Kafka({
-        clientId: 'test',
-        brokers: [
-            'localhost:9092'
-        ]
-    });
+    return Kafka();
 }
-export { CompressionTypes, Kafka, KafkaJSNonRetriableError, KafkaJSProtocolError, clearAllMocks, createMockKafka, getKafkaMessages, kafkaAssert, kafkaAssertLength, logLevel, mockAdmin, mockConsumer, mockProducer, mockProducerSend, mockTransaction, mockTransactionSend };
+const WOOVI_KAFKA_MOCK_KEY = '__woovi_kafka_mock__';
+function setupKafkaTest() {
+    const mockKafkaInstance = {
+        producer: mockProducer,
+        consumer: mockConsumer,
+        admin: mockAdmin
+    };
+    const g = globalThis;
+    g[WOOVI_KAFKA_MOCK_KEY] = {
+        mock: mockKafkaInstance,
+        testMode: true
+    };
+}
+export { CompressionTypes, Kafka, KafkaJSNonRetriableError, KafkaJSProtocolError, clearAllMocks, createMockKafka, getKafkaMessages, kafkaAssert, kafkaAssertLength, logLevel, mockAdmin, mockConsumer, mockProducer, mockProducerSend, mockTransaction, mockTransactionSend, setupKafkaTest };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@woovi/kafka",
   "description": "Kafka setup and utilities for Woovi microservices",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "author": "",
   "type": "module",
   "dependencies": {