@kaapi/kafka-messaging 0.0.40 → 0.0.41

package/lib/index.d.ts

@@ -1,18 +1,92 @@
 import { Admin, AdminConfig, Consumer, ConsumerConfig, ITopicConfig, Kafka, KafkaConfig, Producer, ProducerConfig } from 'kafkajs';
 import { ILogger, IMessaging, IMessagingContext } from '@kaapi/kaapi';
+/**
+ * Extended messaging context with Kafka-specific metadata.
+ */
 export interface KafkaMessagingContext extends IMessagingContext {
+    /** The Kafka message offset */
     offset?: string;
+    address?: string;
 }
+/**
+ * Configuration options for KafkaMessaging.
+ * Extends KafkaJS's KafkaConfig with additional Kaapi-specific options.
+ */
 export interface KafkaMessagingConfig extends KafkaConfig {
+    /** Optional logger implementing Kaapi's ILogger interface */
     logger?: ILogger;
+    /** Optional unique service address for routing and identification */
     address?: string;
+    /** Optional human-readable name for service tracking/monitoring */
     name?: string;
+    /** Optional default KafkaJS producer configuration */
     producer?: ProducerConfig;
 }
+/**
+ * Configuration options for subscribing to a Kafka topic.
+ * Extends KafkaJS's ConsumerConfig with additional options.
+ */
 export interface KafkaMessagingSubscribeConfig extends Partial<ConsumerConfig> {
+    /** Whether to start consuming from the beginning of the topic */
     fromBeginning?: boolean;
+    /** Callback invoked when the consumer is ready */
     onReady?(consumer: Consumer): void;
+    /**
+     * Custom consumer group ID. If not provided, defaults to `{name}.{topic}`
+     * where `name` is the service name from KafkaMessagingConfig.
+     */
+    groupId?: string;
+    /**
+     * Prefix for the auto-generated group ID. Only used when `groupId` is not provided.
+     * Defaults to the service `name` or 'group' if name is not set.
+     */
+    groupIdPrefix?: string;
+    /**
+     * Whether to log partition offsets on subscribe.
+     * Requires an admin client connection, adding some overhead.
+     * @default false
+     */
+    logOffsets?: boolean;
+    /**
+     * Called when a message handler throws an error.
+     * Allows custom error handling (e.g., alerting, metrics, logging to external service).
+     *
+     * @param error - The error thrown by the handler
+     * @param message - The parsed message that failed
+     * @param context - The message context (offset, headers, etc.)
+     */
+    onError?(error: unknown, message: unknown, context: KafkaMessagingContext): void | Promise<void>;
 }
