@opra/kafka 1.26.2 → 1.26.4

package/README.md

@@ -1,3 +1,26 @@
-# @opra/core
+# @opra/kafka
 
-OPRA schema package.
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+- node >= 20.x
+
+
+## License
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/kafka
+[npm-url]: https://npmjs.org/package/@opra/kafka
+[downloads-image]: https://img.shields.io/npm/dm/@opra/kafka.svg
+[downloads-url]: https://npmjs.org/package/@opra/kafka
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/augmentation/opra-common.augmentation.d.ts

@@ -2,6 +2,12 @@ import '@opra/core';
 import { KafkaAdapter } from '../kafka-adapter.js';
 declare module '@opra/common' {
     interface MQOperationDecorator {
+        /**
+         * Decorator for configuring Kafka-specific options for an MQ operation.
+         *
+         * @param config - The Kafka operation options or a resolver function.
+         * @returns The decorator instance.
+         */
         Kafka(config: KafkaAdapter.OperationOptions | (() => KafkaAdapter.OperationOptions | Promise<KafkaAdapter.OperationOptions>)): this;
     }
 }

package/augmentation/opra-common.augmentation.js

@@ -1,7 +1,7 @@
 import '@opra/core';
 import { classes } from '@opra/common';
 import { KAFKA_OPERATION_METADATA, KAFKA_OPERATION_METADATA_RESOLVER, } from '../constants.js';
