@opra/nestjs-http 1.26.2 → 1.26.4

package/README.md

@@ -1,3 +1,26 @@
-# OPRA
+# @opra/nestjs-http
 
-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-http
+[npm-url]: https://npmjs.org/package/@opra/nestjs-http
+[downloads-image]: https://img.shields.io/npm/dm/@opra/nestjs-http.svg
+[downloads-url]: https://npmjs.org/package/@opra/nestjs-http
+[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/opra-exception-filter.d.ts

@@ -1,7 +1,21 @@
 import { type ArgumentsHost } from '@nestjs/common';
 import { BaseExceptionFilter, ModuleRef } from '@nestjs/core';
+/**
+ * OpraExceptionFilter
+ *
+ * NestJS exception filter that catches errors during OPRA HTTP requests
+ * and returns responses according to OPRA standards.
+ */
 export declare class OpraExceptionFilter extends BaseExceptionFilter {
     private moduleRef;
     constructor(moduleRef: ModuleRef);
+    /**
+     * Processes the caught exception.
+     * If the request has an OPRA context, it responds by converting the error to the OPRA error format.
+     * Otherwise, it uses the default NestJS exception handling mechanism.
+     *
+     * @param exception - The caught exception object.
+     * @param host - The arguments host.
+     */
     catch(exception: any, host: ArgumentsHost): Promise<void> | undefined;
 }

package/opra-exception-filter.js

@@ -2,12 +2,26 @@ import { __decorate, __metadata } from "tslib";
 import { Catch } from '@nestjs/common';
 import { BaseExceptionFilter, ModuleRef } from '@nestjs/core';
 import { OpraHttpNestjsAdapter } from './opra-http-nestjs-adapter.js';
+/**
+ * OpraExceptionFilter
+ *
+ * NestJS exception filter that catches errors during OPRA HTTP requests
+ * and returns responses according to OPRA standards.
+ */
 let OpraExceptionFilter = class OpraExceptionFilter extends BaseExceptionFilter {
     moduleRef;
     constructor(moduleRef) {
         super();
         this.moduleRef = moduleRef;
     }
+    /**
+     * Processes the caught exception.
+     * If the request has an OPRA context, it responds by converting the error to the OPRA error format.
+     * Otherwise, it uses the default NestJS exception handling mechanism.
+     *
+     * @param exception - The caught exception object.
+     * @param host - The arguments host.
+     */
     catch(exception, host) {
         const ctx = host.switchToHttp().getRequest().opraContext;
         if (ctx) {

package/opra-http-nestjs-adapter.d.ts

@@ -1,13 +1,49 @@
 import { type Type } from '@nestjs/common';
 import { HttpAdapter } from '@opra/http';
+/**
+ * OpraHttpNestjsAdapter
+ *
+ * HTTP adapter used to integrate OPRA APIs with the NestJS framework.
+ * This adapter converts OPRA controllers into NestJS controllers and
+ * exports the OPRA documentation ($schema).
+ */
 export declare class OpraHttpNestjsAdapter extends HttpAdapter {
+    /** List of controller classes to be registered with NestJS */
     readonly nestControllers: Type[];
+    /** Platform identifier */
     readonly platform = "nestjs";
+    /**
+     * Creates a new instance of OpraHttpNestjsAdapter.
+     *
+     * @param options - Adapter configuration options.
+     */
     constructor(options: HttpAdapter.Options & {
+        /** Indicates whether the schema is public */
         schemaIsPublic?: boolean;
+        /** Manually added NestJS controllers */
         controllers?: Type[];
     });
+    /**
+     * Closes the adapter.
+     * @returns {Promise<void>}
+     */
     close(): Promise<void>;
+    /**
+     * Adds the root controller that serves the OPRA schema.
+     *
+     * @param isPublic - Whether the schema is accessible without authentication.
+     * @protected
+     */
     protected _addRootController(isPublic?: boolean): void;
+    /**
+     * Adds the specified class and its sub-controllers to the NestJS controller list.
+     *
+     * @param sourceClass - Source OPRA controller class.
+     * @param currentPath - Current URL path.
+     * @param parentTree - List of parent controller classes.
+     * @protected
+     * @throws {@link NotFoundError} Thrown when no suitable endpoint is found for the operation.
+     * @throws {@link TypeError} Thrown when the controller is not a class.
+     */
     protected _addToNestControllers(sourceClass: Type, currentPath: string, parentTree: Type[]): void;
 }

package/opra-http-nestjs-adapter.js

@@ -6,9 +6,23 @@ import { HTTP_CONTROLLER_METADATA, NotFoundError, } from '@opra/common';
 import { HttpAdapter } from '@opra/http';
 import { OpraNestUtils, Public } from '@opra/nestjs';
 import { asMutable } from 'ts-gems';
+/**
+ * OpraHttpNestjsAdapter
+ *
+ * HTTP adapter used to integrate OPRA APIs with the NestJS framework.
+ * This adapter converts OPRA controllers into NestJS controllers and
+ * exports the OPRA documentation ($schema).
+ */
 export class OpraHttpNestjsAdapter extends HttpAdapter {
+    /** List of controller classes to be registered with NestJS */
     nestControllers = [];
+    /** Platform identifier */
     platform = 'nestjs';
+    /**
+     * Creates a new instance of OpraHttpNestjsAdapter.
+     *
+     * @param options - Adapter configuration options.
+     */
     constructor(options) {
         super(options);
         this._addRootController(options.schemaIsPublic);
@@ -18,9 +32,19 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
             }
         }
     }
+    /**
+     * Closes the adapter.
+     * @returns {Promise<void>}
+     */
     async close() {
         //
     }
+    /**
+     * Adds the root controller that serves the OPRA schema.
+     *
+     * @param isPublic - Whether the schema is accessible without authentication.
+     * @protected
+     */
     _addRootController(isPublic) {
         const _this = this;
         let RootController = class RootController {
@@ -46,16 +70,26 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
         }
         this.nestControllers.push(RootController);
     }
+    /**
+     * Adds the specified class and its sub-controllers to the NestJS controller list.
+     *
+     * @param sourceClass - Source OPRA controller class.
+     * @param currentPath - Current URL path.
+     * @param parentTree - List of parent controller classes.
+     * @protected
+     * @throws {@link NotFoundError} Thrown when no suitable endpoint is found for the operation.
+     * @throws {@link TypeError} Thrown when the controller is not a class.
+     */
     _addToNestControllers(sourceClass, currentPath, parentTree) {
         const metadata = Reflect.getMetadata(HTTP_CONTROLLER_METADATA, sourceClass);
         if (!metadata)
             return;
-        /** 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, ...parentTree);
         Controller()(newClass);
         const newPath = metadata.path
@@ -63,7 +97,7 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
             : currentPath;
         const adapter = this;
         // adapter.logger =
-        /** Disable default error handler. Errors will be handled by OpraExceptionFilter */
+        /* Disable default error handler. Errors will be handled by OpraExceptionFilter */
         adapter.handler.onError = (context, error) => {
             throw error;
         };
@@ -74,7 +108,7 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
                 const operationHandler = sourceClass.prototype[k];
                 Object.defineProperty(newClass.prototype, k, {
                     writable: true,
-                    /** NestJS handler method */
+                    /* NestJS handler method */
                     async value(_req, _res) {
                         _res.statusCode = 200;
                         const api = adapter.document.api;
@@ -90,17 +124,17 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
                                 },
                             });
                         }
-                        /** Configure the HttpContext */
+                        /* Configure the HttpContext */
                         context.__docNode = operation.node;
                         context.__oprDef = operation;
                         context.__contDef = operation.owner;
                         context.__controller = this;
                         context.__handler = operationHandler;
-                        /** Handle request */
+                        /* Handle request */
                         await adapter.handler.handleRequest(context);
                     },
                 });
