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

package/build/{chunk-ASX56VAK.js → chunk-NQNHMINZ.js}

@@ -15,6 +15,63 @@ function parseRoute(pattern, matchers) {
   const tokens = matchit.parse(pattern, matchers);
   return tokens;
 }
+function createURL(pattern, tokens, searchParamsStringifier, params, options) {
+  const uriSegments = [];
+  const paramsArray = Array.isArray(params) ? params : null;
+  const paramsObject = !Array.isArray(params) ? params ?? {} : {};
+  let paramsIndex = 0;
+  for (const token of tokens) {
+    if (token.type === 0) {
+      uriSegments.push(token.val === "/" ? "" : `${token.val}${token.end}`);
+      continue;
+    }
+    if (token.type === 2) {
+      const values = paramsArray ? paramsArray.slice(paramsIndex) : paramsObject["*"];
+      if (!Array.isArray(values) || !values.length) {
+        throw new Error(
+          `Cannot make URL for "${pattern}". Invalid value provided for the wildcard param`
+        );
+      }
+      uriSegments.push(`${values.join("/")}${token.end}`);
+      break;
+    }
+    const paramName = token.val;
+    const value = paramsArray ? paramsArray[paramsIndex] : paramsObject[paramName];
+    const isDefined = value !== void 0 && value !== null;
+    if (token.type === 1 && !isDefined) {
+      throw new Error(
+        `Cannot make URL for "${pattern}". Missing value for the "${paramName}" param`
+      );
+    }
+    if (isDefined) {
+      uriSegments.push(`${value}${token.end}`);
+    }
+    paramsIndex++;
+  }
+  let URI = `/${uriSegments.join("/")}`;
+  if (options?.prefixUrl) {
+    URI = `${options?.prefixUrl.replace(/\/$/, "")}${URI}`;
+  }
+  if (options?.qs) {
+    const queryString = searchParamsStringifier(options?.qs);
+    URI = queryString ? `${URI}?${queryString}` : URI;
+  }
+  return URI;
+}
+function createSignedURL(identifier, tokens, searchParamsStringifier, encryption, params, options) {
+  const signature = encryption.verifier.sign(
+    createURL(identifier, tokens, searchParamsStringifier, params, {
+      ...options,
+      prefixUrl: void 0
+    }),
+    options?.expiresIn,
+    options?.purpose
+  );
+  return createURL(identifier, tokens, searchParamsStringifier, params, {
+    ...options,
+    qs: { ...options?.qs, signature }
+  });
+}
 function matchRoute(url, patterns) {
   const tokensBucket = patterns.map((pattern) => parseRoute(pattern));
   const match = matchit.match(url, tokensBucket);
@@ -67,6 +124,8 @@ async function routeInfo(route) {
 export {
   __export,
   parseRoute,
+  createURL,
+  createSignedURL,
   matchRoute,
   serializeCookie,
   middlewareInfo,

package/build/factories/http_context.d.ts

@@ -15,10 +15,11 @@ export declare class HttpContextFactory {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**
-     * Create request
+     * Create HTTP context instance
      */
     create(): HttpContext;
 }

package/build/factories/http_server.d.ts

@@ -1,5 +1,12 @@
 import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+/**
+ * HTTP server factory for testing purposes
+ */
 export declare const httpServer: {
+    /**
+     * Creates a new HTTP server for testing with automatic cleanup
+     * @param handler - The request handler function
+     */
     create(handler: (req: IncomingMessage, res: ServerResponse) => any | Promise<any>): Promise<{
         server: Server;
         url: string;

package/build/factories/main.js

@@ -6,8 +6,8 @@ import {
   Router,
   Server,
   defineConfig
-} from "../chunk-BFGF3A5X.js";
-import "../chunk-ASX56VAK.js";
+} from "../chunk-7ROFCP6L.js";
+import "../chunk-NQNHMINZ.js";
 
 // factories/router.ts
 import { AppFactory } from "@adonisjs/application/factories";
@@ -15,6 +15,9 @@ import { EncryptionFactory } from "@adonisjs/encryption/factories";
 
 // factories/qs_parser_factory.ts
 var QsParserFactory = class {
+  /**
+   * Default configuration options for the QS parser
+   */
   #options = {
     parse: {
       depth: 5,
@@ -31,7 +34,8 @@ var QsParserFactory = class {
     }
   };
   /**
-   * Merge encryption factory options
+   * Merge QS parser factory options
+   * @param options - Partial options to merge with existing configuration
    */
   merge(options) {
     Object.assign(this.#options.parse, options.parse);
@@ -39,7 +43,7 @@ var QsParserFactory = class {
     return this;
   }
   /**
-   * Create instance of the logger class
+   * Create instance of the QS parser class
    */
   create() {
     return new Qs(this.#options);
@@ -48,6 +52,9 @@ var QsParserFactory = class {
 
 // factories/router.ts
 var RouterFactory = class {
+  /**
+   * Factory parameters for creating router instances
+   */
   #parameters = {};
   /**
    * Returns an instance of the application class
@@ -64,6 +71,7 @@ var RouterFactory = class {
   }
   /**
    * Merge factory params
+   * @param params - Partial factory parameters to merge
    */
   merge(params) {
     Object.assign(this.#parameters, params);
@@ -84,6 +92,9 @@ import { randomUUID } from "crypto";
 import { IncomingMessage, ServerResponse } from "http";
 import { EncryptionFactory as EncryptionFactory2 } from "@adonisjs/encryption/factories";
 var RequestFactory = class {
+  /**
+   * Factory parameters for creating request instances
+   */
   #parameters = {};
   /**
    * Returns the config for the request class
@@ -115,6 +126,7 @@ var RequestFactory = class {
   }
   /**
    * Returns the HTTP res object
+   * @param req - The incoming message request object
    */
   #createResponse(req) {
     return this.#parameters.res || new ServerResponse(req);
@@ -128,6 +140,7 @@ var RequestFactory = class {
   }
   /**
    * Merge factory params
+   * @param params - Partial factory parameters to merge
    */
   merge(params) {
     Object.assign(this.#parameters, params);
@@ -153,6 +166,9 @@ import { Socket as Socket2 } from "net";
 import { IncomingMessage as IncomingMessage2, ServerResponse as ServerResponse2 } from "http";
 import { EncryptionFactory as EncryptionFactory3 } from "@adonisjs/encryption/factories";
 var ResponseFactory = class {
+  /**
+   * Factory parameters for creating response instances
+   */
   #parameters = {};
   /**
    * Returns the config for the request class
@@ -185,6 +201,7 @@ var ResponseFactory = class {
   }
   /**
    * Returns the HTTP res object
+   * @param req - The incoming message request object
    */
   #createResponse(req) {
     return this.#parameters.res || new ServerResponse2(req);
@@ -198,6 +215,7 @@ var ResponseFactory = class {
   }
   /**
    * Merge factory params
+   * @param params - Partial factory parameters to merge
    */
   merge(params) {
     Object.assign(this.#parameters, params);
@@ -225,6 +243,9 @@ import { Emitter } from "@adonisjs/events";
 import { AppFactory as AppFactory2 } from "@adonisjs/application/factories";
 import { EncryptionFactory as EncryptionFactory4 } from "@adonisjs/encryption/factories";
 var ServerFactory = class {
+  /**
+   * Factory parameters for creating server instances
+   */
   #parameters = {};
   /**
    * Returns the emitter instance
@@ -259,6 +280,7 @@ var ServerFactory = class {
   }
   /**
    * Merge factory params
+   * @param params - Partial factory parameters to merge
    */
   merge(params) {
     Object.assign(this.#parameters, params);
@@ -282,6 +304,9 @@ var ServerFactory = class {
 import { Container } from "@adonisjs/fold";
 import { LoggerFactory } from "@adonisjs/logger/factories";
 var HttpContextFactory = class {
+  /**
+   * Factory parameters for creating HTTP context instances
+   */
   #parameters = {};
   /**
    * Returns the request class instance
@@ -303,13 +328,14 @@ var HttpContextFactory = class {
   }
   /**
    * Merge factory params
+   * @param params - Partial factory parameters to merge
    */
   merge(params) {
     Object.assign(this.#parameters, params);
     return this;
   }
   /**
-   * Create request
+   * Create HTTP context instance
    */
   create() {
     return new HttpContext(

package/build/factories/qs_parser_factory.d.ts

@@ -7,14 +7,15 @@ import type { QSParserConfig } from '../src/types/qs.ts';
 export declare class QsParserFactory {
     #private;
     /**
-     * Merge encryption factory options
+     * Merge QS parser factory options
+     * @param options - Partial options to merge with existing configuration
      */
     merge(options: Partial<{
         parse: Partial<QSParserConfig['parse']>;
         stringify: Partial<QSParserConfig['stringify']>;
     }>): this;
     /**
-     * Create instance of the logger class
+     * Create instance of the QS parser class
      */
     create(): Qs;
 }

package/build/factories/request.d.ts

@@ -18,6 +18,7 @@ export declare class RequestFactory {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**

package/build/factories/response.d.ts

@@ -18,6 +18,7 @@ export declare class ResponseFactory {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**

package/build/factories/router.d.ts

@@ -13,6 +13,7 @@ export declare class RouterFactory {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**

package/build/factories/server_factory.d.ts

@@ -19,6 +19,7 @@ export declare class ServerFactory {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**

package/build/factories/url_builder_factory.d.ts

@@ -12,6 +12,7 @@ export declare class URLBuilderFactory<Routes extends LookupList> {
     #private;
     /**
      * Merge factory params
+     * @param params - Partial factory parameters to merge
      */
     merge(params: Partial<FactoryParameters>): this;
     /**

package/build/index.d.ts

@@ -9,8 +9,10 @@ export { BriskRoute } from './src/router/brisk.ts';
 export { RouteGroup } from './src/router/group.ts';
 export { defineConfig } from './src/define_config.ts';
 export { CookieClient } from './src/cookies/client.ts';
+export { CookieParser } from './src/cookies/parser.ts';
 export { HttpContext } from './src/http_context/main.ts';
 export { RouteResource } from './src/router/resource.ts';
 export { ResponseStatus } from './src/response_status.ts';
-export { ExceptionHandler } from './src/exception_handler.ts';
 export * as tracingChannels from './src/tracing_channels.ts';
+export { ExceptionHandler } from './src/exception_handler.ts';
+export { CookieSerializer } from './src/cookies/serializer.ts';

package/build/index.js

@@ -1,6 +1,8 @@
 import {
   BriskRoute,
   CookieClient,
+  CookieParser,
+  CookieSerializer,
   E_CANNOT_LOOKUP_ROUTE,
   E_HTTP_EXCEPTION,
   E_HTTP_REQUEST_ABORTED,
@@ -20,39 +22,43 @@ import {
   errors_exports,
   parseRange,
   tracing_channels_exports
-} from "./chunk-BFGF3A5X.js";
-import "./chunk-ASX56VAK.js";
+} from "./chunk-7ROFCP6L.js";
+import "./chunk-NQNHMINZ.js";
 
 // src/exception_handler.ts
 import is from "@sindresorhus/is";
 import Macroable from "@poppinss/macroable";
 var ExceptionHandler = class extends Macroable {
   /**
-   * Computed from the status pages property
+   * Cached expanded status pages mapping individual status codes to their renderers
+   * Computed from the statusPages property when first accessed
    */
   #expandedStatusPages;
   /**
-   * 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
    */
   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.
+   * 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
    */
   renderStatusPages = process.env.NODE_ENV === "production";
   /**
-   * 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'
    */
   statusPages = {};
   /**
-   * Enable/disable errors reporting
+   * Controls whether errors should be reported to logging systems
+   * When disabled, errors are handled but not logged or reported
    */
   reportErrors = true;
   /**
-   * 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
    */
   ignoreExceptions = [
     E_HTTP_EXCEPTION,
@@ -61,17 +67,19 @@ var ExceptionHandler = class extends Macroable {
     E_HTTP_REQUEST_ABORTED
   ];
   /**
-   * 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
    */
   ignoreStatuses = [400, 422, 401];
   /**
-   * 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
    */
   ignoreCodes = [];
   /**
-   * Expands status pages
+   * Expands status page ranges into individual status code mappings
+   * Creates a cached lookup table for faster status page resolution
+   * @returns Mapping of status codes to renderers
    */
   #expandStatusPages() {
     if (!this.#expandedStatusPages) {
@@ -87,8 +95,10 @@ var ExceptionHandler = class extends Macroable {
     return this.#expandedStatusPages;
   }
   /**
-   * Forcefully tweaking the type of the error object to
-   * have known properties.
+   * Normalizes any thrown value into a standardized HttpError object
+   * Ensures the error has required properties like message and status
+   * @param error - Any thrown value (Error, string, object, etc.)
+   * @returns {HttpError} Normalized error object with status and message
    */
   #toHttpError(error) {
     const httpError = is.object(error) ? error : new Error(String(error));
@@ -101,7 +111,10 @@ var ExceptionHandler = class extends Macroable {
     return httpError;
   }
   /**
-   * 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
    */
   context(ctx) {
     const requestId = ctx.request.id();
@@ -110,8 +123,10 @@ var ExceptionHandler = class extends Macroable {
     } : {};
   }
   /**
-   * 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
    */
   getErrorLogLevel(error) {
     if (error.status >= 500) {
@@ -123,14 +138,19 @@ var ExceptionHandler = class extends Macroable {
     return "info";
   }
   /**
-   * 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
    */
   isDebuggingEnabled(_) {
     return this.debug;
   }
   /**
-   * 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
    */
   shouldReport(error) {
     if (this.reportErrors === false) {
@@ -148,7 +168,10 @@ var ExceptionHandler = class extends Macroable {
     return true;
   }
   /**
-   * 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
    */
   async renderErrorAsJSON(error, ctx) {
     if (this.isDebuggingEnabled(ctx)) {
@@ -160,7 +183,10 @@ var ExceptionHandler = class extends Macroable {
     ctx.response.status(error.status).send({ message: error.message });
   }
   /**
-   * 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
    */
   async renderErrorAsJSONAPI(error, ctx) {
     if (this.isDebuggingEnabled(ctx)) {
@@ -180,7 +206,10 @@ var ExceptionHandler = class extends Macroable {
     });
   }
   /**
-   * 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
    */
   async renderErrorAsHTML(error, ctx) {
     const statusPages = this.#expandStatusPages();
@@ -203,8 +232,10 @@ var ExceptionHandler = class extends Macroable {
     ctx.response.status(error.status).send(`<p> ${error.message} </p>`);
   }
   /**
-   * 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
    */
   async renderValidationErrorAsJSON(error, ctx) {
     ctx.response.status(error.status).send({
@@ -212,8 +243,10 @@ var ExceptionHandler = class extends Macroable {
     });
   }
   /**
-   * 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
    */
   async renderValidationErrorAsJSONAPI(error, ctx) {
     ctx.response.status(error.status).send({
@@ -230,7 +263,10 @@ var ExceptionHandler = class extends Macroable {
     });
   }
   /**
-   * 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
    */
   async renderValidationErrorAsHTML(error, ctx) {
     ctx.response.status(error.status).type("html").send(
@@ -240,7 +276,10 @@ var ExceptionHandler = class extends Macroable {
     );
   }
   /**
-   * 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, ctx) {
     switch (ctx.request.accepts(["html", "application/vnd.api+json", "json"])) {
@@ -254,7 +293,10 @@ var ExceptionHandler = class extends Macroable {
     }
   }
   /**
-   * 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, ctx) {
     switch (ctx.request.accepts(["html", "application/vnd.api+json", "json"])) {
@@ -268,7 +310,10 @@ var ExceptionHandler = class extends Macroable {
     }
   }
   /**
-   * 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
    */
   async report(error, ctx) {
     const httpError = this.#toHttpError(error);
@@ -290,7 +335,10 @@ var ExceptionHandler = class extends Macroable {
     );
   }
   /**
-   * 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
    */
   async handle(error, ctx) {
     const httpError = this.#toHttpError(error);
@@ -306,6 +354,8 @@ var ExceptionHandler = class extends Macroable {
 export {
   BriskRoute,
   CookieClient,
+  CookieParser,
+  CookieSerializer,
   ExceptionHandler,
   HttpContext,
   Redirect,

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

@@ -5,33 +5,68 @@ import type { Encryption } from '@adonisjs/encryption';
  */
 export declare class CookieClient {
     #private;
+    /**
+     * Create a new instance of CookieClient
+     *
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(encryption: Encryption);
     /**
      * Encrypt a key value pair to be sent in the cookie header
+     *
+     * @param key - The cookie key
+     * @param value - The value to encrypt
+     * @returns The encrypted cookie string or null if encryption fails
      */
     encrypt(key: string, value: any): string | null;
     /**
      * Sign a key value pair to be sent in the cookie header
+     *
+     * @param key - The cookie key
+     * @param value - The value to sign
+     * @returns The signed cookie string or null if signing fails
      */
     sign(key: string, value: any): string | null;
     /**
      * Encode a key value pair to be sent in the cookie header
+     *
+     * @param _ - Unused key parameter
+     * @param value - The value to encode
+     * @param stringify - Whether to stringify the value before encoding
+     * @returns The encoded cookie string or null if encoding fails
      */
     encode(_: string, value: any, stringify?: boolean): string | null;
     /**
      * Unsign a signed cookie value
+     *
+     * @param key - The cookie key
+     * @param value - The signed cookie value to unsign
+     * @returns The original value if valid signature, null otherwise
      */
     unsign(key: string, value: string): any;
     /**
      * Decrypt an encrypted cookie value
+     *
+     * @param key - The cookie key
+     * @param value - The encrypted cookie value to decrypt
+     * @returns The decrypted value or null if decryption fails
      */
     decrypt(key: string, value: string): any;
     /**
      * Decode an encoded cookie value
+     *
+     * @param _ - Unused key parameter
+     * @param value - The encoded cookie value to decode
+     * @param stringified - Whether the value was stringified during encoding
+     * @returns The decoded value or null if decoding fails
      */
     decode(_: string, value: string, stringified?: boolean): any;
     /**
      * Parse response cookie
+     *
+     * @param key - The cookie key
+     * @param value - The cookie value to parse
+     * @returns The parsed value or undefined if parsing fails
      */
     parse(key: string, value: any): any;
 }