@kaapi/kafka-messaging 0.0.39 → 0.0.41

package/lib/index.js

@@ -1,11 +1,28 @@
 "use strict";
-var _KafkaMessaging_config, _KafkaMessaging_producerConfig, _KafkaMessaging_address, _KafkaMessaging_name, _KafkaMessaging_consumers, _KafkaMessaging_producers, _KafkaMessaging_admins;
+var _KafkaMessaging_config, _KafkaMessaging_producerConfig, _KafkaMessaging_address, _KafkaMessaging_name, _KafkaMessaging_consumers, _KafkaMessaging_producers, _KafkaMessaging_admins, _KafkaMessaging_producerPromise, _KafkaMessaging_sharedAdmin, _KafkaMessaging_sharedAdminPromise;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KafkaMessaging = void 0;
 exports.safeDisconnect = safeDisconnect;
 const tslib_1 = require("tslib");
 const kafkajs_1 = require("kafkajs");
 const crypto_1 = require("crypto");
+/**
+ * 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));
+ * ```
+ */
 class KafkaMessaging {
     get activeConsumers() {
         return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_consumers, "f");
@@ -13,6 +30,11 @@ class KafkaMessaging {
     get activeProducers() {
         return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producers, "f");
     }
+    /**
+     * Creates a new KafkaMessaging instance.
+     *
+     * @param arg - Configuration options for the Kafka client
+     */
     constructor(arg) {
         _KafkaMessaging_config.set(this, void 0);
         _KafkaMessaging_producerConfig.set(this, void 0);
@@ -21,6 +43,10 @@ class KafkaMessaging {
         _KafkaMessaging_consumers.set(this, new Set());
         _KafkaMessaging_producers.set(this, new Set());
         _KafkaMessaging_admins.set(this, new Set());
+        _KafkaMessaging_producerPromise.set(this, void 0);
+        /** Shared admin instance for internal operations (lazy initialized) */
+        _KafkaMessaging_sharedAdmin.set(this, void 0);
+        _KafkaMessaging_sharedAdminPromise.set(this, void 0);
         const { logger, address, name, producer } = arg, kafkaConfig = tslib_1.__rest(arg, ["logger", "address", "name", "producer"]);
         tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_config, kafkaConfig, "f");
         tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_producerConfig, producer, "f");
@@ -34,7 +60,7 @@ class KafkaMessaging {
         if (!tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_config, "f").brokers)
             return;
         return new kafkajs_1.Kafka(Object.assign({ logCreator: () => ({ namespace, level, label, log }) => {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _f;
                 let lvl = level;
                 if (!log[level])
                     lvl = null;
@@ -53,16 +79,109 @@ class KafkaMessaging {
                         (_d = this.logger) === null || _d === void 0 ? void 0 : _d.debug('KAFKA', label, namespace, log.message);
                         break;
                     default:
-                        (_e = this.logger) === null || _e === void 0 ? void 0 : _e.silly('KAFKA', label, namespace, log.message);
+                        (_f = this.logger) === null || _f === void 0 ? void 0 : _f.silly('KAFKA', label, namespace, log.message);
                 }
             } }, tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_config, "f")));
     }
