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

package/build/{chunk-BFGF3A5X.js → chunk-3XEJZ4S4.js}

@@ -1,10 +1,12 @@
 import {
   __export,
+  createSignedURL,
+  createURL,
   default as default2,
   default2 as default3,
   parseRoute,
   serializeCookie
-} from "./chunk-ASX56VAK.js";
+} from "./chunk-NQNHMINZ.js";
 
 // src/errors.ts
 var errors_exports = {};
@@ -107,42 +109,76 @@ function unpack3(key, encryptedValue, encryption) {
 
 // src/cookies/client.ts
 var CookieClient = class {
+  /**
+   * Private encryption instance used for signing and encrypting cookies
+   */
   #encryption;
+  /**
+   * Create a new instance of CookieClient
+   *
+   * @param encryption - The encryption instance for cookie operations
+   */
   constructor(encryption) {
     this.#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, value) {
     return pack3(key, value, this.#encryption);
   }
   /**
    * 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, value) {
     return pack2(key, value, this.#encryption);
   }
   /**
    * 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(_, value, stringify2 = true) {
     return stringify2 ? pack(value) : value;
   }
   /**
    * 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, value) {
     return canUnpack2(value) ? unpack2(key, value, this.#encryption) : null;
   }
   /**
    * 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, value) {
     return canUnpack3(value) ? unpack3(key, value, this.#encryption) : null;
   }
   /**
    * 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(_, value, stringified = true) {
     if (!stringified) {
@@ -152,6 +188,10 @@ var CookieClient = class {
   }
   /**
    * 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, value) {
     if (canUnpack2(value)) {
@@ -166,6 +206,129 @@ var CookieClient = class {
   }
 };
 
+// src/cookies/parser.ts
+import cookie from "cookie";
+var CookieParser = class {
+  /**
+   * Cookie client instance for handling cookie operations
+   */
+  #client;
+  /**
+   * A copy of cached cookies, they are cached during a request after
+   * initial decoding, unsigning or decrypting.
+   */
+  #cachedCookies = {
+    signedCookies: {},
+    plainCookies: {},
+    encryptedCookies: {}
+  };
+  /**
+   * An object of key-value pair collected by parsing
+   * the request cookie header.
+   */
+  #cookies;
+  /**
+   * 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, encryption) {
+    this.#client = new CookieClient(encryption);
+    this.#cookies = this.#parse(cookieHeader);
+  }
+  /**
+   * Parses the request `cookie` header
+   *
+   * @param cookieHeader - The cookie header string to parse
+   * @returns Parsed cookies as key-value pairs
+   */
+  #parse(cookieHeader) {
+    if (!cookieHeader) {
+      return {};
+    }
+    return cookie.parse(cookieHeader);
+  }
+  /**
+   * 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, stringified = true) {
+    const value = this.#cookies[key];
+    if (value === null || value === void 0) {
+      return null;
+    }
+    const cache = this.#cachedCookies.plainCookies;
+    if (cache[key] !== void 0) {
+      return cache[key];
+    }
+    const parsed = this.#client.decode(key, value, stringified);
+    if (parsed !== null) {
+      cache[key] = parsed;
+    }
+    return parsed;
+  }
+  /**
+   * 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) {
+    const value = this.#cookies[key];
+    if (value === null || value === void 0) {
+      return null;
+    }
+    const cache = this.#cachedCookies.signedCookies;
+    if (cache[key] !== void 0) {
+      return cache[key];
+    }
+    const parsed = this.#client.unsign(key, value);
+    if (parsed !== null) {
+      cache[key] = parsed;
+    }
+    return parsed;
+  }
+  /**
+   * 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) {
+    const value = this.#cookies[key];
+    if (value === null || value === void 0) {
+      return null;
+    }
+    const cache = this.#cachedCookies.encryptedCookies;
+    if (cache[key] !== void 0) {
+      return cache[key];
+    }
+    const parsed = this.#client.decrypt(key, value);
+    if (parsed !== null) {
+      cache[key] = parsed;
+    }
+    return parsed;
+  }
+  /**
+   * 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() {
+    return this.#cookies;
+  }
+};
+
 // src/tracing_channels.ts
 var tracing_channels_exports = {};
 __export(tracing_channels_exports, {
@@ -176,14 +339,14 @@ __export(tracing_channels_exports, {
   httpRouteHandler: () => httpRouteHandler
 });
 import diagnostics_channel from "diagnostics_channel";
-var httpRequest = diagnostics_channel.tracingChannel("adonisjs:http.request");
-var httpMiddleware = diagnostics_channel.tracingChannel("adonisjs:http.middleware");
+var httpRequest = diagnostics_channel.tracingChannel("adonisjs.http.request");
+var httpMiddleware = diagnostics_channel.tracingChannel("adonisjs.http.middleware");
 var httpExceptionHandler = diagnostics_channel.tracingChannel(
-  "adonisjs:http.exception.handler"
+  "adonisjs.http.exception.handler"
 );
-var httpRouteHandler = diagnostics_channel.tracingChannel("adonisjs:http.route.handler");
+var httpRouteHandler = diagnostics_channel.tracingChannel("adonisjs.http.route.handler");
 var httpResponseSerializer = diagnostics_channel.tracingChannel(
-  "adonisjs:http.response.serializer"
+  "adonisjs.http.response.serializer"
 );
 
 // src/router/route.ts
@@ -217,14 +380,14 @@ function execute(route, resolver, ctx, errorResponder) {
     if (typeof route.handler === "function") {
       return httpRouteHandler.tracePromise(
         ($ctx) => Promise.resolve(route.handler($ctx)),
-        route,
+        httpRouteHandler.hasSubscribers ? { route } : void 0,
         void 0,
         ctx
       ).then(useReturnValue(ctx));
     }
     return httpRouteHandler.tracePromise(
       route.handler.handle,
-      route,
+      httpRouteHandler.hasSubscribers ? { route } : void 0,
       void 0,
       resolver,
       ctx
@@ -233,7 +396,7 @@ function execute(route, resolver, ctx, errorResponder) {
     if (typeof middleware === "function") {
       return httpMiddleware.tracePromise(
         middleware,
-        middleware,
+        httpMiddleware.hasSubscribers ? { middleware } : void 0,
         void 0,
         ctx,
         next
@@ -241,7 +404,7 @@ function execute(route, resolver, ctx, errorResponder) {
     }
     return httpMiddleware.tracePromise(
       middleware.handle,
-      middleware,
+      httpMiddleware.hasSubscribers ? { middleware } : void 0,
       void 0,
       resolver,
       ctx,
@@ -281,6 +444,12 @@ var BriskRoute = class extends Macroable {
    * Reference to route instance. Set after `setHandler` is called
    */
   route = null;
+  /**
+   * Creates a new BriskRoute instance
+   * @param app - The AdonisJS application instance
+   * @param routerMiddleware - Array of global middleware registered on the router
+   * @param options - Configuration options for the brisk route
+   */
   constructor(app, routerMiddleware, options) {
     super();
     this.#app = app;
@@ -290,6 +459,8 @@ var BriskRoute = class extends Macroable {
   }
   /**
    * Set handler for the brisk route
+   * @param handler - The route handler function
+   * @returns The created route instance
    */
   setHandler(handler) {
     this.route = new Route(this.#app, this.#routerMiddleware, {
@@ -303,6 +474,8 @@ var BriskRoute = class extends Macroable {
   /**
    * Redirects to a given route. Params from the original request will
    * be used when no custom params are defined.
+   * @param args - Route identifier, parameters, and options for building the redirect URL
+   * @returns The created route instance
    */
   redirect(...args) {
     const [identifier, params, options] = args;
@@ -318,6 +491,9 @@ var BriskRoute = class extends Macroable {
   }
   /**
    * Redirect request to a fixed URL
+   * @param url - The URL to redirect to
+   * @param options - Optional redirect options including HTTP status code
+   * @returns The created route instance
    */
   redirectToPath(url, options) {
     function redirectsToPath(ctx) {
@@ -378,6 +554,12 @@ var RouteResource = class extends Macroable2 {
    * A collection of routes instances that belongs to this resource
    */
   routes = [];
+  /**
+   * Creates a new RouteResource instance
+   * @param app - The AdonisJS application instance
+   * @param routerMiddleware - Array of global middleware registered on the router
+   * @param options - Configuration options for the route resource
+   */
   constructor(app, routerMiddleware, options) {
     super();
     this.#validateResourceName(options.resource);
@@ -468,6 +650,8 @@ var RouteResource = class extends Macroable2 {
   }
   /**
    * Register only given routes and remove others
+   * @param names - Array of action names to keep
+   * @returns Current RouteResource instance with filtered actions
    */
   only(names) {
     this.#filter(names, true).forEach((route) => route.markAsDeleted());
@@ -475,6 +659,8 @@ var RouteResource = class extends Macroable2 {
   }
   /**
    * Register all routes, except the one's defined
+   * @param names - Array of action names to exclude
+   * @returns Current RouteResource instance with filtered actions
    */
   except(names) {
     this.#filter(names, false).forEach((route) => route.markAsDeleted());
@@ -483,12 +669,16 @@ var RouteResource = class extends Macroable2 {
   /**
    * Register api only routes. The `create` and `edit` routes, which
    * are meant to show forms will not be registered
+   * @returns Current RouteResource instance without create and edit actions
    */
   apiOnly() {
     return this.except(["create", "edit"]);
   }
   /**
    * Define matcher for params inside the resource
+   * @param key - The parameter name to match
+   * @param matcher - The matcher pattern (RegExp, string, or RouteMatcher)
+   * @returns Current RouteResource instance for method chaining
    */
   where(key, matcher) {
     this.routes.forEach((route) => {
@@ -514,6 +704,8 @@ var RouteResource = class extends Macroable2 {
   }
   /**
    * Set the param name for a given resource
+   * @param resources - Object mapping resource names to parameter names
+   * @returns Current RouteResource instance for method chaining
    */
   params(resources) {
     Object.keys(resources).forEach((resource) => {
@@ -534,6 +726,9 @@ var RouteResource = class extends Macroable2 {
    *
    * Calling this method multiple times will append middleware
    * to existing list.
+   * @param actions - Action name(s) or '*' for all actions
+   * @param middleware - Middleware function(s) to apply
+   * @returns Current RouteResource instance for method chaining
    */
   use(actions, middleware) {
     if (actions === "*") {
@@ -544,13 +739,19 @@ var RouteResource = class extends Macroable2 {
     return this;
   }
   /**
-   * @alias use
+   * Alias for {@link RouteResource.use}
+   * @param actions - Action name(s) or '*' for all actions
+   * @param middleware - Middleware function(s) to apply
+   * @returns Current RouteResource instance for method chaining
    */
   middleware(actions, middleware) {
     return this.use(actions, middleware);
   }
   /**
    * Prepend name to all the routes
+   * @param name - The name to prepend to all route names
+   * @param normalizeName - Whether to normalize the name to snake_case
+   * @returns Current RouteResource instance for method chaining
    */
   as(name, normalizeName = true) {
     name = normalizeName ? string.snakeCase(name) : name;
@@ -564,6 +765,10 @@ var RouteResource = class extends Macroable2 {
 
 // src/router/group.ts
 var RouteGroup = class _RouteGroup extends Macroable3 {
+  /**
+   * Creates a new RouteGroup instance
+   * @param routes - Array of routes that belong to this group
+   */
   constructor(routes) {
     super();
     this.routes = routes;
@@ -679,6 +884,9 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
    * Route.group(() => {
    * }).where('id', /^[0-9]+/)
    * ```
+   * @param param - The parameter name to match
+   * @param matcher - The matcher pattern (RegExp, string, or RouteMatcher)
+   * @returns Current RouteGroup instance for method chaining
    */
   where(param, matcher) {
     this.routes.forEach((route) => this.#updateRouteMatchers(route, param, matcher));
@@ -691,6 +899,8 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
    * Route.group(() => {
    * }).prefix('v1')
    * ```
+   * @param prefix - The prefix to add to all routes in the group
+   * @returns Current RouteGroup instance for method chaining
    */
   prefix(prefix) {
     this.routes.forEach((route) => this.#setRoutePrefix(route, prefix));
@@ -703,6 +913,8 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
    * Route.group(() => {
    * }).domain(':name.adonisjs.com')
    * ```
+   * @param domain - The domain pattern for all routes in the group
+   * @returns Current RouteGroup instance for method chaining
    */
   domain(domain) {
     this.routes.forEach((route) => this.#updateRouteDomain(route, domain));
@@ -715,6 +927,8 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
    * Route.group(() => {
    * }).as('version1')
    * ```
+   * @param name - The name to prepend to all route names in the group
+   * @returns Current RouteGroup instance for method chaining
    */
   as(name) {
     this.routes.forEach((route) => this.#updateRouteName(route, name));
@@ -727,6 +941,8 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
    * Route.group(() => {
    * }).use(middleware.auth())
    * ```
+   * @param middleware - Middleware function(s) to apply to all routes in the group
+   * @returns Current RouteGroup instance for method chaining
    */
   use(middleware) {
     if (!this.#middleware.length) {
@@ -742,7 +958,9 @@ var RouteGroup = class _RouteGroup extends Macroable3 {
     return this;
   }
   /**
-   * @alias use
+   * Alias for {@link RouteGroup.use}
+   * @param middleware - Middleware function(s) to apply to all routes in the group
+   * @returns Current RouteGroup instance for method chaining
    */
   middleware(middleware) {
     return this.use(middleware);
@@ -934,6 +1152,12 @@ var Route = class extends Macroable4 {
    * routes. We mantain an array for each layer of the stack
    */
   #middleware = [];
+  /**
+   * Creates a new Route instance
+   * @param app - The AdonisJS application instance
+   * @param routerMiddleware - Array of global middleware registered on the router
+   * @param options - Configuration options for the route
+   */
   constructor(app, routerMiddleware, options) {
     super();
     this.#app = app;
@@ -1037,6 +1261,8 @@ var Route = class extends Macroable4 {
   /**
    * Define prefix for the route. Calling this method multiple times
    * applies multiple prefixes in the reverse order.
+   * @param prefix - The prefix to add to the route
+   * @returns Current Route instance for method chaining
    */
   prefix(prefix) {
     this.#prefixes.push(prefix);
@@ -1064,7 +1290,7 @@ var Route = class extends Macroable4 {
     return this;
   }
   /**
-   * @alias use
+   * Alias for {@link Route.use}
    */
   middleware(middleware) {
     return this.use(middleware);
@@ -1175,108 +1401,15 @@ import proxyaddr from "proxy-addr";
 import { safeEqual } from "@poppinss/utils";
 import Macroable5 from "@poppinss/macroable";
 import lodash from "@poppinss/utils/lodash";
-
-// src/cookies/parser.ts
-import cookie from "cookie";
-var CookieParser = class {
-  #client;
-  /**
-   * A copy of cached cookies, they are cached during a request after
-   * initial decoding, unsigning or decrypting.
-   */
-  #cachedCookies = {
-    signedCookies: {},
-    plainCookies: {},
-    encryptedCookies: {}
-  };
-  /**
-   * An object of key-value pair collected by parsing
-   * the request cookie header.
-   */
-  #cookies;
-  constructor(cookieHeader, encryption) {
-    this.#client = new CookieClient(encryption);
-    this.#cookies = this.#parse(cookieHeader);
-  }
-  /**
-   * Parses the request `cookie` header
-   */
-  #parse(cookieHeader) {
-    if (!cookieHeader) {
-      return {};
-    }
-    return cookie.parse(cookieHeader);
-  }
-  /**
-   * 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.
-   */
-  decode(key, stringified = true) {
-    const value = this.#cookies[key];
-    if (value === null || value === void 0) {
-      return null;
-    }
-    const cache = this.#cachedCookies.plainCookies;
-    if (cache[key] !== void 0) {
-      return cache[key];
-    }
-    const parsed = this.#client.decode(key, value, stringified);
-    if (parsed !== null) {
-      cache[key] = parsed;
-    }
-    return parsed;
-  }
-  /**
-   * Attempts to unsign a cookie by the name. When calling this method,
-   * you are assuming that the cookie was signed in the first place.
-   */
-  unsign(key) {
-    const value = this.#cookies[key];
-    if (value === null || value === void 0) {
-      return null;
-    }
-    const cache = this.#cachedCookies.signedCookies;
-    if (cache[key] !== void 0) {
-      return cache[key];
-    }
-    const parsed = this.#client.unsign(key, value);
-    if (parsed !== null) {
-      cache[key] = parsed;
-    }
-    return parsed;
-  }
-  /**
-   * Attempts to decrypt a cookie by the name. When calling this method,
-   * you are assuming that the cookie was encrypted in the first place.
-   */
-  decrypt(key) {
-    const value = this.#cookies[key];
-    if (value === null || value === void 0) {
-      return null;
-    }
-    const cache = this.#cachedCookies.encryptedCookies;
-    if (cache[key] !== void 0) {
-      return cache[key];
-    }
-    const parsed = this.#client.decrypt(key, value);
-    if (parsed !== null) {
-      cache[key] = parsed;
-    }
-    return parsed;
-  }
+var Request = class extends Macroable5 {
   /**
-   * Returns an object of cookies key-value pair. Do note, the
-   * cookies are not decoded, unsigned or decrypted inside this
-   * list.
+   * Creates a new Request instance wrapping the native Node.js HTTP request
+   * @param request - Native Node.js incoming message instance
+   * @param response - Native Node.js server response instance
+   * @param encryption - Encryption module for cookie and URL signing
+   * @param config - Request configuration options
+   * @param qsParser - Query string parser instance
    */
-  list() {
-    return this.#cookies;
-  }
-};
-
-// src/request.ts
-var Request = class extends Macroable5 {
   constructor(request, response, encryption, config, qsParser) {
     super();
     this.request = request;
@@ -1331,16 +1464,15 @@ var Request = class extends Macroable5 {
    */
   #cookieParser;
   /**
-   * Parsed URL with query string stored as a string.
+   * Parsed URL with query string stored as a string and decode flag
    */
   parsedUrl;
   /**
-   * The ctx will be set by the context itself. It creates a circular
-   * reference
+   * HTTP context reference - creates a circular reference when set by the context
    */
   ctx;
   /**
-   * Parses the query string
+   * Parses the query string from the parsed URL and updates internal state
    */
   #parseQueryString() {
     if (this.parsedUrl.query) {
@@ -1349,7 +1481,7 @@ var Request = class extends Macroable5 {
     }
   }
   /**
-   * Initiates the cookie parser lazily
+   * Initiates the cookie parser lazily when first needed
    */
   #initiateCookieParser() {
     if (!this.#cookieParser) {
@@ -1367,6 +1499,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns the request id from the `x-request-id` header. The
    * header is untouched, if it already exists.
+   * @returns The request ID or undefined if not found/generated
    */
   id() {
     let requestId = this.header("x-request-id");
@@ -1383,6 +1516,8 @@ var Request = class extends Macroable5 {
    *
    * This method is supposed to be invoked by the body parser and must be called only
    * once. For further mutations make use of `updateBody` method.
+   * @param body - Parsed request body data
+   * @returns {void}
    */
   setInitialBody(body) {
     if (this.#originalRequestData && Object.isFrozen(this.#originalRequestData)) {
@@ -1395,6 +1530,8 @@ var Request = class extends Macroable5 {
    * Update the request body with new data object. The `all` property
    * will be re-computed by merging the query string and request
    * body.
+   * @param body - New request body data to set
+   * @returns {void}
    */
   updateBody(body) {
     this.#requestBody = body;
@@ -1403,6 +1540,8 @@ var Request = class extends Macroable5 {
   /**
    * Update the request raw body. Bodyparser sets this when unable to parse
    * the request body or when request is multipart/form-data.
+   * @param rawBody - Raw request body as string
+   * @returns {void}
    */
   updateRawBody(rawBody) {
     this.#rawRequestBody = rawBody;
@@ -1410,6 +1549,8 @@ var Request = class extends Macroable5 {
   /**
    * Update the query string with the new data object. The `all` property
    * will be re-computed by merging the query and the request body.
+   * @param data - New query string data to set
+   * @returns {void}
    */
   updateQs(data) {
     this.#requestQs = data;
@@ -1417,18 +1558,21 @@ var Request = class extends Macroable5 {
   }
   /**
    * Returns route params
+   * @returns {Record<string, any>} Object containing route parameters
    */
   params() {
     return this.ctx?.params || {};
   }
   /**
    * Returns the query string object by reference
+   * @returns {Record<string, any>} Object containing parsed query string parameters
    */
   qs() {
     return this.#requestQs;
   }
   /**
    * Returns reference to the request body
+   * @returns {Record<string, any>} Object containing parsed request body
    */
   body() {
     return this.#requestBody;
@@ -1436,6 +1580,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns reference to the merged copy of request body
    * and query string
+   * @returns {Record<string, any>} Object containing merged request body and query parameters
    */
   all() {
     return this.#requestData;
@@ -1443,6 +1588,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns reference to the merged copy of original request
    * query string and body
+   * @returns {Record<string, any>} Object containing original merged request data
    */
   original() {
     return this.#originalRequestData;
@@ -1452,6 +1598,7 @@ var Request = class extends Macroable5 {
    *
    * Ideally you must be dealing with the parsed body accessed using [[input]], [[all]] or
    * [[post]] methods. The `raw` body is always a string.
+   * @returns {string | null} Raw request body as string or null if not set
    */
   raw() {
     return this.#rawRequestBody || null;
@@ -1467,6 +1614,9 @@ var Request = class extends Macroable5 {
    * // with default value
    * request.input('username', 'virk')
    * ```
+   * @param key - Key to lookup in request data
+   * @param defaultValue - Default value when key is not found
+   * @returns Value from request data or default value
    */
   input(key, defaultValue) {
     return lodash.get(this.#requestData, key, defaultValue);
@@ -1481,6 +1631,9 @@ var Request = class extends Macroable5 {
    * // with default value
    * request.param('id', 1)
    * ```
+   * @param key - Parameter key to lookup
+   * @param defaultValue - Default value when parameter is not found
+   * @returns Value from route parameters or default value
    */
   param(key, defaultValue) {
     return lodash.get(this.params(), key, defaultValue);
@@ -1492,6 +1645,8 @@ var Request = class extends Macroable5 {
    * ```js
    * request.except(['_csrf'])
    * ```
+   * @param keys - Array of keys to exclude from the result
+   * @returns {Record<string, any>} Object with all request data except specified keys
    */
   except(keys) {
     return lodash.omit(this.#requestData, keys);
@@ -1503,6 +1658,8 @@ var Request = class extends Macroable5 {
    * ```js
    * request.only(['username', 'age'])
    * ```
+   * @param keys - Array of keys to include in the result
+   * @returns {{ [K in T]: any }} Object with only the specified keys from request data
    */
   only(keys) {
     return lodash.pick(this.#requestData, keys);
@@ -1516,6 +1673,7 @@ var Request = class extends Macroable5 {
    * ```js
    * request.intended()
    * ```
+   * @returns {string} Original HTTP method from the request
    */
   intended() {
     return this.request.method;
@@ -1533,6 +1691,7 @@ var Request = class extends Macroable5 {
    * ```js
    * request.method()
    * ```
+   * @returns {string} HTTP method (potentially spoofed)
    */
   method() {
     if (this.#config.allowMethodSpoofing && this.intended() === "POST") {
@@ -1542,6 +1701,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * Returns a copy of headers as an object
+   * @returns {IncomingHttpHeaders} Object containing all HTTP headers
    */
   headers() {
     return this.request.headers;
@@ -1549,6 +1709,9 @@ var Request = class extends Macroable5 {
   /**
    * Returns value for a given header key. The default value is
    * used when original value is `undefined`.
+   * @param key - Header name to lookup
+   * @param defaultValue - Default value when header is not found
+   * @returns {string | undefined} Header value or default value if not found
    */
   header(key, defaultValue) {
     key = key.toLowerCase();
@@ -1591,6 +1754,7 @@ var Request = class extends Macroable5 {
    * ```
    *
    * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+   * @returns {string} Client IP address
    */
   ip() {
     const ipFn = this.#config.getIp;
@@ -1616,6 +1780,7 @@ var Request = class extends Macroable5 {
    * ```
    *
    * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+   * @returns {string[]} Array of IP addresses from most to least trusted
    */
   ips() {
     return proxyaddr.all(this.request, this.#config.trustProxy);
@@ -1639,6 +1804,7 @@ var Request = class extends Macroable5 {
    * ```
    *
    * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+   * @returns {string} Request protocol ('http' or 'https')
    */
   protocol() {
     if ("encrypted" in this.request.socket) {
@@ -1654,6 +1820,7 @@ var Request = class extends Macroable5 {
    * Returns a boolean telling if request is served over `https`
    * or not. Check [[protocol]] method to know how protocol is
    * fetched.
+   * @returns {boolean} True if request is served over HTTPS
    */
   secure() {
     return this.protocol() === "https";
@@ -1674,6 +1841,7 @@ var Request = class extends Macroable5 {
    * ```
    *
    * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+   * @returns {string | null} Request host or null if not found
    */
   host() {
     let host = this.header("host");
@@ -1701,6 +1869,7 @@ var Request = class extends Macroable5 {
    * ```
    *
    * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+   * @returns {string | null} Request hostname (without port) or null if not found
    */
   hostname() {
     const host = this.host();
@@ -1716,6 +1885,7 @@ var Request = class extends Macroable5 {
    * returned if [[hostname]] is `null` or is an IP address.
    *
    * Also `www` is not considered as a subdomain
+   * @returns {string[]} Array of subdomains (excluding www)
    */
   subdomains() {
     const hostname = this.hostname();
@@ -1732,6 +1902,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns a boolean telling, if request `X-Requested-With === 'xmlhttprequest'`
    * or not.
+   * @returns {boolean} True if request is an AJAX request
    */
   ajax() {
     const xRequestedWith = this.header("X-Requested-With", "");
@@ -1740,6 +1911,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns a boolean telling, if request has `X-Pjax` header
    * set or not
+   * @returns {boolean} True if request is a PJAX request
    */
   pjax() {
     return !!this.header("X-Pjax");
@@ -1754,6 +1926,8 @@ var Request = class extends Macroable5 {
    * // include query string
    * request.url(true)
    * ```
+   * @param includeQueryString - Whether to include query string in the URL
+   * @returns {string} Request pathname, optionally with query string
    */
   url(includeQueryString) {
     const pathname = this.parsedUrl.pathname;
@@ -1770,6 +1944,8 @@ var Request = class extends Macroable5 {
    * // include query string
    * request.completeUrl(true)
    * ```
+   * @param includeQueryString - Whether to include query string in the URL
+   * @returns {string} Complete URL including protocol and host
    */
   completeUrl(includeQueryString) {
     const protocol = this.protocol();
@@ -1778,6 +1954,8 @@ var Request = class extends Macroable5 {
   }
   /**
    * Find if the current HTTP request is for the given route or the routes
+   * @param routeIdentifier - Route name, pattern, or handler reference to match
+   * @returns {boolean} True if the request matches any of the given route identifiers
    */
   matchesRoute(routeIdentifier) {
     if (!this.ctx || !this.ctx.route) {
@@ -1823,6 +2001,8 @@ var Request = class extends Macroable5 {
    *  // process XML
    * }
    * ```
+   * @param types - Array of content types to match against
+   * @returns {string | null} Best matching content type or null if no match
    */
   is(types) {
     return typeIs(this.request, types) || null;
@@ -1847,6 +2027,8 @@ var Request = class extends Macroable5 {
    *     // decide yourself
    * }
    * ```
+   * @param types - Array of types to match against Accept header
+   * @returns {T | null} Best matching accept type or null if no match
    */
   accepts(types) {
     this.#initiateAccepts();
@@ -1858,6 +2040,7 @@ var Request = class extends Macroable5 {
    *
    * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
    * docs too.
+   * @returns {string[]} Array of accepted types in preference order
    */
   types() {
     this.#initiateAccepts();
@@ -1883,6 +2066,8 @@ var Request = class extends Macroable5 {
    *     return view.render('about', { lang: 'en' })
    * }
    * ```
+   * @param languages - Array of languages to match against Accept-Language header
+   * @returns {T | null} Best matching language or null if no match
    */
   language(languages) {
     this.#initiateAccepts();
@@ -1894,6 +2079,7 @@ var Request = class extends Macroable5 {
    *
    * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
    * docs too.
+   * @returns {string[]} Array of accepted languages in preference order
    */
   languages() {
     this.#initiateAccepts();
@@ -1917,6 +2103,8 @@ var Request = class extends Macroable5 {
    *     // make ISO-8859-1 friendly response
    * }
    * ```
+   * @param charsets - Array of charsets to match against Accept-Charset header
+   * @returns {T | null} Best matching charset or null if no match
    */
   charset(charsets) {
     this.#initiateAccepts();
@@ -1928,6 +2116,7 @@ var Request = class extends Macroable5 {
    *
    * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
    * docs too.
+   * @returns {string[]} Array of accepted charsets in preference order
    */
   charsets() {
     this.#initiateAccepts();
@@ -1941,17 +2130,20 @@ var Request = class extends Macroable5 {
    *
    * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
    * docs too.
+   * @param encodings - Array of encodings to match against Accept-Encoding header
+   * @returns {T | null} Best matching encoding or null if no match
    */
   encoding(encodings) {
     this.#initiateAccepts();
     return this.#lazyAccepts.encoding(encodings) || null;
   }
   /**
-   * Return the charsets that the request accepts, in the order of the
+   * Return the encodings that the request accepts, in the order of the
    * client's preference (most preferred first).
    *
    * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
    * docs too.
+   * @returns {string[]} Array of accepted encodings in preference order
    */
   encodings() {
     this.#initiateAccepts();
@@ -1959,6 +2151,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * Returns a boolean telling if request has body
+   * @returns {boolean} True if request contains a body
    */
   hasBody() {
     return typeIs.hasBody(this.request);
@@ -1986,6 +2179,7 @@ var Request = class extends Macroable5 {
    *   response.send(responseBody)
    * }
    * ```
+   * @returns {boolean} True if client cache is fresh (should return 304)
    */
   fresh() {
     if (["GET", "HEAD"].indexOf(this.intended()) === -1) {
@@ -1999,6 +2193,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * Opposite of [[fresh]]
+   * @returns {boolean} True if client cache is stale (should send new response)
    */
   stale() {
     return !this.fresh();
@@ -2006,6 +2201,7 @@ var Request = class extends Macroable5 {
   /**
    * Returns all parsed and signed cookies. Signed cookies ensures
    * that their value isn't tampered.
+   * @returns {{ [key: string]: any }} Object containing all parsed cookies
    */
   cookiesList() {
     this.#initiateCookieParser();
@@ -2014,14 +2210,20 @@ var Request = class extends Macroable5 {
   /**
    * Returns value for a given key from signed cookies. Optional
    * defaultValue is returned when actual value is undefined.
+   * @param key - Cookie name to lookup
+   * @param defaultValue - Default value when cookie is not found
+   * @returns Cookie value or default value if not found
    */
   cookie(key, defaultValue) {
     this.#initiateCookieParser();
     return this.#cookieParser.unsign(key) || defaultValue;
   }
   /**
-   * Returns value for a given key from signed cookies. Optional
+   * Returns value for a given key from encrypted cookies. Optional
    * defaultValue is returned when actual value is undefined.
+   * @param key - Cookie name to lookup
+   * @param defaultValue - Default value when cookie is not found
+   * @returns Decrypted cookie value or default value if not found
    */
   encryptedCookie(key, defaultValue) {
     this.#initiateCookieParser();
@@ -2035,8 +2237,10 @@ var Request = class extends Macroable5 {
     return this.#cookieParser.decode(key, encoded) || defaultValueOrOptions;
   }
   /**
-   * Returns a boolean telling if a signed url as a valid signature
+   * Returns a boolean telling if a signed url has a valid signature
    * or not.
+   * @param purpose - Optional purpose for signature verification
+   * @returns {boolean} True if the signed URL has a valid signature
    */
   hasValidSignature(purpose) {
     const { signature, ...rest } = this.qs();
@@ -2052,6 +2256,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * Serializes request to JSON format
+   * @returns Object representation of the request
    */
   serialize() {
     return {
@@ -2071,6 +2276,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * toJSON copy of the request
+   * @returns JSON representation of the request
    */
   toJSON() {
     return this.serialize();
@@ -2081,21 +2287,40 @@ var Request = class extends Macroable5 {
 import { parse } from "url";
 var Redirect = class {
   /**
-   * A boolean to forward the existing query string
+   * Flag indicating whether to forward the existing query string from the current request
    */
   #forwardQueryString = false;
   /**
-   * The status code for the redirect
+   * HTTP status code to use for the redirect response (defaults to 302)
    */
   #statusCode = 302;
   /**
-   * A custom query string to forward
+   * Custom query string parameters to include in the redirect URL
    */
   #queryString = {};
+  /**
+   * Reference to the Node.js incoming HTTP request
+   */
   #request;
+  /**
+   * Reference to the AdonisJS response instance
+   */
   #response;
+  /**
+   * Reference to the AdonisJS router instance for URL building
+   */
   #router;
+  /**
+   * Query string parser instance
+   */
   #qs;
+  /**
+   * 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, response, router, qs) {
     this.#request = request;
     this.#response = response;
@@ -2103,7 +2328,9 @@ var Redirect = class {
     this.#qs = qs;
   }
   /**
-   * Sends response by setting require headers
+   * Sends the redirect response by setting required headers and status code
+   * @param url - Target URL for redirection
+   * @param query - Query string parameters to append
    */
   #sendResponse(url, query) {
     const stringified = this.#qs.stringify(query);
@@ -2115,22 +2342,25 @@ var Redirect = class {
     this.#response.send(`Redirecting to ${url}`);
   }
   /**
-   * Returns the referrer url
+   * Extracts and returns the referrer URL from request headers
+   * @returns {string} The referrer URL or '/' if not found
    */
   #getReferrerUrl() {
     let url = this.#request.headers["referer"] || this.#request.headers["referrer"] || "/";
     return Array.isArray(url) ? url[0] : url;
   }
   /**
-   * 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) {
     this.#statusCode = statusCode;
     return 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.#forwardQueryString = false;
@@ -2150,7 +2380,8 @@ var Redirect = class {
     return this;
   }
   /**
-   * Redirect to the previous path.
+   * Redirects to the previous path using the Referer header
+   * Falls back to '/' if no referrer is found
    */
   back() {
     let query = {};
@@ -2165,7 +2396,8 @@ var Redirect = class {
     this.#sendResponse(url.pathname || "", query);
   }
   /**
-   * 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(...args) {
     const [identifier, params, options] = args;
@@ -2177,7 +2409,8 @@ var Redirect = class {
     return this.toPath(url);
   }
   /**
-   * Redirect the request using a path.
+   * Redirects to a specific URL path
+   * @param url - Target URL path for redirection
    */
   toPath(url) {
     let query = {};
@@ -2255,24 +2488,17 @@ var ResponseStatus = {
   NetworkAuthenticationRequired: 511
 };
 
-// src/response.ts
-import etag from "etag";
-import vary from "vary";
-import fresh2 from "fresh";
-import destroy from "destroy";
-import { extname } from "path";
-import { Buffer } from "buffer";
-import onFinished from "on-finished";
-import { stat } from "fs/promises";
-import Macroable6 from "@poppinss/macroable";
-import { createReadStream } from "fs";
-import contentDisposition from "content-disposition";
-import { safeStringify } from "@poppinss/utils/json";
-import { RuntimeException as RuntimeException3 } from "@poppinss/utils/exception";
-
 // src/cookies/serializer.ts
 var CookieSerializer = class {
+  /**
+   * Cookie client instance for handling cookie operations
+   */
   #client;
+  /**
+   * Create a new instance of CookieSerializer
+   *
+   * @param encryption - The encryption instance for cookie operations
+   */
   constructor(encryption) {
     this.#client = new CookieClient(encryption);
   }
@@ -2286,6 +2512,11 @@ var CookieSerializer = class {
    *  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, value, options) {
     const stringify2 = options?.stringify ?? options?.encode;
@@ -2298,6 +2529,11 @@ var CookieSerializer = class {
   /**
    * 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, value, options) {
     const packedValue = this.#client.sign(key, value);
@@ -2308,6 +2544,11 @@ var CookieSerializer = class {
   }
   /**
    * 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, value, options) {
     const packedValue = this.#client.encrypt(key, value);
@@ -2319,8 +2560,31 @@ var CookieSerializer = class {
 };
 
 // src/response.ts
+import etag from "etag";
+import vary from "vary";
+import fresh2 from "fresh";
+import destroy from "destroy";
+import { extname } from "path";
+import { Buffer } from "buffer";
+import onFinished from "on-finished";
+import { stat } from "fs/promises";
+import Macroable6 from "@poppinss/macroable";
+import { createReadStream } from "fs";
+import contentDisposition from "content-disposition";
+import { safeStringify } from "@poppinss/utils/json";
+import { RuntimeException as RuntimeException3 } from "@poppinss/utils/exception";
 var CACHEABLE_HTTP_METHODS = ["GET", "HEAD"];
 var Response = class extends Macroable6 {
+  /**
+   * Creates a new Response instance
+   *
+   * @param request - Node.js IncomingMessage instance
+   * @param response - Node.js ServerResponse instance
+   * @param encryption - Encryption service for cookie handling
+   * @param config - Response configuration settings
+   * @param router - Router instance for URL generation
+   * @param qs - Query string parser
+   */
   constructor(request, response, encryption, config, router, qs) {
     super();
     this.request = request;
@@ -2331,73 +2595,67 @@ var Response = class extends Macroable6 {
     this.#cookieSerializer = new CookieSerializer(encryption);
   }
   /**
-   * Query string parser
+   * Query string parser instance used for URL manipulation
    */
   #qs;
   /**
-   * Outgoing headers
+   * Collection of outgoing HTTP headers to be sent with the response
    */
   #headers = {};
   /**
-   * Has explicit status been set
+   * Flag indicating whether an explicit status code has been set
    */
   #hasExplicitStatus = false;
   /**
-   * Cookies serializer to serialize the outgoing cookies
+   * Cookie serializer instance for handling cookie encryption, signing, and encoding
    */
   #cookieSerializer;
   /**
-   * Router is used to make the redirect URLs from routes
+   * Router instance used for generating redirect URLs from route definitions
    */
   #router;
   /**
-   * Response config
+   * Configuration object containing response-related settings
    */
   #config;
   /**
-   * Does response has body set that will written to the
-   * response socket at the end of the request
+   * Indicates whether the response has any content (body, stream, or file) ready to be sent
    */
   get hasLazyBody() {
     return !!(this.lazyBody.content || this.lazyBody.fileToStream || this.lazyBody.stream);
   }
   /**
-   * Find if the response has non-stream content
+   * Indicates whether the response has non-stream content set
    */
   get hasContent() {
     return !!this.lazyBody.content;
   }
   /**
-   * Returns true when response body is set using "response.stream"
-   * method
+   * Indicates whether the response body is set as a readable stream
    */
   get hasStream() {
     return !!this.lazyBody.stream;
   }
   /**
-   * Returns true when response body is set using "response.download"
-   * or "response.attachment" methods
+   * Indicates whether the response is configured to stream a file
    */
   get hasFileToStream() {
     return !!this.lazyBody.fileToStream;
   }
   /**
-   * Returns the response content. Check if the response
-   * has content using the "hasContent" method
+   * The response content data
    */
   get content() {
     return this.lazyBody.content;
   }
   /**
-   * Returns reference to the stream set using "response.stream"
-   * method
+   * The readable stream instance configured for the response
    */
   get outgoingStream() {
     return this.lazyBody.stream?.[0];
   }
   /**
-   * Returns reference to the file path set using "response.stream"
-   * method.
+   * Configuration for file streaming including path and etag generation flag
    */
   get fileToStream() {
     return this.lazyBody.fileToStream ? {
@@ -2406,48 +2664,46 @@ var Response = class extends Macroable6 {
     } : void 0;
   }
   /**
-   * Lazy body is used to set the response body. However, do not
-   * write it on the socket immediately unless `response.finish`
-   * is called.
+   * Lazy body container that holds response content until ready to send.
+   * Contains different types of response data: content, stream, or fileToStream.
    */
   lazyBody = {};
   /**
-   * The ctx will be set by the context itself. It creates a circular
-   * reference
+   * HTTP context reference (creates circular dependency with HttpContext)
    */
   ctx;
   /**
-   * Returns a boolean telling if response is finished or not.
-   * Any more attempts to update headers or body will result
-   * in raised exceptions.
+   * Indicates whether the response has been completely sent
    */
   get finished() {
     return this.response.writableFinished;
   }
   /**
-   * Returns a boolean telling if response headers has been sent or not.
-   * Any more attempts to update headers will result in raised
-   * exceptions.
+   * Indicates whether response headers have been sent to the client
    */
   get headersSent() {
     return this.response.headersSent;
   }
   /**
-   * Returns a boolean telling if response headers and body is written
-   * or not. When value is `true`, you can feel free to write headers
-   * and body.
+   * Indicates whether the response is still pending (headers and body can still be modified)
    */
   get isPending() {
     return !this.headersSent && !this.finished;
   }
   /**
-   * Normalizes header value to a string or an array of string
+   * Normalizes header value to a string or an array of strings
+   *
+   * @param value - The header value to normalize
+   * @returns Normalized header value
    */
   #castHeaderValue(value) {
     return Array.isArray(value) ? value.map(String) : String(value);
   }
   /**
    * Ends the response by flushing headers and writing body
+   *
+   * @param body - Optional response body
+   * @param statusCode - Optional status code
    */
   #endResponse(body, statusCode) {
     this.writeHead(statusCode);
@@ -2455,14 +2711,18 @@ var Response = class extends Macroable6 {
     res.end(body, null, null);
   }
   /**
-   * Returns type for the content body. Only following types are allowed
+   * Determines the data type of the content for serialization
    *
+   * Supported types:
    * - Dates
    * - Arrays
    * - Booleans
    * - Objects
    * - Strings
    * - Buffer
+   *
+   * @param content - The content to analyze
+   * @returns The determined data type as string
    */
   #getDataType(content) {
     const dataType = typeof content;
@@ -2484,10 +2744,17 @@ var Response = class extends Macroable6 {
     throw new RuntimeException3(`Cannot serialize "${dataType}" to HTTP response`);
   }
   /**
-   * Writes the body with appropriate response headers. Etag header is set
-   * when `generateEtag` is set to `true`.
+   * Writes the response body with appropriate headers and content type detection
+   *
+   * Automatically sets:
+   * - Content-Type based on content analysis
+   * - Content-Length header
+   * - ETag header (if enabled)
+   * - Status code 204 for empty bodies
    *
-   * Empty body results in `204`.
+   * @param content - The response content
+   * @param generateEtag - Whether to generate ETag header
+   * @param jsonpCallbackName - Optional JSONP callback name
    */
   writeBody(content, generateEtag, jsonpCallbackName) {
     const hasEmptyBody = content === null || content === void 0 || content === "";
@@ -2557,7 +2824,16 @@ var Response = class extends Macroable6 {
     this.#endResponse(content);
   }
   /**
-   * Stream the body to the response and handles cleaning up the stream
+   * Streams the response body and handles error cleanup
+   *
+   * Manages stream lifecycle including:
+   * - Error handling with custom callbacks
+   * - Proper stream cleanup to prevent memory leaks
+   * - Response finalization
+   *
+   * @param body - The readable stream to pipe
+   * @param errorCallback - Optional custom error handler
+   * @returns Promise that resolves when streaming is complete
    */
   streamBody(body, errorCallback) {
     return new Promise((resolve) => {
@@ -2598,7 +2874,19 @@ var Response = class extends Macroable6 {
     });
   }
   /**
-   * Downloads a file by streaming it to the response
+   * Streams a file for download with proper headers and caching support
+   *
+   * Sets appropriate headers:
+   * - Last-Modified based on file stats
+   * - Content-Type based on file extension
+   * - Content-Length from file size
+   * - ETag (if enabled)
+   *
+   * Handles HEAD requests and cache validation (304 responses).
+   *
+   * @param filePath - Path to the file to stream
+   * @param generateEtag - Whether to generate ETag header
+   * @param errorCallback - Optional custom error handler
    */
   async streamFileForDownload(filePath, generateEtag, errorCallback) {
     try {
@@ -2638,18 +2926,18 @@ var Response = class extends Macroable6 {
     }
   }
   /**
-   * Listen for the event the response is written
-   * to the TCP socket.
+   * Registers a callback to be called when the response is finished
    *
-   * Under the hood the callback is registered with
-   * the "https://github.com/jshttp/on-finished" package
+   * The callback is executed when the response has been completely sent.
+   * Uses the "on-finished" package internally.
+   *
+   * @param callback - Function to call when response is finished
    */
   onFinish(callback) {
     onFinished(this.response, callback);
   }
   /**
-   * Writes headers with the Node.js res object using the
-   * response.setHeader method
+   * Transfers all buffered headers to the underlying Node.js response object
    */
   relayHeaders() {
     if (!this.headersSent) {
@@ -2662,22 +2950,29 @@ var Response = class extends Macroable6 {
     }
   }
   /**
-   * Calls res.writeHead on the Node.js res object.
+   * Writes the response status code and headers
+   *
+   * @param statusCode - Optional status code to set
+   * @returns The Response instance for chaining
    */
   writeHead(statusCode) {
     this.response.writeHead(statusCode || this.response.statusCode, this.#headers);
     return this;
   }
   /**
-   * Returns the existing value for a given HTTP response
-   * header.
+   * Gets the value of a response header
+   *
+   * @param key - Header name
+   * @returns The header value
    */
   getHeader(key) {
     const value = this.#headers[key.toLowerCase()];
     return value === void 0 ? this.response.getHeader(key) : value;
   }
   /**
-   * Get response headers
+   * Gets all response headers as an object
+   *
+   * @returns Object containing all headers
    */
   getHeaders() {
     return {
@@ -2686,14 +2981,15 @@ var Response = class extends Macroable6 {
     };
   }
   /**
-   * Set header on the response. To `append` values to the existing header, we suggest
-   * using [[append]] method.
+   * Sets a response header (replaces existing value)
    *
-   * If `value` is non existy, then header won't be set.
+   * @param key - Header name
+   * @param value - Header value (ignored if null/undefined)
+   * @returns The Response instance for chaining
    *
    * @example
-   * ```js
-   * response.header('content-type', 'application/json')
+   * ```ts
+   * response.header('Content-Type', 'application/json')
    * ```
    */
   header(key, value) {
@@ -2704,14 +3000,15 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Append value to an existing header. To replace the value, we suggest using
-   * [[header]] method.
+   * Appends a value to an existing response header
    *
-   * If `value` is not existy, then header won't be set.
+   * @param key - Header name
+   * @param value - Header value to append (ignored if null/undefined)
+   * @returns The Response instance for chaining
    *
    * @example
-   * ```js
-   * response.append('set-cookie', 'username=virk')
+   * ```ts
+   * response.append('Set-Cookie', 'session=abc123')
    * ```
    */
   append(key, value) {
@@ -2731,7 +3028,11 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Adds HTTP response header, when it doesn't exists already.
+   * Sets a header only if it doesn't already exist
+   *
+   * @param key - Header name
+   * @param value - Header value
+   * @returns The Response instance for chaining
    */
   safeHeader(key, value) {
     if (!this.getHeader(key)) {
@@ -2740,7 +3041,10 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Removes the existing response header from being sent.
+   * Removes a response header
+   *
+   * @param key - Header name to remove
+   * @returns The Response instance for chaining
    */
   removeHeader(key) {
     key = key.toLowerCase();
@@ -2751,13 +3055,18 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Returns the status code for the response
+   * Gets the current response status code
+   *
+   * @returns The HTTP status code
    */
   getStatus() {
     return this.response.statusCode;
   }
   /**
-   * Set HTTP status code
+   * Sets the response status code
+   *
+   * @param code - HTTP status code
+   * @returns The Response instance for chaining
    */
   status(code) {
     this.#hasExplicitStatus = true;
@@ -2765,8 +3074,10 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Set's status code only when it's not explictly
-   * set
+   * Sets the status code only if not explicitly set already
+   *
+   * @param code - HTTP status code
+   * @returns The Response instance for chaining
    */
   safeStatus(code) {
     if (this.#hasExplicitStatus) {
@@ -2776,15 +3087,16 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Set response type by looking up for the mime-type using
-   * partial types like file extensions.
+   * Sets the Content-Type header based on mime type lookup
    *
-   * Make sure to read [mime-types](https://www.npmjs.com/package/mime-types) docs
-   * too.
+   * @param type - File extension or mime type
+   * @param charset - Optional character encoding
+   * @returns The Response instance for chaining
    *
    * @example
-   * ```js
-   * response.type('.json') // Content-type: application/json
+   * ```ts
+   * response.type('.json') // Content-Type: application/json
+   * response.type('html', 'utf-8') // Content-Type: text/html; charset=utf-8
    * ```
    */
   type(type, charset) {
@@ -2793,25 +3105,30 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Set the Vary HTTP header
+   * Sets the Vary HTTP header for cache control
+   *
+   * @param field - Header field name(s) to vary on
+   * @returns The Response instance for chaining
    */
   vary(field) {
     vary(this.response, field);
     return this;
   }
   /**
-   * Set etag by computing hash from the body. This class will set the etag automatically
-   * when `etag = true` in the defined config object.
+   * Sets the ETag header by computing a hash from the response body
    *
-   * Use this function, when you want to compute etag manually for some other resons.
+   * @param body - The response body to hash
+   * @param weak - Whether to generate a weak ETag
+   * @returns The Response instance for chaining
    */
   setEtag(body, weak = false) {
     this.header("Etag", etag(body, { weak }));
     return this;
   }
   /**
-   * Set X-Request-Id header by copying the header value from the request if it exists.
+   * Sets the X-Request-Id header by copying from the incoming request
    *
+   * @returns The Response instance for chaining
    */
   setRequestId() {
     const requestId = this.request.headers["x-request-id"];
@@ -2821,27 +3138,20 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Returns a boolean telling if the new response etag evaluates same
-   * as the request header `if-none-match`. In case of `true`, the
-   * server must return `304` response, telling the browser to
-   * use the client cache.
+   * Checks if the response is fresh (client cache is valid)
    *
-   * You won't have to deal with this method directly, since AdonisJs will
-   * handle this for you when `http.etag = true` inside `config/app.js` file.
+   * Compares ETags and modified dates between request and response
+   * to determine if a 304 Not Modified response should be sent.
    *
-   * However, this is how you can use it manually.
+   * @returns True if client cache is fresh, false otherwise
    *
    * @example
-   * ```js
-   * const responseBody = view.render('some-view')
-   *
-   * // sets the HTTP etag header for response
-   * response.setEtag(responseBody)
-   *
+   * ```ts
+   * response.setEtag(content)
    * if (response.fresh()) {
-   *   response.sendStatus(304)
+   *   response.status(304).send(null)
    * } else {
-   *   response.send(responseBody)
+   *   response.send(content)
    * }
    * ```
    */
@@ -2856,8 +3166,9 @@ var Response = class extends Macroable6 {
     return false;
   }
   /**
-   * Returns the response body. Returns null when response
-   * body is a stream
+   * Gets the response body content
+   *
+   * @returns The response body or null if not set or is a stream
    */
   getBody() {
     if (this.lazyBody.content) {
@@ -2866,58 +3177,54 @@ var Response = class extends Macroable6 {
     return null;
   }
   /**
-   * Send the body as response and optionally generate etag. The default value
-   * is read from `config/app.js` file, using `http.etag` property.
+   * Sends the response body with optional ETag generation
    *
-   * This method buffers the body if `explicitEnd = true`, which is the default
-   * behavior and do not change, unless you know what you are doing.
+   * @param body - The response body
+   * @param generateEtag - Whether to generate ETag header (defaults to config)
    */
   send(body, generateEtag = this.#config.etag) {
     this.lazyBody.content = [body, generateEtag];
   }
   /**
-   * Alias of [[send]]
+   * Sends a JSON response (alias for send)
+   *
+   * @param body - The response body to serialize as JSON
+   * @param generateEtag - Whether to generate ETag header
    */
   json(body, generateEtag = this.#config.etag) {
     return this.send(body, generateEtag);
   }
   /**
-   * Writes response as JSONP. The callback name is resolved as follows, with priority
-   * from top to bottom.
+   * Sends a JSONP response with callback wrapping
    *
-   * 1. Explicitly defined as 2nd Param.
-   * 2. Fetch from request query string.
-   * 3. Use the config value `http.jsonpCallbackName` from `config/app.js`.
-   * 4. Fallback to `callback`.
+   * Callback name resolution priority:
+   * 1. Explicit callbackName parameter
+   * 2. Query string parameter
+   * 3. Config value
+   * 4. Default "callback"
    *
-   * This method buffers the body if `explicitEnd = true`, which is the default
-   * behavior and do not change, unless you know what you are doing.
+   * @param body - The response body
+   * @param callbackName - JSONP callback function name
+   * @param generateEtag - Whether to generate ETag header
    */
   jsonp(body, callbackName = this.#config.jsonpCallbackName, generateEtag = this.#config.etag) {
     this.lazyBody.content = [body, generateEtag, callbackName];
   }
   /**
-   * Pipe stream to the response. This method will gracefully destroy
-   * the stream, avoiding memory leaks.
-   *
-   * If `raiseErrors=false`, then this method will self handle all the exceptions by
-   * writing a generic HTTP response. To have more control over the error, it is
-   * recommended to set `raiseErrors=true` and wrap this function inside a
-   * `try/catch` statement.
+   * Pipes a readable stream to the response with graceful error handling
    *
-   * Streaming a file from the disk and showing 404 when file is missing.
+   * @param body - The readable stream to pipe
+   * @param errorCallback - Optional custom error handler
    *
    * @example
-   * ```js
-   * // Errors handled automatically with generic HTTP response
+   * ```ts
+   * // Auto error handling
    * response.stream(fs.createReadStream('file.txt'))
    *
-   * // Manually handle (note the await call)
-   * try {
-   *   await response.stream(fs.createReadStream('file.txt'))
-   * } catch () {
-   *   response.status(404).send('File not found')
-   * }
+   * // Custom error handling
+   * response.stream(stream, (error) => {
+   *   return error.code === 'ENOENT' ? ['Not found', 404] : ['Error', 500]
+   * })
    * ```
    */
   stream(body, errorCallback) {
@@ -2927,38 +3234,35 @@ var Response = class extends Macroable6 {
     this.lazyBody.stream = [body, errorCallback];
   }
   /**
-   * Download file by streaming it from the file path. This method will setup
-   * appropriate `Content-type`, `Content-type` and `Last-modified` headers.
+   * Downloads a file by streaming it with appropriate headers
    *
-   * Unexpected stream errors are handled gracefully to avoid memory leaks.
+   * Automatically sets:
+   * - Content-Type from file extension
+   * - Content-Length from file size
+   * - Last-Modified from file stats
+   * - ETag (if enabled)
    *
-   * If `raiseErrors=false`, then this method will self handle all the exceptions by
-   * writing a generic HTTP response. To have more control over the error, it is
-   * recommended to set `raiseErrors=true` and wrap this function inside a
-   * `try/catch` statement.
+   * @param filePath - Path to the file to download
+   * @param generateEtag - Whether to generate ETag header
+   * @param errorCallback - Optional custom error handler
    *
    * @example
-   * ```js
-   * // Errors handled automatically with generic HTTP response
-   * response.download('somefile.jpg')
-   *
-   * // Manually handle (note the await call)
-   * try {
-   *   await response.download('somefile.jpg')
-   * } catch (error) {
-   *   response.status(error.code === 'ENOENT' ? 404 : 500)
-   *   response.send('Cannot process file')
-   * }
+   * ```ts
+   * response.download('/path/to/file.pdf')
+   * response.download('/images/photo.jpg', true, (err) => ['Custom error', 500])
    * ```
    */
   download(filePath, generateEtag = this.#config.etag, errorCallback) {
     this.lazyBody.fileToStream = [filePath, generateEtag, errorCallback];
   }
   /**
-   * Download the file by forcing the user to save the file vs displaying it
-   * within the browser.
+   * Forces file download by setting Content-Disposition header
    *
-   * Internally calls [[download]]
+   * @param filePath - Path to the file to download
+   * @param name - Optional filename for download (defaults to original filename)
+   * @param disposition - Content-Disposition type (defaults to 'attachment')
+   * @param generateEtag - Whether to generate ETag header
+   * @param errorCallback - Optional custom error handler
    */
   attachment(filePath, name, disposition, generateEtag, errorCallback) {
     name = name || filePath;
@@ -2966,11 +3270,14 @@ var Response = class extends Macroable6 {
     return this.download(filePath, generateEtag, errorCallback);
   }
   /**
-   * Set the location header.
+   * Sets the Location header for redirects
+   *
+   * @param url - The URL to redirect to
+   * @returns The Response instance for chaining
    *
    * @example
-   * ```js
-   * response.location('/login')
+   * ```ts
+   * response.location('/dashboard')
    * ```
    */
   location(url) {
@@ -2991,15 +3298,21 @@ var Response = class extends Macroable6 {
     return handler;
   }
   /**
-   * Abort the request with custom body and a status code. 400 is
-   * used when status is not defined
+   * Aborts the request with a custom response body and status code
+   *
+   * @param body - Response body for the aborted request
+   * @param status - HTTP status code (defaults to 400)
+   * @throws Always throws an HTTP exception
    */
   abort(body, status) {
     throw E_HTTP_REQUEST_ABORTED.invoke(body, status || ResponseStatus.BadRequest);
   }
   /**
-   * Abort the request with custom body and a status code when
-   * passed condition returns `true`
+   * Conditionally aborts the request if the condition is truthy
+   *
+   * @param condition - Condition to evaluate
+   * @param body - Response body for the aborted request
+   * @param status - HTTP status code (defaults to 400)
    */
   abortIf(condition, body, status) {
     if (condition) {
@@ -3007,8 +3320,11 @@ var Response = class extends Macroable6 {
     }
   }
   /**
-   * Abort the request with custom body and a status code when
-   * passed condition returns `false`
+   * Conditionally aborts the request if the condition is falsy
+   *
+   * @param condition - Condition to evaluate
+   * @param body - Response body for the aborted request
+   * @param status - HTTP status code (defaults to 400)
    */
   abortUnless(condition, body, status) {
     if (!condition) {
@@ -3016,8 +3332,12 @@ var Response = class extends Macroable6 {
     }
   }
   /**
-   * Set signed cookie as the response header. The inline options overrides
-   * all options from the config.
+   * Sets a signed cookie in the response
+   *
+   * @param key - Cookie name
+   * @param value - Cookie value
+   * @param options - Cookie options (overrides config defaults)
+   * @returns The Response instance for chaining
    */
   cookie(key, value, options) {
     options = Object.assign({}, this.#config.cookie, options);
@@ -3029,8 +3349,12 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Set encrypted cookie as the response header. The inline options overrides
-   * all options from the config.
+   * Sets an encrypted cookie in the response
+   *
+   * @param key - Cookie name
+   * @param value - Cookie value
+   * @param options - Cookie options (overrides config defaults)
+   * @returns The Response instance for chaining
    */
   encryptedCookie(key, value, options) {
     options = Object.assign({}, this.#config.cookie, options);
@@ -3042,8 +3366,12 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Set unsigned cookie as the response header. The inline options overrides
-   * all options from the config.
+   * Sets a plain (unsigned/unencrypted) cookie in the response
+   *
+   * @param key - Cookie name
+   * @param value - Cookie value
+   * @param options - Cookie options including encode flag
+   * @returns The Response instance for chaining
    */
   plainCookie(key, value, options) {
     options = Object.assign({}, this.#config.cookie, options);
@@ -3055,7 +3383,11 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Clear existing cookie.
+   * Clears an existing cookie by setting it to expire
+   *
+   * @param key - Cookie name to clear
+   * @param options - Cookie options (should match original cookie options)
+   * @returns The Response instance for chaining
    */
   clearCookie(key, options) {
     options = Object.assign({}, this.#config.cookie, options);
@@ -3066,10 +3398,10 @@ var Response = class extends Macroable6 {
     return this;
   }
   /**
-   * Finishes the response by writing the lazy body, when `explicitEnd = true`
-   * and response is already pending.
+   * Finalizes and sends the response
    *
-   * Calling this method twice or when `explicitEnd = false` is noop.
+   * Writes the buffered body (content, stream, or file) to the client.
+   * This method is idempotent - calling it multiple times has no effect.
    */
   finish() {
     if (!this.isPending) {
@@ -3090,294 +3422,408 @@ var Response = class extends Macroable6 {
     this.#endResponse();
   }
   /**
-   * Shorthand method to finish request with "100" status code
+   * Sends a 100 Continue response
    */
   continue() {
     this.status(ResponseStatus.Continue);
     return this.send(null, false);
   }
   /**
-   * Shorthand method to finish request with "101" status code
+   * Sends a 101 Switching Protocols response
    */
   switchingProtocols() {
     this.status(ResponseStatus.SwitchingProtocols);
     return this.send(null, false);
   }
   /**
-   * Shorthand method to finish request with "200" status code
+   * Sends a 200 OK response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   ok(body, generateEtag) {
     this.status(ResponseStatus.Ok);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "201" status code
+   * Sends a 201 Created response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   created(body, generateEtag) {
     this.status(ResponseStatus.Created);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "202" status code
+   * Sends a 202 Accepted response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   accepted(body, generateEtag) {
     this.status(ResponseStatus.Accepted);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "203" status code
+   * Sends a 203 Non-Authoritative Information response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   nonAuthoritativeInformation(body, generateEtag) {
     this.status(ResponseStatus.NonAuthoritativeInformation);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "204" status code
+   * Sends a 204 No Content response
    */
   noContent() {
     this.status(ResponseStatus.NoContent);
     return this.send(null, false);
   }
   /**
-   * Shorthand method to finish request with "205" status code
+   * Sends a 205 Reset Content response
    */
   resetContent() {
     this.status(ResponseStatus.ResetContent);
     return this.send(null, false);
   }
   /**
-   * Shorthand method to finish request with "206" status code
+   * Sends a 206 Partial Content response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   partialContent(body, generateEtag) {
     this.status(ResponseStatus.PartialContent);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "300" status code
+   * Sends a 300 Multiple Choices response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   multipleChoices(body, generateEtag) {
     this.status(ResponseStatus.MultipleChoices);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "301" status code
+   * Sends a 301 Moved Permanently response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   movedPermanently(body, generateEtag) {
     this.status(ResponseStatus.MovedPermanently);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "302" status code
+   * Sends a 302 Found (Moved Temporarily) response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   movedTemporarily(body, generateEtag) {
     this.status(ResponseStatus.Found);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "303" status code
+   * Sends a 303 See Other response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   seeOther(body, generateEtag) {
     this.status(ResponseStatus.SeeOther);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "304" status code
+   * Sends a 304 Not Modified response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   notModified(body, generateEtag) {
     this.status(ResponseStatus.NotModified);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "305" status code
+   * Sends a 305 Use Proxy response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   useProxy(body, generateEtag) {
     this.status(ResponseStatus.UseProxy);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "307" status code
+   * Sends a 307 Temporary Redirect response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   temporaryRedirect(body, generateEtag) {
     this.status(ResponseStatus.TemporaryRedirect);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "400" status code
+   * Sends a 400 Bad Request response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   badRequest(body, generateEtag) {
     this.status(ResponseStatus.BadRequest);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "401" status code
+   * Sends a 401 Unauthorized response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   unauthorized(body, generateEtag) {
     this.status(ResponseStatus.Unauthorized);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "402" status code
+   * Sends a 402 Payment Required response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   paymentRequired(body, generateEtag) {
     this.status(ResponseStatus.PaymentRequired);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "403" status code
+   * Sends a 403 Forbidden response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   forbidden(body, generateEtag) {
     this.status(ResponseStatus.Forbidden);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "404" status code
+   * Sends a 404 Not Found response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   notFound(body, generateEtag) {
     this.status(ResponseStatus.NotFound);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "405" status code
+   * Sends a 405 Method Not Allowed response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   methodNotAllowed(body, generateEtag) {
     this.status(ResponseStatus.MethodNotAllowed);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "406" status code
+   * Sends a 406 Not Acceptable response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   notAcceptable(body, generateEtag) {
     this.status(ResponseStatus.NotAcceptable);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "407" status code
+   * Sends a 407 Proxy Authentication Required response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   proxyAuthenticationRequired(body, generateEtag) {
     this.status(ResponseStatus.ProxyAuthenticationRequired);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "408" status code
+   * Sends a 408 Request Timeout response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   requestTimeout(body, generateEtag) {
     this.status(ResponseStatus.RequestTimeout);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "409" status code
+   * Sends a 409 Conflict response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   conflict(body, generateEtag) {
     this.status(ResponseStatus.Conflict);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "401" status code
+   * Sends a 410 Gone response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   gone(body, generateEtag) {
     this.status(ResponseStatus.Gone);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "411" status code
+   * Sends a 411 Length Required response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   lengthRequired(body, generateEtag) {
     this.status(ResponseStatus.LengthRequired);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "412" status code
+   * Sends a 412 Precondition Failed response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   preconditionFailed(body, generateEtag) {
     this.status(ResponseStatus.PreconditionFailed);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "413" status code
+   * Sends a 413 Payload Too Large response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   requestEntityTooLarge(body, generateEtag) {
     this.status(ResponseStatus.PayloadTooLarge);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "414" status code
+   * Sends a 414 URI Too Long response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   requestUriTooLong(body, generateEtag) {
     this.status(ResponseStatus.URITooLong);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "415" status code
+   * Sends a 415 Unsupported Media Type response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   unsupportedMediaType(body, generateEtag) {
     this.status(ResponseStatus.UnsupportedMediaType);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "416" status code
+   * Sends a 416 Range Not Satisfiable response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   requestedRangeNotSatisfiable(body, generateEtag) {
     this.status(ResponseStatus.RangeNotSatisfiable);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "417" status code
+   * Sends a 417 Expectation Failed response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   expectationFailed(body, generateEtag) {
     this.status(ResponseStatus.ExpectationFailed);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "422" status code
+   * Sends a 422 Unprocessable Entity response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   unprocessableEntity(body, generateEtag) {
     this.status(ResponseStatus.UnprocessableEntity);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "429" status code
+   * Sends a 429 Too Many Requests response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   tooManyRequests(body, generateEtag) {
     this.status(ResponseStatus.TooManyRequests);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "500" status code
+   * Sends a 500 Internal Server Error response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   internalServerError(body, generateEtag) {
     this.status(ResponseStatus.InternalServerError);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "501" status code
+   * Sends a 501 Not Implemented response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   notImplemented(body, generateEtag) {
     this.status(ResponseStatus.NotImplemented);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "502" status code
+   * Sends a 502 Bad Gateway response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   badGateway(body, generateEtag) {
     this.status(ResponseStatus.BadGateway);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "503" status code
+   * Sends a 503 Service Unavailable response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   serviceUnavailable(body, generateEtag) {
     this.status(ResponseStatus.ServiceUnavailable);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "504" status code
+   * Sends a 504 Gateway Timeout response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   gatewayTimeout(body, generateEtag) {
     this.status(ResponseStatus.GatewayTimeout);
     return this.send(body, generateEtag);
   }
   /**
-   * Shorthand method to finish request with "505" status code
+   * Sends a 505 HTTP Version Not Supported response
+   *
+   * @param body - Response body
+   * @param generateEtag - Whether to generate ETag header
    */
   httpVersionNotSupported(body, generateEtag) {
     this.status(ResponseStatus.HTTPVersionNotSupported);
@@ -3472,6 +3918,8 @@ var RoutesStore = class {
    *   }
    * })
    * ```
+   * @param route - The route to add to the store
+   * @returns Current RoutesStore instance for method chaining
    */
   add(route) {
     if (route.domain !== "root") {
@@ -3492,6 +3940,11 @@ var RoutesStore = class {
    * The domain parameter has to be a registered pattern and not the fully
    * qualified runtime domain. You must call `matchDomain` first to fetch
    * the pattern for qualified domain
+   * @param url - The URL to match
+   * @param method - HTTP method
+   * @param shouldDecodeParam - Whether to decode parameters
+   * @param domain - Optional domain tokens and hostname
+   * @returns Matched route or null if no match found
    */
   match(url, method, shouldDecodeParam, domain) {
     const domainName = domain?.tokens[0]?.old || "root";
@@ -3517,6 +3970,8 @@ var RoutesStore = class {
   }
   /**
    * Match hostname against registered domains.
+   * @param hostname - The hostname to match
+   * @returns Array of matched domain tokens
    */
   matchDomain(hostname) {
     if (!hostname || !this.usingDomains) {
@@ -3526,6 +3981,84 @@ var RoutesStore = class {
   }
 };
 
+// src/router/url_builder.ts
+function createUrlBuilder(router, searchParamsStringifier) {
+  let domainsList;
+  function createUrlForRoute(identifier, params, options, method) {
+    if (!domainsList) {
+      domainsList = Object.keys(router.toJSON()).filter((domain2) => domain2 !== "root");
+    }
+    const domain = domainsList.find((name) => identifier.startsWith(`${name}@`));
+    const routeIdentifier = domain ? identifier.replace(new RegExp(`^${domain}@`), "") : identifier;
+    const route = router.findOrFail(routeIdentifier, domain, method, true);
+    return createURL(
+      route.name ?? route.pattern,
+      route.tokens,
+      searchParamsStringifier,
+      params,
+      options
+    );
+  }
+  const urlFor = function route(...[identifier, params, options]) {
+    return createUrlForRoute(identifier, params, options);
+  };
+  urlFor.get = function urlForMethodGet(...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, "GET"),
+      method: "get",
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  urlFor.post = function urlForMethodPost(...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, "POST"),
+      method: "post",
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  urlFor.put = function urlForMethodPut(...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, "PUT"),
+      method: "put",
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  urlFor.patch = function urlForMethodPatch(...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, "PATCH"),
+      method: "patch",
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  urlFor.delete = function urlForMethodDelete(...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, "DELETE"),
+      method: "delete",
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  urlFor.method = function urlForCustomMethod(method, ...[identifier, params, options]) {
+    return {
+      url: createUrlForRoute(identifier, params, options, method),
+      method,
+      toString() {
+        return this.url;
+      }
+    };
+  };
+  return urlFor;
+}
+
 // src/router/legacy/url_builder.ts
 var UrlBuilder = class {
   /**
@@ -3549,15 +4082,22 @@ var UrlBuilder = class {
    * Route finder for finding route pattern
    */
   #router;
+  /**
+   * Domain to use for URL generation
+   */
   #domain;
+  /**
+   * Creates a new UrlBuilder instance
+   * @param router - The router instance
+   * @param domain - Optional domain for URL generation
+   */
   constructor(router, domain) {
     this.#router = router;
     this.#domain = domain;
   }
   /**
    * Prefix a custom base URL to the final URI
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    */
   prefixUrl(url) {
     this.#baseUrl = url;
@@ -3566,8 +4106,7 @@ var UrlBuilder = class {
   /**
    * Disable route lookup. Calling this method considers
    * the "identifier" as the route pattern
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    */
   disableRouteLookup() {
     this.#shouldPerformLookup = false;
@@ -3575,8 +4114,7 @@ var UrlBuilder = class {
   }
   /**
    * Append query string to the final URI
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    */
   qs(queryString) {
     if (!queryString) {
@@ -3587,8 +4125,7 @@ var UrlBuilder = class {
   }
   /**
    * Specify params to apply to the route pattern
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    */
   params(params) {
     if (!params) {
@@ -3602,8 +4139,9 @@ var UrlBuilder = class {
    * route name, controller.method name or the route pattern
    * itself.
    *
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
+   * @param identifier - Route identifier to generate URL for
+   * @returns Generated URL string
    */
   make(identifier) {
     return this.#router.makeUrl(identifier, this.#params, {
@@ -3618,8 +4156,7 @@ var UrlBuilder = class {
    * route name, controller.method name or the route pattern
    * itself.
    *
-   * @deprecated
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    *
    */
   makeSigned(identifier, options) {
@@ -3639,12 +4176,14 @@ var RouteMatchers = class extends Macroable7 {
   /**
    * Enforce value to be a number and also casts it to number data
    * type
+   * @returns Route matcher configuration for numeric values
    */
   number() {
     return { match: /^[0-9]+$/, cast: (value) => Number(value) };
   }
   /**
    * Enforce value to be formatted as uuid
+   * @returns Route matcher configuration for UUID values
    */
   uuid() {
     return {
@@ -3654,133 +4193,13 @@ var RouteMatchers = class extends Macroable7 {
   }
   /**
    * Enforce value to be formatted as slug
+   * @returns Route matcher configuration for slug values
    */
   slug() {
     return { match: /^[^\s-_](?!.*?[-_]{2,})([a-z0-9-\\]{1,})[^\s]*[^-_\s]$/ };
   }
 };
 
-// src/router/url_builder.ts
-function createURL(identifier, 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 "${identifier}". 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 "${identifier}". 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 createUrlBuilder(router, searchParamsStringifier) {
-  let domainsList;
-  function createUrlForRoute(identifier, params, options, method) {
-    if (!domainsList) {
-      domainsList = Object.keys(router.toJSON()).filter((domain2) => domain2 !== "root");
-    }
-    const domain = domainsList.find((name) => identifier.startsWith(`${name}@`));
-    const routeIdentifier = domain ? identifier.replace(new RegExp(`^${domain}@`), "") : identifier;
-    const route = router.findOrFail(routeIdentifier, domain, method, true);
-    return createURL(
-      route.name ?? route.pattern,
-      route.tokens,
-      searchParamsStringifier,
-      params,
-      options
-    );
-  }
-  const urlFor = function route(...[identifier, params, options]) {
-    return createUrlForRoute(identifier, params, options);
-  };
-  urlFor.get = function urlForMethodGet(...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, "GET"),
-      method: "get",
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  urlFor.post = function urlForMethodPost(...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, "POST"),
-      method: "post",
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  urlFor.put = function urlForMethodPut(...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, "PUT"),
-      method: "put",
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  urlFor.patch = function urlForMethodPatch(...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, "PATCH"),
-      method: "patch",
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  urlFor.delete = function urlForMethodDelete(...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, "DELETE"),
-      method: "delete",
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  urlFor.method = function urlForCustomMethod(method, ...[identifier, params, options]) {
-    return {
-      url: createUrlForRoute(identifier, params, options, method),
-      method,
-      toString() {
-        return this.url;
-      }
-    };
-  };
-  return urlFor;
-}
-
 // src/define_middleware.ts
 import { moduleImporter as moduleImporter2 } from "@adonisjs/fold";
 function middlewareReferenceBuilder(name, middleware) {
@@ -3805,20 +4224,6 @@ function defineNamedMiddleware(collection) {
 }
 
 // src/router/signed_url_builder.ts
-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 createSignedUrlBuilder(router, encryption, searchParamsStringifier) {
   let domainsList;
   function createSignedUrlForRoute(identifier, params, options, method) {
@@ -3966,6 +4371,12 @@ var Router = class {
    * List of route references kept for lookup.
    */
   routes = {};
+  /**
+   * Creates a new Router instance
+   * @param app - The AdonisJS application instance
+   * @param encryption - Encryption service for signed URLs
+   * @param qsParser - Query string parser for URL generation
+   */
   constructor(app, encryption, qsParser) {
     this.#app = app;
     this.#encryption = encryption;
@@ -3996,6 +4407,8 @@ var Router = class {
   }
   /**
    * Parses the route pattern
+   * @param pattern - The route pattern to parse
+   * @param matchers - Optional route matchers
    */
   parsePattern(pattern, matchers) {
     return parseRoute(pattern, matchers);
@@ -4004,6 +4417,8 @@ var Router = class {
    * Define an array of middleware to use on all the routes.
    * Calling this method multiple times pushes to the
    * existing list of middleware
+   * @param middleware - Array of middleware classes to apply globally
+   * @returns Current Router instance for method chaining
    */
   use(middleware) {
     middleware.forEach(
@@ -4018,12 +4433,18 @@ var Router = class {
    * Define a collection of named middleware. The defined collection is
    * not registered anywhere, but instead converted in a new collection
    * of functions you can apply on the routes, or router groups.
+   * @param collection - Object mapping middleware names to middleware classes
+   * @returns Named middleware functions
    */
   named(collection) {
     return defineNamedMiddleware(collection);
   }
   /**
    * Add route for a given pattern and methods
+   * @param pattern - The route pattern
+   * @param methods - Array of HTTP methods
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   route(pattern, methods, handler) {
     const route = new Route(this.#app, this.#middleware, {
@@ -4037,6 +4458,9 @@ var Router = class {
   }
   /**
    * Define a route that handles all common HTTP methods
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   any(pattern, handler) {
     return this.route(
@@ -4047,30 +4471,45 @@ var Router = class {
   }
   /**
    * Define `GET` route
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   get(pattern, handler) {
     return this.route(pattern, ["GET", "HEAD"], handler);
   }
   /**
    * Define `POST` route
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   post(pattern, handler) {
     return this.route(pattern, ["POST"], handler);
   }
   /**
    * Define `PUT` route
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   put(pattern, handler) {
     return this.route(pattern, ["PUT"], handler);
   }
   /**
    * Define `PATCH` route
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   patch(pattern, handler) {
     return this.route(pattern, ["PATCH"], handler);
   }
   /**
    * Define `DELETE` route
+   * @param pattern - The route pattern
+   * @param handler - Route handler (function, string, or controller tuple)
+   * @returns The created route instance
    */
   delete(pattern, handler) {
     return this.route(pattern, ["DELETE"], handler);
@@ -4078,6 +4517,8 @@ var Router = class {
   /**
    * Creates a group of routes. A route group can apply transforms
    * to routes in bulk
+   * @param callback - Function that defines routes within the group
+   * @returns The created route group instance
    */
   group(callback) {
     const group = new RouteGroup([]);
@@ -4089,6 +4530,9 @@ var Router = class {
   }
   /**
    * Registers a route resource with conventional set of routes
+   * @param resource - The resource name
+   * @param controller - Controller to handle the resource
+   * @returns The created route resource instance
    */
   resource(resource, controller) {
     const resourceInstance = new RouteResource(this.#app, this.#middleware, {
@@ -4102,6 +4546,9 @@ var Router = class {
   }
   /**
    * Register a route resource with shallow nested routes.
+   * @param resource - The resource name
+   * @param controller - Controller to handle the resource
+   * @returns The created route resource instance
    */
   shallowResource(resource, controller) {
     const resourceInstance = new RouteResource(this.#app, this.#middleware, {
@@ -4115,6 +4562,8 @@ var Router = class {
   }
   /**
    * Returns a brisk route instance for a given URL pattern
+   * @param pattern - The route pattern
+   * @returns The created brisk route instance
    */
   on(pattern) {
     const briskRoute = new BriskRoute(this.#app, this.#middleware, {
@@ -4127,6 +4576,9 @@ var Router = class {
   /**
    * Define matcher for a given param. The global params are applied
    * on all the routes (unless overridden at the route level).
+   * @param param - The parameter name to match
+   * @param matcher - The matcher pattern (RegExp, string, or RouteMatcher)
+   * @returns Current Router instance for method chaining
    */
   where(param, matcher) {
     if (typeof matcher === "string") {
@@ -4179,6 +4631,11 @@ var Router = class {
    *
    * When "disableLegacyLookup" is set, the lookup will be performed
    * only using the route name
+   * @param routeIdentifier - Route name, pattern, or controller reference
+   * @param domain - Optional domain to search within
+   * @param method - Optional HTTP method to filter by
+   * @param disableLegacyLookup - Whether to disable legacy lookup strategies
+   * @returns Found route or null if not found
    */
   find(routeIdentifier, domain, method, disableLegacyLookup) {
     if (!domain) {
@@ -4220,6 +4677,12 @@ var Router = class {
    *
    * When "disableLegacyLookup" is set, the lookup will be performed
    * only using the route name
+   * @param routeIdentifier - Route name, pattern, or controller reference
+   * @param domain - Optional domain to search within
+   * @param method - Optional HTTP method to filter by
+   * @param disableLegacyLookup - Whether to disable legacy lookup strategies
+   * @returns Found route
+   * @throws Error when route is not found
    */
   findOrFail(routeIdentifier, domain, method, disableLegacyLookup) {
     const route = this.find(routeIdentifier, domain, method, disableLegacyLookup);
@@ -4236,12 +4699,18 @@ var Router = class {
    * When "followLookupStrategy" is enabled, the lookup will be performed
    * on the basis of the lookup strategy enabled via the "lookupStrategies"
    * method. The default lookupStrategy is "name" and "pattern".
+   * @param routeIdentifier - Route name, pattern, or controller reference
+   * @param domain - Optional domain to search within
+   * @param method - Optional HTTP method to filter by
+   * @param followLookupStrategy - Whether to follow the configured lookup strategy
+   * @returns True if route exists, false otherwise
    */
   has(routeIdentifier, domain, method, followLookupStrategy) {
     return !!this.find(routeIdentifier, domain, method, followLookupStrategy);
   }
   /**
    * Returns a list of routes grouped by their domain names
+   * @returns Object mapping domain names to route arrays
    */
   toJSON() {
     return this.routes;
@@ -4250,6 +4719,8 @@ var Router = class {
    * Generates types for the URL builder. These types must
    * be written inside a file for the URL builder to
    * pick them up.
+   * @param indentation - Indentation level for generated types
+   * @returns Generated TypeScript types as string
    */
   generateTypes(indentation = 0) {
     const routesList = {};
@@ -4318,6 +4789,11 @@ var Router = class {
   }
   /**
    * Find route for a given URL, method and optionally domain
+   * @param uri - The URI to match
+   * @param method - HTTP method
+   * @param shouldDecodeParam - Whether to decode parameters
+   * @param hostname - Optional hostname for domain matching
+   * @returns Matched route or null if no match found
    */
   match(uri, method, shouldDecodeParam, hostname) {
     const matchingDomain = this.#store.matchDomain(hostname);
@@ -4328,9 +4804,7 @@ var Router = class {
   }
   /**
    * Create URL builder instance.
-   * @deprecated
-   *
-   * Instead use "@adonisjs/core/services/url_builder" instead
+   * @deprecated Instead use "@adonisjs/core/services/url_builder" instead
    */
   builder() {
     return new UrlBuilder(this);
@@ -4402,27 +4876,13 @@ import { RuntimeException as RuntimeException6 } from "@poppinss/utils/exception
 // src/http_context/local_storage.ts
 import { AsyncLocalStorage } from "async_hooks";
 var 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;
@@ -4431,6 +4891,14 @@ var asyncLocalStorage = {
 
 // src/http_context/main.ts
 var HttpContext = class extends Macroable8 {
+  /**
+   * 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, response, logger, containerResolver) {
     super();
     this.request = request;
@@ -4517,13 +4985,30 @@ import { moduleCaller as moduleCaller2, moduleImporter as moduleImporter4 } from
 // src/qs.ts
 import { parse as parse2, stringify } from "qs";
 var Qs = class {
+  /**
+   * Configuration object containing parse and stringify options for query strings
+   */
   #config;
+  /**
+   * Creates a new query string parser instance with the provided configuration
+   * @param config - Configuration object with parse and stringify options
+   */
   constructor(config) {
     this.#config = config;
   }
+  /**
+   * 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) => {
     return parse2(value, this.#config.parse);
   };
+  /**
+   * 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) => {
     return stringify(value, this.#config.stringify);
   };
@@ -4566,7 +5051,7 @@ function middlewareHandler(resolver, ctx) {
     debug_default("executing middleware %s", fn.name);
     return httpMiddleware.tracePromise(
       fn.handle,
-      fn,
+      httpMiddleware.hasSubscribers ? { middleware: fn } : void 0,
       void 0,
       resolver,
       ctx,
@@ -4577,9 +5062,12 @@ function middlewareHandler(resolver, ctx) {
 
 // src/server/main.ts
 var Server = class {
+  /**
+   * Flag indicating whether the server has been booted and initialized
+   */
   #booted = false;
   /**
-   * The default error handler to use
+   * Built-in fallback error handler used when no custom handler is registered
    */
   #defaultErrorHandler = {
     report() {
@@ -4589,86 +5077,88 @@ var Server = class {
     }
   };
   /**
-   * Logger instance, a child logger is added
-   * to the context to have request specific
-   * logging capabilities.
+   * Logger instance for server-level logging (child loggers are created per request)
    */
   #logger;
   /**
-   * Registered error handler (if any)
+   * Lazy import reference to the custom error handler class
    */
   #errorHandler;
   /**
-   * Resolved error handler is an instance of the lazily imported error
-   * handler class.
+   * Active error handler instance (either custom or default)
    */
   #resolvedErrorHandler = this.#defaultErrorHandler;
   /**
-   * Emitter is required to notify when a request finishes
+   * Event emitter for HTTP server lifecycle events
    */
   #emitter;
   /**
-   * The application instance to be shared with the router
+   * AdonisJS application instance providing IoC container and configuration
    */
   #app;
   /**
-   * The encryption instance to be shared with the router
+   * Encryption service for secure cookie handling and data encryption
    */
   #encryption;
   /**
-   * Server config
+   * Server configuration settings including timeouts, middleware options, etc.
    */
   #config;
   /**
-   * Query string parser used by the server
+   * Query string parser instance for URL parameter processing
    */
   #qsParser;
   /**
-   * Server middleware stack runs on every incoming HTTP request
+   * Compiled middleware stack that executes on every incoming HTTP request
    */
   #serverMiddlewareStack;
   /**
-   * Reference to the router used by the server
+   * Router instance responsible for route registration and matching
    */
   #router;
   /**
-   * Reference to the underlying Node HTTP server in use
+   * Reference to the underlying Node.js HTTP or HTTPS server instance
    */
   #nodeHttpServer;
   /**
-   * Middleware store to be shared with the routes
+   * Collection of registered global middleware before compilation
    */
   #middleware = [];
   /**
-   * The request error response is attached to the middleware
-   * pipeline to intercept errors and invoke the user
-   * registered error handler.
-   *
-   * We share this with the route middleware pipeline as well,
-   * so that it does not throw any exceptions
+   * Error responder function that handles exceptions in middleware and routes.
+   * Reports errors and delegates handling to the configured error handler.
    */
   #requestErrorResponder = (error, ctx) => {
     this.#resolvedErrorHandler.report(error, ctx);
     return httpExceptionHandler.tracePromise(
       this.#resolvedErrorHandler.handle,
       void 0,
-      void 0,
+      this.#resolvedErrorHandler,
       error,
       ctx
     );
   };
   /**
-   * Check if the server has already been booted
+   * Indicates whether the server has completed its boot process
    */
   get booted() {
     return this.#booted;
   }
   /**
-   * Know if async local storage is enabled or not.
+   * Indicates whether async local storage is enabled for request context
    */
   get usingAsyncLocalStorage() {
     return asyncLocalStorage.isEnabled;
   }
+  /**
+   * Creates a new Server instance
+   *
+   * @param app - AdonisJS application instance
+   * @param encryption - Encryption service for secure operations
+   * @param emitter - Event emitter for server lifecycle events
+   * @param logger - Logger instance for server operations
+   * @param config - Server configuration settings
+   */
   constructor(app, encryption, emitter, logger, config) {
     this.#app = app;
     this.#emitter = emitter;
@@ -4681,7 +5171,7 @@ var Server = class {
     debug_default("server config: %O", this.#config);
   }
   /**
-   * Create async local storage store when enabled
+   * Initializes or destroys async local storage based on configuration
    */
   #createAsyncLocalStore() {
     if (this.#config.useAsyncLocalStorage) {
@@ -4692,7 +5182,7 @@ var Server = class {
     }
   }
   /**
-   * Creates an instance of the server middleware stack
+   * Compiles registered middleware into a frozen middleware stack for execution
    */
   #createServerMiddlewareStack() {
     this.#serverMiddlewareStack = new Middleware2();
@@ -4701,7 +5191,11 @@ var Server = class {
     this.#middleware = [];
   }
   /**
-   * Handles the HTTP request
+   * Processes an HTTP request through the middleware pipeline and routing
+   *
+   * @param ctx - HTTP context containing request/response objects
+   * @param resolver - Container resolver for dependency injection
+   * @returns Promise that resolves when request processing is complete
    */
   #handleRequest(ctx, resolver) {
     return this.#serverMiddlewareStack.runner().errorHandler((error) => this.#requestErrorResponder(error, ctx)).finalHandler(routeFinder(this.#router, resolver, ctx, this.#requestErrorResponder)).run(middlewareHandler(resolver, ctx)).catch((error) => {
@@ -4710,7 +5204,10 @@ var Server = class {
     }).finally(writeResponse(ctx));
   }
   /**
-   * Creates a pipeline of middleware.
+   * Creates a testing middleware pipeline for unit/integration testing
+   *
+   * @param middleware - Array of middleware classes to include in pipeline
+   * @returns TestingMiddlewarePipeline instance for test execution
    */
   pipeline(middleware) {
     const middlewareStack = new Middleware2();
@@ -4739,9 +5236,10 @@ var Server = class {
     };
   }
   /**
-   * Define an array of middleware to use on all the incoming HTTP request.
-   * Calling this method multiple times pushes to the existing list
-   * of middleware
+   * Registers global middleware to run on all incoming HTTP requests
+   *
+   * @param middleware - Array of lazy-imported middleware classes
+   * @returns The Server instance for method chaining
    */
   use(middleware) {
     middleware.forEach(
@@ -4753,18 +5251,22 @@ var Server = class {
     return this;
   }
   /**
-   * Register a custom error handler for HTTP requests.
-   * All errors will be reported to this method
+   * Registers a custom error handler for HTTP request processing
+   *
+   * @param handler - Lazy import of the error handler class
+   * @returns The Server instance for method chaining
    */
   errorHandler(handler) {
     this.#errorHandler = handler;
     return this;
   }
   /**
-   * Boot the server. Calling this method performs the following actions.
+   * Initializes the server by compiling middleware, committing routes, and resolving handlers
    *
-   * - Register routes with the store.
-   * - Resolve and construct the error handler.
+   * Performs the following operations:
+   * - Compiles the middleware stack
+   * - Commits registered routes to the router
+   * - Resolves and instantiates the custom error handler
    */
   async boot() {
     if (this.#booted) {
@@ -4783,7 +5285,9 @@ var Server = class {
     this.#booted = true;
   }
   /**
-   * Set the HTTP server instance used to listen for requests.
+   * Configures the underlying Node.js HTTP/HTTPS server with timeout settings
+   *
+   * @param server - Node.js HTTP or HTTPS server instance
    */
   setNodeServer(server) {
     server.timeout = this.#config.timeout ?? server.timeout;
@@ -4793,33 +5297,48 @@ var Server = class {
     this.#nodeHttpServer = server;
   }
   /**
-   * Returns reference to the underlying HTTP server
-   * in use
+   * Gets the underlying Node.js HTTP/HTTPS server instance
+   *
+   * @returns The configured server instance or undefined if not set
    */
   getNodeServer() {
     return this.#nodeHttpServer;
   }
   /**
-   * Returns reference to the router instance used
-   * by the server.
+   * Gets the router instance used for route registration and matching
+   *
+   * @returns The Router instance
    */
   getRouter() {
     return this.#router;
   }
   /**
-   * Creates an instance of the [[Request]] class
+   * Creates a Request instance from Node.js request/response objects
+   *
+   * @param req - Node.js IncomingMessage
+   * @param res - Node.js ServerResponse
+   * @returns New Request instance
    */
   createRequest(req, res) {
     return new Request(req, res, this.#encryption, this.#config, this.#qsParser);
   }
   /**
-   * Creates an instance of the [[Response]] class
+   * Creates a Response instance from Node.js request/response objects
+   *
+   * @param req - Node.js IncomingMessage
+   * @param res - Node.js ServerResponse
+   * @returns New Response instance
    */
   createResponse(req, res) {
     return new Response(req, res, this.#encryption, this.#config, this.#router, this.#qsParser);
   }
   /**
-   * Creates an instance of the [[HttpContext]] class
+   * Creates an HttpContext instance with request-specific logger
+   *
+   * @param request - Request instance
+   * @param response - Response instance
+   * @param resolver - Container resolver for dependency injection
+   * @returns New HttpContext instance
    */
   createHttpContext(request, response, resolver) {
     return new HttpContext(
@@ -4830,13 +5349,19 @@ var Server = class {
     );
   }
   /**
-   * Returns a list of server middleware stack
+   * Gets the list of registered global middleware
+   *
+   * @returns Array of parsed global middleware
    */
   getMiddlewareList() {
     return this.#serverMiddlewareStack ? Array.from(this.#serverMiddlewareStack.all()) : [...this.#middleware];
   }
   /**
-   * Handle request
+   * Handles an incoming HTTP request by creating context and processing through pipeline
+   *
+   * @param req - Node.js IncomingMessage
+   * @param res - Node.js ServerResponse
+   * @returns Promise that resolves when request processing is complete
    */
   handle(req, res) {
     const hasRequestListener = this.#emitter.hasListeners("http:request_completed");
@@ -4858,10 +5383,22 @@ var Server = class {
     if (this.usingAsyncLocalStorage) {
       return asyncLocalStorage.storage.run(
         ctx,
-        () => httpRequest.tracePromise(this.#handleRequest, ctx, this, ctx, resolver)
+        () => httpRequest.tracePromise(
+          this.#handleRequest,
+          httpRequest.hasSubscribers ? { ctx } : void 0,
+          this,
+          ctx,
+          resolver
+        )
       );
     }
-    return httpRequest.tracePromise(this.#handleRequest, ctx, this, ctx, resolver);
+    return httpRequest.tracePromise(
+      this.#handleRequest,
+      httpRequest.hasSubscribers ? { ctx } : void 0,
+      this,
+      ctx,
+      resolver
+    );
   }
 };
 
@@ -4928,6 +5465,7 @@ export {
   E_HTTP_REQUEST_ABORTED,
   errors_exports,
   CookieClient,
+  CookieParser,
   canWriteResponseBody,
   tracing_channels_exports,
   Route,
@@ -4938,6 +5476,7 @@ export {
   Request,
   Redirect,
   ResponseStatus,
+  CookieSerializer,
   Response,
   Qs,
   Router,