@adonisjs/http-server 8.0.0-next.1 → 8.0.0-next.10

package/build/src/errors.d.ts

@@ -1,15 +1,41 @@
 import { Exception } from '@poppinss/utils/exception';
 import type { HttpContext } from './http_context/main.ts';
 /**
- * Thrown when unable to find a matching route for the given request
+ * Thrown when unable to find a matching route for the given request.
+ *
+ * This error is raised when the router cannot match the incoming HTTP method
+ * and URL pattern to any registered route in the application.
+ *
+ * @example
+ * ```ts
+ * throw new E_ROUTE_NOT_FOUND(['GET', '/nonexistent'])
+ * ```
  */
 export declare const E_ROUTE_NOT_FOUND: new (args: [method: string, url: string], options?: ErrorOptions) => Exception;
 /**
  * Thrown when unable to lookup a route by its identifier.
+ *
+ * This error occurs when trying to generate URLs or find routes using
+ * a route name, pattern, or controller reference that doesn't exist.
+ *
+ * @example
+ * ```ts
+ * throw new E_CANNOT_LOOKUP_ROUTE(['nonexistent.route'])
+ * ```
  */
 export declare const E_CANNOT_LOOKUP_ROUTE: new (args: [routeIdentifier: string], options?: ErrorOptions) => Exception;
 /**
- * A generic HTTP exception to convert errors to HTTP response
+ * A generic HTTP exception for converting errors to HTTP responses.
+ *
+ * This class provides a standardized way to create HTTP exceptions with
+ * specific status codes and response bodies. It handles various input types
+ * including strings, objects, and null/undefined values.
+ *
+ * @example
+ * ```ts
+ * throw E_HTTP_EXCEPTION.invoke('Not found', 404)
+ * throw E_HTTP_EXCEPTION.invoke({ error: 'Invalid data' }, 422)
+ * ```
  */
 export declare const E_HTTP_EXCEPTION: {
     new (message?: string, options?: ErrorOptions & {
@@ -29,7 +55,17 @@ export declare const E_HTTP_EXCEPTION: {
     };
     code: string;
     /**
-     * This method returns an instance of the exception class
+     * Creates and returns an instance of the HttpException class.
+     *
+     * @param body - The response body (string, object, or null/undefined)
+     * @param status - HTTP status code for the response
+     * @param code - Optional error code (defaults to 'E_HTTP_EXCEPTION')
+     *
+     * @example
+     * ```ts
+     * const error = HttpException.invoke('Resource not found', 404)
+     * const error2 = HttpException.invoke({ message: 'Validation failed' }, 422)
+     * ```
      */
     invoke(body: any, status: number, code?: string): {
         body: any;
@@ -52,7 +88,16 @@ export declare const E_HTTP_EXCEPTION: {
     stackTraceLimit: number;
 };
 /**
- * Thrown when the "response.abort" method is called
+ * Thrown when the "response.abort" method is called.
+ *
+ * This exception is used to immediately terminate request processing
+ * and send a response. It includes a built-in handler that automatically
+ * sends the appropriate status and body to the client.
+ *
+ * @example
+ * ```ts
+ * throw new E_HTTP_REQUEST_ABORTED()
+ * ```
  */
 export declare const E_HTTP_REQUEST_ABORTED: {
     new (message?: string, options?: ErrorOptions & {
@@ -73,7 +118,17 @@ export declare const E_HTTP_REQUEST_ABORTED: {
     };
     code: string;
     /**
-     * This method returns an instance of the exception class
+     * Creates and returns an instance of the HttpException class.
+     *
+     * @param body - The response body (string, object, or null/undefined)
+     * @param status - HTTP status code for the response
+     * @param code - Optional error code (defaults to 'E_HTTP_EXCEPTION')
+     *
+     * @example
+     * ```ts
+     * const error = HttpException.invoke('Resource not found', 404)
+     * const error2 = HttpException.invoke({ message: 'Validation failed' }, 422)
+     * ```
      */
     invoke(body: any, status: number, code?: string): {
         body: any;

package/build/src/exception_handler.d.ts

@@ -3,111 +3,165 @@ import type { Level } from '@adonisjs/logger/types';
 import type { HttpContext } from './http_context/main.ts';
 import type { HttpError, StatusPageRange, StatusPageRenderer } from './types/server.ts';
 /**
- * The base HTTP exception handler one can inherit from to handle
- * HTTP exceptions.
+ * The base HTTP exception handler that provides comprehensive error handling capabilities.
  *
- * The HTTP exception handler has support for
+ * This class can be inherited to create custom exception handlers for your application.
+ * It provides built-in 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
+ * - Self-handling exceptions via their own render/handle methods
+ * - Custom status page rendering for different HTTP error codes
+ * - Debug-friendly error display during development
+ * - Content negotiation for JSON, JSON API, and HTML error responses
+ * - Configurable error reporting and logging
+ * - Validation error handling with field-specific messages
+ *
+ * @example
+ * ```ts
+ * export default class HttpExceptionHandler extends ExceptionHandler {
+ *   protected debug = app.inDev
+ *   protected renderStatusPages = app.inProduction
+ *
+ *   protected statusPages = {
+ *     '404': (error, ctx) => ctx.view.render('errors/404')
+ *   }
+ * }
+ * ```
  */
 export declare class ExceptionHandler extends Macroable {
     #private;
     /**
-     * Whether or not to render debug info. When set to true, the errors
-     * will have the complete error stack.
+     * Controls whether to include debug information in error responses
+     * When enabled, errors include complete stack traces and detailed debugging info
+     * Defaults to true in non-production environments
      */
     protected debug: boolean;
     /**
-     * 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.
+     * Controls whether to render custom status pages for unhandled errors
+     * When enabled, errors with matching status codes use configured status page renderers
+     * Defaults to true in production environments
      */
     protected renderStatusPages: boolean;
     /**
-     * A collection of error status code range and the view to render.
+     * Mapping of HTTP status code ranges to their corresponding page renderers
+     * Supports ranges like '400-499' or individual codes like '404'
      */
     protected statusPages: Record<StatusPageRange, StatusPageRenderer>;
     /**
-     * Enable/disable errors reporting
+     * Controls whether errors should be reported to logging systems
+     * When disabled, errors are handled but not logged or reported
      */
     protected reportErrors: boolean;
     /**
-     * An array of exception classes to ignore when
-     * reporting an error
+     * Array of exception class constructors to exclude from error reporting
+     * These exceptions are handled but not logged or reported to external systems
      */
     protected ignoreExceptions: any[];
     /**
-     * An array of HTTP status codes to ignore when reporting
-     * an error
+     * Array of HTTP status codes to exclude from error reporting
+     * Errors with these status codes are handled but not logged
      */
     protected ignoreStatuses: number[];
     /**
-     * An array of error codes to ignore when reporting
-     * an error
+     * Array of custom error codes to exclude from error reporting
+     * Errors with these codes are handled but not logged
      */
     protected ignoreCodes: string[];
     /**
-     * Error reporting context
+     * Provides additional context information for error reporting
+     * Includes request ID when available for correlation across logs
+     * @param ctx - HTTP context containing request information
+     * @returns Additional context data for error reporting
      */
     protected context(ctx: HttpContext): any;
     /**
-     * Returns the log level for an error based upon the error
-     * status code.
+     * Determines the appropriate log level based on HTTP status code
+     * 5xx errors are logged as 'error', 4xx as 'warn', others as 'info'
+     * @param error - HTTP error object with status code
+     * @returns {Level} Appropriate logging level for the error
      */
     protected getErrorLogLevel(error: HttpError): Level;
     /**
-     * A boolean to control if errors should be rendered with
-     * all the available debugging info.
+     * Determines whether debug information should be included in error responses
+     * Override this method to implement context-specific debug control
+     * @param _ - HTTP context (unused in base implementation)
+     * @returns {boolean} True if debugging should be enabled
      */
     protected isDebuggingEnabled(_: HttpContext): boolean;
     /**
-     * Returns a boolean by checking if an error should be reported.
+     * Determines whether an error should be reported to logging systems
+     * Checks against ignore lists for exceptions, status codes, and error codes
+     * @param error - HTTP error to evaluate for reporting
+     * @returns {boolean} True if the error should be reported
      */
     protected shouldReport(error: HttpError): boolean;
     /**
-     * Renders an error to JSON response
+     * Renders an error as a JSON response
+     * In debug mode, includes full stack trace using Youch
+     * @param error - HTTP error to render
+     * @param ctx - HTTP context for the request
      */
     renderErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Renders an error to JSON API response
+     * Renders an error as a JSON API compliant response
+     * Follows JSON API specification for error objects
+     * @param error - HTTP error to render
+     * @param ctx - HTTP context for the request
      */
     renderErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Renders an error to HTML response
+     * Renders an error as an HTML response
+     * Uses status pages if configured, otherwise shows debug info or simple message
+     * @param error - HTTP error to render
+     * @param ctx - HTTP context for the request
      */
     renderErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<any>;
     /**
-     * Renders the validation error message to a JSON
-     * response
+     * Renders validation error messages as a JSON response
+     * Returns errors in a simple format with field-specific messages
+     * @param error - Validation error containing messages array
+     * @param ctx - HTTP context for the request
      */
     renderValidationErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Renders the validation error message as per JSON API
-     * spec
+     * Renders validation error messages as JSON API compliant response
+     * Transforms validation messages to JSON API error object format
+     * @param error - Validation error containing messages array
+     * @param ctx - HTTP context for the request
      */
     renderValidationErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Renders the validation error as an HTML string
+     * Renders validation error messages as an HTML response
+     * Creates simple HTML list of field errors separated by line breaks
+     * @param error - Validation error containing messages array
+     * @param ctx - HTTP context for the request
      */
     renderValidationErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Renders the error to response
+     * Renders an error to the appropriate response format based on content negotiation
+     * Supports HTML, JSON API, and JSON formats based on Accept headers
+     * @param error - HTTP error to render
+     * @param ctx - HTTP context for the request
      */
     renderError(error: HttpError, ctx: HttpContext): Promise<any>;
     /**
-     * Renders the validation error to response
+     * Renders validation errors to the appropriate response format based on content negotiation
+     * Supports HTML, JSON API, and JSON formats for validation error messages
+     * @param error - Validation error to render
+     * @param ctx - HTTP context for the request
      */
     renderValidationError(error: HttpError, ctx: HttpContext): Promise<void>;
     /**
-     * Reports an error during an HTTP request
+     * Reports an error to logging systems if reporting is enabled
+     * Allows errors to self-report via their own report method if available
+     * @param error - Any error object to report
+     * @param ctx - HTTP context for additional reporting context
      */
     report(error: unknown, ctx: HttpContext): Promise<void>;
     /**
-     * Handles the error during the HTTP request.
+     * Handles errors during HTTP request processing
+     * Delegates to error's own handle method if available, otherwise renders response
+     * @param error - Any error object to handle
+     * @param ctx - HTTP context for error handling
      */
     handle(error: unknown, ctx: HttpContext): Promise<any>;
 }

package/build/src/helpers.d.ts

@@ -1,6 +1,11 @@
+import { type Encryption } from '@adonisjs/encryption';
+import { type Qs } from './qs.ts';
+import { createURL } from './client/helpers.ts';
 import { type CookieOptions } from './types/response.ts';
+import { type SignedURLOptions } from './types/url_builder.ts';
 import type { RouteMatchers, RouteJSON, MatchItRouteToken } from './types/route.ts';
 import { type MiddlewareFn, type RouteHandlerInfo, type MiddlewareHandlerInfo, type ParsedGlobalMiddleware, type ParsedNamedMiddleware } from './types/middleware.ts';
+export { createURL };
 /**
  * This function is similar to the intrinsic function encodeURI. However, it will not encode:
  *  - The \, ^, or | characters
@@ -34,25 +39,77 @@ export { default as mime } from 'mime-types';
  * Value (val) refers to the segment value
  *
  * end refers to be the suffix or the segment (if any)
+ *
+ * @param pattern - The route pattern to parse
+ * @param matchers - Optional route matchers
+ * @returns {MatchItRouteToken[]} Array of parsed route tokens
  */
 export declare function parseRoute(pattern: string, matchers?: RouteMatchers): MatchItRouteToken[];
+/**
+ * Makes signed URL for a given route pattern using its parsed tokens. The
+ * tokens could be generated using the "parseRoute" method.
+ *
+ * @param identifier - Route identifier
+ * @param tokens - Array of parsed route tokens
+ * @param searchParamsStringifier - Function to stringify query parameters
+ * @param encryption - Encryption instance for signing
+ * @param params - Route parameters as array or object
+ * @param options - Signed URL options
+ * @returns {string} The generated signed URL
+ */
+export declare function createSignedURL(identifier: string, tokens: MatchItRouteToken[], searchParamsStringifier: (qs: Record<string, any>) => string, encryption: Encryption, params?: any[] | {
+    [param: string]: any;
+}, options?: SignedURLOptions): string;
 /**
  * Match a given URI with an array of patterns and extract the params
  * from the URL. Null value is returned in case of no match
+ *
+ * @param url - The URL to match
+ * @param patterns - Array of route patterns to match against
+ * @returns {null | Record<string, string>} Extracted parameters or null if no match
  */
 export declare function matchRoute(url: string, patterns: string[]): null | Record<string, string>;
 /**
  * Serialize the value of a cookie to a string you can send via
  * set-cookie response header.
+ *
+ * @param key - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @returns {string} Serialized cookie string
  */
 export declare function serializeCookie(key: string, value: string, options?: Partial<CookieOptions>): string;
 /**
  * Returns the info about a middleware handler. In case of lazy imports, the method
  * will return the import path
+ *
+ * @param middleware - The middleware function or parsed middleware
+ * @returns {Promise<MiddlewareHandlerInfo>} Promise resolving to middleware handler information
  */
 export declare function middlewareInfo(middleware: MiddlewareFn | ParsedGlobalMiddleware | ParsedNamedMiddleware): Promise<MiddlewareHandlerInfo>;
 /**
  * Returns the info about a route handler. In case of lazy imports, the method
  * will return the import path.
+ *
+ * @param route - The route JSON object
+ * @returns {Promise<RouteHandlerInfo>} Promise resolving to route handler information
  */
 export declare function routeInfo(route: RouteJSON): Promise<RouteHandlerInfo>;
+/**
+ * Appends query string parameters to a URI. Existing query parameters
+ * in the URI are merged with the new ones.
+ *
+ * @param uri - The base URI to append query string to
+ * @param queryString - Object containing query parameters to append
+ * @param qsParser - Query string parser instance for stringify/parse operations
+ *
+ * @example
+ * ```ts
+ * const result = appendQueryString('/users', { page: 1, limit: 10 }, qsParser)
+ * // Returns: '/users?page=1&limit=10'
+ *
+ * const result2 = appendQueryString('/users?sort=name', { page: 1 }, qsParser)
+ * // Returns: '/users?sort=name&page=1'
+ * ```
+ */
+export declare function appendQueryString(uri: string, queryString: Record<string, any>, qsParser: Qs): string;

package/build/src/helpers.js

@@ -1,4 +1,6 @@
 import {
+  appendQueryString,
+  createSignedURL,
   default as default2,
   default2 as default3,
   matchRoute,
@@ -6,8 +8,14 @@ import {
   parseRoute,
   routeInfo,
   serializeCookie
-} from "../chunk-ASX56VAK.js";
+} from "../chunk-QDK57QGB.js";
+import {
+  createURL
+} from "../chunk-2QM3D5BN.js";
 export {
+  appendQueryString,
+  createSignedURL,
+  createURL,
   default2 as encodeUrl,
   matchRoute,
   middlewareInfo,

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

@@ -1,11 +1,28 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { HttpContext } from './main.ts';
+/**
+ * Async local storage for HTTP context
+ */
 /**
  * Async local storage for HTTP context
  */
 export declare const asyncLocalStorage: {
+    /**
+     * Check if the async local storage for the HTTP context is enabled or not
+     */
     isEnabled: boolean;
+    /**
+     * HTTP context storage instance for the current scope
+     */
     storage: null | AsyncLocalStorage<HttpContext>;
+    /**
+     * Create the storage instance. This method must be called only once.
+     *
+     * @returns {AsyncLocalStorage<HttpContext>} The created storage instance
+     */
     create(): AsyncLocalStorage<HttpContext>;
+    /**
+     * Destroy the create storage instance
+     */
     destroy(): void;
 };

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

@@ -5,8 +5,22 @@ import type { Request } from '../request.ts';
 import type { Response } from '../response.ts';
 import type { RouteJSON } from '../types/route.ts';
 /**
- * Http context encapsulates properties for a given HTTP request. The
- * context class can be extended using macros and getters.
+ * HTTP context encapsulates all properties and services for a given HTTP request.
+ *
+ * The HttpContext class serves as the central hub for request-specific data and services.
+ * It provides access to the request, response, route information, container resolver,
+ * and logger instances. The context can be extended using macros and getters for
+ * application-specific functionality.
+ *
+ * @example
+ * ```ts
+ * export default class UsersController {
+ *   async show({ request, response, params }: HttpContext) {
+ *     const user = await User.find(params.id)
+ *     return response.json(user)
+ *   }
+ * }
+ * ```
  */
 export declare class HttpContext extends Macroable {
     request: Request;
@@ -14,23 +28,59 @@ export declare class HttpContext extends Macroable {
     logger: Logger;
     containerResolver: ContainerResolver<any>;
     /**
-     * Find if async localstorage is enabled for HTTP requests
-     * or not
+     * Indicates whether async local storage is enabled for HTTP requests.
+     *
+     * When enabled, the HTTP context is automatically available within the
+     * scope of request processing through static methods like get() and getOrFail().
      */
     static get usingAsyncLocalStorage(): boolean;
     /**
-     * Get access to the HTTP context. Available only when
-     * "usingAsyncLocalStorage" is true
+     * Get access to the current HTTP context from async local storage.
+     *
+     * This method is only available when async local storage is enabled.
+     * Returns null if called outside of an HTTP request context.
+     *
+     * @example
+     * ```ts
+     * const ctx = HttpContext.get()
+     * if (ctx) {
+     *   console.log(ctx.request.url())
+     * }
+     * ```
      */
     static get(): HttpContext | null;
     /**
-     * Get the HttpContext instance or raise an exception if not
-     * available
+     * Get the HttpContext instance or raise an exception if not available.
+     *
+     * This method is useful when you need guaranteed access to the HTTP context
+     * and want to fail fast if it's not available.
+     *
+     * @throws RuntimeException when async local storage is disabled or context is unavailable
+     *
+     * @example
+     * ```ts
+     * const ctx = HttpContext.getOrFail()
+     * const userId = ctx.request.input('user_id')
+     * ```
      */
     static getOrFail(): HttpContext;
     /**
-     * Run a method that doesn't have access to HTTP context from
-     * the async local storage.
+     * Run a method outside of the HTTP context scope.
+     *
+     * This method allows you to execute code that should not have access to
+     * the current HTTP context from async local storage. Useful for background
+     * tasks or operations that should be context-independent.
+     *
+     * @param callback - Function to execute outside the context
+     * @param args - Arguments to pass to the callback
+     *
+     * @example
+     * ```ts
+     * HttpContext.runOutsideContext(() => {
+     *   // This code cannot access HttpContext.get()
+     *   performBackgroundTask()
+     * })
+     * ```
      */
     static runOutsideContext<T>(callback: (...args: any[]) => T, ...args: any[]): T;
     /**
@@ -50,6 +100,14 @@ export declare class HttpContext extends Macroable {
      * Route subdomains
      */
     subdomains: Record<string, any>;
+    /**
+     * Creates a new HttpContext instance
+     *
+     * @param {Request} request - The HTTP request instance
+     * @param {Response} response - The HTTP response instance
+     * @param {Logger} logger - The logger instance
+     * @param {ContainerResolver<any>} containerResolver - The IoC container resolver
+     */
     constructor(request: Request, response: Response, logger: Logger, containerResolver: ContainerResolver<any>);
     /**
      * A helper to see top level properties on the context object

package/build/src/qs.d.ts

@@ -1,11 +1,39 @@
 import { type QSParserConfig } from './types/qs.ts';
 /**
- * Query string parser used to parse and stringify query
- * strings.
+ * Query string parser that provides methods to parse and stringify query strings.
+ *
+ * This class wraps the popular 'qs' package with configurable options for parsing
+ * and stringifying query parameters. It allows customization of array handling,
+ * depth limits, and encoding behavior.
+ *
+ * @example
+ * ```ts
+ * const qs = new Qs({
+ *   parse: { depth: 5, arrayLimit: 20 },
+ *   stringify: { encode: false, skipNulls: true }
+ * })
+ *
+ * const parsed = qs.parse('users[0][name]=john&users[0][age]=25')
+ * const stringified = qs.stringify({ users: [{ name: 'john', age: 25 }] })
+ * ```
  */
 export declare class Qs {
     #private;
+    /**
+     * Creates a new query string parser instance with the provided configuration
+     * @param config - Configuration object with parse and stringify options
+     */
     constructor(config: QSParserConfig);
+    /**
+     * Parses a query string into a JavaScript object using the configured options
+     * @param value - Query string to parse (e.g., "foo=bar&baz=qux")
+     * @returns Parsed object representation of the query string
+     */
     parse: (value: string) => import("qs").ParsedQs;
+    /**
+     * Converts a JavaScript object into a query string using the configured options
+     * @param value - Object to convert to query string
+     * @returns Stringified query string representation of the object
+     */
     stringify: (value: any) => string;
 }