+    /**
+     * Internal method to initialize the shared admin.
+     * @private
+     */
+    _initializeSharedAdmin() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdmin, "f")) {
+                return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdmin, "f");
+            }
+            const admin = yield this.createAdmin();
+            if (!admin)
+                return;
+            tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_sharedAdmin, admin, "f");
+            admin.on(admin.events.DISCONNECT, () => {
+                if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdmin, "f") === admin) {
+                    tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_sharedAdmin, undefined, "f");
+                }
+            });
+            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.debug('✔️  Shared admin connected');
+            return admin;
+        });
+    }
+    /**
+     * Internal method to initialize the producer.
+     * @private
+     */
+    _initializeProducer() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Double-check in case producer was created while waiting
+            if (this.producer) {
+                return this.producer;
+            }
+            const producer = yield this.createProducer(tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producerConfig, "f"));
+            if (!producer)
+                return;
+            const producerId = (0, crypto_1.randomBytes)(16).toString('hex');
+            this.producer = producer;
+            this.currentProducerId = producerId;
+            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.debug('✔️  Producer connected');
+            producer.on(producer.events.DISCONNECT, () => {
+                var _a;
+                if (this.currentProducerId === producerId) {
+                    (_a = this.logger) === null || _a === void 0 ? void 0 : _a.warn('⚠️  Producer disconnected');
+                    this.producer = undefined;
+                    this.currentProducerId = undefined;
+                }
+            });
+            return producer;
+        });
+    }
     getKafka() {
         if (!this.kafka) {
             this.kafka = this._createInstance();
         }
         return this.kafka;
     }
+    /**
+     * 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
+     */
+    getSharedAdmin() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // Return existing admin if available and connected
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdmin, "f")) {
+                return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdmin, "f");
+            }
+            // If an admin is already being created, wait for it
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdminPromise, "f")) {
+                return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdminPromise, "f");
+            }
+            // Create the admin with a lock
+            tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_sharedAdminPromise, this._initializeSharedAdmin(), "f");
+            try {
+                const admin = yield tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_sharedAdminPromise, "f");
+                return admin;
+            }
+            finally {
+                tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_sharedAdminPromise, undefined, "f");
+            }
+        });
+    }
+    /**
+     * 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) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             // Get kafka instance
@@ -79,6 +198,26 @@ class KafkaMessaging {
             return admin;
         });
     }
+    /**
+     * 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, config) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             const admin = yield this.createAdmin();
@@ -128,10 +267,42 @@ class KafkaMessaging {
         });
     }
     /**
-     * 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) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const admin = yield this.getSharedAdmin();
+            if (!admin)
+                return;
+            try {
+                const partitions = yield admin.fetchTopicOffsets(topic);
+                return partitions;
+            }
+            catch (error) {
+                (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`Failed to fetch offsets for topic "${topic}":`, error);
+                return 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, config) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -158,9 +329,18 @@ class KafkaMessaging {
         });
     }
     /**
-     * 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) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -192,33 +372,37 @@ class KafkaMessaging {
         });
     }
     /**
-     * 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() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a;
-            if (!this.producer) {
-                const producer = yield this.createProducer(tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producerConfig, "f"));
-                if (!producer)
-                    return;
-                const producerId = (0, crypto_1.randomBytes)(16).toString('hex');
-                this.producer = producer;
-                this.currentProducerId = producerId;
-                (_a = this.logger) === null || _a === void 0 ? void 0 : _a.debug('✔️  Producer connected');
-                producer.on(producer.events.DISCONNECT, () => {
-                    var _a;
-                    if (this.currentProducerId === producerId) {
-                        (_a = this.logger) === null || _a === void 0 ? void 0 : _a.warn('⚠️  Producer disconnected');
-                        this.producer = undefined;
-                        this.currentProducerId = undefined;
-                    }
-                });
+            // Return existing producer if available
+            if (this.producer) {
+                return this.producer;
+            }
+            // If a producer is already being created, wait for it
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producerPromise, "f")) {
+                return tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producerPromise, "f");
+            }
+            // Create the producer with a lock
+            tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_producerPromise, this._initializeProducer(), "f");
+            try {
+                const producer = yield tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_producerPromise, "f");
+                return producer;
+            }
+            finally {
+                // Clear the promise after resolution (success or failure)
+                tslib_1.__classPrivateFieldSet(this, _KafkaMessaging_producerPromise, undefined, "f");
             }
-            return this.producer;
         });
     }
     /**
-     * Disconnect the producer
+     * Disconnects the singleton producer instance.
+     *
+     * @returns A promise that resolves when the producer is disconnected
      */
     disconnectProducer() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -229,9 +413,86 @@ class KafkaMessaging {
             }
         });
     }
