@adonisjs/http-server 6.8.2-5 → 6.8.2-7

package/build/src/exception_handler.js

@@ -1,11 +1,49 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import is from '@sindresorhus/is';
 import { parseRange } from './helpers.js';
 import * as errors from './exceptions.js';
+/**
+ * The base HTTP exception handler one can inherit from to handle
+ * HTTP exceptions.
+ *
+ * The HTTP exception handler has support for
+ *
+ * - Ability to render exceptions by calling the render method on the exception.
+ * - Rendering status pages
+ * - Pretty printing errors during development
+ * - Transforming errors to JSON or HTML using content negotiation
+ * - Reporting errors
+ */
 export class ExceptionHandler {
+    /**
+     * Whether or not to render debug info. When set to true, the errors
+     * will have the complete error stack.
+     */
     debug = process.env.NODE_ENV !== 'production';
+    /**
+     * Whether or not to render status pages. When set to true, the unhandled
+     * errors with matching status codes will be rendered using a status
+     * page.
+     */
     renderStatusPages = process.env.NODE_ENV === 'production';
+    /**
+     * A collection of error status code range and the view to render.
+     */
     statusPages = {};
+    /**
+     * Computed from the status pages property
+     */
     #expandedStatusPages;
+    /**
+     * Renderers for rendering an error.
+     */
     renderers = {
         html: async (error, ctx) => {
             if (this.isDebuggingEnabled(ctx)) {
@@ -43,15 +81,33 @@ export class ExceptionHandler {
             });
         },
     };
+    /**
+     * Enable/disable errors reporting
+     */
     reportErrors = true;
+    /**
+     * An array of exception classes to ignore when
+     * reporting an error
+     */
     ignoreExceptions = [
         errors.E_HTTP_EXCEPTION,
         errors.E_ROUTE_NOT_FOUND,
         errors.E_CANNOT_LOOKUP_ROUTE,
         errors.E_HTTP_REQUEST_ABORTED,
     ];
+    /**
+     * An array of HTTP status codes to ignore when reporting
+     * an error
+     */
     ignoreStatuses = [400, 422, 401];
+    /**
+     * An array of error codes to ignore when reporting
+     * an error
+     */
     ignoreCodes = [];
+    /**
+     * Expands status pages
+     */
     #expandStatusPages() {
         if (!this.#expandedStatusPages) {
             this.#expandedStatusPages = Object.keys(this.statusPages).reduce((result, range) => {
@@ -62,12 +118,19 @@ export class ExceptionHandler {
         }
         return this.#expandedStatusPages;
     }
+    /**
+     * Forcefully tweaking the type of the error object to
+     * have known properties.
+     */
     #toHttpError(error) {
         const httpError = is.object(error) ? error : new Error(String(error));
         httpError.message = httpError.message || 'Internal server error';
         httpError.status = httpError.status || 500;
         return httpError;
     }
+    /**
+     * Error reporting context
+     */
     context(ctx) {
         const requestId = ctx.request.id();
         return requestId
@@ -76,6 +139,9 @@ export class ExceptionHandler {
             }
             : {};
     }
+    /**
+     * The format in which the error should be rendered.
+     */
     getResponseFormat(ctx) {
         switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
             case 'application/vnd.api+json':
@@ -87,6 +153,10 @@ export class ExceptionHandler {
                 return 'html';
         }
     }
