@opra/nestjs 1.26.3 → 1.26.4

package/README.md

@@ -1,3 +1,26 @@
-# OPRA
+# @opra/nestjs
 
-Open Protocol for Restful Api
+[![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/nestjs
+[npm-url]: https://npmjs.org/package/@opra/nestjs
+[downloads-image]: https://img.shields.io/npm/dm/@opra/nestjs.svg
+[downloads-url]: https://npmjs.org/package/@opra/nestjs
+[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/nestjs.augmentation.js

@@ -3,6 +3,7 @@ import { ExternalExceptionFilter } from '@nestjs/core/exceptions/external-except
 import { classes, } from '@opra/common';
 var WSControllerDecoratorFactory = classes.WSControllerDecoratorFactory;
 const { MQControllerDecoratorFactory } = classes;
+/* Augment ExternalExceptionFilter to prevent error logging for Opra controllers */
 const oldCatchMethod = ExternalExceptionFilter.prototype.catch;
 ExternalExceptionFilter.prototype.catch = function (exception, host) {
     const opraContext = host.getArgByIndex(3);
@@ -11,11 +12,13 @@ ExternalExceptionFilter.prototype.catch = function (exception, host) {
         throw exception;
     oldCatchMethod(exception, host);
 };
+/* Augment MQControllerDecoratorFactory to automatically apply @Controller() decorator */
 MQControllerDecoratorFactory.augment((decorator, decoratorChain) => {
     decoratorChain.push((_, target) => {
         Controller()(target);
     });
 });
+/* Augment WSControllerDecoratorFactory to automatically apply @Controller() decorator */
 WSControllerDecoratorFactory.augment((decorator, decoratorChain) => {
     decoratorChain.push((_, target) => {
         Controller()(target);

package/constants.d.ts

@@ -1 +1,4 @@
+/**
+ * Metadata key for marking controllers or methods as public.
+ */
 export declare const IS_PUBLIC_KEY = "opra:isPublic";

package/constants.js

@@ -1 +1,4 @@
+/**
+ * Metadata key for marking controllers or methods as public.
+ */
 export const IS_PUBLIC_KEY = 'opra:isPublic';

package/decorators/public.decorator.d.ts

@@ -1 +1,4 @@
+/**
+ * Decorator that marks a controller or method as public.
+ */
 export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;

package/decorators/public.decorator.js

@@ -1,3 +1,6 @@
 import { SetMetadata } from '@nestjs/common';
 import { IS_PUBLIC_KEY } from '../constants.js';
+/**
+ * Decorator that marks a controller or method as public.
+ */
 export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/mq-controller.factory.d.ts

@@ -1,4 +1,7 @@
 import { RpcControllerFactory } from './rpc-controller.factory.js';
+/**
+ * Factory class that wraps Opra Message Queue controllers into NestJS controllers.
+ */
 export declare class MQControllerFactory extends RpcControllerFactory {
     protected _metadataKey: symbol;
 }

package/mq-controller.factory.js

@@ -1,5 +1,8 @@
 import { MQ_CONTROLLER_METADATA } from '@opra/common';
 import { RpcControllerFactory } from './rpc-controller.factory.js';
+/**
+ * Factory class that wraps Opra Message Queue controllers into NestJS controllers.
+ */
 export class MQControllerFactory extends RpcControllerFactory {
     _metadataKey = MQ_CONTROLLER_METADATA;
 }

package/opra-nest-utils.d.ts

@@ -1,4 +1,14 @@
 import type { Type } from '@nestjs/common';
+/**
+ * Utility class for Opra-NestJS integration.
+ */
 export declare class OpraNestUtils {
+    /**
+     * Copies Opra-related decorator metadata from source classes to a target class.
+     * Also merges NestJS guards, interceptors, and exception filters.
+     *
+     * @param target - The target class to receive the metadata.
+     * @param source - The source classes to copy metadata from.
+     */
     static copyDecoratorMetadata(target: Type, ...source: Type[]): void;
 }

package/opra-nest-utils.js

@@ -1,7 +1,17 @@
 const GUARDS_METADATA = '__guards__';
 const INTERCEPTORS_METADATA = '__interceptors__';
 const EXCEPTION_FILTERS_METADATA = '__exceptionFilters__';
+/**
+ * Utility class for Opra-NestJS integration.
+ */
 export class OpraNestUtils {
+    /**
+     * Copies Opra-related decorator metadata from source classes to a target class.
+     * Also merges NestJS guards, interceptors, and exception filters.
+     *
+     * @param target - The target class to receive the metadata.
+     * @param source - The source classes to copy metadata from.
+     */
     static copyDecoratorMetadata(target, ...source) {
         for (const parent of source) {
             const metadataKeys = Reflect.getOwnMetadataKeys(parent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/nestjs",
-  "version": "1.26.3",
+  "version": "1.26.4",
   "description": "Opra NestJS module",
   "author": "Panates",
   "license": "MIT",
@@ -10,8 +10,8 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.3",
-    "@opra/core": "^1.26.3",
+    "@opra/common": "^1.26.4",
+    "@opra/core": "^1.26.4",
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
     "@nestjs/microservices": "^10.0.0 || ^11.0.0"

package/rpc-controller.factory.d.ts

@@ -3,6 +3,9 @@ import { ModulesContainer } from '@nestjs/core';
 import { ExternalContextCreator } from '@nestjs/core/helpers/external-context-creator.js';
 import type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper.js';
 import type { Module } from '@nestjs/core/injector/module.js';
+/**
+ * Factory class that wraps Opra controllers into NestJS controllers.
+ */
 export declare class RpcControllerFactory {
     private readonly modulesContainer;
     private readonly externalContextCreator;
@@ -11,9 +14,37 @@ export declare class RpcControllerFactory {
     private readonly paramsFactory;
     private readonly injector;
     constructor(modulesContainer: ModulesContainer, externalContextCreator: ExternalContextCreator);
+    /**
+     * Wraps and returns the controllers as NestJS compatible classes.
+     *
+     * @returns An array of NestJS compatible controller classes.
+     */
     wrapControllers(): Type[];
+    /**
+     * Creates a context callback for a controller method.
+     *
+     * @param instance - The controller instance.
+     * @param wrapper - The instance wrapper.
+     * @param moduleRef - The module reference.
+     * @param methodName - The name of the method to wrap.
+     * @param isRequestScoped - Whether the controller is request-scoped.
+     * @param contextType - The NestJS context type.
+     * @param options - Optional external context options.
+     * @returns A callback function that handles the execution context.
+     */
     private _createContextCallback;
+    /**
+     * Registers a context provider for the given request and context ID.
+     *
+     * @param request - The request object (Opra execution context).
+     * @param contextId - The NestJS context ID.
+     */
     private registerContextProvider;
+    /**
+     * Explores and returns all Opra controllers within the NestJS application.
+     *
+     * @returns An array of objects containing the module and instance wrapper for each controller.
+     */
     exploreControllers(): {
         module: Module;
         wrapper: InstanceWrapper;

package/rpc-controller.factory.js

@@ -9,6 +9,9 @@ import { PARAM_ARGS_METADATA } from '@nestjs/microservices/constants.js';
 import { RPC_CONTROLLER_METADATA } from '@opra/common';
 import { OpraNestUtils } from './opra-nest-utils.js';
 import { RpcParamsFactory } from './rpc-params.factory.js';
+/**
+ * Factory class that wraps Opra controllers into NestJS controllers.
+ */
 let RpcControllerFactory = class RpcControllerFactory {
     modulesContainer;
     externalContextCreator;
@@ -20,6 +23,11 @@ let RpcControllerFactory = class RpcControllerFactory {
         this.modulesContainer = modulesContainer;
         this.externalContextCreator = externalContextCreator;
     }
+    /**
+     * Wraps and returns the controllers as NestJS compatible classes.
+     *
+     * @returns An array of NestJS compatible controller classes.
+     */
     wrapControllers() {
         const out = [];
         for (const { module, wrapper } of this.exploreControllers()) {
@@ -27,12 +35,12 @@ let RpcControllerFactory = class RpcControllerFactory {
             const sourceClass = instance.constructor;
             const metadata = Reflect.getMetadata(this._metadataKey, sourceClass);
             const isRequestScoped = !wrapper.isDependencyTreeStatic();
-            /** Create a new controller class */
+            /* Create a new controller class */
             const newClass = {
                 [sourceClass.name]: class extends sourceClass {
                 },
             }[sourceClass.name];
-            /** Copy metadata keys from source class to new one */
+            /* Copy metadata keys from source class to new one */
             OpraNestUtils.copyDecoratorMetadata(newClass, sourceClass);
             Controller()(newClass);
             out.push(newClass);
@@ -46,6 +54,18 @@ let RpcControllerFactory = class RpcControllerFactory {
         }
         return out;
     }
+    /**
+     * Creates a context callback for a controller method.
+     *
+     * @param instance - The controller instance.
+     * @param wrapper - The instance wrapper.
+     * @param moduleRef - The module reference.
+     * @param methodName - The name of the method to wrap.
+     * @param isRequestScoped - Whether the controller is request-scoped.
+     * @param contextType - The NestJS context type.
+     * @param options - Optional external context options.
+     * @returns A callback function that handles the execution context.
+     */
     _createContextCallback(instance, wrapper, moduleRef, methodName, isRequestScoped, contextType, options) {
         const paramsFactory = this.paramsFactory;
         if (isRequestScoped) {
@@ -65,6 +85,12 @@ let RpcControllerFactory = class RpcControllerFactory {
         }
         return this.externalContextCreator.create(instance, instance[methodName], methodName, PARAM_ARGS_METADATA, paramsFactory, undefined, undefined, options, contextType);
     }
+    /**
+     * Registers a context provider for the given request and context ID.
+     *
+     * @param request - The request object (Opra execution context).
+     * @param contextId - The NestJS context ID.
+     */
     registerContextProvider(request, contextId) {
         if (!this._coreModuleRef) {
             const coreModuleArray = [...this.modulesContainer.entries()]
@@ -84,6 +110,11 @@ let RpcControllerFactory = class RpcControllerFactory {
             isResolved: true,
         });
     }
+    /**
+     * Explores and returns all Opra controllers within the NestJS application.
+     *
+     * @returns An array of objects containing the module and instance wrapper for each controller.
+     */
     exploreControllers() {
         const scannedModules = new Set();
         const controllers = new Set();

package/rpc-params.factory.d.ts

@@ -1,4 +1,15 @@
 import type { ParamsFactory } from '@nestjs/core/helpers/external-context-creator.js';
+/**
+ * Factory class that provides parameters for NestJS RPC controllers.
+ */
 export declare class RpcParamsFactory implements ParamsFactory {
+    /**
+     * Exchanges a metadata key for a value from the arguments.
+     *
+     * @param type - The metadata type.
+     * @param data - The metadata data.
+     * @param args - The arguments array.
+     * @returns The first argument if available, otherwise null.
+     */
     exchangeKeyForValue(type: number, data: any, args: any): any;
 }

package/rpc-params.factory.js

@@ -1,4 +1,15 @@
+/**
+ * Factory class that provides parameters for NestJS RPC controllers.
+ */
 export class RpcParamsFactory {
+    /**
+     * Exchanges a metadata key for a value from the arguments.
+     *
+     * @param type - The metadata type.
+     * @param data - The metadata data.
+     * @param args - The arguments array.
+     * @returns The first argument if available, otherwise null.
+     */
     exchangeKeyForValue(type, data, args) {
         if (!args) {
             return null;

package/ws-controller.factory.d.ts

@@ -1,4 +1,7 @@
 import { RpcControllerFactory } from './rpc-controller.factory.js';
+/**
+ * Factory class that wraps Opra WebSocket controllers into NestJS controllers.
+ */
 export declare class WSControllerFactory extends RpcControllerFactory {
     protected _metadataKey: symbol;
 }

package/ws-controller.factory.js

@@ -1,5 +1,8 @@
 import { WS_CONTROLLER_METADATA } from '@opra/common';
 import { RpcControllerFactory } from './rpc-controller.factory.js';
+/**
+ * Factory class that wraps Opra WebSocket controllers into NestJS controllers.
+ */
 export class WSControllerFactory extends RpcControllerFactory {
     _metadataKey = WS_CONTROLLER_METADATA;
 }