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

package/build/{chunk-VYBTM3NC.js → chunk-YBLFT4O6.js}

@@ -1,10 +1,62 @@
 import {
-  __export,
+  BriskRoute,
+  Route,
+  RouteGroup,
+  RouteResource,
+  createSignedURL,
+  debug_default,
   default as default2,
   default2 as default3,
+  httpExceptionHandler,
+  httpMiddleware,
+  httpRequest,
+  httpResponseSerializer,
   parseRoute,
-  serializeCookie
-} from "./chunk-ASX56VAK.js";
+  safeDecodeURI,
+  serializeCookie,
+  toRoutesJSON,
+  trustProxy
+} from "./chunk-QDK57QGB.js";
+import {
+  createUrlBuilder
+} from "./chunk-5PWHBE2E.js";
+import {
+  __export,
+  createURL,
+  findRoute
+} from "./chunk-2QM3D5BN.js";
+
+// src/qs.ts
+import { parse, 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 parse(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);
+  };
+};
 
 // src/errors.ts
 var errors_exports = {};
@@ -29,7 +81,17 @@ var E_HTTP_EXCEPTION = class HttpException extends Exception {
   body;
   static code = "E_HTTP_EXCEPTION";
   /**
-   * This method returns an instance of the exception class
+   * Creates and returns an instance of the HttpException class.
+   *
+   * @param body - The response body (string, object, or null/undefined)
+   * @param status - HTTP status code for the response
+   * @param code - Optional error code (defaults to 'E_HTTP_EXCEPTION')
+   *
+   * @example
+   * ```ts
+   * const error = HttpException.invoke('Resource not found', 404)
+   * const error2 = HttpException.invoke({ message: 'Validation failed' }, 422)
+   * ```
    */
   static invoke(body, status, code = "E_HTTP_EXCEPTION") {
     if (body === null || body === void 0) {
@@ -107,42 +169,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) {
@@ -151,7 +247,21 @@ var CookieClient = class {
     return canUnpack(value) ? unpack(value) : null;
   }
   /**
-   * Parse response cookie
+   * Parse a cookie value by attempting to decrypt, unsign, or decode it.
+   *
+   * This method tries different unpacking strategies in order:
+   * 1. Unsign if it's a signed cookie
+   * 2. Decrypt if it's an encrypted cookie
+   * 3. Decode if it's a plain encoded cookie
+   *
+   * @param key - The cookie key
+   * @param value - The cookie value to parse
+   *
+   * @example
+   * ```ts
+   * const parsed = client.parse('session', 'e30.abc123def')
+   * // Returns the original value if successfully parsed
+   * ```
    */
   parse(key, value) {
     if (canUnpack2(value)) {
@@ -166,998 +276,12 @@ var CookieClient = class {
   }
 };
 
-// src/tracing_channels.ts
-var tracing_channels_exports = {};
-__export(tracing_channels_exports, {
-  httpExceptionHandler: () => httpExceptionHandler,
-  httpMiddleware: () => httpMiddleware,
-  httpRequest: () => httpRequest,
-  httpResponseSerializer: () => httpResponseSerializer,
-  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 httpExceptionHandler = diagnostics_channel.tracingChannel(
-  "adonisjs:http.exception.handler"
-);
-var httpRouteHandler = diagnostics_channel.tracingChannel("adonisjs:http.route.handler");
-var httpResponseSerializer = diagnostics_channel.tracingChannel(
-  "adonisjs:http.response.serializer"
-);
-
-// src/router/route.ts
-import is from "@sindresorhus/is";
-import Macroable4 from "@poppinss/macroable";
-import Middleware from "@poppinss/middleware";
-import { RuntimeException as RuntimeException2 } from "@poppinss/utils/exception";
-import { moduleCaller, moduleImporter } from "@adonisjs/fold";
-
-// src/debug.ts
-import { debuglog } from "util";
-var debug_default = debuglog("adonisjs:http");
-
-// src/router/factories/use_return_value.ts
-function canWriteResponseBody(value, ctx) {
-  return value !== void 0 && // Return value is explicitly defined
-  !ctx.response.hasLazyBody && // Lazy body is not set
-  value !== ctx.response;
-}
-function useReturnValue(ctx) {
-  return function(value) {
-    if (canWriteResponseBody(value, ctx)) {
-      ctx.response.send(value);
-    }
-  };
-}
-
-// src/router/executor.ts
-function execute(route, resolver, ctx, errorResponder) {
-  return route.middleware.runner().errorHandler((error) => errorResponder(error, ctx)).finalHandler(() => {
-    if (typeof route.handler === "function") {
-      return httpRouteHandler.tracePromise(
-        ($ctx) => Promise.resolve(route.handler($ctx)),
-        route,
-        void 0,
-        ctx
-      ).then(useReturnValue(ctx));
-    }
-    return httpRouteHandler.tracePromise(
-      route.handler.handle,
-      route,
-      void 0,
-      resolver,
-      ctx
-    ).then(useReturnValue(ctx));
-  }).run(async (middleware, next) => {
-    if (typeof middleware === "function") {
-      return httpMiddleware.tracePromise(
-        middleware,
-        middleware,
-        void 0,
-        ctx,
-        next
-      );
-    }
-    return httpMiddleware.tracePromise(
-      middleware.handle,
-      middleware,
-      void 0,
-      resolver,
-      ctx,
-      next,
-      middleware.args
-    );
-  });
-}
-
-// src/utils.ts
-import Cache from "tmp-cache";
-import { InvalidArgumentsException } from "@poppinss/utils/exception";
-
-// src/router/group.ts
-import Macroable3 from "@poppinss/macroable";
-
-// src/router/brisk.ts
-import Macroable from "@poppinss/macroable";
-var BriskRoute = class extends Macroable {
-  /**
-   * Route pattern
-   */
-  #pattern;
-  /**
-   * Matchers inherited from the router
-   */
-  #globalMatchers;
-  /**
-   * Reference to the AdonisJS application
-   */
-  #app;
-  /**
-   * Middleware registered on the router
-   */
-  #routerMiddleware;
-  /**
-   * Reference to route instance. Set after `setHandler` is called
-   */
-  route = null;
-  constructor(app, routerMiddleware, options) {
-    super();
-    this.#app = app;
-    this.#routerMiddleware = routerMiddleware;
-    this.#pattern = options.pattern;
-    this.#globalMatchers = options.globalMatchers;
-  }
-  /**
-   * Set handler for the brisk route
-   */
-  setHandler(handler) {
-    this.route = new Route(this.#app, this.#routerMiddleware, {
-      pattern: this.#pattern,
-      globalMatchers: this.#globalMatchers,
-      methods: ["GET", "HEAD"],
-      handler
-    });
-    return this.route;
-  }
-  /**
-   * Redirects to a given route. Params from the original request will
-   * be used when no custom params are defined.
-   */
-  redirect(...args) {
-    const [identifier, params, options] = args;
-    function redirectsToRoute(ctx) {
-      const redirector = ctx.response.redirect();
-      if (options?.status) {
-        redirector.status(options.status);
-      }
-      return redirector.toRoute(identifier, params || ctx.params, options);
-    }
-    Object.defineProperty(redirectsToRoute, "listArgs", { value: identifier, writable: false });
-    return this.setHandler(redirectsToRoute);
-  }
-  /**
-   * Redirect request to a fixed URL
-   */
-  redirectToPath(url, options) {
-    function redirectsToPath(ctx) {
-      const redirector = ctx.response.redirect();
-      if (options?.status) {
-        redirector.status(options.status);
-      }
-      return redirector.toPath(url);
-    }
-    Object.defineProperty(redirectsToPath, "listArgs", { value: url, writable: false });
-    return this.setHandler(redirectsToPath);
-  }
-};
-
-// src/router/resource.ts
-import string from "@poppinss/utils/string";
-import Macroable2 from "@poppinss/macroable";
-import { RuntimeException } from "@poppinss/utils/exception";
-var RouteResource = class extends Macroable2 {
-  /**
-   * Resource identifier. Nested resources are separated
-   * with a dot notation
-   */
-  #resource;
-  /**
-   * The controller to handle resource routing requests
-   */
-  #controller;
-  /**
-   * Is it a shallow resource? Shallow resources URLs do not have parent
-   * resource name and id once they can be identified with the id.
-   */
-  #shallow = false;
-  /**
-   * Matchers inherited from the router
-   */
-  #globalMatchers;
-  /**
-   * Reference to the AdonisJS application
-   */
-  #app;
-  /**
-   * Middleware registered on the router
-   */
-  #routerMiddleware;
-  /**
-   * Parameter names for the resources. Defaults to `id` for
-   * a singular resource and `resource_id` for nested
-   * resources.
-   */
-  #params = {};
-  /**
-   * Base name for the routes. We suffix action names
-   * on top of the base name
-   */
-  #routesBaseName;
-  /**
-   * A collection of routes instances that belongs to this resource
-   */
-  routes = [];
-  constructor(app, routerMiddleware, options) {
-    super();
-    this.#validateResourceName(options.resource);
-    this.#app = app;
-    this.#shallow = options.shallow;
-    this.#routerMiddleware = routerMiddleware;
-    this.#controller = options.controller;
-    this.#globalMatchers = options.globalMatchers;
-    this.#resource = this.#normalizeResourceName(options.resource);
-    this.#routesBaseName = this.#getRoutesBaseName();
-    this.#buildRoutes();
-  }
-  /**
-   * Normalizes the resource name to dropping leading and trailing
-   * slashes.
-   */
-  #normalizeResourceName(resource) {
-    return resource.replace(/^\//, "").replace(/\/$/, "");
-  }
-  /**
-   * Ensure resource name is not an empty string
-   */
-  #validateResourceName(resource) {
-    if (!resource || resource === "/") {
-      throw new RuntimeException(`Invalid resource name "${resource}"`);
-    }
-  }
-  /**
-   * Converting segments of a resource to snake case to
-   * make the route name.
-   */
-  #getRoutesBaseName() {
-    return this.#resource.split(".").map((token) => string.snakeCase(token)).join(".");
-  }
-  /**
-   * Create a new route for the given pattern, methods and controller action
-   */
-  #createRoute(pattern, methods, action) {
-    const route = new Route(this.#app, this.#routerMiddleware, {
-      pattern,
-      methods,
-      handler: typeof this.#controller === "string" ? `${this.#controller}.${action}` : [this.#controller, action],
-      globalMatchers: this.#globalMatchers
-    });
-    route.as(`${this.#routesBaseName}.${action}`);
-    this.routes.push(route);
-  }
-  /**
-   * Returns the `resource_id` name for a given resource. The
-   * resource name is converted to singular form and
-   * transformed to snake case.
-   *
-   * photos becomes photo_id
-   * users becomes user_id
-   */
-  #getResourceId(resource) {
-    return `${string.snakeCase(string.singular(resource))}_id`;
-  }
-  /**
-   * Build routes for the given resource
-   */
-  #buildRoutes() {
-    const resources = this.#resource.split(".");
-    const mainResource = resources.pop();
-    this.#params[mainResource] = ":id";
-    const baseURI = `${resources.map((resource) => {
-      const paramName = `:${this.#getResourceId(resource)}`;
-      this.#params[resource] = paramName;
-      return `${resource}/${paramName}`;
-    }).join("/")}/${mainResource}`;
-    this.#createRoute(baseURI, ["GET", "HEAD"], "index");
-    this.#createRoute(`${baseURI}/create`, ["GET", "HEAD"], "create");
-    this.#createRoute(baseURI, ["POST"], "store");
-    this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id`, ["GET", "HEAD"], "show");
-    this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id/edit`, ["GET", "HEAD"], "edit");
-    this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id`, ["PUT", "PATCH"], "update");
-    this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id`, ["DELETE"], "destroy");
-  }
-  /**
-   * Filter the routes based on their partial names
-   */
-  #filter(names, inverse) {
-    const actions = Array.isArray(names) ? names : [names];
-    return this.routes.filter((route) => {
-      const match = actions.find((name) => route.getName().endsWith(name));
-      return inverse ? !match : match;
-    });
-  }
-  /**
-   * Register only given routes and remove others
-   */
-  only(names) {
-    this.#filter(names, true).forEach((route) => route.markAsDeleted());
-    return this;
-  }
-  /**
-   * Register all routes, except the one's defined
-   */
-  except(names) {
-    this.#filter(names, false).forEach((route) => route.markAsDeleted());
-    return this;
-  }
-  /**
-   * Register api only routes. The `create` and `edit` routes, which
-   * are meant to show forms will not be registered
-   */
-  apiOnly() {
-    return this.except(["create", "edit"]);
-  }
-  /**
-   * Define matcher for params inside the resource
-   */
-  where(key, matcher) {
-    this.routes.forEach((route) => {
-      route.where(key, matcher);
-    });
-    return this;
-  }
-  tap(actions, callback) {
-    if (typeof actions === "function") {
-      this.routes.forEach((route) => {
-        if (!route.isDeleted()) {
-          actions(route);
-        }
-      });
-      return this;
-    }
-    this.#filter(actions, false).forEach((route) => {
-      if (!route.isDeleted()) {
-        callback(route);
-      }
-    });
-    return this;
-  }
-  /**
-   * Set the param name for a given resource
-   */
-  params(resources) {
-    Object.keys(resources).forEach((resource) => {
-      const param = resources[resource];
-      const existingParam = this.#params[resource];
-      this.#params[resource] = `:${param}`;
-      this.routes.forEach((route) => {
-        route.setPattern(
-          route.getPattern().replace(`${resource}/${existingParam}`, `${resource}/:${param}`)
-        );
-      });
-    });
-    return this;
-  }
-  /**
-   * Define one or more middleware on the routes created by
-   * the resource.
-   *
-   * Calling this method multiple times will append middleware
-   * to existing list.
-   */
-  use(actions, middleware) {
-    if (actions === "*") {
-      this.tap((route) => route.use(middleware));
-    } else {
-      this.tap(actions, (route) => route.use(middleware));
-    }
-    return this;
-  }
-  /**
-   * @alias use
-   */
-  middleware(actions, middleware) {
-    return this.use(actions, middleware);
-  }
-  /**
-   * Prepend name to all the routes
-   */
-  as(name, normalizeName = true) {
-    name = normalizeName ? string.snakeCase(name) : name;
-    this.routes.forEach((route) => {
-      route.as(route.getName().replace(this.#routesBaseName, name), false);
-    });
-    this.#routesBaseName = name;
-    return this;
-  }
-};
-
-// src/router/group.ts
-var RouteGroup = class _RouteGroup extends Macroable3 {
-  constructor(routes) {
-    super();
-    this.routes = routes;
-  }
-  /**
-   * Array of middleware registered on the group.
-   */
-  #middleware = [];
-  /**
-   * Shares midldeware stack with the routes. The method is invoked recursively
-   * to only register middleware with the route class and not with the
-   * resource or the child group
-   */
-  #shareMiddlewareStackWithRoutes(route) {
-    if (route instanceof _RouteGroup) {
-      route.routes.forEach((child) => this.#shareMiddlewareStackWithRoutes(child));
-      return;
-    }
-    if (route instanceof RouteResource) {
-      route.routes.forEach((child) => child.getMiddleware().unshift(this.#middleware));
-      return;
-    }
-    if (route instanceof BriskRoute) {
-      route.route.getMiddleware().unshift(this.#middleware);
-      return;
-    }
-    route.getMiddleware().unshift(this.#middleware);
-  }
-  /**
-   * Updates the route name. The method is invoked recursively to only update
-   * the name with the route class and not with the resource or the child
-   * group.
-   */
-  #updateRouteName(route, name) {
-    if (route instanceof _RouteGroup) {
-      route.routes.forEach((child) => this.#updateRouteName(child, name));
-      return;
-    }
-    if (route instanceof RouteResource) {
-      route.routes.forEach((child) => child.as(name, true));
-      return;
-    }
-    if (route instanceof BriskRoute) {
-      route.route.as(name, true);
-      return;
-    }
-    route.as(name, true);
-  }
-  /**
-   * Sets prefix on the route. The method is invoked recursively to only set
-   * the prefix with the route class and not with the resource or the
-   * child group.
-   */
-  #setRoutePrefix(route, prefix) {
-    if (route instanceof _RouteGroup) {
-      route.routes.forEach((child) => this.#setRoutePrefix(child, prefix));
-      return;
-    }
-    if (route instanceof RouteResource) {
-      route.routes.forEach((child) => child.prefix(prefix));
-      return;
-    }
-    if (route instanceof BriskRoute) {
-      route.route.prefix(prefix);
-      return;
-    }
-    route.prefix(prefix);
-  }
-  /**
-   * Updates domain on the route. The method is invoked recursively to only update
-   * the domain with the route class and not with the resource or the child
-   * group.
-   */
-  #updateRouteDomain(route, domain) {
-    if (route instanceof _RouteGroup) {
-      route.routes.forEach((child) => this.#updateRouteDomain(child, domain));
-      return;
-    }
-    if (route instanceof RouteResource) {
-      route.routes.forEach((child) => child.domain(domain));
-      return;
-    }
-    if (route instanceof BriskRoute) {
-      route.route.domain(domain, false);
-      return;
-    }
-    route.domain(domain, false);
-  }
-  /**
-   * Updates matchers on the route. The method is invoked recursively to only update
-   * the matchers with the route class and not with the resource or the child
-   * group.
-   */
-  #updateRouteMatchers(route, param, matcher) {
-    if (route instanceof _RouteGroup) {
-      route.routes.forEach((child) => this.#updateRouteMatchers(child, param, matcher));
-      return;
-    }
-    if (route instanceof RouteResource) {
-      route.routes.forEach((child) => child.where(param, matcher));
-      return;
-    }
-    if (route instanceof BriskRoute) {
-      route.route.where(param, matcher);
-      return;
-    }
-    route.where(param, matcher);
-  }
-  /**
-   * Define route param matcher
-   *
-   * ```ts
-   * Route.group(() => {
-   * }).where('id', /^[0-9]+/)
-   * ```
-   */
-  where(param, matcher) {
-    this.routes.forEach((route) => this.#updateRouteMatchers(route, param, matcher));
-    return this;
-  }
-  /**
-   * Define prefix all the routes in the group.
-   *
-   * ```ts
-   * Route.group(() => {
-   * }).prefix('v1')
-   * ```
-   */
-  prefix(prefix) {
-    this.routes.forEach((route) => this.#setRoutePrefix(route, prefix));
-    return this;
-  }
-  /**
-   * Define domain for all the routes.
-   *
-   * ```ts
-   * Route.group(() => {
-   * }).domain(':name.adonisjs.com')
-   * ```
-   */
-  domain(domain) {
-    this.routes.forEach((route) => this.#updateRouteDomain(route, domain));
-    return this;
-  }
-  /**
-   * Prepend name to the routes name.
-   *
-   * ```ts
-   * Route.group(() => {
-   * }).as('version1')
-   * ```
-   */
-  as(name) {
-    this.routes.forEach((route) => this.#updateRouteName(route, name));
-    return this;
-  }
-  /**
-   * Prepend an array of middleware to all routes middleware.
-   *
-   * ```ts
-   * Route.group(() => {
-   * }).use(middleware.auth())
-   * ```
-   */
-  use(middleware) {
-    if (!this.#middleware.length) {
-      this.routes.forEach((route) => this.#shareMiddlewareStackWithRoutes(route));
-    }
-    if (Array.isArray(middleware)) {
-      for (let one of middleware) {
-        this.#middleware.push(one);
-      }
-    } else {
-      this.#middleware.push(middleware);
-    }
-    return this;
-  }
-  /**
-   * @alias use
-   */
-  middleware(middleware) {
-    return this.use(middleware);
-  }
-};
-
-// src/utils.ts
-var proxyCache = new Cache({ max: 200 });
-function dropSlash(input) {
-  if (input === "/") {
-    return "/";
-  }
-  return `/${input.replace(/^\//, "").replace(/\/$/, "")}`;
-}
-function toRoutesJSON(routes) {
-  return routes.reduce((list, route) => {
-    if (route instanceof RouteGroup) {
-      list = list.concat(toRoutesJSON(route.routes));
-      return list;
-    }
-    if (route instanceof RouteResource) {
-      list = list.concat(toRoutesJSON(route.routes));
-      return list;
-    }
-    if (route instanceof BriskRoute) {
-      if (route.route && !route.route.isDeleted()) {
-        list.push(route.route.toJSON());
-      }
-      return list;
-    }
-    if (!route.isDeleted()) {
-      list.push(route.toJSON());
-    }
-    return list;
-  }, []);
-}
-function trustProxy(remoteAddress, proxyFn) {
-  if (proxyCache.has(remoteAddress)) {
-    return proxyCache.get(remoteAddress);
-  }
-  const result = proxyFn(remoteAddress, 0);
-  proxyCache.set(remoteAddress, result);
-  return result;
-}
-function parseRange(range, value) {
-  const parts = range.split("..");
-  const min = Number(parts[0]);
-  const max = Number(parts[1]);
-  if (parts.length === 1 && !Number.isNaN(min)) {
-    return {
-      [min]: value
-    };
-  }
-  if (Number.isNaN(min) || Number.isNaN(max)) {
-    return {};
-  }
-  if (min === max) {
-    return {
-      [min]: value
-    };
-  }
-  if (max < min) {
-    throw new InvalidArgumentsException(`Invalid range "${range}"`);
-  }
-  return [...Array(max - min + 1).keys()].reduce(
-    (result, step) => {
-      result[min + step] = value;
-      return result;
-    },
-    {}
-  );
-}
-function decodeComponentChar(highCharCode, lowCharCode) {
-  if (highCharCode === 50) {
-    if (lowCharCode === 53) return "%";
-    if (lowCharCode === 51) return "#";
-    if (lowCharCode === 52) return "$";
-    if (lowCharCode === 54) return "&";
-    if (lowCharCode === 66) return "+";
-    if (lowCharCode === 98) return "+";
-    if (lowCharCode === 67) return ",";
-    if (lowCharCode === 99) return ",";
-    if (lowCharCode === 70) return "/";
-    if (lowCharCode === 102) return "/";
-    return null;
-  }
-  if (highCharCode === 51) {
-    if (lowCharCode === 65) return ":";
-    if (lowCharCode === 97) return ":";
-    if (lowCharCode === 66) return ";";
-    if (lowCharCode === 98) return ";";
-    if (lowCharCode === 68) return "=";
-    if (lowCharCode === 100) return "=";
-    if (lowCharCode === 70) return "?";
-    if (lowCharCode === 102) return "?";
-    return null;
-  }
-  if (highCharCode === 52 && lowCharCode === 48) {
-    return "@";
-  }
-  return null;
-}
-function safeDecodeURI(path, useSemicolonDelimiter) {
-  let shouldDecode = false;
-  let shouldDecodeParam = false;
-  let querystring = "";
-  for (let i = 1; i < path.length; i++) {
-    const charCode = path.charCodeAt(i);
-    if (charCode === 37) {
-      const highCharCode = path.charCodeAt(i + 1);
-      const lowCharCode = path.charCodeAt(i + 2);
-      if (decodeComponentChar(highCharCode, lowCharCode) === null) {
-        shouldDecode = true;
-      } else {
-        shouldDecodeParam = true;
-        if (highCharCode === 50 && lowCharCode === 53) {
-          shouldDecode = true;
-          path = path.slice(0, i + 1) + "25" + path.slice(i + 1);
-          i += 2;
-        }
-        i += 2;
-      }
-    } else if (charCode === 63 || charCode === 35 || charCode === 59 && useSemicolonDelimiter) {
-      querystring = path.slice(i + 1);
-      path = path.slice(0, i);
-      break;
-    }
-  }
-  const decodedPath = shouldDecode ? decodeURI(path) : path;
-  return { pathname: decodedPath, query: querystring, shouldDecodeParam };
-}
-
-// src/router/route.ts
-var Route = class extends Macroable4 {
-  /**
-   * Route pattern
-   */
-  #pattern;
-  /**
-   * HTTP Methods for the route
-   */
-  #methods;
-  /**
-   * A unique name for the route
-   */
-  #name;
-  /**
-   * A boolean to prevent route from getting registered within
-   * the store.
-   *
-   * This flag must be set before "Router.commit" method
-   */
-  #isDeleted = false;
-  /**
-   * Route handler
-   */
-  #handler;
-  /**
-   * Matchers inherited from the router
-   */
-  #globalMatchers;
-  /**
-   * Reference to the AdonisJS application
-   */
-  #app;
-  /**
-   * Middleware registered on the router
-   */
-  #routerMiddleware;
-  /**
-   * By default the route is part of the `root` domain. Root domain is used
-   * when no domain is defined
-   */
-  #routeDomain = "root";
-  /**
-   * An object of matchers to be forwarded to the store. The matchers
-   * list is populated by calling `where` method
-   */
-  #matchers = {};
-  /**
-   * Custom prefixes defined on the route or the route parent
-   * groups
-   */
-  #prefixes = [];
-  /**
-   * Middleware defined directly on the route or the route parent
-   * routes. We mantain an array for each layer of the stack
-   */
-  #middleware = [];
-  constructor(app, routerMiddleware, options) {
-    super();
-    this.#app = app;
-    this.#routerMiddleware = routerMiddleware;
-    this.#pattern = options.pattern;
-    this.#methods = options.methods;
-    this.#handler = this.#resolveRouteHandle(options.handler);
-    this.#globalMatchers = options.globalMatchers;
-  }
-  /**
-   * Resolves the route handler string expression to a
-   * handler method object
-   */
-  #resolveRouteHandle(handler) {
-    if (typeof handler === "string") {
-      const parts = handler.split(".");
-      const method = parts.length === 1 ? "handle" : parts.pop();
-      const moduleRefId = parts.join(".");
-      return {
-        reference: handler,
-        ...moduleImporter(() => this.#app.import(moduleRefId), method).toHandleMethod(),
-        name: handler
-      };
-    }
-    if (Array.isArray(handler)) {
-      if (is.class(handler[0])) {
-        return {
-          reference: handler,
-          ...moduleCaller(handler[0], handler[1] || "handle").toHandleMethod()
-        };
-      }
-      return {
-        reference: handler,
-        ...moduleImporter(handler[0], handler[1] || "handle").toHandleMethod()
-      };
-    }
-    return handler;
-  }
-  /**
-   * Returns an object of param matchers by merging global and local
-   * matchers. The local copy is given preference over the global
-   * one's
-   */
-  #getMatchers() {
-    return { ...this.#globalMatchers, ...this.#matchers };
-  }
-  /**
-   * Returns a normalized pattern string by prefixing the `prefix` (if defined).
-   */
-  #computePattern() {
-    const pattern = dropSlash(this.#pattern);
-    const prefix = this.#prefixes.slice().reverse().map((one) => dropSlash(one)).join("");
-    return prefix ? `${prefix}${pattern === "/" ? "" : pattern}` : pattern;
-  }
-  /**
-   * Define matcher for a given param. If a matcher exists, then we do not
-   * override that, since the routes inside a group will set matchers
-   * before the group, so they should have priority over the group
-   * matchers.
-   *
-   * ```ts
-   * Route.group(() => {
-   *   Route.get('/:id', 'handler').where('id', /^[0-9]$/)
-   * }).where('id', /[^a-z$]/)
-   * ```
-   *
-   * The `/^[0-9]$/` will win over the matcher defined by the group
-   */
-  where(param, matcher) {
-    if (this.#matchers[param]) {
-      return this;
-    }
-    if (typeof matcher === "string") {
-      this.#matchers[param] = { match: new RegExp(matcher) };
-    } else if (is.regExp(matcher)) {
-      this.#matchers[param] = { match: matcher };
-    } else {
-      this.#matchers[param] = matcher;
-    }
-    return this;
-  }
-  /**
-   * Define prefix for the route. Calling this method multiple times
-   * applies multiple prefixes in the reverse order.
-   */
-  prefix(prefix) {
-    this.#prefixes.push(prefix);
-    return this;
-  }
-  /**
-   * Define a custom domain for the route. We do not overwrite the domain
-   * unless `overwrite` flag is set to true.
-   */
-  domain(domain, overwrite = false) {
-    if (this.#routeDomain === "root" || overwrite) {
-      this.#routeDomain = domain;
-    }
-    return this;
-  }
-  /**
-   * Define one or more middleware to be executed before the route
-   * handler.
-   *
-   * Named middleware can be referenced using the name registered with
-   * the router middleware store.
-   */
-  use(middleware) {
-    this.#middleware.push(Array.isArray(middleware) ? middleware : [middleware]);
-    return this;
-  }
-  /**
-   * @alias use
-   */
-  middleware(middleware) {
-    return this.use(middleware);
-  }
-  /**
-   * Give a unique name to the route. Assinging a new unique removes the
-   * existing name of the route.
-   *
-   * Setting prepends to true prefixes the name to the existing name.
-   */
-  as(name, prepend = false) {
-    if (prepend) {
-      if (!this.#name) {
-        throw new RuntimeException2(
-          `Routes inside a group must have names before calling "router.group.as"`
-        );
-      }
-      this.#name = `${name}.${this.#name}`;
-      return this;
-    }
-    this.#name = name;
-    return this;
-  }
-  /**
-   * Check if the route was marked to be deleted
-   */
-  isDeleted() {
-    return this.#isDeleted;
-  }
-  /**
-   * Mark route as deleted. Deleted routes are not registered
-   * with the route store
-   */
-  markAsDeleted() {
-    this.#isDeleted = true;
-  }
-  /**
-   * Get the route name
-   */
-  getName() {
-    return this.#name;
-  }
-  /**
-   * Get the route pattern
-   */
-  getPattern() {
-    return this.#pattern;
-  }
-  /**
-   * Set the route pattern
-   */
-  setPattern(pattern) {
-    this.#pattern = pattern;
-    return this;
-  }
-  /**
-   * Returns the stack of middleware registered on the route.
-   * The value is shared by reference.
-   */
-  getMiddleware() {
-    return this.#middleware;
-  }
-  /**
-   * Returns the middleware instance for persistence inside the
-   * store
-   */
-  #getMiddlewareForStore() {
-    const middleware = new Middleware();
-    this.#routerMiddleware.forEach((one) => {
-      debug_default("adding global middleware to route %s, %O", this.#pattern, one);
-      middleware.add(one);
-    });
-    this.#middleware.flat().forEach((one) => {
-      debug_default("adding named middleware to route %s, %O", this.#pattern, one);
-      middleware.add(one);
-    });
-    middleware.freeze();
-    return middleware;
-  }
-  /**
-   * Returns JSON representation of the route
-   */
-  toJSON() {
-    const pattern = this.#computePattern();
-    const matchers = this.#getMatchers();
-    return {
-      domain: this.#routeDomain,
-      pattern,
-      matchers,
-      tokens: parseRoute(pattern, matchers),
-      meta: {},
-      name: this.#name,
-      handler: this.#handler,
-      methods: this.#methods,
-      middleware: this.#getMiddlewareForStore(),
-      execute
-    };
-  }
-};
-
-// src/request.ts
-import fresh from "fresh";
-import typeIs from "type-is";
-import accepts from "accepts";
-import { isIP } from "net";
-import is2 from "@sindresorhus/is";
-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 {
+  /**
+   * Cookie client instance for handling cookie operations
+   */
   #client;
   /**
    * A copy of cached cookies, they are cached during a request after
@@ -1173,12 +297,21 @@ var CookieParser = class {
    * 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) {
@@ -1190,6 +323,10 @@ var CookieParser = class {
    * 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];
@@ -1209,6 +346,9 @@ var CookieParser = class {
   /**
    * 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];
@@ -1228,6 +368,9 @@ var CookieParser = class {
   /**
    * 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];
@@ -1248,6 +391,8 @@ var CookieParser = class {
    * 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;
@@ -1255,7 +400,24 @@ var CookieParser = class {
 };
 
 // src/request.ts
-var Request = class extends Macroable5 {
+import fresh from "fresh";
+import typeIs from "type-is";
+import accepts from "accepts";
+import { isIP } from "net";
+import is from "@sindresorhus/is";
+import proxyaddr from "proxy-addr";
+import { safeEqual } from "@poppinss/utils";
+import Macroable from "@poppinss/macroable";
+import lodash from "@poppinss/utils/lodash";
+var Request = class extends Macroable {
+  /**
+   * 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
+   */
   constructor(request, response, encryption, config, qsParser) {
     super();
     this.request = request;
@@ -1310,16 +472,18 @@ 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.
+   *
+   * This method extracts query parameters from the URL and merges them into
+   * the request data object, also creating a frozen copy for original data reference.
    */
   #parseQueryString() {
     if (this.parsedUrl.query) {
@@ -1328,7 +492,10 @@ var Request = class extends Macroable5 {
     }
   }
   /**
-   * Initiates the cookie parser lazily
+   * Initiates the cookie parser lazily when first needed.
+   *
+   * Creates a CookieParser instance with the current request's cookie header
+   * and the configured encryption service for handling signed/encrypted cookies.
    */
   #initiateCookieParser() {
     if (!this.#cookieParser) {
@@ -1336,16 +503,26 @@ var Request = class extends Macroable5 {
     }
   }
   /**
-   * Lazily initiates the `accepts` module to make sure to parse
-   * the request headers only when one of the content-negotiation
-   * methods are used.
+   * Lazily initiates the `accepts` module for content negotiation.
+   *
+   * Creates an accepts instance that parses the request headers only when
+   * one of the content-negotiation methods (like accepts, acceptsLanguages) are used.
+   * This improves performance by avoiding unnecessary header parsing.
    */
   #initiateAccepts() {
     this.#lazyAccepts = this.#lazyAccepts || accepts(this.request);
   }
   /**
-   * Returns the request id from the `x-request-id` header. The
-   * header is untouched, if it already exists.
+   * Returns the request ID from the `x-request-id` header.
+   *
+   * If the header doesn't exist and request ID generation is enabled,
+   * a new UUID will be generated and added to the request headers.
+   *
+   * @example
+   * ```ts
+   * const requestId = request.id()
+   * console.log(requestId) // '550e8400-e29b-41d4-a716-446655440000'
+   * ```
    */
   id() {
     let requestId = this.header("x-request-id");
@@ -1362,6 +539,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)) {
@@ -1374,6 +553,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;
@@ -1382,6 +563,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;
@@ -1389,6 +572,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;
@@ -1396,18 +581,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;
@@ -1415,6 +603,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;
@@ -1422,6 +611,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;
@@ -1431,6 +621,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;
@@ -1446,6 +637,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);
@@ -1460,6 +654,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);
@@ -1471,6 +668,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);
@@ -1482,6 +681,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);
@@ -1495,6 +696,7 @@ var Request = class extends Macroable5 {
    * ```js
    * request.intended()
    * ```
+   * @returns {string} Original HTTP method from the request
    */
   intended() {
     return this.request.method;
@@ -1512,6 +714,7 @@ var Request = class extends Macroable5 {
    * ```js
    * request.method()
    * ```
+   * @returns {string} HTTP method (potentially spoofed)
    */
   method() {
     if (this.#config.allowMethodSpoofing && this.intended() === "POST") {
@@ -1521,6 +724,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;
@@ -1528,6 +732,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();
@@ -1570,6 +777,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;
@@ -1595,6 +803,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);
@@ -1618,6 +827,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) {
@@ -1633,6 +843,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";
@@ -1653,6 +864,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");
@@ -1680,6 +892,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();
@@ -1695,6 +908,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();
@@ -1711,6 +925,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", "");
@@ -1719,6 +934,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");
@@ -1733,6 +949,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;
@@ -1749,6 +967,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();
@@ -1757,6 +977,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) {
@@ -1802,6 +1024,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;
@@ -1826,6 +1050,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();
@@ -1837,6 +1063,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();
@@ -1862,6 +1089,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();
@@ -1873,6 +1102,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();
@@ -1896,6 +1126,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();
@@ -1907,6 +1139,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();
@@ -1920,17 +1153,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();
@@ -1938,6 +1174,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);
@@ -1965,6 +1202,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) {
@@ -1978,6 +1216,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();
@@ -1985,6 +1224,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();
@@ -1993,14 +1233,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();
@@ -2008,14 +1254,16 @@ var Request = class extends Macroable5 {
   }
   plainCookie(key, defaultValueOrOptions, encoded) {
     this.#initiateCookieParser();
-    if (is2.object(defaultValueOrOptions)) {
+    if (is.object(defaultValueOrOptions)) {
       return this.#cookieParser.decode(key, defaultValueOrOptions?.encoded) || defaultValueOrOptions.defaultValue;
     }
     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();
@@ -2031,6 +1279,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * Serializes request to JSON format
+   * @returns Object representation of the request
    */
   serialize() {
     return {
@@ -2050,6 +1299,7 @@ var Request = class extends Macroable5 {
   }
   /**
    * toJSON copy of the request
+   * @returns JSON representation of the request
    */
   toJSON() {
     return this.serialize();
@@ -2057,24 +1307,42 @@ var Request = class extends Macroable5 {
 };
 
 // src/redirect.ts
-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;
@@ -2082,7 +1350,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);
@@ -2094,22 +1364,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;
@@ -2129,12 +1402,13 @@ 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 = {};
     const referrerUrl = this.#getReferrerUrl();
-    const url = parse(referrerUrl);
+    const url = safeDecodeURI(referrerUrl, false);
     debug_default('referrer url "%s"', referrerUrl);
     debug_default('referrer base url "%s"', url.pathname);
     if (this.#forwardQueryString) {
@@ -2144,7 +1418,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;
@@ -2156,12 +1431,13 @@ 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 = {};
     if (this.#forwardQueryString) {
-      query = this.#qs.parse(parse(this.#request.url).query || "");
+      query = this.#qs.parse(safeDecodeURI(this.#request.url, false).query || "");
     }
     Object.assign(query, this.#queryString);
     this.#sendResponse(url, query);
@@ -2234,24 +1510,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);
   }
@@ -2265,6 +1534,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;
@@ -2277,6 +1551,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);
@@ -2287,6 +1566,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);
@@ -2298,8 +1582,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 Macroable2 from "@poppinss/macroable";
+import { createReadStream } from "fs";
+import contentDisposition from "content-disposition";
+import { safeStringify } from "@poppinss/utils/json";
+import { RuntimeException } from "@poppinss/utils/exception";
 var CACHEABLE_HTTP_METHODS = ["GET", "HEAD"];
-var Response = class extends Macroable6 {
+var Response = class extends Macroable2 {
+  /**
+   * 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;
@@ -2310,73 +1617,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 ? {
@@ -2385,48 +1686,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);
@@ -2434,14 +1733,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;
@@ -2460,13 +1763,20 @@ var Response = class extends Macroable6 {
       }
       return "object";
     }
-    throw new RuntimeException3(`Cannot serialize "${dataType}" to HTTP response`);
+    throw new RuntimeException(`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
    *
-   * Empty body results in `204`.
+   * Automatically sets:
+   * - Content-Type based on content analysis
+   * - Content-Length header
+   * - ETag header (if enabled)
+   * - Status code 204 for empty bodies
+   *
+   * @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 === "";
@@ -2536,7 +1846,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) => {
@@ -2577,7 +1896,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 {
@@ -2617,18 +1948,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) {
@@ -2641,22 +1972,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 {
@@ -2665,14 +2003,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) {
@@ -2683,14 +2022,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) {
@@ -2710,7 +2050,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)) {
@@ -2719,7 +2063,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();
@@ -2730,13 +2077,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;
@@ -2744,8 +2096,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) {
@@ -2755,15 +2109,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) {
@@ -2772,25 +2127,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"];
@@ -2800,27 +2160,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)
    * }
    * ```
    */
@@ -2835,8 +2188,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) {
@@ -2845,58 +2199,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.
+   * Pipes a readable stream to the response with graceful error handling
    *
-   * 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.
-   *
-   * 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) {
@@ -2906,38 +2256,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;
@@ -2945,11 +2292,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) {
@@ -2970,15 +2320,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) {
@@ -2986,8 +2342,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) {
@@ -2995,8 +2354,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);
@@ -3008,8 +2371,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);
@@ -3021,8 +2388,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);
@@ -3034,7 +2405,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);
@@ -3045,10 +2420,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) {
@@ -3069,294 +2444,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);
@@ -3365,14 +2854,13 @@ var Response = class extends Macroable6 {
 };
 
 // src/router/main.ts
-import is3 from "@sindresorhus/is";
-import lodash2 from "@poppinss/utils/lodash";
-import { moduleImporter as moduleImporter3 } from "@adonisjs/fold";
-import { RuntimeException as RuntimeException5 } from "@poppinss/utils/exception";
+import is2 from "@sindresorhus/is";
+import { moduleImporter as moduleImporter2 } from "@adonisjs/fold";
+import { RuntimeException as RuntimeException3 } from "@poppinss/utils/exception";
 
 // src/router/store.ts
 import matchit from "@poppinss/matchit";
-import { RuntimeException as RuntimeException4 } from "@poppinss/utils/exception";
+import { RuntimeException as RuntimeException2 } from "@poppinss/utils/exception";
 var RoutesStore = class {
   /**
    * A flag to know if routes for explicit domains
@@ -3411,7 +2899,7 @@ var RoutesStore = class {
     for (let token of tokens) {
       if ([1, 3].includes(token.type)) {
         if (collectedParams.has(token.val)) {
-          throw new RuntimeException4(`Duplicate param "${token.val}" found in "${route.pattern}"`);
+          throw new RuntimeException2(`Duplicate param "${token.val}" found in "${route.pattern}"`);
         } else {
           collectedParams.add(token.val);
         }
@@ -3427,7 +2915,7 @@ var RoutesStore = class {
   #registerRoute(domain, method, tokens, route) {
     const methodRoutes = this.#getMethodNode(domain, method);
     if (methodRoutes.routes[route.pattern]) {
-      throw new RuntimeException4(
+      throw new RuntimeException2(
         `Duplicate route found. "${method}: ${route.pattern}" route already exists`
       );
     }
@@ -3452,6 +2940,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") {
@@ -3472,144 +2962,44 @@ 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";
     const matchedDomain = this.tree.domains[domainName];
-    if (!matchedDomain) {
-      return null;
-    }
-    const matchedMethod = this.tree.domains[domainName][method];
-    if (!matchedMethod) {
-      return null;
-    }
-    const matchedRoute = matchit.match(url, matchedMethod.tokens);
-    if (!matchedRoute.length) {
-      return null;
-    }
-    const route = matchedMethod.routes[matchedRoute[0].old];
-    return {
-      route,
-      routeKey: matchedMethod.routeKeys[route.pattern],
-      params: matchit.exec(url, matchedRoute, shouldDecodeParam),
-      subdomains: domain?.hostname ? matchit.exec(domain.hostname, domain.tokens) : {}
-    };
-  }
-  /**
-   * Match hostname against registered domains.
-   */
-  matchDomain(hostname) {
-    if (!hostname || !this.usingDomains) {
-      return [];
-    }
-    return matchit.match(hostname, this.tree.tokens);
-  }
-};
-
-// src/client/router.ts
-var RouterClient = class {
-  /**
-   * List of route references kept for lookup.
-   */
-  routes;
-  /**
-   * The lookup strategies to follow when generating URL builder
-   * types and client
-   */
-  lookupStrategies = ["name", "pattern"];
-  constructor(routes) {
-    this.routes = routes ?? {};
-  }
-  /**
-   * Register route JSON payload
-   */
-  register(route) {
-    this.routes[route.domain] = this.routes[route.domain] || [];
-    this.routes[route.domain].push(route);
-  }
-  /**
-   * Define the lookup strategies to follow when generating URL builder
-   * types and client.
-   */
-  updateLookupStrategies(strategies) {
-    this.lookupStrategies = strategies;
-    return this;
-  }
-  /**
-   * Finds a route by its identifier. The identifier can be the
-   * route name, controller.method name or the route pattern
-   * itself.
-   *
-   * 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".
-   */
-  find(routeIdentifier, domain, method, followLookupStrategy) {
-    if (!domain) {
-      let route = null;
-      for (const routeDomain of Object.keys(this.routes)) {
-        route = this.find(routeIdentifier, routeDomain, method, followLookupStrategy);
-        if (route) {
-          break;
-        }
-      }
-      return route;
-    }
-    const routes = this.routes[domain];
-    if (!routes) {
-      return null;
-    }
-    const lookupByName = !followLookupStrategy || this.lookupStrategies.includes("name");
-    const lookupByPattern = !followLookupStrategy || this.lookupStrategies.includes("pattern");
-    const lookupByController = !followLookupStrategy || this.lookupStrategies.includes("controller");
-    return routes.find((route) => {
-      if (method && !route.methods.includes(method)) {
-        return false;
-      }
-      if (route.name === routeIdentifier && lookupByName || route.pattern === routeIdentifier && lookupByPattern) {
-        return true;
-      }
-      if (typeof route.handler === "function" || !lookupByController) {
-        return false;
-      }
-      return route.handler.reference === routeIdentifier;
-    }) || null;
-  }
-  /**
-   * Finds a route by its identifier. The identifier can be the
-   * route name, controller.method name or the route pattern
-   * itself.
-   *
-   * An error is raised when unable to find the route.
-   *
-   * 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".
-   */
-  findOrFail(routeIdentifier, domain, method, followLookupStrategy) {
-    const route = this.find(routeIdentifier, domain, method, followLookupStrategy);
-    if (!route) {
-      throw new Error(`Cannot lookup route "${routeIdentifier}"`);
-    }
-    return route;
-  }
-  /**
-   * Check if a route exists. The identifier can be the
-   * route name, controller.method name or the route pattern
-   * itself.
-   *
-   * 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".
-   */
-  has(routeIdentifier, domain, method, followLookupStrategy) {
-    return !!this.find(routeIdentifier, domain, method, followLookupStrategy);
+    if (!matchedDomain) {
+      return null;
+    }
+    const matchedMethod = this.tree.domains[domainName][method];
+    if (!matchedMethod) {
+      return null;
+    }
+    const matchedRoute = matchit.match(url, matchedMethod.tokens);
+    if (!matchedRoute.length) {
+      return null;
+    }
+    const route = matchedMethod.routes[matchedRoute[0].old];
+    return {
+      route,
+      routeKey: matchedMethod.routeKeys[route.pattern],
+      params: matchit.exec(url, matchedRoute, shouldDecodeParam),
+      subdomains: domain?.hostname ? matchit.exec(domain.hostname, domain.tokens) : {}
+    };
   }
   /**
-   * Returns a list of routes grouped by their domain names
+   * Match hostname against registered domains.
+   * @param hostname - The hostname to match
+   * @returns Array of matched domain tokens
    */
-  toJSON() {
-    return this.routes;
+  matchDomain(hostname) {
+    if (!hostname || !this.usingDomains) {
+      return [];
+    }
+    return matchit.match(hostname, this.tree.tokens);
   }
 };
 
@@ -3636,15 +3026,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;
@@ -3653,8 +3050,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;
@@ -3662,8 +3058,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) {
@@ -3674,8 +3069,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) {
@@ -3689,8 +3083,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, {
@@ -3705,8 +3100,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) {
@@ -3721,17 +3115,19 @@ var UrlBuilder = class {
 };
 
 // src/router/matchers.ts
-import Macroable7 from "@poppinss/macroable";
-var RouteMatchers = class extends Macroable7 {
+import Macroable3 from "@poppinss/macroable";
+var RouteMatchers = class extends Macroable3 {
   /**
    * 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 {
@@ -3741,6 +3137,7 @@ 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]$/ };
@@ -3748,9 +3145,9 @@ var RouteMatchers = class extends Macroable7 {
 };
 
 // src/define_middleware.ts
-import { moduleImporter as moduleImporter2 } from "@adonisjs/fold";
+import { moduleImporter } from "@adonisjs/fold";
 function middlewareReferenceBuilder(name, middleware) {
-  const handler = moduleImporter2(middleware, "handle").toHandleMethod();
+  const handler = moduleImporter(middleware, "handle").toHandleMethod();
   return function(...args) {
     return {
       ...handler,
@@ -3770,142 +3167,7 @@ function defineNamedMiddleware(collection) {
   );
 }
 
-// src/client/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/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) {
@@ -3928,56 +3190,91 @@ function createSignedUrlBuilder(router, encryption, searchParamsStringifier) {
     return createSignedUrlForRoute(identifier, params, options);
   };
   signedRoute.get = function routeGet(...[identifier, params, options]) {
+    const method = "GET";
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, "GET"),
-      method: "get",
+      url,
+      method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
   signedRoute.post = function routePost(...[identifier, params, options]) {
+    const method = "POST";
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, "POST"),
-      method: "post",
+      url,
+      method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
   signedRoute.put = function routePut(...[identifier, params, options]) {
+    const method = "PUT";
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, "PUT"),
-      method: "put",
+      url,
+      method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
   signedRoute.patch = function routePatch(...[identifier, params, options]) {
+    const method = "PATCH";
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, "PATCH"),
-      method: "patch",
+      url,
+      method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
   signedRoute.delete = function routeDelete(...[identifier, params, options]) {
+    const method = "DELETE";
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, "DELETE"),
-      method: "delete",
+      url,
+      method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
   signedRoute.method = function routeGet(method, ...[identifier, params, options]) {
+    const url = createSignedUrlForRoute(identifier, params, options, method);
     return {
-      url: createSignedUrlForRoute(identifier, params, options, method),
+      url,
       method,
       toString() {
-        return this.url;
+        return url;
+      },
+      form: {
+        action: url,
+        method
       }
     };
   };
@@ -3985,7 +3282,7 @@ function createSignedUrlBuilder(router, encryption, searchParamsStringifier) {
 }
 
 // src/router/main.ts
-var Router = class extends RouterClient {
+var Router = class {
   /**
    * Flag to avoid re-comitting routes to the store
    */
@@ -4049,16 +3346,32 @@ var Router = class extends RouterClient {
    * methods.
    */
   urlBuilder;
+  /**
+   * 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) {
-    super();
     this.#app = app;
     this.#encryption = encryption;
     this.qs = qsParser;
     this.urlBuilder = {
-      urlFor: createUrlBuilder(this, this.qs.stringify),
+      urlFor: createUrlBuilder(() => this.toJSON(), this.qs.stringify),
       signedUrlFor: createSignedUrlBuilder(this, this.#encryption, this.qs.stringify)
     };
   }
+  /**
+   * Register route JSON payload
+   */
+  register(route) {
+    this.routes[route.domain] = this.routes[route.domain] || [];
+    this.routes[route.domain].push(route);
+  }
   /**
    * Push a give router entity to the list of routes or the
    * recently opened group.
@@ -4073,6 +3386,8 @@ var Router = class extends RouterClient {
   }
   /**
    * Parses the route pattern
+   * @param pattern - The route pattern to parse
+   * @param matchers - Optional route matchers
    */
   parsePattern(pattern, matchers) {
     return parseRoute(pattern, matchers);
@@ -4081,12 +3396,14 @@ var Router = class extends RouterClient {
    * 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(
       (one) => this.#middleware.push({
         reference: one,
-        ...moduleImporter3(one, "handle").toHandleMethod()
+        ...moduleImporter2(one, "handle").toHandleMethod()
       })
     );
     return this;
@@ -4095,12 +3412,18 @@ var Router = class extends RouterClient {
    * 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, {
@@ -4114,6 +3437,9 @@ var Router = class extends RouterClient {
   }
   /**
    * 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(
@@ -4124,30 +3450,45 @@ var Router = class extends RouterClient {
   }
   /**
    * 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);
@@ -4155,6 +3496,8 @@ var Router = class extends RouterClient {
   /**
    * 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([]);
@@ -4166,6 +3509,9 @@ var Router = class extends RouterClient {
   }
   /**
    * 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, {
@@ -4179,6 +3525,9 @@ var Router = class extends RouterClient {
   }
   /**
    * 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, {
@@ -4192,6 +3541,8 @@ var Router = class extends RouterClient {
   }
   /**
    * 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, {
@@ -4204,11 +3555,14 @@ var Router = class extends RouterClient {
   /**
    * 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") {
       this.#globalMatchers[param] = { match: new RegExp(matcher) };
-    } else if (is3.regExp(matcher)) {
+    } else if (is2.regExp(matcher)) {
       this.#globalMatchers[param] = { match: matcher };
     } else {
       this.#globalMatchers[param] = matcher;
@@ -4231,8 +3585,8 @@ var Router = class extends RouterClient {
       }
       const routeNames = routeNamesByDomain.get(route.domain);
       if (route.name && routeNames.has(route.name)) {
-        throw new RuntimeException5(
-          `Route with duplicate name found. A route with name "${route.name}" already exists`
+        throw new RuntimeException3(
+          `A route with name "${route.name}" already exists. It may happen when two routes use the same controller, so make sure to give explicit names to these routes`
         );
       }
       if (route.name) {
@@ -4249,10 +3603,75 @@ var Router = class extends RouterClient {
     this.#openedGroups = [];
     this.#commited = true;
   }
+  /**
+   * Finds a route by its identifier. The identifier can be the
+   * route name, controller.method name or the route pattern
+   * itself.
+   *
+   * 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) {
+    return findRoute(this.routes, routeIdentifier, domain, method, disableLegacyLookup);
+  }
+  /**
+   * Finds a route by its identifier. The identifier can be the
+   * route name, controller.method name or the route pattern
+   * itself.
+   *
+   * An error is raised when unable to find the route.
+   *
+   * 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);
+    if (!route) {
+      throw new Error(`Cannot lookup route "${routeIdentifier}"`);
+    }
+    return route;
+  }
+  /**
+   * Check if a route exists. The identifier can be the
+   * route name, controller.method name or the route pattern
+   * itself.
+   *
+   * 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;
+  }
   /**
    * 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 = {};
@@ -4279,21 +3698,11 @@ var Router = class extends RouterClient {
         routesList["ALL"] = routesList["ALL"] ?? {};
         routesList[method] = routesList[method] ?? {};
         const identifiers = [];
-        if (this.lookupStrategies.includes("pattern")) {
-          if (!routesList[method][route.pattern]) {
-            identifiers.push(route.pattern);
-          }
-        }
-        if (this.lookupStrategies.includes("name") && route.name) {
+        if (route.name) {
           identifiers.push(
             domain && routesList[method][route.name] ? `${domain}@${route.name}` : route.name
           );
         }
-        if (this.lookupStrategies.includes("controller") && "reference" in route.handler && typeof route.handler.reference === "string") {
-          identifiers.push(
-            domain && routesList[method][route.handler.reference] ? `${domain}@${route.handler.reference}` : route.handler.reference
-          );
-        }
         identifiers.forEach((identifier) => {
           routesList["ALL"][identifier] = {
             params,
@@ -4309,12 +3718,12 @@ var Router = class extends RouterClient {
       });
     }
     const domains = Object.keys(this.routes).filter((domain) => domain !== "root");
-    this.routes["root"].forEach((route) => trackRoute.bind(this)(route));
+    this.routes["root"]?.forEach((route) => trackRoute.bind(this)(route));
     domains.forEach(
       (domain) => this.routes[domain].forEach((route) => trackRoute.bind(this)(route, domain))
     );
     return Object.keys(routesList).reduce((result, method) => {
-      result.push(`${" ".repeat(indentation)}'${method}': {`);
+      result.push(`${" ".repeat(indentation)}${method}: {`);
       Object.keys(routesList[method]).forEach((identifier) => {
         const key = `'${identifier}'`;
         const { paramsTuple, hasRequiredParams, params } = routesList[method][identifier];
@@ -4322,47 +3731,20 @@ var Router = class extends RouterClient {
         const tupleName = hasRequiredParams ? "paramsTuple" : "paramsTuple?";
         const dictValue = `{${params.join(",")}}`;
         const tupleValue = `[${paramsTuple?.join(",")}]`;
-        const value = `{ ${tupleName}: ${tupleValue}, ${dictName}: ${dictValue} }`;
-        result.push(`${" ".repeat(indentation + 2)}${key}: ${value},`);
+        const value = `{ ${tupleName}: ${tupleValue}; ${dictName}: ${dictValue} }`;
+        result.push(`${" ".repeat(indentation + 2)}${key}: ${value}`);
       });
-      result.push(`${" ".repeat(indentation)}},`);
+      result.push(`${" ".repeat(indentation)}}`);
       return result;
     }, []).join("\n");
   }
-  generateClient() {
-    const routesForClient = Object.keys(this.routes).reduce(
-      (result, domain) => {
-        const routes = this.routes[domain];
-        result[domain] = routes.map((route) => {
-          const controller = "reference" in route.handler && typeof route.handler.reference === "string" ? route.handler.reference : void 0;
-          return {
-            pattern: route.pattern,
-            name: route.name,
-            handler: {
-              reference: controller
-            },
-            methods: route.methods,
-            domain: route.domain,
-            tokens: route.tokens.map((tokens) => {
-              return lodash2.pick(tokens, ["val", "type", "end"]);
-            })
-          };
-        });
-        return result;
-      },
-      {}
-    );
-    return `import type { RoutesList } from '@adonisjs/core/types/http'
-import { RouterClient, createUrlBuilder, ClientRouteJSON } from 'adonisjs/core/http/client'
-
-const routes = ${JSON.stringify(routesForClient)} satisfies { [domain: string]: ClientRouteJSON[] }
-const router = new RouterClient(routes)
-export const urlFor = createUrlBuilder<RoutesList>(router, (qs) => {
-  return new URLSearchParams(qs).toString()
-})`;
-  }
   /**
    * 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);
@@ -4373,9 +3755,7 @@ export const urlFor = createUrlBuilder<RoutesList>(router, (qs) => {
   }
   /**
    * 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);
@@ -4441,33 +3821,19 @@ export const urlFor = createUrlBuilder<RoutesList>(router, (qs) => {
 
 // src/http_context/main.ts
 import { inspect } from "util";
-import Macroable8 from "@poppinss/macroable";
-import { RuntimeException as RuntimeException6 } from "@poppinss/utils/exception";
+import Macroable4 from "@poppinss/macroable";
+import { RuntimeException as RuntimeException4 } 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;
@@ -4475,7 +3841,15 @@ var asyncLocalStorage = {
 };
 
 // src/http_context/main.ts
-var HttpContext = class extends Macroable8 {
+var HttpContext = class extends Macroable4 {
+  /**
+   * 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;
@@ -4486,15 +3860,27 @@ var HttpContext = class extends Macroable8 {
     this.response.ctx = this;
   }
   /**
-   * Find if async localstorage is enabled for HTTP requests
-   * or not
+   * Indicates whether async local storage is enabled for HTTP requests.
+   *
+   * When enabled, the HTTP context is automatically available within the
+   * scope of request processing through static methods like get() and getOrFail().
    */
   static get usingAsyncLocalStorage() {
     return asyncLocalStorage.isEnabled;
   }
   /**
-   * Get access to the HTTP context. Available only when
-   * "usingAsyncLocalStorage" is true
+   * Get access to the current HTTP context from async local storage.
+   *
+   * This method is only available when async local storage is enabled.
+   * Returns null if called outside of an HTTP request context.
+   *
+   * @example
+   * ```ts
+   * const ctx = HttpContext.get()
+   * if (ctx) {
+   *   console.log(ctx.request.url())
+   * }
+   * ```
    */
   static get() {
     if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
@@ -4503,24 +3889,48 @@ var HttpContext = class extends Macroable8 {
     return asyncLocalStorage.storage.getStore() || null;
   }
   /**
-   * Get the HttpContext instance or raise an exception if not
-   * available
+   * Get the HttpContext instance or raise an exception if not available.
+   *
+   * This method is useful when you need guaranteed access to the HTTP context
+   * and want to fail fast if it's not available.
+   *
+   * @throws RuntimeException when async local storage is disabled or context is unavailable
+   *
+   * @example
+   * ```ts
+   * const ctx = HttpContext.getOrFail()
+   * const userId = ctx.request.input('user_id')
+   * ```
    */
   static getOrFail() {
     if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
-      throw new RuntimeException6(
+      throw new RuntimeException4(
         'HTTP context is not available. Enable "useAsyncLocalStorage" inside "config/app.ts" file'
       );
     }
     const store = this.get();
     if (!store) {
-      throw new RuntimeException6("Http context is not available outside of an HTTP request");
+      throw new RuntimeException4("Http context is not available outside of an HTTP request");
     }
     return store;
   }
   /**
-   * Run a method that doesn't have access to HTTP context from
-   * the async local storage.
+   * Run a method outside of the HTTP context scope.
+   *
+   * This method allows you to execute code that should not have access to
+   * the current HTTP context from async local storage. Useful for background
+   * tasks or operations that should be context-independent.
+   *
+   * @param callback - Function to execute outside the context
+   * @param args - Arguments to pass to the callback
+   *
+   * @example
+   * ```ts
+   * HttpContext.runOutsideContext(() => {
+   *   // This code cannot access HttpContext.get()
+   *   performBackgroundTask()
+   * })
+   * ```
    */
   static runOutsideContext(callback, ...args) {
     if (!asyncLocalStorage.storage) {
@@ -4556,23 +3966,8 @@ var HttpContext = class extends Macroable8 {
 
 // src/server/main.ts
 import onFinished2 from "on-finished";
-import Middleware2 from "@poppinss/middleware";
-import { moduleCaller as moduleCaller2, moduleImporter as moduleImporter4 } from "@adonisjs/fold";
-
-// src/qs.ts
-import { parse as parse2, stringify } from "qs";
-var Qs = class {
-  #config;
-  constructor(config) {
-    this.#config = config;
-  }
-  parse = (value) => {
-    return parse2(value, this.#config.parse);
-  };
-  stringify = (value) => {
-    return stringify(value, this.#config.stringify);
-  };
-};
+import Middleware from "@poppinss/middleware";
+import { moduleCaller, moduleImporter as moduleImporter3 } from "@adonisjs/fold";
 
 // src/server/factories/route_finder.ts
 function routeFinder(router, resolver, ctx, errorResponder) {
@@ -4611,7 +4006,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,
@@ -4622,9 +4017,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() {
@@ -4634,86 +4032,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;
@@ -4726,7 +4126,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) {
@@ -4737,16 +4137,20 @@ 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();
+    this.#serverMiddlewareStack = new Middleware();
     this.#middleware.forEach((middleware) => this.#serverMiddlewareStack.add(middleware));
     this.#serverMiddlewareStack.freeze();
     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) => {
@@ -4755,14 +4159,17 @@ 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();
+    const middlewareStack = new Middleware();
     middleware.forEach((one) => {
       middlewareStack.add({
         reference: one,
-        ...moduleCaller2(one, "handle").toHandleMethod()
+        ...moduleCaller(one, "handle").toHandleMethod()
       });
     });
     middlewareStack.freeze();
@@ -4784,32 +4191,37 @@ 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(
       (one) => this.#middleware.push({
         reference: one,
-        ...moduleImporter4(one, "handle").toHandleMethod()
+        ...moduleImporter3(one, "handle").toHandleMethod()
       })
     );
     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) {
@@ -4828,7 +4240,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;
@@ -4838,33 +4252,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(
@@ -4875,13 +4304,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");
@@ -4903,17 +4338,29 @@ 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
+    );
   }
 };
 
 // src/define_config.ts
 import proxyAddr from "proxy-addr";
-import string2 from "@poppinss/utils/string";
-import lodash3 from "@poppinss/utils/lodash";
+import string from "@poppinss/utils/string";
+import lodash2 from "@poppinss/utils/lodash";
 function defineConfig(config) {
   const { trustProxy: trustProxy2, ...rest } = config;
   const defaults = {
@@ -4950,9 +4397,9 @@ function defineConfig(config) {
       }
     }
   };
-  const normalizedConfig = lodash3.merge({}, defaults, rest);
+  const normalizedConfig = lodash2.merge({}, defaults, rest);
   if (normalizedConfig.cookie.maxAge) {
-    normalizedConfig.cookie.maxAge = string2.seconds.parse(normalizedConfig.cookie.maxAge);
+    normalizedConfig.cookie.maxAge = string.seconds.parse(normalizedConfig.cookie.maxAge);
   }
   if (typeof trustProxy2 === "boolean") {
     const tpValue = trustProxy2;
@@ -4967,24 +4414,19 @@ function defineConfig(config) {
 }
 
 export {
+  Qs,
   E_ROUTE_NOT_FOUND,
   E_CANNOT_LOOKUP_ROUTE,
   E_HTTP_EXCEPTION,
   E_HTTP_REQUEST_ABORTED,
   errors_exports,
   CookieClient,
-  canWriteResponseBody,
-  tracing_channels_exports,
-  Route,
-  BriskRoute,
-  RouteResource,
-  RouteGroup,
-  parseRange,
+  CookieParser,
   Request,
   Redirect,
   ResponseStatus,
+  CookieSerializer,
   Response,
-  Qs,
   Router,
   HttpContext,
   Server,