@opra/rabbitmq 1.26.3 → 1.27.0

package/README.md

@@ -1,3 +1,26 @@
-# @opra/core
+# @opra/rabbitmq
 
-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/rabbitmq
+[npm-url]: https://npmjs.org/package/@opra/rabbitmq
+[downloads-image]: https://img.shields.io/npm/dm/@opra/rabbitmq.svg
+[downloads-url]: https://npmjs.org/package/@opra/rabbitmq
+[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.js

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

package/config-builder.d.ts

@@ -1,19 +1,40 @@
 import { ApiDocument, MQController, MQOperation } from '@opra/common';
 import type { RabbitmqAdapter } from './rabbitmq-adapter.js';
+/**
+ * Helper class for building RabbitMQ adapter configuration and operation handlers.
+ */
 export declare class ConfigBuilder {
     readonly document: ApiDocument;
     readonly config: RabbitmqAdapter.Config;
     connectionOptions: RabbitmqAdapter.ConnectionOptions;
     controllerInstances: Map<MQController, any>;
     handlerArgs: ConfigBuilder.OperationArguments[];
+    /**
+     * Initializes a new instance of the ConfigBuilder.
+     *
+     * @param document - The API document.
+     * @param config - The adapter configuration.
+     */
     constructor(document: ApiDocument, config: RabbitmqAdapter.Config);
+    /**
+     * Builds the configuration, identifying controller instances and operation handlers.
+     *
+     * @returns A promise that resolves when the build is complete.
+     */
     build(): Promise<void>;
+    /**
+     * Prepares the RabbitMQ connection options from the provided configuration.
+     *
+     * @protected
+     */
     protected _prepareConnectionOptions(): void;
     /**
+     * Resolves the consumer configuration for a specific operation.
      *
-     * @param controller
-     * @param instance
-     * @param operation
+     * @param controller - The MQ controller definition.
+     * @param instance - The controller instance.
+     * @param operation - The MQ operation definition.
+     * @returns A promise that resolves to the consumer configuration or undefined.
      * @protected
      */
     protected _getConsumerConfig(controller: MQController, instance: any, operation: MQOperation): Promise<RabbitmqAdapter.ConsumerConfig | undefined>;

package/config-builder.js

@@ -1,18 +1,32 @@
 import { merge } from '@jsopen/objects';
 import { MQ_CONTROLLER_METADATA, } from '@opra/common';
 import { RMQ_OPERATION_METADATA, RMQ_OPERATION_METADATA_RESOLVER, } from './constants.js';
+/**
+ * Helper class for building RabbitMQ adapter configuration and operation handlers.
+ */
 export class ConfigBuilder {
     document;
     config;
+    /**
+     * Initializes a new instance of the ConfigBuilder.
+     *
+     * @param document - The API document.
+     * @param config - The adapter configuration.
+     */
     constructor(document, config) {
         this.document = document;
         this.config = config;
     }
+    /**
+     * Builds the configuration, identifying controller instances and operation handlers.
+     *
+     * @returns A promise that resolves when the build is complete.
+     */
     async build() {
         this.controllerInstances = new Map();
         this.handlerArgs = [];
         this._prepareConnectionOptions();
-        /** Initialize consumers */
+        /* Initialize consumers */
         for (const controller of this.document.getMqApi().controllers.values()) {
             let instance = controller.instance;
             if (!instance && controller.ctor)
@@ -20,7 +34,7 @@ export class ConfigBuilder {
             if (!instance)
                 continue;
             this.controllerInstances.set(controller, instance);
-            /** Build HandlerData array */
+            /* Build HandlerData array */
             for (const operation of controller.operations.values()) {
                 const consumerConfig = await this._getConsumerConfig(controller, instance, operation);
                 if (!consumerConfig)
@@ -40,6 +54,11 @@ export class ConfigBuilder {
             }
         }
     }
+    /**
+     * Prepares the RabbitMQ connection options from the provided configuration.
+     *
+     * @protected
+     */
     _prepareConnectionOptions() {
         this.connectionOptions = {};
         if (Array.isArray(this.config.connection))
@@ -53,10 +72,12 @@ export class ConfigBuilder {
             ];
     }
     /**
+     * Resolves the consumer configuration for a specific operation.
      *
-     * @param controller
-     * @param instance
-     * @param operation
+     * @param controller - The MQ controller definition.
+     * @param instance - The controller instance.
+     * @param operation - The MQ operation definition.
+     * @returns A promise that resolves to the consumer configuration or undefined.
      * @protected
      */
     async _getConsumerConfig(controller, instance, operation) {

package/constants.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Default group name for RabbitMQ consumers.
+ */
 export declare const RMQ_DEFAULT_GROUP = "default";
+/**
+ * Metadata key for RabbitMQ operation configuration.
+ */
 export declare const RMQ_OPERATION_METADATA = "RMQ_OPERATION_METADATA";
+/**
+ * Metadata key for RabbitMQ operation configuration resolver.
+ */
 export declare const RMQ_OPERATION_METADATA_RESOLVER = "RMQ_OPERATION_METADATA_RESOLVER";

package/constants.js

@@ -1,3 +1,12 @@
+/**
+ * Default group name for RabbitMQ consumers.
+ */
 export const RMQ_DEFAULT_GROUP = 'default';
+/**
+ * Metadata key for RabbitMQ operation configuration.
+ */
 export const RMQ_OPERATION_METADATA = 'RMQ_OPERATION_METADATA';
+/**
+ * Metadata key for RabbitMQ operation configuration resolver.
+ */
 export const RMQ_OPERATION_METADATA_RESOLVER = 'RMQ_OPERATION_METADATA_RESOLVER';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/rabbitmq",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Opra RabbitMQ adapter",
   "author": "Panates",
   "license": "MIT",
@@ -14,8 +14,8 @@
     "valgen": "^6.0.3"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.3",
-    "@opra/core": "^1.26.3",
+    "@opra/common": "^1.27.0",
+    "@opra/core": "^1.27.0",
     "rabbitmq-client": ">=5.0.0 <6"
   },
   "type": "module",

package/rabbitmq-adapter.d.ts

@@ -5,8 +5,10 @@ import type { Envelope, MessageBody } from 'rabbitmq-client/lib/codec.js';
 import { ConfigBuilder } from './config-builder.js';
 import { RabbitmqContext } from './rabbitmq-context.js';
 /**
+ * RabbitMQ platform adapter for Opra.
  *
- * @class RabbitmqAdapter
+ * This adapter handles communication with RabbitMQ, including connection management,
+ * queue subscription, message parsing, and operation execution.
  */
 export declare class RabbitmqAdapter extends PlatformAdapter<RabbitmqAdapter.Events> {
     static readonly PlatformName = "rabbitmq";
@@ -19,33 +21,80 @@ export declare class RabbitmqAdapter extends PlatformAdapter<RabbitmqAdapter.Eve
     readonly platform = "rabbitmq";
     readonly interceptors: (RabbitmqAdapter.InterceptorFunction | RabbitmqAdapter.IRabbitmqInterceptor)[];
     /**
+     * Initializes a new instance of the RabbitmqAdapter.
      *
-     * @param document
-     * @param config
-     * @constructor
+     * @param document - The API document instance.
+     * @param config - Configuration options for the RabbitMQ adapter.
+     * @throws {@link TypeError} Throws if the document does not expose a RabbitMQ API.
      */
     constructor(document: ApiDocument, config: RabbitmqAdapter.Config);
+    /**
+     * Gets the MQ API instance associated with this adapter.
+     */
     get api(): MQApi;
+    /**
+     * Gets the active RabbitMQ connection, if any.
+     */
     get connection(): rabbit.Connection | undefined;
+    /**
+     * Gets the optional scope for this adapter.
+     */
     get scope(): string | undefined;
+    /**
+     * Gets the current status of the adapter.
+     */
     get status(): RabbitmqAdapter.Status;
     /**
-     * Starts the service
+     * Starts the RabbitMQ service by establishing a connection and subscribing to queues.
+     *
+     * @returns A promise that resolves when the service has started.
+     * @throws {@link Error} Throws if the connection or subscription fails.
      */
     start(): Promise<void>;
     /**
-     * Closes all connections and stops the service
+     * Closes all connections and stops the service.
+     *
+     * @returns A promise that resolves when all connections are closed.
      */
     close(): Promise<void>;
+    /**
+     * Retrieves the controller instance for a given path.
+     *
+     * @param controllerPath - The path of the controller.
+     * @returns The controller instance, or undefined if not found.
+     */
     getControllerInstance<T>(controllerPath: string): T | undefined;
     /**
+     * Creates a message handler for a specific operation.
      *
-     * @param args
+     * @param args - Arguments required to create the handler.
+     * @returns A function that processes incoming RabbitMQ messages.
      * @protected
      */
     protected _createHandler(args: ConfigBuilder.OperationArguments): (consumer: rabbit.Consumer, queue: string, message: rabbit.AsyncMessage, _reply: RabbitmqAdapter.ReplyFunction) => Promise<void>;
+    /**
+     * Parses the content of a RabbitMQ message, handling encodings like gzip, deflate, and brotli.
+     *
+     * @param msg - The message to parse.
+     * @returns The parsed content, which may be a string, buffer, or object.
+     * @protected
+     */
     protected _parseContent(msg: rabbit.AsyncMessage): Promise<any>;
+    /**
+     * Emits an error event and logs the error.
+     *
+     * @param error - The error to emit.
+     * @param context - The RabbitMQ context associated with the error.
+     * @protected
+     */
     protected _emitError(error: any, context?: RabbitmqContext): void;
+    /**
+     * Wraps exceptions into OpraException instances.
+     *
+     * @param exceptions - An array of exceptions to wrap.
+     * @returns An array of OpraException instances.
+     * @protected
+     */
     protected _wrapExceptions(exceptions: any[]): OpraException[];
 }
 /**

package/rabbitmq-adapter.js

@@ -18,8 +18,10 @@ const globalErrorTypes = ['unhandledRejection', 'uncaughtException'];
 const signalTraps = ['SIGTERM', 'SIGINT', 'SIGUSR2'];
 const noOp = () => undefined;
 /**
+ * RabbitMQ platform adapter for Opra.
  *
- * @class RabbitmqAdapter
+ * This adapter handles communication with RabbitMQ, including connection management,
+ * queue subscription, message parsing, and operation execution.
  */
 export class RabbitmqAdapter extends PlatformAdapter {
     static PlatformName = 'rabbitmq';
@@ -32,10 +34,11 @@ export class RabbitmqAdapter extends PlatformAdapter {
     platform = RabbitmqAdapter.PlatformName;
     interceptors;
     /**
+     * Initializes a new instance of the RabbitmqAdapter.
      *
-     * @param document
-     * @param config
-     * @constructor
+     * @param document - The API document instance.
+     * @param config - Configuration options for the RabbitMQ adapter.
+     * @throws {@link TypeError} Throws if the document does not expose a RabbitMQ API.
      */
     constructor(document, config) {
         super(config);
@@ -56,20 +59,35 @@ export class RabbitmqAdapter extends PlatformAdapter {
             process.once(type, () => this.close());
         });
     }
+    /**
+     * Gets the MQ API instance associated with this adapter.
+     */
     get api() {
         return this.document.getMqApi();
     }
+    /**
+     * Gets the active RabbitMQ connection, if any.
+     */
     get connection() {
         return this._connection;
     }
+    /**
+     * Gets the optional scope for this adapter.
+     */
     get scope() {
         return this._config.scope;
     }
+    /**
+     * Gets the current status of the adapter.
+     */
     get status() {
         return this._status;
     }
     /**
-     * Starts the service
+     * Starts the RabbitMQ service by establishing a connection and subscribing to queues.
+     *
+     * @returns A promise that resolves when the service has started.
+     * @throws {@link Error} Throws if the connection or subscription fails.
      */
     async start() {
         if (this.status !== 'idle')
@@ -80,13 +98,13 @@ export class RabbitmqAdapter extends PlatformAdapter {
         await configBuilder.build();
         this._connection = new rabbit.Connection(configBuilder.connectionOptions);
         try {
-            /** Establish connection */
+            /* Establish connection */
             await this._connection.onConnect().catch(e => {
                 updateErrorMessage(e, `RabbitMQ connection error. ${e.message}`);
                 throw e;
             });
             this.logger?.info?.(`Connected RabbitMQ at ${configBuilder.connectionOptions.urls}`);
-            /** Subscribe to queues */
+            /* Subscribe to queues */
             const promises = [];
             for (const args of configBuilder.handlerArgs) {
                 for (const queue of args.topics) {
@@ -130,7 +148,9 @@ export class RabbitmqAdapter extends PlatformAdapter {
         }
     }
     /**
-     * Closes all connections and stops the service
+     * Closes all connections and stops the service.
+     *
+     * @returns A promise that resolves when all connections are closed.
      */
     async close() {
         if (this._consumers.length)
@@ -141,18 +161,26 @@ export class RabbitmqAdapter extends PlatformAdapter {
         this._controllerInstances.clear();
         this._status = 'idle';
     }
+    /**
+     * Retrieves the controller instance for a given path.
+     *
+     * @param controllerPath - The 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);
     }
     /**
+     * Creates a message handler for a specific operation.
      *
-     * @param args
+     * @param args - Arguments required to create the handler.
+     * @returns A function that processes incoming RabbitMQ messages.
      * @protected
      */
     _createHandler(args) {
         const { controller, instance, operation } = args;
-        /** Prepare parsers */
+        /* Prepare parsers */
         const decodePayload = operation.generateCodec('decode', {
             scope: this.scope,
             ignoreReadonlyFields: true,
@@ -179,7 +207,7 @@ export class RabbitmqAdapter extends PlatformAdapter {
                 return _reply(body, envelope);
             };
             const headers = {};
-            /** Create context */
+            /* Create context */
             const context = new RabbitmqContext({
                 __adapter: this,
                 __contDef: controller,
@@ -194,7 +222,7 @@ export class RabbitmqAdapter extends PlatformAdapter {
                 reply,
             });
             try {
-                /** Parse and decode `payload` */
+                /* Parse and decode `payload` */
                 let content = await this._parseContent(message);
                 if (content && decodePayload) {
                     if (Buffer.isBuffer(content))
@@ -202,7 +230,7 @@ export class RabbitmqAdapter extends PlatformAdapter {
                     content = decodePayload(content);
                 }
                 // message.properties.
-                /** 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);
@@ -218,7 +246,7 @@ export class RabbitmqAdapter extends PlatformAdapter {
             }
             await this.emitAsync('execute', context).catch(noOp);
             try {
-                /** Call operation handler */
+                /* Call operation handler */
                 const result = await operationHandler.call(instance, context);
                 if (result !== undefined)
                     await reply(result);
@@ -229,6 +257,13 @@ export class RabbitmqAdapter extends PlatformAdapter {
             }
         };
     }
+    /**
+     * Parses the content of a RabbitMQ message, handling encodings like gzip, deflate, and brotli.
+     *
+     * @param msg - The message to parse.
+     * @returns The parsed content, which may be a string, buffer, or object.
+     * @protected
+     */
     async _parseContent(msg) {
         if (!Buffer.isBuffer(msg.body))
             return msg.body;
@@ -273,6 +308,13 @@ export class RabbitmqAdapter extends PlatformAdapter {
         }
         return content;
     }
+    /**
+     * Emits an error event and logs the error.
+     *
+     * @param error - The error to emit.
+     * @param context - The RabbitMQ context associated with the error.
+     * @protected
+     */
     _emitError(error, context) {
         Promise.resolve()
             .then(async () => {
@@ -297,6 +339,13 @@ export class RabbitmqAdapter extends PlatformAdapter {
         })
             .catch(noOp);
     }
+    /**
+     * Wraps exceptions into OpraException instances.
+     *
+     * @param exceptions - An array of exceptions to wrap.
+     * @returns An array of OpraException instances.
+     * @protected
+     */
     _wrapExceptions(exceptions) {
         const wrappedErrors = exceptions.map(e => e instanceof OpraException ? e : new OpraException(e));
         if (!wrappedErrors.length)

package/rabbitmq-context.d.ts

@@ -20,8 +20,9 @@ export declare class RabbitmqContext extends ExecutionContext implements AsyncEv
     readonly headers: Record<string, any>;
     readonly reply: RabbitmqAdapter.ReplyFunction;
     /**
-     * Constructor
-     * @param init the context options
+     * Initializes a new instance of the RabbitmqContext.
+     *
+     * @param init - The initialization options for the context.
      */
     constructor(init: RabbitmqContext.Initiator);
 }

package/rabbitmq-context.js

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