+    /**
+     * 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(topic, messages) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (!messages.length)
+                return;
+            const producer = yield this.getProducer();
+            // If we don't have a producer, abort
+            if (!producer)
+                return (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error('❌  Could not get producer');
+            const baseHeaders = {};
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_name, "f"))
+                baseHeaders.name = tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_name, "f");
+            if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_address, "f"))
+                baseHeaders.address = tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_address, "f");
+            const kafkaMessages = messages.map((msg) => {
+                var _a;
+                return ({
+                    value: (msg.value instanceof Buffer ?
+                        msg.value : typeof msg.value === 'string' ?
+                        msg.value : (msg.value === null ? null : JSON.stringify(msg.value))),
+                    key: msg.key,
+                    partition: msg.partition,
+                    timestamp: `${Date.now()}`,
+                    headers: Object.assign(Object.assign({}, baseHeaders), ((_a = msg.headers) !== null && _a !== void 0 ? _a : {})),
+                });
+            });
+            try {
+                const res = yield producer.send({
+                    topic,
+                    messages: kafkaMessages,
+                });
+                (_b = this.logger) === null || _b === void 0 ? void 0 : _b.verbose(`📤  Sent batch to KAFKA topic "${topic}" (${messages.length} messages, offset ${res[0].baseOffset})`);
+            }
+            catch (error) {
+                (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error(`❌  Failed to publish batch to "${topic}":`, error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * 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(topic, message) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c;
             // Get kafka producer
             const producer = yield this.getProducer();
             // If we don't have a producer, abort
@@ -244,20 +505,59 @@ class KafkaMessaging {
             if (tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_address, "f")) {
                 headers.address = tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_address, "f");
             }
-            // Listen to the topic
-            const res = yield producer.send({
-                topic,
-                messages: [{
-                        value: JSON.stringify(message),
-                        timestamp: `${Date.now()}`,
-                        headers
-                    }],
-            });
-            (_b = this.logger) === null || _b === void 0 ? void 0 : _b.verbose(`📤  Sent to KAFKA topic "${topic}" (offset ${res[0].baseOffset})`);
+            try {
+                // Send message to the topic
+                const res = yield producer.send({
+                    topic,
+                    messages: [{
+                            value: (message instanceof Buffer ?
+                                message : typeof message === 'string' ?
+                                message : (message === null ? null : JSON.stringify(message))),
+                            timestamp: `${Date.now()}`,
+                            headers
+                        }],
+                });
+                (_b = this.logger) === null || _b === void 0 ? void 0 : _b.verbose(`📤  Sent to KAFKA topic "${topic}" (offset ${res[0].baseOffset})`);
+            }
+            catch (error) {
+                (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error(`❌  Failed to publish to "${topic}":`, error);
+                throw error;
+            }
         });
     }
     /**
-     * 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(topic, handler, config) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -266,46 +566,51 @@ class KafkaMessaging {
             let consumerConfig;
             let fromBeginning;
             let onReady;
+            let groupId;
+            let groupIdPrefix;
+            let logOffsets = false;
+            let onError;
             if (config) {
-                const { fromBeginning: tmpFromBeginning, onReady: tmpOnReady } = config, tmpConsumerConfig = tslib_1.__rest(config, ["fromBeginning", "onReady"]);
+                const { fromBeginning: tmpFromBeginning, onReady: tmpOnReady, groupId: tmpGroupId, groupIdPrefix: tmpGroupIdPrefix, logOffsets: tmpLogOffsets, onError: tmpOnError } = config, tmpConsumerConfig = tslib_1.__rest(config, ["fromBeginning", "onReady", "groupId", "groupIdPrefix", "logOffsets", "onError"]);
                 fromBeginning = tmpFromBeginning;
                 onReady = tmpOnReady;
+                groupId = tmpGroupId;
+                groupIdPrefix = tmpGroupIdPrefix;
+                logOffsets = tmpLogOffsets !== null && tmpLogOffsets !== void 0 ? tmpLogOffsets : false;
+                onError = tmpOnError;
                 consumerConfig = tmpConsumerConfig;
             }
+            // Determine the consumer group ID
+            const resolvedGroupId = groupId !== null && groupId !== void 0 ? groupId : `${(_b = groupIdPrefix !== null && groupIdPrefix !== void 0 ? groupIdPrefix : tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_name, "f")) !== null && _b !== void 0 ? _b : 'group'}.${topic}`;
             // Get kafka consumer
-            const consumer = yield this.createConsumer(`${tslib_1.__classPrivateFieldGet(this, _KafkaMessaging_name, "f") || 'group'}---${topic}`, consumerConfig);
+            const consumer = yield this.createConsumer(resolvedGroupId, consumerConfig);
             // If we don't have a consumer, abort
             if (!consumer)
-                return (_b = this.logger) === null || _b === void 0 ? void 0 : _b.error('❌  Could not get consumer');
+                return (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error('❌  Could not get consumer');
             // Listen to the topic
             yield consumer.subscribe({
                 topic,
                 fromBeginning
             });
-            const admin = yield this.createAdmin();
-            if (admin) {
-                try {
-                    const partitions = yield admin.fetchTopicOffsets(topic);
-                    if (partitions) {
-                        partitions.forEach((partition) => {
-                            var _a;
-                            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.info(`👂  Start "${topic}" partition: ${partition.partition} | offset: ${partition.offset} | high: ${partition.high} | low: ${partition.low}`);
-                        });
-                    }
+            // Only fetch offsets if explicitly requested (avoids admin overhead)
+            if (logOffsets) {
+                const partitions = yield this.fetchTopicOffsets(topic);
+                if (partitions) {
+                    partitions.forEach((partition) => {
+                        var _a;
+                        (_a = this.logger) === null || _a === void 0 ? void 0 : _a.info(`👂  Start "${topic}" partition: ${partition.partition} | offset: ${partition.offset} | high: ${partition.high} | low: ${partition.low}`);
+                    });
                 }
-                catch (error) {
-                    (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error(error);
-                }
-                yield admin.disconnect();
             }
             yield consumer.run({
                 eachBatchAutoResolve: false,
                 eachBatch: (_a) => tslib_1.__awaiter(this, [_a], void 0, function* ({ batch, resolveOffset, heartbeat, }) {
-                    var _b, _c, _d, _e, _f, _g;
+                    var _b, _c, _d, _f, _g, _h, _j;
                     (_b = this.logger) === null || _b === void 0 ? void 0 : _b.verbose(`📥  Received from KAFKA topic "${topic}" (${batch.messages.length} messages)`);
                     for (const message of batch.messages) {
+                        const context = {};
+                        let value = message.value;
                         try {
-                            const context = {};
                             try {
                                 // unbufferize header values
                                 Object.keys((message.headers || {})).forEach(key => {
@@ -320,14 +625,34 @@ class KafkaMessaging {
                             catch (e) {
                                 (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error(`KafkaMessaging.subscribe('${topic}', …) error:`, e);
                             }
-                            const res = handler(JSON.parse(((_e = (_d = message.value) === null || _d === void 0 ? void 0 : _d.toString) === null || _e === void 0 ? void 0 : _e.call(_d)) || ''), context);
+                            const tmpValue = ((_f = (_d = message.value) === null || _d === void 0 ? void 0 : _d.toString) === null || _f === void 0 ? void 0 : _f.call(_d)) || null;
+                            if (tmpValue) {
+                                try {
+                                    value = JSON.parse(tmpValue);
+                                }
+                                catch (_e) {
+                                    // not important - keep original value
+                                }
+                            }
+                            const res = handler(value, context);
                             if (res)
                                 yield res;
                             resolveOffset(message.offset);
-                            (_f = this.logger) === null || _f === void 0 ? void 0 : _f.debug(`✔️  Resolved offset ${message.offset} from KAFKA topic "${topic}"`);
+                            (_g = this.logger) === null || _g === void 0 ? void 0 : _g.debug(`✔️  Resolved offset ${message.offset} from KAFKA topic "${topic}"`);
                         }
                         catch (e) {
-                            (_g = this.logger) === null || _g === void 0 ? void 0 : _g.error(`KafkaMessaging.subscribe('${topic}', …) handler throwed an error:`, e);
+                            (_h = this.logger) === null || _h === void 0 ? void 0 : _h.error(`KafkaMessaging.subscribe('${topic}', …) handler throwed an error:`, e);
+                            // Call custom error handler if provided
+                            if (onError) {
+                                try {
+                                    const errorResult = onError(e, value, context);
+                                    if (errorResult)
+                                        yield errorResult;
+                                }
+                                catch (onErrorError) {
+                                    (_j = this.logger) === null || _j === void 0 ? void 0 : _j.error(`KafkaMessaging.subscribe('${topic}', …) onError callback failed:`, onErrorError);
+                                }
+                            }
                         }
                         yield heartbeat();
                     }
@@ -336,14 +661,39 @@ class KafkaMessaging {
             onReady === null || onReady === void 0 ? void 0 : onReady(consumer);
         });
     }
+    /**
+     * 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_1) {
         return tslib_1.__awaiter(this, arguments, void 0, function* (client, timeoutMs = 5000) {
             return safeDisconnect(client, timeoutMs);
         });
     }
+    /**
+     * 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() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _f, _g;
             let errorCount = 0;
             let successProducers = 0;
             let successConsumers = 0;
@@ -381,8 +731,8 @@ class KafkaMessaging {
                     errorCount++;
                 }
             }
-            (_e = this.logger) === null || _e === void 0 ? void 0 : _e.info('KafkaMessaging shutdown complete');
-            (_f = this.logger) === null || _f === void 0 ? void 0 : _f.info(`Disconnected ${successProducers} producers, ${successConsumers} consumers and ${successAdmins} admins with ${errorCount} errors.`);
+            (_f = this.logger) === null || _f === void 0 ? void 0 : _f.info('KafkaMessaging shutdown complete');
+            (_g = this.logger) === null || _g === void 0 ? void 0 : _g.info(`Disconnected ${successProducers} producers, ${successConsumers} consumers and ${successAdmins} admins with ${errorCount} errors.`);
             return {
                 successProducers,
                 successConsumers,
@@ -393,7 +743,15 @@ class KafkaMessaging {
     }
 }
 exports.KafkaMessaging = KafkaMessaging;
-_KafkaMessaging_config = new WeakMap(), _KafkaMessaging_producerConfig = new WeakMap(), _KafkaMessaging_address = new WeakMap(), _KafkaMessaging_name = new WeakMap(), _KafkaMessaging_consumers = new WeakMap(), _KafkaMessaging_producers = new WeakMap(), _KafkaMessaging_admins = new WeakMap();
+_KafkaMessaging_config = new WeakMap(), _KafkaMessaging_producerConfig = new WeakMap(), _KafkaMessaging_address = new WeakMap(), _KafkaMessaging_name = new WeakMap(), _KafkaMessaging_consumers = new WeakMap(), _KafkaMessaging_producers = new WeakMap(), _KafkaMessaging_admins = new WeakMap(), _KafkaMessaging_producerPromise = new WeakMap(), _KafkaMessaging_sharedAdmin = new WeakMap(), _KafkaMessaging_sharedAdminPromise = new WeakMap();
+/**
+ * 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
+ */
 function safeDisconnect(client_1) {
     return tslib_1.__awaiter(this, arguments, void 0, function* (client, timeoutMs = 5000) {
         return Promise.race([