@opra/http 1.26.2 → 1.26.4

package/README.md

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

@@ -1,12 +1,27 @@
 import { ApiDocument, HttpController } from '@opra/common';
 import { type Application } from 'express';
 import { HttpAdapter } from './http-adapter.js';
+/**
+ * ExpressAdapter is a platform adapter for the Express.js framework.
+ * It integrates Opra with Express applications and routers.
+ */
 export declare class ExpressAdapter extends HttpAdapter {
     readonly app: Application;
     protected _controllerInstances: Map<HttpController, any>;
     constructor(app: Application, document: ApiDocument, options?: HttpAdapter.Options);
     get platform(): string;
+    /**
+     * Closes the adapter and performs cleanup.
+     *
+     * @returns A promise that resolves when the adapter is closed.
+     */
     close(): Promise<void>;
+    /**
+     * Retrieves a controller instance by its path.
+     *
+     * @param controllerPath - The path of the controller.
+     * @returns The controller instance, or undefined if not found.
+     */
     getControllerInstance<T>(controllerPath: string): T | undefined;
     protected _initRouter(): void;
     protected _createControllers(controller: HttpController): void;

package/express-adapter.js

@@ -5,6 +5,10 @@ import { HttpAdapter } from './http-adapter.js';
 import { HttpContext } from './http-context.js';
 import { HttpIncoming } from './interfaces/http-incoming.interface.js';
 import { HttpOutgoing } from './interfaces/http-outgoing.interface.js';
+/**
+ * ExpressAdapter is a platform adapter for the Express.js framework.
+ * It integrates Opra with Express applications and routers.
+ */
 export class ExpressAdapter extends HttpAdapter {
     app;
     _controllerInstances = new Map();
@@ -21,6 +25,11 @@ export class ExpressAdapter extends HttpAdapter {
     get platform() {
         return 'express';
     }
+    /**
+     * Closes the adapter and performs cleanup.
+     *
+     * @returns A promise that resolves when the adapter is closed.
+     */
     async close() {
         const processInstance = async (controller) => {
             if (controller.controllers.size) {
@@ -35,6 +44,12 @@ export class ExpressAdapter extends HttpAdapter {
             await processInstance(c);
         this._controllerInstances.clear();
     }
+    /**
+     * Retrieves a controller instance by its 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);
@@ -58,13 +73,13 @@ export class ExpressAdapter extends HttpAdapter {
             await this.emitAsync('createContext', ctx);
             return ctx;
         };
-        /** Add an endpoint that returns document schema */
+        /* Add an endpoint that returns document schema */
         router.get('/\\$schema', (_req, _res, next) => {
             createContext(_req, _res)
                 .then(ctx => this.handler.sendDocumentSchema(ctx).catch(next))
                 .catch(next);
         });
-        /** Add operation endpoints */
+        /* Add operation endpoints */
         if (this.api.controllers.size) {
             const processResource = (controller, currentPath) => {
                 currentPath = nodePath.posix.join(currentPath, controller.path);
@@ -74,7 +89,7 @@ export class ExpressAdapter extends HttpAdapter {
                     const operationHandler = controllerInstance[operation.name];
                     if (!operationHandler)
                         continue;
-                    /** Define router callback */
+                    /* Define router callback */
                     router[operation.method.toLowerCase()](routePath, (_req, _res, _next) => {
                         createContext(_req, _res, {
                             controller,
@@ -98,7 +113,7 @@ export class ExpressAdapter extends HttpAdapter {
             for (const c of this.api.controllers.values())
                 processResource(c, '/');
         }
-        /** Add an endpoint that returns 404 error at last */
+        /* Add an endpoint that returns 404 error at last */
         router.use('/{*splat}', (_req, _res, next) => {
             createContext(_req, _res)
                 .then(ctx => {

package/http-adapter.d.ts

@@ -4,8 +4,10 @@ import { EventMap } from 'node-events-async';
 import { HttpContext } from './http-context.js';
 import { HttpHandler } from './http-handler.js';
 /**
+ * HttpAdapter is the base class for all HTTP platform adapters.
+ * It provides core functionality for handling HTTP requests and managing interceptors.
  *
- * @class HttpAdapter
+ * @abstract
  */
 export declare abstract class HttpAdapter<T extends HttpAdapter.Events = HttpAdapter.Events> extends PlatformAdapter<EventMap<T>> {
     readonly handler: HttpHandler;
@@ -19,11 +21,11 @@ export declare abstract class HttpAdapter<T extends HttpAdapter.Events = HttpAda
 export declare namespace HttpAdapter {
     type NextCallback = () => Promise<void>;
     /**
-     * @type InterceptorFunction
+     * The interceptor function signature.
      */
     type InterceptorFunction = IHttpInterceptor['intercept'];
     /**
-     * @interface IHttpInterceptor
+     * Interface for HTTP interceptors.
      */
     type IHttpInterceptor = {
         intercept(context: HttpContext, next: NextCallback): Promise<void>;

package/http-adapter.js

@@ -1,8 +1,10 @@
 import { PlatformAdapter } from '@opra/core';
 import { HttpHandler } from './http-handler.js';
 /**
+ * HttpAdapter is the base class for all HTTP platform adapters.
+ * It provides core functionality for handling HTTP requests and managing interceptors.
  *
- * @class HttpAdapter
+ * @abstract
  */
 export class HttpAdapter extends PlatformAdapter {
     handler;

package/http-context.d.ts

@@ -21,8 +21,26 @@ export declare class HttpContext extends ExecutionContext {
     readonly queryParams: Record<string, any>;
     errors: Error[];
     constructor(init: HttpContext.Initiator);
+    /**
+     * Checks if the request is a multipart request.
+     */
     get isMultipart(): boolean;
+    /**
+     * Retrieves the multipart reader for the current context.
+     *
+     * @returns A promise that resolves to the multipart reader.
+     * @throws {@link InternalServerError} If the request content is not multipart.
+     * @throws {@link NotAcceptableError} If the endpoint does not accept multipart requests.
+     */
     getMultipartReader(): Promise<MultipartReader>;
+    /**
+     * Retrieves and parses the request body.
+     *
+     * @param args - Optional arguments for body retrieval.
+     * @param args.toFile - Whether to save the body to a file.
+     * @returns A promise that resolves to the parsed body.
+     * @throws {@link BadRequestError} If the body cannot be parsed or validated.
+     */
     getBody<T>(args?: {
         toFile: boolean | string;
     }): Promise<T>;

package/http-context.js

@@ -44,9 +44,19 @@ export class HttpContext extends ExecutionContext {
                 this._multipartReader.purge().catch(() => undefined);
         });
     }
+    /**
+     * Checks if the request is a multipart request.
+     */
     get isMultipart() {
         return !!this.request.is('multipart');
     }
+    /**
+     * Retrieves the multipart reader for the current context.
+     *
+     * @returns A promise that resolves to the multipart reader.
+     * @throws {@link InternalServerError} If the request content is not multipart.
+     * @throws {@link NotAcceptableError} If the endpoint does not accept multipart requests.
+     */
     async getMultipartReader() {
         if (!this.isMultipart)
             throw new InternalServerError('Request content is not a multipart content');
@@ -72,6 +82,14 @@ export class HttpContext extends ExecutionContext {
         this._multipartReader = reader;
         return reader;
     }
+    /**
+     * Retrieves and parses the request body.
+     *
+     * @param args - Optional arguments for body retrieval.
+     * @param args.toFile - Whether to save the body to a file.
+     * @returns A promise that resolves to the parsed body.
+     * @throws {@link BadRequestError} If the body cannot be parsed or validated.
+     */
     async getBody(args) {
         if (this._body !== undefined)
             return this._body;
@@ -79,9 +97,9 @@ export class HttpContext extends ExecutionContext {
             const { request, __oprDef, mediaType } = this;
             if (this.isMultipart) {
                 const reader = await this.getMultipartReader();
-                /** Retrieve all fields */
+                /* Retrieve all fields */
                 const parts = await reader.getAll();
-                /** Filter fields according to configuration */
+                /* Filter fields according to configuration */
                 this._body = [...parts];
                 return this._body;
             }

package/http-handler.d.ts

@@ -18,7 +18,8 @@ export declare namespace HttpHandler {
     }
 }
 /**
- * @class HttpHandler
+ * HttpHandler is responsible for processing incoming HTTP requests.
+ * It handles request parsing, interceptor execution, and response generation.
  */
 export declare class HttpHandler {
     readonly adapter: HttpAdapter;
@@ -26,25 +27,35 @@ export declare class HttpHandler {
     onError?: (context: HttpContext, error: OpraException) => void | Promise<void>;
     constructor(adapter: HttpAdapter);
     /**
-     * Main http request handler
-     * @param context
+     * Main HTTP request handler.
+     *
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the request is handled.
      * @protected
      */
     handleRequest(context: HttpContext): Promise<void>;
     /**
+     * Parses the HTTP request, including parameters and content type.
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the request is parsed.
      */
     parseRequest(context: HttpContext): Promise<void>;
     /**
+     * Parses various HTTP parameters (cookies, headers, path, query).
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when parameters are parsed.
+     * @throws {@link BadRequestError} If parameter validation fails.
      * @protected
      */
     protected _parseParameters(context: HttpContext): Promise<void>;
     /**
+     * Parses and validates the request content type.
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when content type is parsed.
+     * @throws {@link BadRequestError} If the content type is invalid or missing.
      * @protected
      */
     protected _parseContentType(context: HttpContext): Promise<void>;
@@ -55,18 +66,28 @@ export declare class HttpHandler {
      */
     protected _executeRequest(context: HttpContext): Promise<any>;
     /**
+     * Sends an HTTP response back to the client.
      *
-     * @param context
-     * @param responseValue
-     * @protected
+     * @param context - The HTTP execution context.
+     * @param responseValue - The value to be sent in the response body.
+     * @returns A promise that resolves when the response is sent.
      */
     sendResponse(context: HttpContext, responseValue?: any): Promise<void>;
     protected _sendErrorResponse(context: HttpContext): Promise<void>;
+    /**
+     * Sends the document schema as a JSON response.
+     *
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the schema is sent.
+     */
     sendDocumentSchema(context: HttpContext): Promise<void>;
     /**
+     * Determines the response arguments (status code, content type, etc.) for a given response value.
      *
-     * @param context
-     * @param body
+     * @param context - The HTTP execution context.
+     * @param body - The response body.
+     * @returns The determined response arguments.
+     * @throws {@link InternalServerError} If response configuration is missing or invalid.
      * @protected
      */
     protected _determineResponseArgs(context: HttpContext, body: any): HttpHandler.ResponseArgs;

package/http-handler.js

@@ -9,7 +9,8 @@ import { asMutable } from 'ts-gems';
 import { toArray, ValidationError, vg, } from 'valgen';
 import { wrapException } from './utils/wrap-exception.js';
 /**
- * @class HttpHandler
+ * HttpHandler is responsible for processing incoming HTTP requests.
+ * It handles request parsing, interceptor execution, and response generation.
  */
 export class HttpHandler {
     adapter;
@@ -20,8 +21,10 @@ export class HttpHandler {
         this[kAssetCache] = adapter[kAssetCache];
     }
     /**
-     * Main http request handler
-     * @param context
+     * Main HTTP request handler.
+     *
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the request is handled.
      * @protected
      */
     async handleRequest(context) {
@@ -88,15 +91,17 @@ export class HttpHandler {
         }
     }
     /**
+     * Parses the HTTP request, including parameters and content type.
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the request is parsed.
      */
     async parseRequest(context) {
         await this._parseParameters(context);
         await this._parseContentType(context);
         if (context.__oprDef?.requestBody?.immediateFetch)
             await context.getBody();
-        /** Set default status code as the first status code between 200 and 299 */
+        /* Set default status code as the first status code between 200 and 299 */
         if (context.__oprDef) {
             for (const r of context.__oprDef.responses) {
                 const st = r.statusCode.find(sc => sc.start <= 299 && sc.end >= 200);
@@ -108,8 +113,11 @@ export class HttpHandler {
         }
     }
     /**
+     * Parses various HTTP parameters (cookies, headers, path, query).
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when parameters are parsed.
+     * @throws {@link BadRequestError} If parameter validation fails.
      * @protected
      */
     async _parseParameters(context) {
@@ -122,7 +130,7 @@ export class HttpHandler {
                 issue.location = key;
                 return issue;
             };
-            /** prepare decoders */
+            /* prepare decoders */
             const getDecoder = (prm) => {
                 let decode = this[kAssetCache].get(prm, 'decode');
                 if (!decode) {
@@ -138,7 +146,7 @@ export class HttpHandler {
                 ...__oprDef.parameters,
                 ...__oprDef.owner.parameters,
             ]);
-            /** parse cookie parameters */
+            /* parse cookie parameters */
             if (request.cookies) {
                 for (key of Object.keys(request.cookies)) {
                     const oprPrm = __oprDef.findParameter(key, 'cookie');
@@ -161,7 +169,7 @@ export class HttpHandler {
                         context.cookies[prmName] = v;
                 }
             }
-            /** parse headers */
+            /* parse headers */
             if (request.headers) {
                 for (key of Object.keys(request.headers)) {
                     const oprPrm = __oprDef.findParameter(key, 'header');
@@ -184,7 +192,7 @@ export class HttpHandler {
                         context.headers[prmName] = v;
                 }
             }
-            /** parse path parameters */
+            /* parse path parameters */
             if (request.params) {
                 for (key of Object.keys(request.params)) {
                     const oprPrm = __oprDef.findParameter(key, 'path');
@@ -206,7 +214,7 @@ export class HttpHandler {
                         context.pathParams[key] = v;
                 }
             }
-            /** parse query parameters */
+            /* parse query parameters */
             const url = new URL(request.originalUrl || request.url || '/', 'http://tempuri.org');
             const { searchParams } = url;
             for (key of searchParams.keys()) {
@@ -267,8 +275,11 @@ export class HttpHandler {
         }
     }
     /**
+     * Parses and validates the request content type.
      *
-     * @param context
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when content type is parsed.
+     * @throws {@link BadRequestError} If the content type is invalid or missing.
      * @protected
      */
     async _parseContentType(context) {
@@ -318,10 +329,11 @@ export class HttpHandler {
         }
     }
     /**
+     * Sends an HTTP response back to the client.
      *
-     * @param context
-     * @param responseValue
-     * @protected
+     * @param context - The HTTP execution context.
+     * @param responseValue - The value to be sent in the response body.
+     * @returns A promise that resolves when the response is sent.
      */
     async sendResponse(context, responseValue) {
         if (context.errors.length)
@@ -341,11 +353,11 @@ export class HttpHandler {
                 });
                 this[kAssetCache].set(operationResultType, 'encode', operationResultEncoder);
             }
-            /** Validate response */
+            /* Validate response */
             if (operationResponse?.type) {
                 if (!(body == null &&
                     statusCode === HttpStatusCode.NO_CONTENT)) {
-                    /** Generate encoder */
+                    /* Generate encoder */
                     const projection = responseArgs.projection || '*';
                     const assetKey = md5(String(projection));
                     let encode = this[kAssetCache].get(operationResponse, 'encode:' + assetKey);
@@ -363,7 +375,7 @@ export class HttpHandler {
                             this[kAssetCache].set(operationResponse, 'encode:' + assetKey, encode);
                         }
                     }
-                    /** Encode body */
+                    /* Encode body */
                     if (operationResponse.type.extendsFrom(operationResultType)) {
                         if (body instanceof OperationResult)
                             body = encode(body);
@@ -410,7 +422,7 @@ export class HttpHandler {
                     body = String(body);
                 }
             }
-            /** Set content-type header value if not set */
+            /* Set content-type header value if not set */
             if (contentType && contentType !== responseArgs.contentType)
                 response.setHeader('content-type', contentType);
             response.status(statusCode);
@@ -497,6 +509,12 @@ export class HttpHandler {
         response.send(safeJsonStringify(body));
         response.end();
     }
+    /**
+     * Sends the document schema as a JSON response.
+     *
+     * @param context - The HTTP execution context.
+     * @returns A promise that resolves when the schema is sent.
+     */
     async sendDocumentSchema(context) {
         const { request, response } = context;
         const { document } = this.adapter;
@@ -511,9 +529,9 @@ export class HttpHandler {
             }));
             return this.sendResponse(context);
         }
-        /** Check if response cache exists */
+        /* Check if response cache exists */
         let responseBody = this[kAssetCache].get(doc, `$schema`);
-        /** Create response if response cache does not exists */
+        /* Create response if response cache does not exists */
         if (!responseBody) {
             const schema = doc.export({
                 scope: this.adapter.scope,
@@ -524,9 +542,12 @@ export class HttpHandler {
         response.end(responseBody);
     }
     /**
+     * Determines the response arguments (status code, content type, etc.) for a given response value.
      *
-     * @param context
-     * @param body
+     * @param context - The HTTP execution context.
+     * @param body - The response body.
+     * @returns The determined response arguments.
+     * @throws {@link InternalServerError} If response configuration is missing or invalid.
      * @protected
      */
     _determineResponseArgs(context, body) {
@@ -535,12 +556,12 @@ export class HttpHandler {
         const statusCode = !hasBody && response.statusCode === HttpStatusCode.OK
             ? HttpStatusCode.NO_CONTENT
             : response.statusCode;
-        /** Parse content-type header */
+        /* Parse content-type header */
         const parsedContentType = hasBody && response.hasHeader('content-type')
             ? parseContentType(response)
             : undefined;
         let contentType = parsedContentType?.type;
-        /** Estimate content type if not defined */
+        /* Estimate content type if not defined */
         if (hasBody && !contentType) {
             if (body instanceof OperationResult)
                 contentType = MimeTypes.opra_response_json;
@@ -553,21 +574,21 @@ export class HttpHandler {
         if (!responseArgs) {
             responseArgs = { statusCode, contentType };
             if (__oprDef?.responses.length) {
-                /** Filter available HttpOperationResponse instances according to status code. */
+                /* Filter available HttpOperationResponse instances according to status code. */
                 const filteredResponses = __oprDef.responses.filter(r => r.statusCode.find(sc => sc.start <= statusCode && sc.end >= statusCode));
-                /** Throw InternalServerError if controller returns non-configured status code */
+                /* Throw InternalServerError if controller returns non-configured status code */
                 if (!filteredResponses.length && statusCode < 400) {
                     throw new InternalServerError(`No responses defined for status code ${statusCode} in operation "${__oprDef.name}"`);
                 }
-                /** We search for content-type in filtered HttpOperationResponse array */
+                /* We search for content-type in filtered HttpOperationResponse array */
                 if (filteredResponses.length) {
-                    /** If no response returned, and content-type has not been set (No response wants to be returned by operation) */
+                    /* If no response returned, and content-type has not been set (No response wants to be returned by operation) */
                     if (!hasBody) {
-                        /** Find HttpOperationResponse with no content-type */
+                        /* Find HttpOperationResponse with no content-type */
                         operationResponse = filteredResponses.find(r => !r.contentType);
                     }
                     if (!operationResponse) {
-                        /** Find HttpOperationResponse according to content-type */
+                        /* Find HttpOperationResponse according to content-type */
                         if (contentType) {
                             // Find HttpEndpointResponse instance according to content-type header
                             operationResponse = filteredResponses.find(r => typeIs.is(contentType, toArray(r.contentType)));
@@ -576,7 +597,7 @@ export class HttpHandler {
                             }
                         }
                         else {
-                            /** Select first HttpOperationResponse if content-type header has not been set */
+                            /* Select first HttpOperationResponse if content-type header has not been set */
                             operationResponse = filteredResponses[0];
                             if (operationResponse.contentType) {
                                 const ct = typeIs.normalize(Array.isArray(operationResponse.contentType)
@@ -603,7 +624,7 @@ export class HttpHandler {
             }
             this[kAssetCache].set(response, cacheKey, { ...responseArgs });
         }
-        /** Fix response value according to composition */
+        /* Fix response value according to composition */
         const composition = operationResponse?.owner.composition;
         if (composition && body != null) {
             switch (composition) {

package/impl/local-file.d.ts

@@ -1,3 +1,7 @@
+/**
+ * LocalFile represents a file stored on the local file system.
+ * It provides utility methods for reading the file content and managing its lifecycle.
+ */
 export declare class LocalFile {
     private _autoDelete;
     readonly storedPath: string;
@@ -7,6 +11,11 @@ export declare class LocalFile {
     constructor(storedPath: string, options?: LocalFile.Options);
     text(): Promise<string>;
     buffer(): Promise<Buffer>;
+    /**
+     * Deletes the local file.
+     *
+     * @returns A promise that resolves when the file is deleted.
+     */
     delete(): Promise<void>;
     get size(): number;
     get autoDelete(): boolean;

package/impl/local-file.js

@@ -6,6 +6,10 @@ import { uid } from 'uid';
 const registry = new FinalizationRegistry((storedPath) => {
     fs.unlink(storedPath, () => undefined);
 });
+/**
+ * LocalFile represents a file stored on the local file system.
+ * It provides utility methods for reading the file content and managing its lifecycle.
+ */
 export class LocalFile {
     _autoDelete = false;
     storedPath;
@@ -25,6 +29,11 @@ export class LocalFile {
     async buffer() {
         return fsAsync.readFile(this.storedPath);
     }
+    /**
+     * Deletes the local file.
+     *
+     * @returns A promise that resolves when the file is deleted.
+     */
     async delete() {
         if (fs.existsSync(this.storedPath)) {
             try {

package/impl/multipart-reader.d.ts

@@ -4,6 +4,10 @@ import { EventEmitter } from 'events';
 import type { StrictOmit } from 'ts-gems';
 import type { HttpContext } from '../http-context.js';
 import { LocalFile } from './local-file.js';
+/**
+ * MultipartReader is responsible for parsing multipart/form-data requests.
+ * It uses busboy to stream incoming parts and can handle both fields and files.
+ */
 export declare class MultipartReader extends EventEmitter {
     protected context: HttpContext;
     protected mediaType?: HttpMediaType | undefined;
@@ -17,12 +21,28 @@ export declare class MultipartReader extends EventEmitter {
     scope?: string;
     constructor(context: HttpContext, options?: MultipartReader.Options, mediaType?: HttpMediaType | undefined);
     get items(): MultipartReader.Item[];
+    /**
+     * Retrieves the next item (field or file) from the multipart stream.
+     *
+     * @returns A promise that resolves to the next item, or undefined if no more items are available.
+     * @throws {@link BadRequestError} If a field is unknown or validation fails.
+     */
     getNext(): Promise<MultipartReader.Item | undefined>;
+    /**
+     * Retrieves all items from the multipart stream.
+     *
+     * @returns A promise that resolves to an array of all items.
+     */
     getAll(): Promise<MultipartReader.Item[]>;
     getAll_(): Promise<MultipartReader.Item[]>;
     cancel(): void;
     resume(): void;
     pause(): void;
+    /**
+     * Purges all temporary files created by the reader.
+     *
+     * @returns A promise that resolves when all files are purged.
+     */
     purge(): Promise<PromiseSettledResult<any>[]>;
 }
 export declare class MultipartFile extends LocalFile {

package/impl/multipart-reader.js

@@ -7,6 +7,10 @@ import { EventEmitter } from 'events';
 import fsPromise from 'fs/promises';
 import { isNotNullish } from 'valgen';
 import { LocalFile } from './local-file.js';
+/**
+ * MultipartReader is responsible for parsing multipart/form-data requests.
+ * It uses busboy to stream incoming parts and can handle both fields and files.
+ */
 export class MultipartReader extends EventEmitter {
     context;
     mediaType;
@@ -70,6 +74,12 @@ export class MultipartReader extends EventEmitter {
     get items() {
         return this._items;
     }
+    /**
+     * Retrieves the next item (field or file) from the multipart stream.
+     *
+     * @returns A promise that resolves to the next item, or undefined if no more items are available.
+     * @throws {@link BadRequestError} If a field is unknown or validation fails.
+     */
     async getNext() {
         let item = this._stack.shift();
         if (!item && !this._finished) {
@@ -122,7 +132,7 @@ export class MultipartReader extends EventEmitter {
                 }
             }
         }
-        /** if all items received we check for required items */
+        /* if all items received we check for required items */
         if (this._finished &&
             this.mediaType &&
             this.mediaType.multipartFields?.length > 0) {
@@ -155,6 +165,11 @@ export class MultipartReader extends EventEmitter {
         }
         return item;
     }
+    /**
+     * Retrieves all items from the multipart stream.
+     *
+     * @returns A promise that resolves to an array of all items.
+     */
     async getAll() {
         const items = [...this._items];
         let item;
@@ -189,6 +204,11 @@ export class MultipartReader extends EventEmitter {
     pause() {
         this.context.request.pause();
     }
+    /**
+     * Purges all temporary files created by the reader.
+     *
+     * @returns A promise that resolves when all files are purged.
+     */
     async purge() {
         const promises = [];
         this._items.forEach(item => {

package/interfaces/http-incoming.interface.d.ts

@@ -3,7 +3,8 @@ import { BodyReader } from '../utils/body-reader.js';
 import type { HttpOutgoing } from './http-outgoing.interface.js';
 import { NodeIncomingMessage } from './node-incoming-message.interface.js';
 /**
- * @interface HttpIncoming
+ * HttpIncoming represents an incoming HTTP request.
+ * It extends NodeIncomingMessage with additional functionality for handling HTTP requests.
  */
 export interface HttpIncoming extends NodeIncomingMessage {
     res: HttpOutgoing;
@@ -180,14 +181,22 @@ export interface HttpIncoming extends NodeIncomingMessage {
      */
     range(size: number, options?: RangeParserOptions): RangeParserRanges | RangeParserResult | undefined;
     /**
-     * Receives the body
-     * @param options
+     * Receives and parses the request body.
+     *
+     * @param options - Optional reader settings.
+     * @returns A promise that resolves to the body content.
      */
     readBody(options?: BodyReader.Options): Promise<string | Buffer | undefined>;
 }
 /**
- * @namespace HttpIncoming
+ * Utility functions for HttpIncoming.
  */
 export declare namespace HttpIncoming {
+    /**
+     * Creates an HttpIncoming instance from various sources.
+     *
+     * @param instance - The source instance.
+     * @returns The HttpIncoming instance.
+     */
     function from(instance: HttpIncoming | NodeIncomingMessage.Initiator | string | Iterable<any> | AsyncIterable<any>): HttpIncoming;
 }

package/interfaces/http-incoming.interface.js

@@ -3,10 +3,16 @@ import { HttpIncomingHost } from '../impl/http-incoming.host.js';
 import { isHttpIncoming, isNodeIncomingMessage } from '../type-guards.js';
 import { NodeIncomingMessage } from './node-incoming-message.interface.js';
 /**
- * @namespace HttpIncoming
+ * Utility functions for HttpIncoming.
  */
 export var HttpIncoming;
 (function (HttpIncoming) {
+    /**
+     * Creates an HttpIncoming instance from various sources.
+     *
+     * @param instance - The source instance.
+     * @returns The HttpIncoming instance.
+     */
     function from(instance) {
         if (isHttpIncoming(instance))
             return instance;

package/interfaces/http-outgoing.interface.d.ts

@@ -1,6 +1,10 @@
 import { type StrictOmit } from 'ts-gems';
 import type { HttpIncoming } from './http-incoming.interface.js';
 import { NodeOutgoingMessage } from './node-outgoing-message.interface.js';
+/**
+ * HttpOutgoing represents an outgoing HTTP response.
+ * It extends NodeOutgoingMessage with additional functionality for handling HTTP responses.
+ */
 export interface HttpOutgoing extends StrictOmit<NodeOutgoingMessage, 'req' | 'appendHeader' | 'setHeader'> {
     req: HttpIncoming;
     readonly finished?: boolean;
@@ -10,7 +14,6 @@ export interface HttpOutgoing extends StrictOmit<NodeOutgoingMessage, 'req' | 'a
      * Set _Content-Disposition_ header to _attachment_ with optional `filename`.
      */
     attachment(filename?: string): this;
-    /** Clear cookie `name`. */
     clearCookie(name: string, options?: CookieOptions): this;
     /**
      * Set cookie `name` to `val`, with the given `options`.
@@ -106,7 +109,7 @@ export interface HttpOutgoing extends StrictOmit<NodeOutgoingMessage, 'req' | 'a
      */
     status(code: number): this;
     /**
-     * Send given HTTP status code.
+     * Send the given HTTP status code.
      *
      * Sets the response status to `statusCode` and the body of the
      * response to the standard description from node's http.STATUS_CODES
@@ -137,8 +140,14 @@ export interface CookieOptions {
     sameSite?: boolean | 'lax' | 'strict' | 'none';
 }
 /**
- * @namespace HttpIncoming
+ * Utility functions for HttpOutgoing.
  */
 export declare namespace HttpOutgoing {
+    /**
+     * Creates an HttpOutgoing instance from various sources.
+     *
+     * @param instance - The source instance.
+     * @returns The HttpOutgoing instance.
+     */
     function from(instance: HttpOutgoing | NodeOutgoingMessage.Initiator): HttpOutgoing;
 }

package/interfaces/http-outgoing.interface.js

@@ -3,10 +3,16 @@ import { HttpOutgoingHost } from '../impl/http-outgoing.host.js';
 import { isHttpOutgoing, isNodeOutgoingMessage } from '../type-guards.js';
 import { NodeOutgoingMessage } from './node-outgoing-message.interface.js';
 /**
- * @namespace HttpIncoming
+ * Utility functions for HttpOutgoing.
  */
 export var HttpOutgoing;
 (function (HttpOutgoing) {
+    /**
+     * Creates an HttpOutgoing instance from various sources.
+     *
+     * @param instance - The source instance.
+     * @returns The HttpOutgoing instance.
+     */
     function from(instance) {
         if (isHttpOutgoing(instance))
             return instance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/http",
-  "version": "1.26.2",
+  "version": "1.26.4",
   "description": "Opra Http Server Adapter",
   "author": "Panates",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "yaml": "^2.8.3"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.2",
-    "@opra/core": "^1.26.2"
+    "@opra/common": "^1.26.4",
+    "@opra/core": "^1.26.4"
   },
   "optionalDependencies": {
     "express": "^4.0.0 || ^5.0.0",

package/type-guards.d.ts

@@ -2,7 +2,31 @@ import type { HttpIncoming } from './interfaces/http-incoming.interface.js';
 import type { HttpOutgoing } from './interfaces/http-outgoing.interface.js';
 import type { NodeIncomingMessage } from './interfaces/node-incoming-message.interface.js';
 import type { NodeOutgoingMessage } from './interfaces/node-outgoing-message.interface.js';
+/**
+ * Checks if the given value is a NodeIncomingMessage.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is a NodeIncomingMessage, false otherwise.
+ */
 export declare function isNodeIncomingMessage(v: any): v is NodeIncomingMessage;
+/**
+ * Checks if the given value is an HttpIncoming instance.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is an HttpIncoming instance, false otherwise.
+ */
 export declare function isHttpIncoming(v: any): v is HttpIncoming;
+/**
+ * Checks if the given value is a NodeOutgoingMessage.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is a NodeOutgoingMessage, false otherwise.
+ */
 export declare function isNodeOutgoingMessage(v: any): v is NodeOutgoingMessage;
+/**
+ * Checks if the given value is an HttpOutgoing instance.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is an HttpOutgoing instance, false otherwise.
+ */
 export declare function isHttpOutgoing(v: any): v is HttpOutgoing;

package/type-guards.js

@@ -1,19 +1,43 @@
 import { isReadable, isStream } from '@opra/common';
+/**
+ * Checks if the given value is a NodeIncomingMessage.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is a NodeIncomingMessage, false otherwise.
+ */
 export function isNodeIncomingMessage(v) {
     return (v &&
         typeof v.method === 'string' &&
         Array.isArray(v.rawHeaders) &&
         isReadable(v));
 }
+/**
+ * Checks if the given value is an HttpIncoming instance.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is an HttpIncoming instance, false otherwise.
+ */
 export function isHttpIncoming(v) {
     return (isNodeIncomingMessage(v) &&
         typeof v.header === 'function' &&
         typeof v.acceptsLanguages === 'function' &&
         typeof v.readBody === 'function');
 }
+/**
+ * Checks if the given value is a NodeOutgoingMessage.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is a NodeOutgoingMessage, false otherwise.
+ */
 export function isNodeOutgoingMessage(v) {
     return v && typeof v.getHeaders === 'function' && isStream(v);
 }
+/**
+ * Checks if the given value is an HttpOutgoing instance.
+ *
+ * @param v - The value to check.
+ * @returns True if the value is an HttpOutgoing instance, false otherwise.
+ */
 export function isHttpOutgoing(v) {
     return (isNodeOutgoingMessage(v) &&
         typeof v.clearCookie === 'function' &&

package/utils/body-reader.d.ts

@@ -15,8 +15,8 @@ export declare namespace BodyReader {
 }
 type Callback = (...args: any[]) => any;
 /**
- *
- * @class BodyReader
+ * BodyReader is responsible for reading and parsing the request body.
+ * It supports various content encodings and can save the body to a file.
  */
 export declare class BodyReader extends EventEmitter {
     readonly req: HttpIncoming;
@@ -32,11 +32,25 @@ export declare class BodyReader extends EventEmitter {
     protected onData: Callback;
     protected onEnd: Callback;
     constructor(req: HttpIncoming, options?: BodyReader.Options);
+    /**
+     * Reads the request body.
+     *
+     * @returns A promise that resolves to the body content (string, Buffer, or LocalFile).
+     * @throws {@link InternalServerError} If the stream is already read or not readable.
+     * @throws {@link OpraHttpError} If the content size exceeds the limit.
+     */
     read(): Promise<string | Buffer<ArrayBufferLike> | undefined>;
     protected _onEnd(error: any): void;
     protected _cleanup(): void;
     protected _onAborted(): void;
     protected _onData(chunk: Buffer | string): void;
+    /**
+     * Static method to read the request body.
+     *
+     * @param req - The incoming HTTP request.
+     * @param options - Optional reader settings.
+     * @returns A promise that resolves to the body content.
+     */
     static read(req: HttpIncoming, options?: BodyReader.Options): Promise<string | Buffer | undefined>;
     protected static encoderPipeline(req: HttpIncoming): nodeStream.Readable;
 }

package/utils/body-reader.js

@@ -11,8 +11,8 @@ import { Writable } from 'stream';
 import * as zlib from 'zlib';
 import { LocalFile } from '../impl/local-file.js';
 /**
- *
- * @class BodyReader
+ * BodyReader is responsible for reading and parsing the request body.
+ * It supports various content encodings and can save the body to a file.
  */
 export class BodyReader extends EventEmitter {
     req;
@@ -53,6 +53,13 @@ export class BodyReader extends EventEmitter {
         if (this._file)
             this._file.autoDelete = true;
     }
+    /**
+     * Reads the request body.
+     *
+     * @returns A promise that resolves to the body content (string, Buffer, or LocalFile).
+     * @throws {@link InternalServerError} If the stream is already read or not readable.
+     * @throws {@link OpraHttpError} If the content size exceeds the limit.
+     */
     async read() {
         /* istanbul ignore next */
         if (this._completed) {
@@ -209,6 +216,13 @@ export class BodyReader extends EventEmitter {
             this._buffer.push(chunk);
         }
     }
+    /**
+     * Static method to read the request body.
+     *
+     * @param req - The incoming HTTP request.
+     * @param options - Optional reader settings.
+     * @returns A promise that resolves to the body content.
+     */
     static async read(req, options) {
         const bodyReady = new BodyReader(req, options);
         return bodyReady.read();

package/utils/common.d.ts

@@ -1,17 +1,25 @@
 /**
- * Verifies that the given val is a valid HTTP token
- * per the rules defined in RFC 7230
- * See https://tools.ietf.org/html/rfc7230#section-3.2.6
+ * Verifies that the given val is a valid HTTP token per the rules defined in RFC 7230.
+ * See {@link https://tools.ietf.org/html/rfc7230#section-3.2.6}
  *
- * https://github.com/nodejs/node/blob/main/lib/_http_common.js
+ * @param val - The value to check.
+ * @returns True if the value is a valid HTTP token, false otherwise.
  */
 export declare function checkIsHttpToken(val: any): boolean;
 /**
- * This function removes unnecessary frames from Node.js core errors.
+ * Hides internal Node.js stack frames for a given function.
  *
- * https://github.com/nodejs/node/blob/main/lib/internal/errors.js
+ * @param fn - The function to hide stack frames for.
+ * @returns The function with hidden stack frames.
  */
 export declare function hideStackFrames(fn: Function): Function;
 export declare const validateHeaderName: Function;
 export declare const validateHeaderValue: Function;
+/**
+ * Validates if the given value is a string.
+ *
+ * @param value - The value to validate.
+ * @param name - The name of the argument being validated.
+ * @throws {@link TypeError} If the value is not a string.
+ */
 export declare function validateString(value: any, name?: string): void;

package/utils/common.js

@@ -5,11 +5,11 @@
 const tokenRegExp = /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/;
 const nodeInternalPrefix = '__node_internal_';
 /**
- * Verifies that the given val is a valid HTTP token
- * per the rules defined in RFC 7230
- * See https://tools.ietf.org/html/rfc7230#section-3.2.6
+ * Verifies that the given val is a valid HTTP token per the rules defined in RFC 7230.
+ * See {@link https://tools.ietf.org/html/rfc7230#section-3.2.6}
  *
- * https://github.com/nodejs/node/blob/main/lib/_http_common.js
+ * @param val - The value to check.
+ * @returns True if the value is a valid HTTP token, false otherwise.
  */
 export function checkIsHttpToken(val) {
     return typeof val === 'string' && tokenRegExp.exec(val) !== null;
@@ -28,9 +28,10 @@ function checkInvalidHeaderChar(val) {
     return typeof val === 'string' && headerCharRegex.exec(val) !== null;
 }
 /**
- * This function removes unnecessary frames from Node.js core errors.
+ * Hides internal Node.js stack frames for a given function.
  *
- * https://github.com/nodejs/node/blob/main/lib/internal/errors.js
+ * @param fn - The function to hide stack frames for.
+ * @returns The function with hidden stack frames.
  */
 export function hideStackFrames(fn) {
     // We rename the functions that will be hidden to cut off the stacktrace
@@ -54,6 +55,13 @@ export const validateHeaderValue = hideStackFrames((name, value) => {
         throw new TypeError(`Invalid character in header content ["${name}"]`);
     }
 });
+/**
+ * Validates if the given value is a string.
+ *
+ * @param value - The value to validate.
+ * @param name - The name of the argument being validated.
+ * @throws {@link TypeError} If the value is not a string.
+ */
 export function validateString(value, name) {
     if (typeof value !== 'string') {
         throw new TypeError(`Invalid ${name ? name + ' ' : ''}argument. Value must be a string`);

package/utils/wrap-exception.d.ts

@@ -1,2 +1,8 @@
 import { OpraHttpError } from '@opra/common';
+/**
+ * Wraps an error into an OpraHttpError.
+ *
+ * @param error - The error to wrap.
+ * @returns The wrapped OpraHttpError.
+ */
 export declare function wrapException(error: any): OpraHttpError;

package/utils/wrap-exception.js

@@ -1,4 +1,10 @@
 import { BadRequestError, FailedDependencyError, ForbiddenError, InternalServerError, MethodNotAllowedError, NotAcceptableError, NotFoundError, OpraHttpError, UnauthorizedError, UnprocessableEntityError, } from '@opra/common';
+/**
+ * Wraps an error into an OpraHttpError.
+ *
+ * @param error - The error to wrap.
+ * @returns The wrapped OpraHttpError.
+ */
 export function wrapException(error) {
     if (error instanceof OpraHttpError)
         return error;