@adonisjs/http-server 8.0.0-next.5 → 8.0.0-next.7

package/build/src/cookies/drivers/encrypted.d.ts

@@ -1,16 +1,29 @@
 import type { Encryption } from '@adonisjs/encryption';
 /**
  * Encrypt a value to be set as cookie
+ *
+ * @param key - The cookie key used for encryption
+ * @param value - The value to encrypt
+ * @param encryption - The encryption instance
+ * @returns The encrypted cookie string or null if value is null/undefined
  */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
 /**
  * Returns a boolean, if the unpack method from this module can attempt
  * to unpack encrypted value.
+ *
+ * @param encryptedValue - The encrypted value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(encryptedValue: string): boolean;
 /**
  * Attempts to unpack the encrypted cookie value. Returns null, when fails to do so.
  * Only call this method, when `canUnpack` returns true, otherwise runtime
  * exceptions can be raised.
+ *
+ * @param key - The cookie key used for decryption
+ * @param encryptedValue - The encrypted value to decrypt
+ * @param encryption - The encryption instance
+ * @returns The decrypted value or null if decryption fails
  */
 export declare function unpack(key: string, encryptedValue: string, encryption: Encryption): null | any;

package/build/src/cookies/drivers/plain.d.ts

@@ -1,15 +1,24 @@
 /**
  * Encodes a value into a base64 url encoded string to
  * be set as cookie
+ *
+ * @param value - The value to encode
+ * @returns The encoded cookie string or null if value is null/undefined
  */
 export declare function pack(value: any): null | string;
 /**
  * Returns true when this `unpack` method of this module can attempt
  * to unpack the encode value.
+ *
+ * @param encodedValue - The encoded value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(encodedValue: string): boolean;
 /**
  * Attempts to unpack the value by decoding it. Make sure to call, `canUnpack`
  * before calling this method
+ *
+ * @param encodedValue - The encoded value to decode
+ * @returns The decoded value or null if decoding fails
  */
 export declare function unpack(encodedValue: string): null | any;

package/build/src/cookies/drivers/signed.d.ts

@@ -2,15 +2,28 @@ import type { Encryption } from '@adonisjs/encryption';
 /**
  * Signs a value to be shared as a cookie. The signed output has a
  * hash to verify tampering with the original value
+ *
+ * @param key - The cookie key used for signing
+ * @param value - The value to sign
+ * @param encryption - The encryption instance
+ * @returns The signed cookie string or null if value is null/undefined
  */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
 /**
  * Returns a boolean, if the unpack method from this module can attempt
  * to unpack the signed value.
+ *
+ * @param signedValue - The signed value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(signedValue: string): boolean;
 /**
  * Attempts to unpack the signed value. Make sure to call `canUnpack` before
  * calling this method.
+ *
+ * @param key - The cookie key used for verification
+ * @param signedValue - The signed value to verify and unpack
+ * @param encryption - The encryption instance
+ * @returns The original value or null if verification fails
  */
 export declare function unpack(key: string, signedValue: string, encryption: Encryption): null | any;

package/build/src/cookies/parser.d.ts

@@ -11,27 +11,45 @@ import type { Encryption } from '@adonisjs/encryption';
  */
 export declare class CookieParser {
     #private;
+    /**
+     * Create a new instance of CookieParser
+     *
+     * @param cookieHeader - The raw cookie header string from the request
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(cookieHeader: string, encryption: Encryption);
     /**
      * Attempts to decode a cookie by the name. When calling this method,
      * you are assuming that the cookie was just stringified in the first
      * place and not signed or encrypted.
+     *
+     * @param key - The cookie key to decode
+     * @param stringified - Whether the cookie value was stringified
+     * @returns The decoded cookie value or null if decoding fails
      */
     decode(key: string, stringified?: boolean): any | null;
     /**
      * Attempts to unsign a cookie by the name. When calling this method,
      * you are assuming that the cookie was signed in the first place.
+     *
+     * @param key - The cookie key to unsign
+     * @returns The original cookie value or null if unsigning fails
      */
     unsign(key: string): null | any;
     /**
      * Attempts to decrypt a cookie by the name. When calling this method,
      * you are assuming that the cookie was encrypted in the first place.
+     *
+     * @param key - The cookie key to decrypt
+     * @returns The decrypted cookie value or null if decryption fails
      */
     decrypt(key: string): null | any;
     /**
      * Returns an object of cookies key-value pair. Do note, the
      * cookies are not decoded, unsigned or decrypted inside this
      * list.
+     *
+     * @returns Raw cookies as key-value pairs
      */
     list(): Record<string, any>;
 }