+    /**
+     * Returns the log level for an error based upon the error
+     * status code.
+     */
     getErrorLogLevel(error) {
         if (error.status >= 500) {
             return 'error';
@@ -96,9 +166,16 @@ export class ExceptionHandler {
         }
         return 'info';
     }
+    /**
+     * A boolean to control if errors should be rendered with
+     * all the available debugging info.
+     */
     isDebuggingEnabled(_) {
         return this.debug;
     }
+    /**
+     * Returns a boolean by checking if an error should be reported.
+     */
     shouldReport(error) {
         if (this.reportErrors === false) {
             return false;
@@ -114,6 +191,9 @@ export class ExceptionHandler {
         }
         return true;
     }
+    /**
+     * Reports an error during an HTTP request
+     */
     async report(error, ctx) {
         const httpError = this.#toHttpError(error);
         if (!this.shouldReport(httpError)) {
@@ -123,21 +203,36 @@ export class ExceptionHandler {
             httpError.report(httpError, ctx);
             return;
         }
+        /**
+         * Log the error using the logger
+         */
         const level = this.getErrorLogLevel(httpError);
         ctx.logger.log(level, {
             ...(level === 'error' || level === 'fatal' ? { err: httpError } : {}),
             ...this.context(ctx),
         }, httpError.message);
     }
+    /**
+     * Handles the error during the HTTP request.
+     */
     async handle(error, ctx) {
         const httpError = this.#toHttpError(error);
+        /**
+         * Self handle exception
+         */
         if (typeof httpError.handle === 'function') {
             return httpError.handle(httpError, ctx);
         }
+        /**
+         * Render status page
+         */
         const statusPages = this.#expandStatusPages();
         if (this.renderStatusPages && statusPages[httpError.status]) {
             return statusPages[httpError.status](httpError, ctx);
         }
+        /**
+         * Use the format renderers.
+         */
         const responseFormat = this.getResponseFormat(ctx);
         return this.renderers[responseFormat](httpError, ctx);
     }

package/build/src/exceptions.d.ts

@@ -20,6 +20,9 @@ export declare const E_HTTP_EXCEPTION: {
         cause?: unknown;
     };
     code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
     invoke(body: any, status: number, code?: string): {
         body: any;
         name: string;
@@ -57,6 +60,9 @@ export declare const E_HTTP_REQUEST_ABORTED: {
         cause?: unknown;
     };
     code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
     invoke(body: any, status: number, code?: string): {
         body: any;
         name: string;
@@ -76,4 +82,3 @@ export declare const E_HTTP_REQUEST_ABORTED: {
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };
-//# sourceMappingURL=exceptions.d.ts.map

package/build/src/exceptions.js

@@ -1,9 +1,20 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { createError, Exception } from '@poppinss/utils';
 export const E_ROUTE_NOT_FOUND = createError('Cannot %s:%s', 'E_ROUTE_NOT_FOUND', 404);
 export const E_CANNOT_LOOKUP_ROUTE = createError('Cannot lookup route "%s"', 'E_CANNOT_LOOKUP_ROUTE', 500);
 export const E_HTTP_EXCEPTION = class HttpException extends Exception {
     body;
     static code = 'E_HTTP_EXCEPTION';
+    /**
+     * This method returns an instance of the exception class
+     */
     static invoke(body, status, code = 'E_HTTP_EXCEPTION') {
         if (body === null || body === undefined) {
             const error = new this('HTTP Exception', { status, code });

package/build/src/helpers.d.ts

@@ -3,8 +3,21 @@ import { BriskRoute } from './router/brisk.js';
 import { RouteGroup } from './router/group.js';
 import type { RouteJSON } from './types/route.js';
 import { RouteResource } from './router/resource.js';
+/**
+ * Makes input string consistent by having only the starting
+ * slash
+ */
 export declare function dropSlash(input: string): string;
+/**
+ * Returns a flat list of routes from the route groups and resources
+ */
 export declare function toRoutesJSON(routes: (RouteGroup | Route | RouteResource | BriskRoute)[]): RouteJSON[];
+/**
+ * Helper to know if the remote address should
+ * be trusted.
+ */
 export declare function trustProxy(remoteAddress: string, proxyFn: (addr: string, distance: number) => boolean): boolean;
+/**
+ * Parses a range expression to an object filled with the range
+ */
 export declare function parseRange<T>(range: string, value: T): Record<number, T>;
-//# sourceMappingURL=helpers.d.ts.map

package/build/src/helpers.js

@@ -1,15 +1,30 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import Cache from 'tmp-cache';
 import { InvalidArgumentsException } from '@poppinss/utils';
 import { BriskRoute } from './router/brisk.js';
 import { RouteGroup } from './router/group.js';
 import { RouteResource } from './router/resource.js';
 const proxyCache = new Cache({ max: 200 });
+/**
+ * Makes input string consistent by having only the starting
+ * slash
+ */
 export function dropSlash(input) {
     if (input === '/') {
         return '/';
     }
     return `/${input.replace(/^\//, '').replace(/\/$/, '')}`;
 }
+/**
+ * Returns a flat list of routes from the route groups and resources
+ */
 export function toRoutesJSON(routes) {
     return routes.reduce((list, route) => {
         if (route instanceof RouteGroup) {
@@ -32,6 +47,10 @@ export function toRoutesJSON(routes) {
         return list;
     }, []);
 }
+/**
+ * Helper to know if the remote address should
+ * be trusted.
+ */
 export function trustProxy(remoteAddress, proxyFn) {
     if (proxyCache.has(remoteAddress)) {
         return proxyCache.get(remoteAddress);
@@ -40,6 +59,9 @@ export function trustProxy(remoteAddress, proxyFn) {
     proxyCache.set(remoteAddress, result);
     return result;
 }
+/**
+ * Parses a range expression to an object filled with the range
+ */
 export function parseRange(range, value) {
     const parts = range.split('..');
     const min = Number(parts[0]);

package/build/src/http_context/local_storage.d.ts

@@ -1,10 +1,12 @@
 /// <reference types="node" resolution-mode="require"/>
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { HttpContext } from './main.js';
+/**
+ * Async local storage for HTTP context
+ */
 export declare const asyncLocalStorage: {
     isEnabled: boolean;
     storage: null | AsyncLocalStorage<HttpContext>;
     create(): AsyncLocalStorage<HttpContext>;
     destroy(): void;
 };
-//# sourceMappingURL=local_storage.d.ts.map

package/build/src/http_context/local_storage.js

@@ -1,12 +1,37 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Async local storage for HTTP context
+ */
 export const asyncLocalStorage = {
+    /**
+     * Check if the async local storage for the HTTP
+     * context is enabled or not
+     */
     isEnabled: false,
+    /**
+     * HTTP context storage instance for the current scope
+     */
     storage: null,
+    /**
+     * Create the storage instance. This method must be called only
+     * once.
+     */
     create() {
         this.isEnabled = true;
         this.storage = new AsyncLocalStorage();
         return this.storage;
     },
+    /**
+     * Destroy the create storage instance
+     */
     destroy() {
         this.isEnabled = false;
         this.storage = null;

package/build/src/http_context/main.d.ts

@@ -4,20 +4,55 @@ import { ContainerResolver } from '@adonisjs/fold';
 import type { Request } from '../request.js';
 import type { Response } from '../response.js';
 import type { StoreRouteNode } from '../types/route.js';
+/**
+ * Http context encapsulates properties for a given HTTP request. The
+ * context class can be extended using macros and getters.
+ */
 export declare class HttpContext extends Macroable {
     request: Request;
     response: Response;
     logger: Logger;
     containerResolver: ContainerResolver<any>;
+    /**
+     * Find if async localstorage is enabled for HTTP requests
+     * or not
+     */
     static get usingAsyncLocalStorage(): boolean;
+    /**
+     * Get access to the HTTP context. Available only when
+     * "usingAsyncLocalStorage" is true
+     */
     static get(): HttpContext | null;
+    /**
+     * Get the HttpContext instance or raise an exception if not
+     * available
+     */
     static getOrFail(): HttpContext;
+    /**
+     * Run a method that doesn't have access to HTTP context from
+     * the async local storage.
+     */
     static runOutsideContext<T>(callback: (...args: any[]) => T, ...args: any[]): T;
+    /**
+     * Reference to the current route. Not available inside
+     * server middleware
+     */
     route?: StoreRouteNode;
+    /**
+     * A unique key for the current route
+     */
     routeKey?: string;
+    /**
+     * Route params
+     */
     params: Record<string, any>;
+    /**
+     * Route subdomains
+     */
     subdomains: Record<string, any>;
     constructor(request: Request, response: Response, logger: Logger, containerResolver: ContainerResolver<any>);
+    /**
+     * A helper to see top level properties on the context object
+     */
     inspect(): string;
 }
-//# sourceMappingURL=main.d.ts.map

package/build/src/http_context/main.js

@@ -1,22 +1,49 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { inspect } from 'node:util';
 import Macroable from '@poppinss/macroable';
 import { RuntimeException } from '@poppinss/utils';
 import { asyncLocalStorage } from './local_storage.js';
+/**
+ * Http context encapsulates properties for a given HTTP request. The
+ * context class can be extended using macros and getters.
+ */
 export class HttpContext extends Macroable {
     request;
     response;
     logger;
     containerResolver;
+    /**
+     * Find if async localstorage is enabled for HTTP requests
+     * or not
+     */
     static get usingAsyncLocalStorage() {
         return asyncLocalStorage.isEnabled;
     }
+    /**
+     * Get access to the HTTP context. Available only when
+     * "usingAsyncLocalStorage" is true
+     */
     static get() {
         if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
             return null;
         }
         return asyncLocalStorage.storage.getStore() || null;
     }
+    /**
+     * Get the HttpContext instance or raise an exception if not
+     * available
+     */
     static getOrFail() {
+        /**
+         * Localstorage is not enabled
+         */
         if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
             throw new RuntimeException('HTTP context is not available. Enable "useAsyncLocalStorage" inside "config/app.ts" file');
         }
@@ -26,15 +53,32 @@ export class HttpContext extends Macroable {
         }
         return store;
     }
+    /**
+     * Run a method that doesn't have access to HTTP context from
+     * the async local storage.
+     */
     static runOutsideContext(callback, ...args) {
         if (!asyncLocalStorage.storage) {
             return callback(...args);
         }
         return asyncLocalStorage.storage.exit(callback, ...args);
     }
+    /**
+     * Reference to the current route. Not available inside
+     * server middleware
+     */
     route;
+    /**
+     * A unique key for the current route
+     */
     routeKey;
+    /**
+     * Route params
+     */
     params = {};
+    /**
+     * Route subdomains
+     */
     subdomains = {};
     constructor(request, response, logger, containerResolver) {
         super();
@@ -42,9 +86,19 @@ export class HttpContext extends Macroable {
         this.response = response;
         this.logger = logger;
         this.containerResolver = containerResolver;
+        /*
+         * Creating the circular reference. We do this, since request and response
+         * are meant to be extended and at times people would want to access
+         * other ctx properties like `logger`, `profiler` inside those
+         * extended methods.
+         */
         this.request.ctx = this;
         this.response.ctx = this;
     }
+    /**
+     * A helper to see top level properties on the context object
+     */
+    /* c8 ignore next 3 */
     inspect() {
         return inspect(this, false, 1, true);
     }

package/build/src/qs.d.ts

@@ -1,8 +1,11 @@
 import { QSParserConfig } from './types/qs.js';
+/**
+ * Query string parser used to parse and stringify query
+ * strings.
+ */
 export declare class Qs {
     #private;
     constructor(config: QSParserConfig);
     parse(value: string): import("qs").ParsedQs;
     stringify(value: any): string;
 }
-//# sourceMappingURL=qs.d.ts.map

package/build/src/qs.js

@@ -1,4 +1,16 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { parse, stringify } from 'qs';
+/**
+ * Query string parser used to parse and stringify query
+ * strings.
+ */
 export class Qs {
     #config;
     constructor(config) {

package/build/src/redirect.d.ts

@@ -4,16 +4,39 @@ import type { Qs } from './qs.js';
 import type { Response } from './response.js';
 import type { Router } from './router/main.js';
 import type { MakeUrlOptions } from './types/route.js';
+/**
+ * Exposes the API to construct redirect routes
+ */
 export declare class Redirect {
     #private;
     constructor(request: IncomingMessage, response: Response, router: Router, qs: Qs);
+    /**
+     * Set a custom status code.
+     */
     status(statusCode: number): this;
+    /**
+     * Clearing query string values added using the
+     * "withQs" method
+     */
     clearQs(): this;
+    /**
+     * Define query string for the redirect. Not passing
+     * any value will forward the current request query
+     * string.
+     */
     withQs(): this;
     withQs(values: Record<string, any>): this;
     withQs(name: string, value: any): this;
+    /**
+     * Redirect to the previous path.
+     */
     back(): void;
+    /**
+     * Redirect the request using a route identifier.
+     */
     toRoute(routeIdentifier: string, params?: any[] | Record<string, any>, options?: MakeUrlOptions): void;
+    /**
+     * Redirect the request using a path.
+     */
     toPath(url: string): void;
 }
-//# sourceMappingURL=redirect.d.ts.map