-/** Implementation **/
+/* Implementation **/
 classes.MQOperationDecoratorFactory.augment((decorator, decoratorChain) => {
     decorator.Kafka = (config) => {
         decoratorChain.push((_, target, propertyKey) => {

package/kafka-adapter.d.ts

@@ -18,8 +18,9 @@ interface HandlerArguments {
     topics: (string | RegExp)[];
 }
 /**
- *
- * @class KafkaAdapter
+ * Adapter for integrating Kafka into the Opra platform.
+ * It manages Kafka consumers, handles message routing to controllers,
+ * and provides integration with the Opra execution context.
  */
 export declare class KafkaAdapter extends PlatformAdapter<KafkaAdapter.Events> {
     static readonly PlatformName = "kafka";
@@ -33,53 +34,107 @@ export declare class KafkaAdapter extends PlatformAdapter<KafkaAdapter.Events> {
     readonly platform = "kafka";
     readonly interceptors: (KafkaAdapter.InterceptorFunction | KafkaAdapter.IKafkaInterceptor)[];
     /**
+     * Initializes a new instance of the KafkaAdapter.
      *
-     * @param document
-     * @param config
-     * @constructor
+     * @param document - The API document that defines the Kafka services and controllers.
+     * @param config - The configuration options for the Kafka adapter.
+     * @throws {@link TypeError} Throws if the document does not expose a Kafka API.
      */
     constructor(document: ApiDocument, config: KafkaAdapter.Config);
+    /**
+     * Gets the MQ API defined in the document.
+     */
     get api(): MQApi;
+    /**
+     * Gets the Kafka client instance.
+     */
     get kafka(): Kafka;
+    /**
+     * Gets the configuration scope for the adapter.
+     */
     get scope(): string | undefined;
+    /**
+     * Gets the current status of the adapter.
+     */
     get status(): KafkaAdapter.Status;
+    /**
+     * Initializes the Kafka client and all defined consumers.
+     * This method is called automatically by {@link start} if not already initialized.
+     */
     initialize(): Promise<void>;
     /**
-     * Starts the service
+     * Starts the Kafka adapter, connecting all consumers and subscribing to topics.
+     *
+     * @throws {@link Error} Throws if a consumer fails to connect or subscribe.
      */
     start(): Promise<void>;
     /**
-     * Closes all connections and stops the service
+     * Closes all active Kafka consumers and clears internal caches.
+     * This effectively stops the service and returns it to the idle state.
      */
     close(): Promise<void>;
+    /**
+     * Retrieves a controller instance by its path.
+     *
+     * @param controllerPath - The unique path of the controller.
+     * @returns The controller instance or undefined if not found.
+     */
     getControllerInstance<T>(controllerPath: string): T | undefined;
     /**
+     * Resolves the configuration for a specific MQ operation.
      *
-     * @param controller
-     * @param instance
-     * @param operation
+     * @param controller - The MQ controller containing the operation.
+     * @param instance - The actual instance of the controller class.
+     * @param operation - The MQ operation being configured.
+     * @returns A promise that resolves to the operation configuration or undefined if not applicable.
      * @protected
      */
     protected _getOperationConfig(controller: MQController, instance: any, operation: MQOperation): Promise<OperationConfig | undefined>;
     /**
-     *
+     * Creates and prepares all consumers defined in the API document.
      * @protected
      */
     protected _createAllConsumers(): Promise<void>;
     /**
+     * Creates a Rabbitmq consumer for the given handler arguments if it doesn't already exist.
      *
-     * @param args
+     * @param args - The handler arguments containing configuration and state.
+     * @throws {@link Error} Throws if a self-consumer for the group ID already exists.
      * @protected
      */
     protected _createConsumer(args: HandlerArguments): Promise<void>;
     /**
+     * Creates a message handler for a specific MQ operation.
+     * This handler processes incoming Kafka messages, decodes them, and executes the operation.
      *
-     * @param args
+     * @param args - The handler arguments for the operation.
      * @protected
      */
     protected _createHandler(args: HandlerArguments): void;
+    /**
+     * Emits an error event and logs the error.
+     *
+     * @param error - The error that occurred.
+     * @param context - The optional Kafka execution context.
+     * @protected
+     */
     protected _emitError(error: any, context?: KafkaContext): void;
+    /**
+     * Wraps multiple exceptions into an array of {@link OpraException}.
+     *
+     * @param exceptions - The array of exceptions to wrap.
+     * @returns An array of wrapped exceptions.
+     * @protected
+     */
     protected _wrapExceptions(exceptions: any[]): OpraException[];
+    /**
+     * Creates a KafkaJS log creator that redirects logs to the provided logger.
+     *
+     * @param logger - The logger instance to use.
+     * @param logExtra - Whether to include additional metadata in the logs.
+     * @returns A log creator function for KafkaJS.
+     * @protected
+     */
     protected _createLogCreator(logger: ILogger, logExtra?: boolean): ({ namespace, level, log }: {
         namespace: any;
         level: any;
@@ -87,11 +142,20 @@ export declare class KafkaAdapter extends PlatformAdapter<KafkaAdapter.Events> {
     }) => any;
 }
 /**
- * @namespace KafkaAdapter
+ * Namespace for KafkaAdapter related types and interfaces.
  */
 export declare namespace KafkaAdapter {
+    /**
+     * Callback function for the next middleware in the interceptor chain.
+     */
     type NextCallback = () => Promise<any>;
+    /**
+     * Represents the operational status of the Kafka adapter.
+     */
     type Status = 'idle' | 'starting' | 'started';
+    /**
+     * Configuration options for the Kafka adapter.
+     */
     interface Config extends PlatformAdapter.Options {
         client: StrictOmit<KafkaConfig, 'logCreator' | 'logLevel'>;
         consumers?: Record<string, StrictOmit<ConsumerConfig, 'groupId'>>;
@@ -105,25 +169,41 @@ export declare namespace KafkaAdapter {
         interceptors?: (InterceptorFunction | IKafkaInterceptor)[];
         logExtra?: boolean;
     }
+    /**
+     * Options for a specific Kafka operation.
+     */
     interface OperationOptions {
         /**
-         * groupId or ConsumerConfig
+         * Group ID or consumer configuration.
          */
         consumer?: string | ConsumerConfig;
+        /**
+         * Subscription options for the topic.
+         */
         subscribe?: {
             fromBeginning?: boolean;
         };
     }
     /**
-     * @type InterceptorFunction
+     * Type definition for a Kafka interceptor function.
      */
     type InterceptorFunction = IKafkaInterceptor['intercept'];
     /**
-     * @interface IKafkaInterceptor
+     * Interface for a Kafka interceptor class.
      */
-    type IKafkaInterceptor = {
+    interface IKafkaInterceptor {
+        /**
+         * Intercepts the execution of a Kafka operation.
+         *
+         * @param context - The Kafka execution context.
+         * @param next - The next function in the chain.
+         * @returns A promise that resolves to the result of the operation.
+         */
         intercept(context: KafkaContext, next: NextCallback): Promise<any>;
-    };
+    }
+    /**
+     * Event definitions for the Kafka adapter.
+     */
     interface Events {
         error: [error: Error, context: KafkaContext | undefined];
         finish: [context: KafkaContext, result: any];

package/kafka-adapter.js

@@ -10,8 +10,9 @@ const signalTraps = ['SIGTERM', 'SIGINT', 'SIGUSR2'];
 const kGroupId = Symbol('kGroupId');
 const noOp = () => undefined;
 /**
- *
- * @class KafkaAdapter
+ * Adapter for integrating Kafka into the Opra platform.
+ * It manages Kafka consumers, handles message routing to controllers,
+ * and provides integration with the Opra execution context.
  */
 export class KafkaAdapter extends PlatformAdapter {
     static PlatformName = 'kafka';
@@ -24,10 +25,11 @@ export class KafkaAdapter extends PlatformAdapter {
     platform = KafkaAdapter.PlatformName;
     interceptors;
     /**
+     * Initializes a new instance of the KafkaAdapter.
      *
-     * @param document
-     * @param config
-     * @constructor
+     * @param document - The API document that defines the Kafka services and controllers.
+     * @param config - The configuration options for the Kafka adapter.
+     * @throws {@link TypeError} Throws if the document does not expose a Kafka API.
      */
     constructor(document, config) {
         super(config);
@@ -49,18 +51,34 @@ export class KafkaAdapter extends PlatformAdapter {
             process.once(type, () => this.close());
         });
     }
+    /**
+     * Gets the MQ API defined in the document.
+     */
     get api() {
         return this.document.getMqApi();
     }
+    /**
+     * Gets the Kafka client instance.
+     */
     get kafka() {
         return this._kafka;
     }
+    /**
+     * Gets the configuration scope for the adapter.
+     */
     get scope() {
         return this._config.scope;
     }
+    /**
+     * Gets the current status of the adapter.
+     */
     get status() {
         return this._status;
     }
+    /**
+     * Initializes the Kafka client and all defined consumers.
+     * This method is called automatically by {@link start} if not already initialized.
+     */
     async initialize() {
         if (this._kafka)
             return;
@@ -73,7 +91,9 @@ export class KafkaAdapter extends PlatformAdapter {
         await this._createAllConsumers();
     }
     /**
-     * Starts the service
+     * Starts the Kafka adapter, connecting all consumers and subscribing to topics.
+     *
+     * @throws {@link Error} Throws if a consumer fails to connect or subscribe.
      */
     async start() {
         if (this.status !== 'idle')
@@ -81,14 +101,14 @@ export class KafkaAdapter extends PlatformAdapter {
         await this.initialize();
         this._status = 'starting';
         try {
-            /** Connect all consumers */
+            /* Connect all consumers */
             for (const consumer of this._consumers.values()) {
                 await consumer.connect().catch(e => {
                     this._emitError(e);
                     throw e;
                 });
             }
-            /** Subscribe to channels */
+            /* Subscribe to channels */
             for (const args of this._handlerArgs) {
                 const { consumer, operation, operationConfig } = args;
                 args.topics = Array.isArray(operation.channel)
@@ -105,7 +125,7 @@ export class KafkaAdapter extends PlatformAdapter {
                 });
                 this.logger?.info?.(`Subscribed to topic${args.topics.length > 1 ? 's' : ''} "${args.topics}"`);
             }
-            /** Start consumer listeners */
+            /* Start consumer listeners */
             const topicMap = new Map();
             for (const consumer of this._consumers.values()) {
                 const groupId = consumer[kGroupId];
@@ -126,7 +146,7 @@ export class KafkaAdapter extends PlatformAdapter {
                             }
                             topicMap.set(topicCacheKey, handlerArgsArray);
                         }
-                        /** Iterate and call all matching handlers */
+                        /* Iterate and call all matching handlers */
                         for (const args of handlerArgsArray) {
                             try {
                                 await args.handler(payload);
@@ -150,7 +170,8 @@ export class KafkaAdapter extends PlatformAdapter {
         }
     }
     /**
-     * Closes all connections and stops the service
+     * Closes all active Kafka consumers and clears internal caches.
+     * This effectively stops the service and returns it to the idle state.
      */
     async close() {
         await Promise.allSettled(Array.from(this._consumers.values()).map(c => c.disconnect()));
@@ -158,15 +179,23 @@ export class KafkaAdapter extends PlatformAdapter {
         this._controllerInstances.clear();
         this._status = 'idle';
     }
+    /**
+     * Retrieves a controller instance by its path.
+     *
+     * @param controllerPath - The unique path of the controller.
+     * @returns The controller instance or undefined if not found.
+     */
     getControllerInstance(controllerPath) {
         const controller = this.api.findController(controllerPath);
         return controller && this._controllerInstances.get(controller);
     }
     /**
+     * Resolves the configuration for a specific MQ operation.
      *
-     * @param controller
-     * @param instance
-     * @param operation
+     * @param controller - The MQ controller containing the operation.
+     * @param instance - The actual instance of the controller class.
+     * @param operation - The MQ operation being configured.
+     * @returns A promise that resolves to the operation configuration or undefined if not applicable.
      * @protected
      */
     async _getOperationConfig(controller, instance, operation) {
@@ -217,7 +246,7 @@ export class KafkaAdapter extends PlatformAdapter {
         return operationConfig;
     }
     /**
-     *
+     * Creates and prepares all consumers defined in the API document.
      * @protected
      */
     async _createAllConsumers() {
@@ -228,7 +257,7 @@ export class KafkaAdapter extends PlatformAdapter {
             if (!instance)
                 continue;
             this._controllerInstances.set(controller, instance);
-            /** Build HandlerData array */
+            /* Build HandlerData array */
             for (const operation of controller.operations.values()) {
                 const operationConfig = await this._getOperationConfig(controller, instance, operation);
                 if (!operationConfig)
@@ -246,14 +275,16 @@ export class KafkaAdapter extends PlatformAdapter {
                 this._handlerArgs.push(args);
             }
         }
-        /** Initialize consumers */
+        /* Initialize consumers */
         for (const args of this._handlerArgs) {
             await this._createConsumer(args);
         }
     }
     /**
+     * Creates a Rabbitmq consumer for the given handler arguments if it doesn't already exist.
      *
-     * @param args
+     * @param args - The handler arguments containing configuration and state.
+     * @throws {@link Error} Throws if a self-consumer for the group ID already exists.
      * @protected
      */
     async _createConsumer(args) {
@@ -262,7 +293,7 @@ export class KafkaAdapter extends PlatformAdapter {
         if (consumer && operationConfig.selfConsumer) {
             throw new Error(`Operation consumer for groupId (${operationConfig.consumer.groupId}) already exists`);
         }
-        /** Create consumers */
+        /* Create consumers */
         if (!consumer) {
             consumer = this.kafka.consumer(operationConfig.consumer);
             consumer[kGroupId] = operationConfig.consumer.groupId;
@@ -271,16 +302,18 @@ export class KafkaAdapter extends PlatformAdapter {
         args.consumer = consumer;
     }
     /**
+     * Creates a message handler for a specific MQ operation.
+     * This handler processes incoming Kafka messages, decodes them, and executes the operation.
      *
-     * @param args
+     * @param args - The handler arguments for the operation.
      * @protected
      */
     _createHandler(args) {
         const { controller, instance, operation } = args;
-        /** Prepare parsers */
+        /* Prepare parsers */
         const parseKey = RequestParser.STRING;
         const parsePayload = RequestParser.STRING;
-        /** Prepare decoders */
+        /* Prepare decoders */
         const decodeKey = operation.generateKeyCodec('decode', {
             scope: this.scope,
             ignoreReadonlyFields: true,
@@ -305,17 +338,17 @@ export class KafkaAdapter extends PlatformAdapter {
             let payload;
             const headers = {};
             try {
-                /** Parse and decode `key` */
+                /* Parse and decode `key` */
                 if (message.key) {
                     const s = parseKey(message.key);
                     key = decodeKey(s);
                 }
-                /** Parse and decode `payload` */
+                /* Parse and decode `payload` */
                 if (message.value != null) {
                     const s = parsePayload(message.value);
                     payload = decodePayload(s);
                 }
-                /** Parse and decode `headers` */
+                /* Parse and decode `headers` */
                 if (message.headers) {
                     for (const [k, v] of Object.entries(message.headers)) {
                         const header = operation.findHeader(k);
@@ -328,7 +361,7 @@ export class KafkaAdapter extends PlatformAdapter {
                 this._emitError(e);
                 return;
             }
-            /** Create context */
+            /* Create context */
             const context = new KafkaContext({
                 __adapter: this,
                 __contDef: controller,
@@ -346,7 +379,7 @@ export class KafkaAdapter extends PlatformAdapter {
             });
             await this.emitAsync('execute', context);
             try {
-                /** Call operation handler */
+                /* Call operation handler */
                 const result = await operationHandler.call(instance, context);
                 await this.emitAsync('finish', context, result);
             }
@@ -355,6 +388,13 @@ export class KafkaAdapter extends PlatformAdapter {
             }
         };
     }
+    /**
+     * Emits an error event and logs the error.
+     *
+     * @param error - The error that occurred.
+     * @param context - The optional Kafka execution context.
+     * @protected
+     */
     _emitError(error, context) {
         Promise.resolve()
             .then(async () => {
@@ -379,12 +419,27 @@ export class KafkaAdapter extends PlatformAdapter {
         })
             .catch(noOp);
     }
+    /**
+     * Wraps multiple exceptions into an array of {@link OpraException}.
+     *
+     * @param exceptions - The array of exceptions to wrap.
+     * @returns An array of wrapped exceptions.
+     * @protected
+     */
     _wrapExceptions(exceptions) {
         const wrappedErrors = exceptions.map(e => e instanceof OpraException ? e : new OpraException(e));
         if (!wrappedErrors.length)
             wrappedErrors.push(new OpraException('Internal Server Error'));
         return wrappedErrors;
     }
+    /**
+     * Creates a KafkaJS log creator that redirects logs to the provided logger.
+     *
+     * @param logger - The logger instance to use.
+     * @param logExtra - Whether to include additional metadata in the logs.
+     * @returns A log creator function for KafkaJS.
+     * @protected
+     */
     _createLogCreator(logger, logExtra) {
         return ({ namespace, level, log }) => {
             const { message, error, ...extra } = log;

package/kafka-context.d.ts

@@ -22,8 +22,9 @@ export declare class KafkaContext extends ExecutionContext implements AsyncEvent
     readonly heartbeat: () => Promise<void>;
     readonly pause: () => void;
     /**
-     * Constructor
-     * @param init the context options
+     * Initializes a new instance of the KafkaContext.
+     *
+     * @param init - The initialization options for the context.
      */
     constructor(init: KafkaContext.Initiator);
 }

package/kafka-context.js

@@ -13,8 +13,9 @@ export class KafkaContext extends ExecutionContext {
     heartbeat;
     pause;
     /**
-     * Constructor
-     * @param init the context options
+     * Initializes a new instance of the KafkaContext.
+     *
+     * @param init - The initialization options for the context.
      */
     constructor(init) {
         super({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/kafka",
-  "version": "1.26.2",
+  "version": "1.26.4",
   "description": "Opra Kafka adapter",
   "author": "Panates",
   "license": "MIT",
@@ -10,8 +10,8 @@
     "valgen": "^6.0.3"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.2",
-    "@opra/core": "^1.26.2",
+    "@opra/common": "^1.26.4",
+    "@opra/core": "^1.26.4",
     "kafkajs": ">=2.2.4 <3"
   },
   "exports": {

package/parsers/binary.parser.d.ts

@@ -1,2 +1,8 @@
 import type { RequestParseFunction } from '../request-parser.js';
+/**
+ * A parser function that returns the input buffer as-is.
+ *
+ * @param buffer - The buffer to be returned.
+ * @returns The original buffer.
+ */
 export declare const binaryParser: RequestParseFunction;

package/parsers/binary.parser.js

@@ -1,3 +1,9 @@
+/**
+ * A parser function that returns the input buffer as-is.
+ *
+ * @param buffer - The buffer to be returned.
+ * @returns The original buffer.
+ */
 export const binaryParser = function (buffer) {
     return buffer;
 };

package/parsers/string.parser.d.ts

@@ -1,2 +1,8 @@
 import type { RequestParseFunction } from '../request-parser.js';
+/**
+ * A parser function that converts the input buffer to a string.
+ *
+ * @param buffer - The buffer to be converted.
+ * @returns The buffer content as a string.
+ */
 export declare const stringParser: RequestParseFunction;

package/parsers/string.parser.js

@@ -1,3 +1,9 @@
+/**
+ * A parser function that converts the input buffer to a string.
+ *
+ * @param buffer - The buffer to be converted.
+ * @returns The buffer content as a string.
+ */
 export const stringParser = function (buffer) {
     return buffer.toString();
 };

package/request-parser.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Type definition for a function that parses a Buffer into a specific format.
+ *
+ * @param buffer - The buffer to be parsed.
+ * @returns The parsed result.
+ */
 export type RequestParseFunction = (buffer: Buffer) => any;
+/**
+ * A registry of pre-defined request parsing functions.
+ */
 export declare const RequestParser: Record<string, RequestParseFunction>;

package/request-parser.js

@@ -1,6 +1,11 @@
 import { binaryParser } from './parsers/binary.parser.js';
 import { stringParser } from './parsers/string.parser.js';
+/**
+ * A registry of pre-defined request parsing functions.
+ */
 export const RequestParser = {
+    /* Parses the buffer as raw binary data (returns the buffer as-is). */
     BINARY: binaryParser,
+    /* Parses the buffer as a UTF-8 string. */
     STRING: stringParser,
 };