package/build/src/cookies/serializer.d.ts

@@ -7,6 +7,11 @@ import type { CookieOptions } from '../types/response.ts';
  */
 export declare class CookieSerializer {
     #private;
+    /**
+     * Create a new instance of CookieSerializer
+     *
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(encryption: Encryption);
     /**
      * Encodes value as a plain cookie. By default, the plain value will be converted
@@ -18,11 +23,15 @@ export declare class CookieSerializer {
      *  serializer.encode('name', 'virk')
      *  serializer.encode('name', 'virk', { stringify: false })
      * ```
+     *
+     * @param key - The cookie key
+     * @param value - The value to encode
+     * @param options - Cookie encoding options
+     * @returns The serialized cookie string or null if encoding fails
      */
     encode(key: string, value: any, options?: Partial<CookieOptions & {
         /**
-         * @depreacted
-         * Instead use stringify option
+         * @depreacted Instead use stringify option
          */
         encode: boolean;
         stringify: boolean;
@@ -30,10 +39,20 @@ export declare class CookieSerializer {
     /**
      * Sign a key-value pair to a signed cookie. The signed value has a
      * verification hash attached to it to detect data tampering.
+     *
+     * @param key - The cookie key
+     * @param value - The value to sign
+     * @param options - Cookie options
+     * @returns The serialized signed cookie string or null if signing fails
      */
     sign(key: string, value: any, options?: Partial<CookieOptions>): string | null;
     /**
      * Encrypts a key-value pair to an encrypted cookie.
+     *
+     * @param key - The cookie key
+     * @param value - The value to encrypt
+     * @param options - Cookie options
+     * @returns The serialized encrypted cookie string or null if encryption fails
      */
     encrypt(key: string, value: any, options?: Partial<CookieOptions>): string | null;
 }

package/build/src/define_config.d.ts

@@ -1,7 +1,5 @@
+import { type DeepPartial } from '@poppinss/utils/types';
 import type { ServerConfig } from './types/server.ts';
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
 type UserDefinedServerConfig = DeepPartial<Omit<ServerConfig, 'trustProxy'> & {
     trustProxy: ((address: string, distance: number) => boolean) | boolean | string;
 }>;

package/build/src/define_middleware.d.ts

@@ -1,5 +1,5 @@
 import type { LazyImport, UnWrapLazyImport } from '@poppinss/utils/types';
-import type { GetMiddlewareArgs, MiddlewareAsClass, ParsedGlobalMiddleware } from './types/middleware.ts';
+import type { MiddlewareAsClass, GetMiddlewareArgs, ParsedGlobalMiddleware } from './types/middleware.ts';
 /**
  * Define an collection of named middleware. The collection gets converted
  * into a collection of factory functions. Calling the function returns

package/build/src/exception_handler.d.ts

@@ -17,97 +17,138 @@ import type { HttpError, StatusPageRange, StatusPageRenderer } from './types/ser
 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,4 +1,6 @@
+import { type Encryption } from '@adonisjs/encryption';
 import { type CookieOptions } from './types/response.ts';
+import { type SignedURLOptions, type URLOptions } 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';
 /**
@@ -34,25 +36,73 @@ 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 URL for a given route pattern using its parsed tokens. The
+ * tokens could be generated using the "parseRoute" method.
+ *
+ * @param pattern - The route pattern
+ * @param tokens - Array of parsed route tokens
+ * @param searchParamsStringifier - Function to stringify query parameters
+ * @param params - Route parameters as array or object
+ * @param options - URL options
+ * @returns {string} The generated URL
+ */
+export declare function createURL(pattern: string, tokens: Pick<MatchItRouteToken, 'val' | 'type' | 'end'>[], searchParamsStringifier: (qs: Record<string, any>) => string, params?: any[] | {
+    [param: string]: any;
+}, options?: URLOptions): string;
+/**
+ * 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>;

package/build/src/helpers.js

@@ -1,4 +1,6 @@
 import {
+  createSignedURL,
+  createURL,
   default as default2,
   default2 as default3,
   matchRoute,
@@ -6,8 +8,10 @@ import {
   parseRoute,
   routeInfo,
   serializeCookie
-} from "../chunk-ASX56VAK.js";
+} from "../chunk-NQNHMINZ.js";
 export {
+  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

@@ -50,6 +50,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

@@ -5,7 +5,21 @@ import { type QSParserConfig } from './types/qs.ts';
  */
 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;
 }

package/build/src/redirect.d.ts

@@ -8,34 +8,87 @@ import type { RoutesList, LookupList, URLOptions, GetRoutesForMethod, RouteBuild
  */
 export declare class Redirect {
     #private;
+    /**
+     * Creates a new Redirect instance for handling HTTP redirects
+     * @param request - Node.js incoming HTTP request
+     * @param response - AdonisJS response instance
+     * @param router - AdonisJS router instance
+     * @param qs - Query string parser instance
+     */
     constructor(request: IncomingMessage, response: Response, router: Router, qs: Qs);
     /**
-     * Set a custom status code.
+     * Sets a custom HTTP status code for the redirect response
+     * @param statusCode - HTTP status code to use (e.g., 301, 302, 307)
+     * @returns {this} The Redirect instance for method chaining
      */
     status(statusCode: number): this;
     /**
-     * Clearing query string values added using the
-     * "withQs" method
+     * Clears any query string values previously added using the withQs method
+     * @returns {this} The Redirect instance for method chaining
      */
     clearQs(): this;
     /**
-     * Define query string for the redirect. Not passing
-     * any value will forward the current request query
-     * string.
+     * Forwards the current request's query string to the redirect URL
+     *
+     * Use this overload when you want to preserve all existing query parameters
+     * from the current request in the redirect URL.
+     *
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * // If current URL is '/search?q=hello&page=2'
+     * response.redirect().withQs().toPath('/results')
+     * // Redirects to: '/results?q=hello&page=2'
+     * ```
      */
     withQs(): this;
+    /**
+     * Adds multiple query string parameters to the redirect URL
+     *
+     * Use this overload when you want to add several query parameters at once
+     * using an object with key-value pairs.
+     *
+     * @param values - Object containing query parameter names and values
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * response.redirect().withQs({ page: 1, sort: 'name' }).toPath('/users')
+     * // Redirects to: '/users?page=1&sort=name'
+     * ```
+     */
     withQs(values: Record<string, any>): this;
+    /**
+     * Adds a single query string parameter to the redirect URL
+     *
+     * Use this overload when you want to add just one query parameter
+     * with a specific name and value.
+     *
+     * @param name - The query parameter name
+     * @param value - The query parameter value
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * response.redirect().withQs('success', 'true').toPath('/dashboard')
+     * // Redirects to: '/dashboard?success=true'
+     * ```
+     */
     withQs(name: string, value: any): this;
     /**
-     * Redirect to the previous path.
+     * Redirects to the previous path using the Referer header
+     * Falls back to '/' if no referrer is found
      */
     back(): void;
     /**
-     * Redirect the request using a route identifier.
+     * Redirects to a route using its identifier (name, pattern, or handler reference)
+     * @param args - Route identifier, parameters, and options for URL building
      */
     toRoute<Identifier extends keyof GetRoutesForMethod<RoutesList, 'GET'> & string>(...args: RoutesList extends LookupList ? RouteBuilderArguments<Identifier, RoutesList['GET'][Identifier], URLOptions> : []): void;
     /**
-     * Redirect the request using a path.
+     * Redirects to a specific URL path
+     * @param url - Target URL path for redirection
      */
     toPath(url: string): void;
 }