-                /** Copy metadata keys from source function to new one */
+                /* Copy metadata keys from source function to new one */
                 metadataKeys = Reflect.getOwnMetadataKeys(operationHandler);
                 const newFn = newClass.prototype[k];
                 for (const key of metadataKeys) {
@@ -115,35 +149,35 @@ export class OpraHttpNestjsAdapter extends HttpAdapter {
                     : nodePath.posix.join(newPath, v.path || '');
                 switch (v.method || 'GET') {
                     case 'DELETE':
-                        /** Call @Delete decorator over new property */
+                        /* Call @Delete decorator over new property */
                         Delete(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'GET':
-                        /** Call @Get decorator over new property */
+                        /* Call @Get decorator over new property */
                         Get(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'HEAD':
-                        /** Call @Head decorator over new property */
+                        /* Call @Head decorator over new property */
                         Head(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'OPTIONS':
-                        /** Call @Options decorator over new property */
+                        /* Call @Options decorator over new property */
                         Options(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'PATCH':
-                        /** Call @Patch decorator over new property */
+                        /* Call @Patch decorator over new property */
                         Patch(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'POST':
-                        /** Call @Post decorator over new property */
+                        /* Call @Post decorator over new property */
                         Post(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'PUT':
-                        /** Call @Put decorator over new property */
+                        /* Call @Put decorator over new property */
                         Put(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     case 'SEARCH':
-                        /** Call @Search decorator over new property */
+                        /* Call @Search decorator over new property */
                         Search(operationPath)(newClass.prototype, k, descriptor);
                         break;
                     default:

package/opra-http.module.d.ts

@@ -2,35 +2,66 @@ import { type DynamicModule, Logger, type Type } from '@nestjs/common';
 import type { ApiDocumentFactory } from '@opra/common';
 import type { HttpAdapter } from '@opra/http';
 export declare namespace OpraHttpModule {
+    /**
+     * Synchronous configuration options for OpraHttpModule.
+     */
     export interface ModuleOptions extends BaseModuleOptions, ApiConfig {
     }
+    /**
+     * Asynchronous configuration options for OpraHttpModule.
+     */
     export interface AsyncModuleOptions extends BaseModuleOptions {
+        /** Providers to be injected into the factory function */
         inject?: any[];
+        /** Factory function that returns the ApiConfig object asynchronously */
         useFactory?: (...args: any[]) => Promise<ApiConfig> | ApiConfig;
     }
+    /**
+     * Base configuration options for the module.
+     */
     interface BaseModuleOptions extends Pick<DynamicModule, 'imports' | 'providers' | 'exports' | 'controllers' | 'global'> {
+        /** Custom token for the module */
         token?: any;
+        /** Base path for the API */
         basePath?: string;
+        /** Whether the API schema is public */
         schemaIsPublic?: boolean;
+        /** Interceptor list for the HTTP adapter */
         interceptors?: (HttpAdapter.InterceptorFunction | HttpAdapter.IHttpInterceptor | Type<HttpAdapter.IHttpInterceptor>)[];
     }
+    /**
+     * OPRA API configuration details.
+     */
     export interface ApiConfig extends Pick<ApiDocumentFactory.InitArguments, 'types' | 'references' | 'info'> {
+        /** API name */
         name: string;
+        /** API description */
         description?: string;
+        /** API scope */
         scope?: string;
+        /** Logger to be used */
         logger?: Logger;
     }
     export {};
 }
+/**
+ * OpraHttpModule
+ *
+ * Module that integrates OPRA HTTP support into the NestJS application.
+ */
 export declare class OpraHttpModule {
     /**
+     * Configures the module synchronously and imports it at the root level.
      *
-     * @param init
+     * @param init - Module configuration options.
+     * @returns {DynamicModule} NestJS dynamic module.
      */
     static forRoot(init: OpraHttpModule.ModuleOptions): DynamicModule;
     /**
+     * Configures the module asynchronously and imports it at the root level.
      *
-     * @param options
+     * @param options - Asynchronous module configuration options.
+     * @returns {DynamicModule} NestJS dynamic module.
      */
     static forRootAsync(options: OpraHttpModule.AsyncModuleOptions): DynamicModule;
 }

package/opra-http.module.js

@@ -2,10 +2,17 @@ var OpraHttpModule_1;
 import { __decorate } from "tslib";
 import { Module } from '@nestjs/common';
 import { OpraHttpCoreModule } from './opra-http-core.module.js';
+/**
+ * OpraHttpModule
+ *
+ * Module that integrates OPRA HTTP support into the NestJS application.
+ */
 let OpraHttpModule = OpraHttpModule_1 = class OpraHttpModule {
     /**
+     * Configures the module synchronously and imports it at the root level.
      *
-     * @param init
+     * @param init - Module configuration options.
+     * @returns {DynamicModule} NestJS dynamic module.
      */
     static forRoot(init) {
         return {
@@ -14,8 +21,10 @@ let OpraHttpModule = OpraHttpModule_1 = class OpraHttpModule {
         };
     }
     /**
+     * Configures the module asynchronously and imports it at the root level.
      *
-     * @param options
+     * @param options - Asynchronous module configuration options.
+     * @returns {DynamicModule} NestJS dynamic module.
      */
     static forRootAsync(options) {
         return {

package/opra-middleware.d.ts

@@ -1,8 +1,21 @@
 import { type NestMiddleware } from '@nestjs/common';
 import type { NextFunction, Request, Response } from 'express';
 import { OpraHttpNestjsAdapter } from './opra-http-nestjs-adapter.js';
+/**
+ * OpraMiddleware
+ *
+ * NestJS middleware that creates an OPRA context (HttpContext) for each HTTP request
+ * and adds it to the request.
+ */
 export declare class OpraMiddleware implements NestMiddleware {
     protected opraAdapter: OpraHttpNestjsAdapter;
     constructor(opraAdapter: OpraHttpNestjsAdapter);
+    /**
+     * Processes requests and creates the OPRA context.
+     *
+     * @param req - Express request object.
+     * @param res - Express response object.
+     * @param next - Function that calls the next middleware.
+     */
     use(req: Request, res: Response, next: NextFunction): void;
 }

package/opra-middleware.js

@@ -2,15 +2,28 @@ import { __decorate, __metadata } from "tslib";
 import { Injectable } from '@nestjs/common';
 import { HttpContext, HttpIncoming, HttpOutgoing } from '@opra/http';
 import { OpraHttpNestjsAdapter } from './opra-http-nestjs-adapter.js';
+/**
+ * OpraMiddleware
+ *
+ * NestJS middleware that creates an OPRA context (HttpContext) for each HTTP request
+ * and adds it to the request.
+ */
 let OpraMiddleware = class OpraMiddleware {
     opraAdapter;
     constructor(opraAdapter) {
         this.opraAdapter = opraAdapter;
     }
+    /**
+     * Processes requests and creates the OPRA context.
+     *
+     * @param req - Express request object.
+     * @param res - Express response object.
+     * @param next - Function that calls the next middleware.
+     */
     use(req, res, next) {
         const request = HttpIncoming.from(req);
         const response = HttpOutgoing.from(res);
-        /** Create the HttpContext */
+        /* Create the HttpContext */
         const context = new HttpContext({
             __adapter: this.opraAdapter,
             platform: req.route ? 'express' : 'fastify',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/nestjs-http",
-  "version": "1.26.2",
+  "version": "1.26.4",
   "description": "Opra NestJS Http Module",
   "author": "Panates",
   "license": "MIT",
@@ -9,10 +9,10 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.2",
-    "@opra/core": "^1.26.2",
-    "@opra/nestjs": "^1.26.2",
-    "@opra/http": "^1.26.2",
+    "@opra/common": "^1.26.4",
+    "@opra/core": "^1.26.4",
+    "@opra/nestjs": "^1.26.4",
+    "@opra/http": "^1.26.4",
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0"
   },