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

package/build/src/types/server.d.ts

@@ -5,63 +5,78 @@ import type { RequestConfig } from './request.ts';
 import type { ResponseConfig } from './response.ts';
 import type { HttpContext } from '../http_context/main.ts';
 /**
- * Normalized HTTP error used by the exception
- * handler.
+ * Normalized HTTP error structure used by exception handlers
  */
 export type HttpError = {
+    /** Error message describing the issue */
     message: string;
+    /** HTTP status code */
     status: number;
+    /** Optional error code identifier */
     code?: string;
+    /** Optional stack trace */
     stack?: string;
+    /** Optional underlying cause of the error */
     cause?: any;
+    /** Optional additional error messages */
     messages?: any;
+    /** Optional validation or field errors */
     errors?: any;
+    /** Optional custom error handler method */
     handle?: (...args: any[]) => any;
+    /** Optional error reporting method */
     report?: (...args: any[]) => any;
 };
 /**
- * The pipeline for executing middleware during tests
+ * Pipeline interface for executing middleware chains during testing
  */
 export interface TestingMiddlewarePipeline {
+    /** Set the final handler for the pipeline */
     finalHandler(handler: FinalHandler): this;
+    /** Set the error handler for the pipeline */
     errorHandler(handler: ErrorHandler): this;
+    /** Execute the middleware pipeline with the given context */
     run(ctx: HttpContext): Promise<any>;
 }
 /**
- * The expression to define a status page range
+ * Expression format for defining HTTP status code ranges for error pages
  */
 export type StatusPageRange = `${number}..${number}` | `${number}` | number;
 /**
- * The callback function to render status page for a given
- * error.
+ * Callback function to render custom status pages for HTTP errors
  */
 export type StatusPageRenderer = (error: HttpError, ctx: HttpContext) => any | Promise<any>;
 /**
- * Data type for the "http:request_completed" event
+ * Payload structure for the http:request_completed event
  */
 export type HttpRequestFinishedPayload = {
+    /** HTTP context for the completed request */
     ctx: HttpContext;
+    /** Request duration as a high-resolution time tuple */
     duration: [number, number];
 };
 /**
- * Events emitted by the HttpServer
+ * Event types and payloads emitted by the HTTP server
  */
 export type HttpServerEvents = {
+    /** Event fired when an HTTP request is completed */
     'http:request_completed': HttpRequestFinishedPayload;
 };
 /**
- * Error handler to handle HTTP errors
+ * Interface for handling and reporting HTTP errors in the server
  */
 export type ServerErrorHandler = {
+    /** Method to report errors for logging or monitoring */
     report: (error: any, ctx: HttpContext) => any;
+    /** Method to handle errors and send appropriate responses */
     handle: (error: any, ctx: HttpContext) => any;
 };
 /**
- * Error handler represented as a class
+ * Constructor type for error handler classes that implement ServerErrorHandler
  */
 export type ErrorHandlerAsAClass = Constructor<ServerErrorHandler>;
 /**
- * Config accepted by the HTTP server
+ * Complete configuration options for the HTTP server extending request and response configs
  */
 export type ServerConfig = RequestConfig & ResponseConfig & {
     /**

package/build/src/types/tracing_channels.d.ts

@@ -1,6 +1,24 @@
 import type { RouteJSON } from './route.ts';
 import type { HttpContext } from '../http_context/main.ts';
 import type { MiddlewareFn, ParsedGlobalMiddleware, ParsedNamedMiddleware } from './middleware.ts';
-export type HTTPRequestTracingData = HttpContext;
-export type MiddlewareTracingData = ParsedGlobalMiddleware | ParsedNamedMiddleware | MiddlewareFn;
-export type RouteHandlerTracingData = RouteJSON;
+/**
+ * Tracing data structure for HTTP request events
+ */
+export type HTTPRequestTracingData = {
+    /** HTTP context for the traced request */
+    ctx: HttpContext;
+};
+/**
+ * Tracing data structure for middleware execution events
+ */
+export type MiddlewareTracingData = {
+    /** The middleware being traced */
+    middleware: ParsedGlobalMiddleware | ParsedNamedMiddleware | MiddlewareFn;
+};
+/**
+ * Tracing data structure for route handler execution events
+ */
+export type RouteHandlerTracingData = {
+    /** The route being traced */
+    route: RouteJSON;
+};

package/build/src/types/url_builder.d.ts

@@ -1,147 +1,22 @@
+import { type UrlFor, type LookupList, type URLOptions, type LookupListRoute, type RouteBuilderArguments } from '../client/types.ts';
+export { URLOptions, LookupListRoute, RouteBuilderArguments, LookupList, UrlFor };
 /**
- * Types shared with the client. These should never import other types
- */
-import { type Prettify } from '@poppinss/utils/types';
-/**
- * Options accepted by "urlFor" helper
- */
-export type URLOptions = {
-    qs?: Record<string, any>;
-    prefixUrl?: string;
-};
-/**
- * Options accepted by "signedUrlFor" helper
+ * Configuration options for signed URL generation helpers
  */
 export type SignedURLOptions = URLOptions & {
+    /** Expiration time for the signed URL */
     expiresIn?: string | number;
+    /** Purpose identifier for the signed URL */
     purpose?: string;
 };
 /**
- * Returns params for a route identifier
- */
-export type RouteBuilderArguments<Routes, Method extends keyof Routes, Identifier extends keyof Routes[Method], Options extends any = URLOptions> = Routes extends LookupList ? Prettify<undefined extends Routes[Method][Identifier]['params'] ? [identifier: Identifier, params?: undefined, options?: Options] : [undefined] extends [Routes[Method][Identifier]['params']] ? [
-    identifier: Identifier,
-    params?: Routes[Method][Identifier]['params'] | Routes[Method][Identifier]['paramsTuple'],
-    options?: Options
-] : [
-    identifier: Identifier,
-    params: Routes[Method][Identifier]['params'] | Routes[Method][Identifier]['paramsTuple'],
-    options?: Options
-]> : never;
-/**
- * LookupList type is used by the URLBuilder to provide
- * type-safety when creating URLs.
- *
- * There is no runtime property that matches this type. Its
- * purely for type-inference.
- */
-export type LookupList = {
-    [method: string]: {
-        [identifier: string]: {
-            paramsTuple?: [...any[]];
-            params?: {
-                [name: string]: any;
-            };
-        };
-    };
-};
-/**
- * The urlFor helper is used to make URLs for pre-existing known routes. You can
- * make a URL using the route name, route pattern, or the route controller
- * reference (depends upon enabled lookupStrategies)
- *
- * ```ts
- * urlFor('users.show', [1]) // /users/1
- *
- * // Lookup inside a specific domain
- * urlFor('blog.adonisjs.com@posts.show', [1]) // /posts/1
- * ```
+ * Utility type to extract routes for a specific HTTP method from the routes collection
  */
-export type UrlFor<Routes extends LookupList, Options extends any = URLOptions> = (<Identifier extends keyof Routes['ALL'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'ALL', Identifier, Options>) => string) & {
-    /**
-     * Make URL for a GET route. An error will be raised if the route doesn't
-     * exist.
-     *
-     * ```ts
-     * urlFor.get('users.show', [1]) // { method: 'get', url: '/users/1' }
-     * urlFor.get('users.store', [1]) // Error: Route not found GET@users/store
-     * ```
-     */
-    get<RouteIdentifier extends keyof Routes['GET'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'GET', RouteIdentifier, Options>): {
-        method: 'get';
-        url: string;
-    };
-    /**
-     * Make URL for a POST route. An error will be raised if the route doesn't
-     * exist.
-     *
-     * ```ts
-     * urlFor.post('users.store') // { method: 'post', url: '/users' }
-     * urlFor.post('users.show', [1]) // Error: Route not found POST@users.show
-     * ```
-     */
-    post<RouteIdentifier extends keyof Routes['POST'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'POST', RouteIdentifier, Options>): {
-        method: 'post';
-        url: string;
-    };
-    /**
-     * Make URL for a PUT route. An error will be raised if the route doesn't
-     * exist.
-     *
-     * ```ts
-     * urlFor.put('users.update', [1]) // { method: 'put', url: '/users/1' }
-     * urlFor.put('users.show', [1]) // Error: Route not found PUT@users.show
-     * ```
-     */
-    put<RouteIdentifier extends keyof Routes['PUT'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'PUT', RouteIdentifier, Options>): {
-        method: 'put';
-        url: string;
-    };
-    /**
-     * Make URL for a PATCH route. An error will be raised if the route doesn't
-     * exist.
-     *
-     * ```ts
-     * urlFor.put('users.update', [1]) // { method: 'patch', url: '/users/1' }
-     * urlFor.put('users.show', [1]) // Error: Route not found PATCH@users.show
-     * ```
-     */
-    patch<RouteIdentifier extends keyof Routes['PATCH'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'PATCH', RouteIdentifier, Options>): {
-        method: 'patch';
-        url: string;
-    };
-    /**
-     * Make URL for a DELETE route. An error will be raised if the route doesn't
-     * exist.
-     *
-     * ```ts
-     * urlFor.delete('users.destroy', [1]) // { method: 'delete', url: '/users/1' }
-     * urlFor.delete('users.show', [1]) // Error: Route not found DELETE@users.show
-     * ```
-     */
-    delete<RouteIdentifier extends keyof Routes['DELETE'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'DELETE', RouteIdentifier, Options>): {
-        method: 'delete';
-        url: string;
-    };
-    /**
-     * Make URL for a custom route method. An error will be raised if the route doesn't
-     * exist for the same method.
-     */
-    method<Method extends keyof Routes & string, RouteIdentifier extends keyof Routes[Method] & string>(method: Method, ...[identifier, params, options]: RouteBuilderArguments<Routes, Method, RouteIdentifier, Options>): {
-        method: Method;
-        url: string;
-    };
-};
+export type GetRoutesForMethod<Routes, Method> = {
+    [K in keyof Routes]: Method extends K ? Routes[Method] : never;
+}[keyof Routes];
 /**
- * To be generated by the router and used by the URL builder
- * and the LookupStore
+ * Interface to be augmented by the router containing all registered routes for type-safe URL generation
  */
 export interface RoutesList {
 }
-/**
- * Helper to get routes for a given method from the RoutesList. The
- * RoutesList is extended in the userland code.
- */
-export type GetRoutesForMethod<Method> = {
-    [K in keyof RoutesList]: Method extends K ? RoutesList[Method] : never;
-};

package/build/src/utils.d.ts

@@ -4,23 +4,88 @@ import { BriskRoute } from './router/brisk.ts';
 import type { RouteJSON } from './types/route.ts';
 import { RouteResource } from './router/resource.ts';
 /**
- * Makes input string consistent by having only the starting
- * slash
+ * Makes input string consistent by having only the starting slash.
+ *
+ * Removes trailing slashes and ensures the path starts with a forward slash,
+ * except for the root path '/' which remains unchanged.
+ *
+ * @param input - The input path string to normalize
+ *
+ * @example
+ * ```ts
+ * dropSlash('/users/') // '/users'
+ * dropSlash('users') // '/users'
+ * dropSlash('/') // '/'
+ * ```
  */
 export declare function dropSlash(input: string): string;
 /**
- * Returns a flat list of routes from the route groups and resources
+ * Returns a flat list of routes from route groups, resources, and brisk routes.
+ *
+ * This function recursively processes route collections, extracting individual routes
+ * from groups and resources while filtering out any deleted routes.
+ *
+ * @param routes - Array containing route groups, individual routes, resources, and brisk routes
+ *
+ * @example
+ * ```ts
+ * const flatRoutes = toRoutesJSON([
+ *   routeGroup,
+ *   singleRoute,
+ *   resourceRoutes
+ * ])
+ * ```
  */
 export declare function toRoutesJSON(routes: (RouteGroup | Route | RouteResource | BriskRoute)[]): RouteJSON[];
 /**
- * Helper to know if the remote address should
- * be trusted.
+ * Helper to determine if a remote address should be trusted.
+ *
+ * Uses caching to avoid repeated expensive proxy function calls for the same
+ * remote address. The cache improves performance when the same addresses are
+ * checked multiple times.
+ *
+ * @param remoteAddress - The remote IP address to check
+ * @param proxyFn - Function that determines if an address should be trusted
+ *
+ * @example
+ * ```ts
+ * const isTrusted = trustProxy('192.168.1.1', proxyAddr.compile('loopback'))
+ * ```
  */
 export declare function trustProxy(remoteAddress: string, proxyFn: (addr: string, distance: number) => boolean): boolean;
 /**
- * Parses a range expression to an object filled with the range
+ * Parses a range expression (e.g., '200..299') into an object with numeric keys.
+ *
+ * Supports both single values and ranges. For ranges, all numbers between
+ * the start and end (inclusive) are mapped to the provided value.
+ *
+ * @param range - Range expression as a string (e.g., '200', '200..299')
+ * @param value - Value to assign to each number in the range
+ *
+ * @example
+ * ```ts
+ * parseRange('200', 'success') // { 200: 'success' }
+ * parseRange('200..202', 'success') // { 200: 'success', 201: 'success', 202: 'success' }
+ * ```
  */
 export declare function parseRange<T>(range: string, value: T): Record<number, T>;
+/**
+ * Safely decodes a URI path while handling special characters and query strings.
+ *
+ * This function carefully parses and decodes URI components, handling edge cases
+ * like double-encoded characters and non-standard query string delimiters.
+ * It separates the pathname from query parameters and determines whether
+ * route parameters should be decoded.
+ *
+ * @param path - The URI path to decode
+ * @param useSemicolonDelimiter - Whether to treat semicolons as query string delimiters
+ *
+ * @example
+ * ```ts
+ * const result = safeDecodeURI('/users/123?name=john', false)
+ * // Returns: { pathname: '/users/123', query: 'name=john', shouldDecodeParam: false }
+ * ```
+ */
 export declare function safeDecodeURI(path: string, useSemicolonDelimiter: boolean): {
     pathname: string;
     query: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/http-server",
-  "version": "8.0.0-next.1",
+  "version": "8.0.0-next.10",
   "description": "AdonisJS HTTP server with support packed with Routing and Cookies",
   "main": "build/index.js",
   "type": "module",
@@ -13,6 +13,7 @@
     ".": "./build/index.js",
     "./helpers": "./build/src/helpers.js",
     "./types": "./build/src/types/main.js",
+    "./client/url_builder": "./build/src/client/url_builder.js",
     "./factories": "./build/factories/main.js"
   },
   "engines": {
@@ -32,7 +33,8 @@
     "format": "prettier --write .",
     "prepublishOnly": "npm run build",
     "lint": "eslint",
-    "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts"
+    "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "docs": "typedoc"
   },
   "keywords": [
     "http",
@@ -41,12 +43,12 @@
   "author": "virk,adonisjs",
   "license": "MIT",
   "devDependencies": {
-    "@adonisjs/application": "^9.0.0-next.2",
-    "@adonisjs/encryption": "^7.0.0-next.0",
-    "@adonisjs/eslint-config": "^3.0.0-next.0",
-    "@adonisjs/events": "^10.1.0-next.1",
-    "@adonisjs/fold": "^11.0.0-next.0",
-    "@adonisjs/logger": "^7.0.0-next.1",
+    "@adonisjs/application": "^9.0.0-next.4",
+    "@adonisjs/encryption": "^7.0.0-next.1",
+    "@adonisjs/eslint-config": "^3.0.0-next.1",
+    "@adonisjs/events": "^10.1.0-next.2",
+    "@adonisjs/fold": "^11.0.0-next.2",
+    "@adonisjs/logger": "^7.1.0-next.0",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/tsconfig": "^2.0.0-next.0",
     "@fastify/middie": "^9.0.3",
@@ -65,7 +67,7 @@
     "@types/fresh": "^0.5.3",
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^24.2.1",
+    "@types/node": "^24.7.0",
     "@types/on-finished": "^2.3.5",
     "@types/pem": "^1.14.4",
     "@types/proxy-addr": "^2.0.3",
@@ -76,27 +78,28 @@
     "@vinejs/vine": "^3.0.1",
     "autocannon": "^8.0.0",
     "c8": "^10.1.3",
-    "cross-env": "^10.0.0",
-    "eslint": "^9.33.0",
-    "fastify": "^5.5.0",
-    "fs-extra": "^11.3.1",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.37.0",
+    "fastify": "^5.6.1",
+    "fs-extra": "^11.3.2",
     "get-port": "^7.1.0",
     "http-status-codes": "^2.3.0",
     "pem": "^1.14.8",
     "prettier": "^3.6.2",
     "reflect-metadata": "^0.2.2",
-    "release-it": "^19.0.4",
+    "release-it": "^19.0.5",
     "supertest": "^7.1.4",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
+    "typedoc": "^0.28.13",
+    "typescript": "^5.9.3",
     "youch": "^4.1.0-beta.11"
   },
   "dependencies": {
-    "@poppinss/macroable": "^1.0.5",
+    "@poppinss/macroable": "^1.1.0",
     "@poppinss/matchit": "^3.2.0",
     "@poppinss/middleware": "^3.2.6",
     "@poppinss/utils": "^7.0.0-next.3",
-    "@sindresorhus/is": "^7.0.2",
+    "@sindresorhus/is": "^7.1.0",
     "accepts": "^1.3.8",
     "content-disposition": "^0.5.4",
     "cookie": "^1.0.2",
@@ -113,11 +116,11 @@
     "vary": "^1.1.2"
   },
   "peerDependencies": {
-    "@adonisjs/application": "^9.0.0-next.2",
-    "@adonisjs/encryption": "^7.0.0-next.0",
-    "@adonisjs/events": "^10.1.0-next.1",
-    "@adonisjs/fold": "^11.0.0-next.0",
-    "@adonisjs/logger": "^7.0.0-next.1",
+    "@adonisjs/application": "^9.0.0-next.4",
+    "@adonisjs/encryption": "^7.0.0-next.1",
+    "@adonisjs/events": "^10.1.0-next.2",
+    "@adonisjs/fold": "^11.0.0-next.2",
+    "@adonisjs/logger": "^7.1.0-next.0",
     "youch": "^4.1.0-beta.11"
   },
   "peerDependenciesMeta": {
@@ -179,6 +182,7 @@
       "./index.ts",
       "./src/helpers.ts",
       "./src/types/main.ts",
+      "./src/client/url_builder.ts",
       "./factories/main.ts"
     ],
     "outDir": "./build",

package/build/chunk-ASX56VAK.js

@@ -1,76 +0,0 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/helpers.ts
-import cookie from "cookie";
-import matchit from "@poppinss/matchit";
-import string from "@poppinss/utils/string";
-import { parseBindingReference } from "@adonisjs/fold";
-import { default as default2 } from "encodeurl";
-import { default as default3 } from "mime-types";
-function parseRoute(pattern, matchers) {
-  const tokens = matchit.parse(pattern, matchers);
-  return tokens;
-}
-function matchRoute(url, patterns) {
-  const tokensBucket = patterns.map((pattern) => parseRoute(pattern));
-  const match = matchit.match(url, tokensBucket);
-  if (!match.length) {
-    return null;
-  }
-  return matchit.exec(url, match);
-}
-function serializeCookie(key, value, options) {
-  let expires;
-  let maxAge;
-  if (options) {
-    expires = typeof options.expires === "function" ? options.expires() : options.expires;
-    maxAge = options.maxAge ? string.seconds.parse(options.maxAge) : void 0;
-  }
-  return cookie.serialize(key, value, { ...options, maxAge, expires });
-}
-async function middlewareInfo(middleware) {
-  if (typeof middleware === "function") {
-    return {
-      type: "closure",
-      name: middleware.name || "closure"
-    };
-  }
-  if ("args" in middleware) {
-    return {
-      type: "named",
-      name: middleware.name,
-      args: middleware.args,
-      ...await parseBindingReference([middleware.reference])
-    };
-  }
-  return {
-    type: "global",
-    name: middleware.name,
-    ...await parseBindingReference([middleware.reference])
-  };
-}
-async function routeInfo(route) {
-  return "reference" in route.handler ? {
-    type: "controller",
-    ...await parseBindingReference(route.handler.reference)
-  } : {
-    type: "closure",
-    name: route.handler.name || "closure",
-    args: "listArgs" in route.handler ? String(route.handler.listArgs) : void 0
-  };
-}
-
-export {
-  __export,
-  parseRoute,
-  matchRoute,
-  serializeCookie,
-  middlewareInfo,
-  routeInfo,
-  default2 as default,
-  default3 as default2
-};

package/build/src/router/url_builder.d.ts

@@ -1,14 +0,0 @@
-import { type Router } from './main.ts';
-import { type MatchItRouteToken } from '../types/route.ts';
-import { type UrlFor, type LookupList, type URLOptions } from '../types/url_builder.ts';
-/**
- * Makes URL for a given route pattern. The route pattern could be an
- * identifier or an array of tokens.
- */
-export declare function createURL(identifier: string, tokens: Pick<MatchItRouteToken, 'val' | 'type' | 'end'>[], searchParamsStringifier: (qs: Record<string, any>) => string, params?: any[] | {
-    [param: string]: any;
-}, options?: URLOptions): string;
-/**
- * Creates the URLBuilder helper
- */
-export declare function createUrlBuilder<Routes extends LookupList>(router: Router, searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes>;