@adonisjs/http-server 8.0.0-next.8 → 8.0.0

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

@@ -0,0 +1,194 @@
+/**
+ * Types shared with the client. These should never import other types
+ */
+export type ClientRouteMatchItTokens = {
+    /** Original token string */
+    old: string;
+    /** Token type identifier (0=static, 1=param, 2=wildcard, 3=optional) */
+    type: 0 | 1 | 2 | 3;
+    /** Token value */
+    val: string;
+    /** Token end delimiter */
+    end: string;
+};
+/**
+ * Complete route definition with all metadata, handlers, and execution context
+ */
+export type ClientRouteJSON = {
+    /**
+     * A unique name for the route
+     */
+    name?: string;
+    /**
+     * Route URI pattern
+     */
+    pattern: string;
+    /**
+     * Route handler
+     */
+    handler?: unknown;
+    /**
+     * Tokens to be used to construct the route URL
+     */
+    tokens: ClientRouteMatchItTokens[];
+    /**
+     * HTTP methods, the route responds to.
+     */
+    methods: string[];
+    /**
+     * The domain for which the route is registered.
+     */
+    domain: string;
+};
+/**
+ * Configuration options for URL generation helpers
+ */
+export type URLOptions = {
+    /** Query string parameters to append to the URL */
+    qs?: Record<string, any>;
+    /** URL prefix to prepend to the generated URL */
+    prefixUrl?: string;
+};
+/**
+ * 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.
+ */
+/**
+ * Route definition structure for type-safe URL building
+ */
+export type LookupListRoute = {
+    /** Parameters as a tuple for positional arguments */
+    paramsTuple?: [...any[]];
+    /** Parameters as a named object */
+    params?: {
+        [name: string]: any;
+    };
+};
+/**
+ * Complete route lookup structure organized by HTTP methods and route identifiers
+ */
+export type LookupList = {
+    /** HTTP method to route mapping */
+    [method: string]: {
+        /** Route identifier to route definition mapping */
+        [identifier: string]: LookupListRoute;
+    };
+};
+/**
+ * Utility type that constructs function arguments for route URL builders based on route parameters
+ */
+export type RouteBuilderArguments<Identifier, Route, Options extends any = URLOptions> = Route extends LookupListRoute ? Route['params'] extends undefined ? [identifier: Identifier, params?: undefined, options?: Options] : [undefined] extends [Route['params']] ? [identifier: Identifier, params?: Route['params'] | Route['paramsTuple'], options?: Options] : [identifier: Identifier, params: Route['params'] | Route['paramsTuple'], options?: Options] : never;
+/**
+ * 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
+ * ```
+ */
+export type UrlFor<Routes extends LookupList, Options extends any = URLOptions> = (<Identifier extends keyof Routes['ALL'] & string>(...[identifier, params, options]: RouteBuilderArguments<Identifier, 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<RouteIdentifier, Routes['GET'][RouteIdentifier], Options>): {
+        method: 'GET';
+        url: string;
+        form: {
+            action: string;
+            method: 'GET';
+        };
+    };
+    /**
+     * 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<RouteIdentifier, Routes['POST'][RouteIdentifier], Options>): {
+        method: 'POST';
+        url: string;
+        form: {
+            action: string;
+            method: 'POST';
+        };
+    };
+    /**
+     * 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<RouteIdentifier, Routes['PUT'][RouteIdentifier], Options>): {
+        method: 'PUT';
+        url: string;
+        form: {
+            action: string;
+            method: 'PUT';
+        };
+    };
+    /**
+     * 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<RouteIdentifier, Routes['PATCH'][RouteIdentifier], Options>): {
+        method: 'PATCH';
+        url: string;
+        form: {
+            action: string;
+            method: 'PATCH';
+        };
+    };
+    /**
+     * 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<RouteIdentifier, Routes['DELETE'][RouteIdentifier], Options>): {
+        method: 'DELETE';
+        url: string;
+        form: {
+            action: string;
+            method: 'DELETE';
+        };
+    };
+    /**
+     * 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<RouteIdentifier, Routes[Method][RouteIdentifier], Options>): {
+        method: Method;
+        url: string;
+        form: {
+            action: string;
+            method: Method;
+        };
+    };
+};

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

@@ -0,0 +1,15 @@
+import { createURL, findRoute } from './helpers.ts';
+import { type UrlFor, type LookupList, type ClientRouteJSON } from './types.ts';
+export * from './types.ts';
+export { createURL, findRoute };
+/**
+ * Creates the URLBuilder helper
+ * @param router - The router instance
+ * @param searchParamsStringifier - Function to stringify query string parameters
+ * @returns URL builder function for creating URLs
+ */
+export declare function createUrlBuilder<Routes extends LookupList>(routesLoader: {
+    [domain: string]: ClientRouteJSON[];
+} | (() => {
+    [domain: string]: ClientRouteJSON[];
+}), searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes>;

package/build/src/client/url_builder.js

@@ -0,0 +1,115 @@
+import { n as findRoute, t as createURL } from "../../helpers-C_2HouOe.js";
+import "../../types-AUwURgIL.js";
+function createUrlBuilder(routesLoader, searchParamsStringifier) {
+	let domainsList;
+	let domainsRoutes;
+	function createUrlForRoute(identifier, params, options, method) {
+		if (!domainsRoutes) {
+			domainsRoutes = typeof routesLoader === "function" ? routesLoader() : routesLoader;
+			if (!domainsRoutes || typeof domainsRoutes !== "object") throw new Error(`Cannot construct routes. Expected the value to be an object, instead received ${typeof domainsRoutes}`);
+			if (!domainsList) domainsList = Object.keys(domainsRoutes).filter((domain) => domain !== "root");
+		}
+		const domain = domainsList.find((name) => identifier.startsWith(`${name}@`));
+		const routeIdentifier = domain ? identifier.replace(new RegExp(`^${domain}@`), "") : identifier;
+		const route = findRoute(domainsRoutes, routeIdentifier, domain, method, true);
+		if (!route) {
+			if (method) throw new Error(`Cannot lookup route "${routeIdentifier}" for method "${method}"`);
+			throw new Error(`Cannot lookup route "${routeIdentifier}"`);
+		}
+		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]) {
+		const method = "GET";
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	urlFor.post = function urlForMethodPost(...[identifier, params, options]) {
+		const method = "POST";
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	urlFor.put = function urlForMethodPut(...[identifier, params, options]) {
+		const method = "PUT";
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	urlFor.patch = function urlForMethodPatch(...[identifier, params, options]) {
+		const method = "PATCH";
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	urlFor.delete = function urlForMethodDelete(...[identifier, params, options]) {
+		const method = "DELETE";
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	urlFor.method = function urlForCustomMethod(method, ...[identifier, params, options]) {
+		const url = createUrlForRoute(identifier, params, options, method);
+		return {
+			url,
+			method,
+			toString() {
+				return url;
+			},
+			form: {
+				action: url,
+				method
+			}
+		};
+	};
+	return urlFor;
+}
+export { createURL, createUrlBuilder, findRoute };

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

@@ -1,7 +1,20 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 /**
- * Cookie client exposes the API to parse/set AdonisJS cookies
- * as a client.
+ * Cookie client provides a unified API for parsing and setting AdonisJS cookies on the client side.
+ *
+ * This class handles different types of cookies including plain, signed, and encrypted cookies.
+ * It provides methods to encode/decode cookies for client-side operations and parse server responses.
+ *
+ * @example
+ * ```ts
+ * const client = new CookieClient(encryption)
+ *
+ * // Encrypt a cookie value
+ * const encrypted = client.encrypt('sessionId', 'abc123')
+ *
+ * // Parse a cookie from server response
+ * const value = client.parse('sessionId', cookieValue)
+ * ```
  */
 export declare class CookieClient {
     #private;
@@ -62,11 +75,21 @@ export declare class CookieClient {
      */
     decode(_: string, value: string, stringified?: boolean): any;
     /**
-     * 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
-     * @returns The parsed value or undefined if parsing fails
+     *
+     * @example
+     * ```ts
+     * const parsed = client.parse('session', 'e30.abc123def')
+     * // Returns the original value if successfully parsed
+     * ```
      */
     parse(key: string, value: any): any;
 }

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

@@ -1,4 +1,4 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 /**
  * Encrypt a value to be set as cookie
  *

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

@@ -1,4 +1,4 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 /**
  * Signs a value to be shared as a cookie. The signed output has a
  * hash to verify tampering with the original value

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

@@ -1,4 +1,4 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 /**
  * Cookie parser parses the HTTP `cookie` header and collects all cookies
  * inside an object of `key-value` pair, but doesn't attempt to decrypt

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

@@ -1,4 +1,4 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 import type { CookieOptions } from '../types/response.ts';
 /**
  * Cookies serializer is used to serialize a value to be set on the `Set-Cookie`
@@ -31,7 +31,7 @@ export declare class CookieSerializer {
      */
     encode(key: string, value: any, options?: Partial<CookieOptions & {
         /**
-         * @depreacted Instead use stringify option
+         * @deprecated Instead use stringify option
          */
         encode: boolean;
         stringify: boolean;

package/build/src/debug.d.ts

@@ -1,2 +1,15 @@
-declare const _default: import("util").DebugLogger;
+/**
+ * Debug logger instance for the AdonisJS HTTP server package.
+ *
+ * This debug logger can be enabled by setting the NODE_DEBUG environment variable
+ * to include 'adonisjs:http'. When enabled, it will output detailed debugging
+ * information about HTTP server operations including route matching, middleware
+ * execution, and response generation.
+ *
+ * @example
+ * ```bash
+ * NODE_DEBUG=adonisjs:http node ace serve
+ * ```
+ */
+declare const _default: import("node:util").DebugLogger;
 export default _default;

package/build/src/define_config.d.ts

@@ -4,7 +4,25 @@ type UserDefinedServerConfig = DeepPartial<Omit<ServerConfig, 'trustProxy'> & {
     trustProxy: ((address: string, distance: number) => boolean) | boolean | string;
 }>;
 /**
- * Define configuration for the HTTP server
+ * Define configuration for the HTTP server with sensible defaults.
+ *
+ * This function merges user-provided configuration with default values,
+ * normalizes certain properties (like cookie maxAge and trustProxy settings),
+ * and returns a complete ServerConfig object.
+ *
+ * @param config - User-defined server configuration options
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   trustProxy: true,
+ *   cookie: {
+ *     maxAge: '7d',
+ *     secure: false
+ *   },
+ *   etag: true
+ * })
+ * ```
  */
 export declare function defineConfig(config: UserDefinedServerConfig): ServerConfig;
 export {};

package/build/src/define_middleware.d.ts

@@ -1,9 +1,25 @@
 import type { LazyImport, UnWrapLazyImport } from '@poppinss/utils/types';
 import type { MiddlewareAsClass, GetMiddlewareArgs, ParsedGlobalMiddleware } from './types/middleware.ts';
 /**
- * Define an collection of named middleware. The collection gets converted
- * into a collection of factory functions. Calling the function returns
- * a reference to the executable middleware.
+ * Define a collection of named middleware that can be referenced by name in routes and route groups.
+ *
+ * This function converts a collection of middleware classes into factory functions that can be
+ * called with arguments to create middleware references. Each middleware in the collection
+ * becomes available as a typed function that preserves the middleware's argument signature.
+ *
+ * @param collection - Object mapping middleware names to their lazy import references
+ *
+ * @example
+ * ```ts
+ * const namedMiddleware = defineNamedMiddleware({
+ *   auth: () => import('./middleware/auth.ts'),
+ *   throttle: () => import('./middleware/throttle.ts')
+ * })
+ *
+ * // Usage in routes
+ * router.get('/dashboard', [namedMiddleware.auth(), handler])
+ * router.get('/api/data', [namedMiddleware.throttle({ max: 100 }), handler])
+ * ```
  */
 export declare function defineNamedMiddleware<NamedMiddleware extends Record<string, LazyImport<MiddlewareAsClass>>>(collection: NamedMiddleware): { [K in keyof NamedMiddleware]: <Args extends GetMiddlewareArgs<UnWrapLazyImport<NamedMiddleware[K]>>>(...args: Args) => {
     name: K;

package/build/src/errors.d.ts

@@ -1,15 +1,41 @@
 import { Exception } from '@poppinss/utils/exception';
 import type { HttpContext } from './http_context/main.ts';
 /**
- * Thrown when unable to find a matching route for the given request
+ * Thrown when unable to find a matching route for the given request.
+ *
+ * This error is raised when the router cannot match the incoming HTTP method
+ * and URL pattern to any registered route in the application.
+ *
+ * @example
+ * ```ts
+ * throw new E_ROUTE_NOT_FOUND(['GET', '/nonexistent'])
+ * ```
  */
 export declare const E_ROUTE_NOT_FOUND: new (args: [method: string, url: string], options?: ErrorOptions) => Exception;
 /**
  * Thrown when unable to lookup a route by its identifier.
+ *
+ * This error occurs when trying to generate URLs or find routes using
+ * a route name, pattern, or controller reference that doesn't exist.
+ *
+ * @example
+ * ```ts
+ * throw new E_CANNOT_LOOKUP_ROUTE(['nonexistent.route'])
+ * ```
  */
 export declare const E_CANNOT_LOOKUP_ROUTE: new (args: [routeIdentifier: string], options?: ErrorOptions) => Exception;
 /**
- * A generic HTTP exception to convert errors to HTTP response
+ * A generic HTTP exception for converting errors to HTTP responses.
+ *
+ * This class provides a standardized way to create HTTP exceptions with
+ * specific status codes and response bodies. It handles various input types
+ * including strings, objects, and null/undefined values.
+ *
+ * @example
+ * ```ts
+ * throw E_HTTP_EXCEPTION.invoke('Not found', 404)
+ * throw E_HTTP_EXCEPTION.invoke({ error: 'Invalid data' }, 422)
+ * ```
  */
 export declare const E_HTTP_EXCEPTION: {
     new (message?: string, options?: ErrorOptions & {
@@ -29,7 +55,17 @@ export declare const E_HTTP_EXCEPTION: {
     };
     code: string;
     /**
-     * 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)
+     * ```
      */
     invoke(body: any, status: number, code?: string): {
         body: any;
@@ -52,7 +88,16 @@ export declare const E_HTTP_EXCEPTION: {
     stackTraceLimit: number;
 };
 /**
- * Thrown when the "response.abort" method is called
+ * Thrown when the "response.abort" method is called.
+ *
+ * This exception is used to immediately terminate request processing
+ * and send a response. It includes a built-in handler that automatically
+ * sends the appropriate status and body to the client.
+ *
+ * @example
+ * ```ts
+ * throw new E_HTTP_REQUEST_ABORTED()
+ * ```
  */
 export declare const E_HTTP_REQUEST_ABORTED: {
     new (message?: string, options?: ErrorOptions & {
@@ -73,7 +118,17 @@ export declare const E_HTTP_REQUEST_ABORTED: {
     };
     code: string;
     /**
-     * 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)
+     * ```
      */
     invoke(body: any, status: number, code?: string): {
         body: any;

package/build/src/exception_handler.d.ts

@@ -3,16 +3,29 @@ import type { Level } from '@adonisjs/logger/types';
 import type { HttpContext } from './http_context/main.ts';
 import type { HttpError, StatusPageRange, StatusPageRenderer } from './types/server.ts';
 /**
- * The base HTTP exception handler one can inherit from to handle
- * HTTP exceptions.
+ * The base HTTP exception handler that provides comprehensive error handling capabilities.
  *
- * The HTTP exception handler has support for
+ * This class can be inherited to create custom exception handlers for your application.
+ * It provides built-in support for:
  *
- * - Ability to render exceptions by calling the render method on the exception.
- * - Rendering status pages
- * - Pretty printing errors during development
- * - Transforming errors to JSON or HTML using content negotiation
- * - Reporting errors
+ * - Self-handling exceptions via their own render/handle methods
+ * - Custom status page rendering for different HTTP error codes
+ * - Debug-friendly error display during development
+ * - Content negotiation for JSON, JSON API, and HTML error responses
+ * - Configurable error reporting and logging
+ * - Validation error handling with field-specific messages
+ *
+ * @example
+ * ```ts
+ * export default class HttpExceptionHandler extends ExceptionHandler {
+ *   protected debug = app.inDev
+ *   protected renderStatusPages = app.inProduction
+ *
+ *   protected statusPages = {
+ *     '404': (error, ctx) => ctx.view.render('errors/404')
+ *   }
+ * }
+ * ```
  */
 export declare class ExceptionHandler extends Macroable {
     #private;
@@ -53,6 +66,13 @@ export declare class ExceptionHandler extends Macroable {
      * Errors with these codes are handled but not logged
      */
     protected ignoreCodes: string[];
+    /**
+     * Normalizes any thrown value into a standardized HttpError object
+     * Ensures the error has required properties like message and status
+     * @param error - Any thrown value (Error, string, object, etc.)
+     * @returns {HttpError} Normalized error object with status and message
+     */
+    protected toHttpError(error: unknown): HttpError;
     /**
      * Provides additional context information for error reporting
      * Includes request ID when available for correlation across logs