+/**
+ * A message to be published in a batch.
+ */
+export interface KafkaMessagingBatchMessage<T = unknown> {
+    /** The message payload */
+    value: T;
+    /** Optional message key for partitioning */
+    key?: string;
+    /** Optional partition to send to */
+    partition?: number;
+    /** Optional custom headers (merged with default headers) */
+    headers?: Record<string, string>;
+}
+/**
+ * A lightweight wrapper around KafkaJS that integrates with the Kaapi framework
+ * to provide a clean and consistent message publishing and consuming interface.
+ *
+ * @example
+ * ```ts
+ * const messaging = new KafkaMessaging({
+ *     clientId: 'my-app',
+ *     brokers: ['localhost:9092'],
+ *     name: 'my-service',
+ *     address: 'service-1'
+ * });
+ *
+ * await messaging.publish('my-topic', { event: 'user.created' });
+ * await messaging.subscribe('my-topic', (msg, ctx) => console.log(msg));
+ * ```
+ */
 export declare class KafkaMessaging implements IMessaging {
     #private;
     protected kafka?: Kafka;
@@ -21,10 +95,66 @@ export declare class KafkaMessaging implements IMessaging {
     protected currentProducerId?: string;
     get activeConsumers(): ReadonlySet<Consumer>;
     get activeProducers(): ReadonlySet<Producer>;
+    /**
+     * Creates a new KafkaMessaging instance.
+     *
+     * @param arg - Configuration options for the Kafka client
+     */
     constructor(arg: KafkaMessagingConfig);
     private _createInstance;
+    /**
+     * Internal method to initialize the shared admin.
+     * @private
+     */
+    private _initializeSharedAdmin;
+    /**
+     * Internal method to initialize the producer.
+     * @private
+     */
+    private _initializeProducer;
     protected getKafka(): Kafka | undefined;
+    /**
+     * Gets or creates a shared admin instance for internal operations.
+     * Uses lazy initialization to avoid unnecessary connections.
+     *
+     * @returns A promise that resolves to the shared admin instance
+     */
+    protected getSharedAdmin(): Promise<Admin | undefined>;
+    /**
+     * Creates and connects a Kafka admin client.
+     * The admin client is automatically tracked and will be disconnected during shutdown.
+     *
+     * @param config - Optional admin client configuration
+     * @returns A promise that resolves to the connected admin client, or undefined if Kafka is unavailable
+     *
+     * @example
+     * ```ts
+     * const admin = await messaging.createAdmin();
+     * const topics = await admin?.listTopics();
+     * await admin?.disconnect();
+     * ```
+     */
     createAdmin(config?: AdminConfig): Promise<Admin | undefined>;
+    /**
+     * Creates a new Kafka topic with the specified configuration.
+     *
+     * @param topic - The topic configuration including name, partitions, and replication factor
+     * @param config - Optional creation options
+     * @param config.validateOnly - If true, only validates the request without creating the topic
+     * @param config.waitForLeaders - If true, waits for partition leaders to be elected
+     * @param config.timeout - Timeout in milliseconds for the operation
+     *
+     * @throws {Error} If the admin client cannot be created
+     *
+     * @example
+     * ```ts
+     * await messaging.createTopic({
+     *     topic: 'my-topic',
+     *     numPartitions: 3,
+     *     replicationFactor: 1
+     * }, { waitForLeaders: true });
+     * ```
+     */
     createTopic(topic: ITopicConfig, config?: {
         validateOnly?: boolean;
         waitForLeaders?: boolean;
@@ -46,32 +176,163 @@ export declare class KafkaMessaging implements IMessaging {
      */
     waitForTopicReady(topic: string, timeoutMs?: number, checkIntervalMs?: number): Promise<void>;
     /**
-     * Create a new consumer with optional configuration overrides
-     * @param groupId Consumer group id
-     * @param config Consumer configuration overrides
-     * @returns
+     * Fetches and logs partition offsets for a topic.
+     * Uses the shared admin instance to minimize connections.
+     *
+     * @param topic - The topic to fetch offsets for
+     * @returns The partition offset information, or undefined if unavailable
+     */
+    fetchTopicOffsets(topic: string): Promise<Array<{
+        partition: number;
+        offset: string;
+        high: string;
+        low: string;
+    }> | undefined>;
+    /**
+     * Creates and connects a new Kafka consumer.
+     * The consumer is automatically tracked and will be disconnected during shutdown.
+     *
+     * @param groupId - The consumer group ID
+     * @param config - Optional consumer configuration overrides
+     * @returns A promise that resolves to the connected consumer, or undefined if Kafka is unavailable
+     *
+     * @example
+     * ```ts
+     * const consumer = await messaging.createConsumer('my-group', {
+     *     sessionTimeout: 30000
+     * });
+     * ```
      */
     createConsumer(groupId: string, config?: Partial<ConsumerConfig>): Promise<Consumer | undefined>;
     /**
-     * Create a new producer with optional configuration overrides
-     * @param config Producer configuration overrides
-     * @returns
+     * Creates and connects a new Kafka producer.
+     * The producer is automatically tracked and will be disconnected during shutdown.
+     *
+     * @param config - Optional producer configuration overrides
+     * @returns A promise that resolves to the connected producer, or undefined if Kafka is unavailable
+     *
+     * @example
+     * ```ts
+     * const producer = await messaging.createProducer({
+     *     idempotent: true
+     * });
+     * ```
      */
     createProducer(config?: Partial<ProducerConfig>): Promise<Producer | undefined>;
     /**
-     * Get the producer
+     * Gets or creates the singleton producer instance.
+     * Uses a promise-based lock to prevent race conditions when called concurrently.
+     *
+     * @returns A promise that resolves to the producer instance, or undefined if unavailable.
      */
     getProducer(): Promise<Producer | undefined>;
     /**
-     * Disconnect the producer
+     * Disconnects the singleton producer instance.
+     *
+     * @returns A promise that resolves when the producer is disconnected
      */
     disconnectProducer(): Promise<void>;
+    /**
+     * Publishes multiple messages to a Kafka topic in a single batch.
+     * More efficient than multiple `publish()` calls for high-throughput scenarios.
+     *
+     * @typeParam T - The type of the message payload
+     * @param topic - The Kafka topic to publish to
+     * @param messages - Array of messages to publish
+     *
+     * @throws {Error} If the batch fails to send
+     *
+     * @example
+     * ```ts
+     * await messaging.publishBatch('user-events', [
+     *     { value: { event: 'user.created', userId: '1' } },
+     *     { value: { event: 'user.created', userId: '2' } },
+     *     { value: { event: 'user.updated', userId: '3' }, key: 'user-3' },
+     * ]);
+     * ```
+     */
+    publishBatch<T = unknown>(topic: string, messages: KafkaMessagingBatchMessage<T>[]): Promise<void>;
+    /**
+     * Publishes a message to the specified Kafka topic.
+     * Automatically manages the producer lifecycle and includes service metadata in headers.
+     *
+     * @typeParam T - The type of the message payload
+     * @param topic - The Kafka topic to publish to
+     * @param message - The message payload (will be JSON serialized)
+     *
+     * @throws {Error} If the message fails to send
+     *
+     * @example
+     * ```ts
+     * await messaging.publish('user-events', {
+     *     event: 'user.created',
+     *     userId: '123',
+     *     timestamp: Date.now()
+     * });
+     * ```
+     */
     publish<T = unknown>(topic: string, message: T): Promise<void>;
     /**
-     * Listen to a topic
+     * Subscribes to a Kafka topic and processes messages with the provided handler.
+     * Creates a new consumer for each subscription with an auto-generated group ID.
+     *
+     * @typeParam T - The expected type of incoming messages
+     * @param topic - The Kafka topic to subscribe to
+     * @param handler - Callback function invoked for each message. Can be async.
+     * @param config - Optional subscription configuration
+     * @param config.fromBeginning - Start consuming from the beginning of the topic
+     * @param config.onReady - Callback invoked when the consumer is ready
+     * @param config.groupId - Override the auto-generated consumer group ID
+     * @param config.groupIdPrefix - Prefix for auto-generated group ID (default: service name)
+     *
+     * @example
+     * ```ts
+     * // Using auto-generated group ID (e.g., "my-service.user-events")
+     * await messaging.subscribe('user-events', handler);
+     *
+     * // Using custom group ID
+     * await messaging.subscribe('user-events', handler, {
+     *     groupId: 'my-custom-consumer-group'
+     * });
+     *
+     * // Using custom prefix (e.g., "analytics.user-events")
+     * await messaging.subscribe('user-events', handler, {
+     *     groupIdPrefix: 'analytics'
+     * });
+     *
+     * // With offset logging enabled
+     * await messaging.subscribe('user-events', handler, {
+     *     logOffsets: true
+     * });
+     * ```
      */
     subscribe<T = unknown>(topic: string, handler: (message: T, context: KafkaMessagingContext) => Promise<void> | void, config?: KafkaMessagingSubscribeConfig): Promise<void>;
+    /**
+     * Safely disconnects a Kafka client with timeout protection.
+     * Prevents hanging if the client fails to disconnect gracefully.
+     *
+     * @param client - The Kafka client (producer, consumer, or admin) to disconnect
+     * @param timeoutMs - Maximum time to wait for disconnection (default: 5000ms)
+     * @returns A promise that resolves when disconnected or rejects on timeout
+     *
+     * @throws {Error} If the disconnect times out
+     */
     safeDisconnect(client: Producer | Consumer | Admin, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Gracefully shuts down all tracked Kafka clients (producers, consumers, and admins).
+     * Should be called during application teardown to release resources.
+     *
+     * @returns A summary of the shutdown operation including success and error counts
+     *
+     * @example
+     * ```ts
+     * process.on('SIGTERM', async () => {
+     *     const result = await messaging.shutdown();
+     *     console.log(`Shutdown complete: ${result.successProducers} producers, ${result.errorCount} errors`);
+     *     process.exit(0);
+     * });
+     * ```
+     */
     shutdown(): Promise<{
         successProducers: number;
         successConsumers: number;
@@ -79,4 +340,12 @@ export declare class KafkaMessaging implements IMessaging {
         errorCount: number;
     }>;
 }
+/**
+ * Safely disconnects a Kafka client with timeout protection.
+ * Standalone utility function.
+ *
+ * @param client - The Kafka client to disconnect
+ * @param timeoutMs - Maximum time to wait (default: 5000ms)
+ * @returns A promise that resolves when disconnected or rejects on timeout
+ */
 export declare function safeDisconnect(client: Producer | Consumer | Admin, timeoutMs?: number): Promise<unknown>;