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

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

@@ -2,10 +2,27 @@ import Macroable from '@poppinss/macroable';
 import type { Application } from '@adonisjs/application';
 import type { Constructor, LazyImport, OneOrMore } from '@poppinss/utils/types';
 import type { MiddlewareFn, ParsedNamedMiddleware, ParsedGlobalMiddleware } from '../types/middleware.ts';
-import type { RouteFn, RouteJSON, RouteMatcher, RouteMatchers, StoreRouteMiddleware, GetControllerHandlers } from '../types/route.ts';
+import type { RouteFn, RouteJSON, RouteMatcher, RouteMatchers, StoreRouteHandler, StoreRouteMiddleware, GetControllerHandlers } from '../types/route.ts';
 /**
- * The route class exposes the APIs for constructing a route using the
- * fluent API.
+ * The Route class provides a fluent API for constructing and configuring HTTP routes.
+ *
+ * Routes define how HTTP requests are handled by mapping URL patterns and HTTP methods
+ * to controller actions or inline handlers. This class supports middleware application,
+ * parameter validation, naming, and various other route-specific configurations.
+ *
+ * @example
+ * ```ts
+ * const route = new Route(app, middleware, {
+ *   pattern: '/users/:id',
+ *   methods: ['GET'],
+ *   handler: 'UsersController.show'
+ * })
+ *
+ * route
+ *   .where('id', /^[0-9]+$/)
+ *   .middleware(['auth'])
+ *   .as('users.show')
+ * ```
  */
 export declare class Route<Controller extends Constructor<any> = any> extends Macroable {
     #private;
@@ -22,79 +39,160 @@ export declare class Route<Controller extends Constructor<any> = any> extends Ma
         globalMatchers: RouteMatchers;
     });
     /**
-     * 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.
+     * Returns the route's handler configuration object.
+     */
+    getHandler(): StoreRouteHandler;
+    /**
+     * Defines a validation matcher for a route parameter. Route-level matchers
+     * take precedence over group-level matchers to ensure routes can override
+     * group constraints.
+     *
+     * @param param - The name of the route parameter to validate
+     * @param matcher - The validation pattern as a string, RegExp, or RouteMatcher object
      *
+     * @example
      * ```ts
+     * // Validate that 'id' is numeric
+     * route.where('id', /^[0-9]+$/)
+     *
+     * // Using a string pattern
+     * route.where('slug', '[a-z0-9-]+')
+     *
+     * // Route matcher takes precedence over group matcher
      * Route.group(() => {
      *   Route.get('/:id', 'handler').where('id', /^[0-9]$/)
      * }).where('id', /[^a-z$]/)
+     * // The route's /^[0-9]$/ wins over the group's matcher
      * ```
-     *
-     * The `/^[0-9]$/` will win over the matcher defined by the group
      */
     where(param: string, matcher: RouteMatcher | string | RegExp): this;
     /**
-     * Define prefix for the route. Calling this method multiple times
-     * applies multiple prefixes in the reverse order.
-     * @param prefix - The prefix to add to the route
-     * @returns Current Route instance for method chaining
+     * Adds a URL prefix to the route pattern. Multiple calls stack prefixes
+     * which are applied in reverse order during pattern computation.
+     *
+     * @param prefix - The URL prefix to prepend to the route pattern
+     *
+     * @example
+     * ```ts
+     * route.prefix('/api').prefix('/v1')
+     * // Results in pattern: /v1/api/users (for original pattern /users)
+     * ```
      */
     prefix(prefix: string): this;
     /**
-     * Define a custom domain for the route. We do not overwrite the domain
-     * unless `overwrite` flag is set to true.
+     * Assigns a custom domain to the route. By default, routes belong to the
+     * 'root' domain. Once set, the domain is not overwritten unless the
+     * overwrite flag is true.
+     *
+     * @param domain - The domain identifier for this route
+     * @param overwrite - Whether to overwrite an existing non-root domain
+     *
+     * @example
+     * ```ts
+     * route.domain('api.example.com')
+     *
+     * // Overwrite existing domain
+     * route.domain('new.example.com', true)
+     * ```
      */
     domain(domain: string, overwrite?: boolean): this;
     /**
-     * Define one or more middleware to be executed before the route
-     * handler.
+     * Registers one or more middleware to execute before the route handler.
+     * Middleware can be inline functions or named middleware references registered
+     * with the router's middleware store.
+     *
+     * @param middleware - Single middleware or array of middleware to apply
+     *
+     * @example
+     * ```ts
+     * // Single middleware
+     * route.use(async (ctx, next) => {
+     *   console.log('Before handler')
+     *   await next()
+     * })
      *
-     * Named middleware can be referenced using the name registered with
-     * the router middleware store.
+     * // Multiple middleware
+     * route.use(['auth', 'admin'])
+     * ```
      */
     use(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
     /**
-     * Alias for {@link Route.use}
+     * Alias for the {@link Route.use} method.
+     *
+     * @param middleware - Single middleware or array of middleware to apply
      */
     middleware(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
     /**
-     * Give a unique name to the route. Assinging a new unique removes the
-     * existing name of the route.
+     * Assigns a unique name to the route for use in URL generation and route
+     * referencing. Assigning a new name replaces any existing name unless
+     * prepend is true.
      *
-     * Setting prepends to true prefixes the name to the existing name.
+     * @param name - The route name to assign
+     * @param prepend - If true, prepends the name to the existing name with a dot separator
+     *
+     * @example
+     * ```ts
+     * // Set route name
+     * route.as('users.show')
+     *
+     * // Prepend to existing name (typically used by route groups)
+     * route.as('admin', true) // Results in 'admin.users.show'
+     * ```
      */
     as(name: string, prepend?: boolean): this;
     /**
-     * Check if the route was marked to be deleted
+     * Checks whether the route has been marked for deletion. Deleted routes
+     * are excluded from the route store during registration.
      */
     isDeleted(): boolean;
     /**
-     * Mark route as deleted. Deleted routes are not registered
-     * with the route store
+     * Marks the route for deletion. Deleted routes will not be registered
+     * with the route store when Router.commit() is called.
+     *
+     * @example
+     * ```ts
+     * const route = Route.get('/admin', 'handler')
+     * route.markAsDeleted()
+     * // This route will not be registered
+     * ```
      */
     markAsDeleted(): void;
     /**
-     * Get the route name
+     * Returns the unique name assigned to the route, if any.
      */
     getName(): string | undefined;
     /**
-     * Get the route pattern
+     * Returns the route's URL pattern with dynamic parameters.
      */
     getPattern(): string;
     /**
-     * Set the route pattern
+     * Updates the route's URL pattern.
+     *
+     * @param pattern - The new URL pattern to assign to the route
+     *
+     * @example
+     * ```ts
+     * route.setPattern('/users/:id/posts/:postId')
+     * ```
      */
     setPattern(pattern: string): this;
     /**
-     * Returns the stack of middleware registered on the route.
-     * The value is shared by reference.
+     * Returns the multi-dimensional middleware stack registered on this route.
+     * The returned value is shared by reference, not a copy.
      */
     getMiddleware(): StoreRouteMiddleware[][];
     /**
-     * Returns JSON representation of the route
+     * Serializes the route into a JSON representation suitable for storage and
+     * execution. This includes the computed pattern with prefixes, merged matchers,
+     * parsed route tokens, and frozen middleware stack.
+     *
+     * @example
+     * ```ts
+     * const json = route.toJSON()
+     * console.log(json.pattern) // '/api/users/:id'
+     * console.log(json.methods) // ['GET']
+     * console.log(json.name) // 'users.show'
+     * ```
      */
     toJSON(): RouteJSON;
 }

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

@@ -1,4 +1,4 @@
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 import { type Router } from './main.ts';
 import { type UrlFor, type LookupList, type SignedURLOptions } from '../types/url_builder.ts';
 /**

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

@@ -1,6 +1,6 @@
 import type { Logger } from '@adonisjs/logger';
 import type { LazyImport } from '@poppinss/utils/types';
-import type { Encryption } from '@adonisjs/encryption';
+import type { Encryption } from '@boringnode/encryption';
 import type { Server as HttpsServer } from 'node:https';
 import type { Application } from '@adonisjs/application';
 import type { EmitterLike } from '@adonisjs/events/types';
@@ -8,9 +8,9 @@ import { type ContainerResolver } from '@adonisjs/fold';
 import type { ServerResponse, IncomingMessage, Server as HttpServer } from 'node:http';
 import type { MiddlewareAsClass, ParsedGlobalMiddleware } from '../types/middleware.ts';
 import type { ServerConfig, HttpServerEvents, ErrorHandlerAsAClass, TestingMiddlewarePipeline } from '../types/server.ts';
-import { Request } from '../request.ts';
-import { Response } from '../response.ts';
+import { HttpRequest } from '../request.ts';
 import { Router } from '../router/main.ts';
+import { HttpResponse } from '../response.ts';
 import { HttpContext } from '../http_context/main.ts';
 /**
  * The Server class provides the core HTTP server implementation for AdonisJS.
@@ -105,7 +105,7 @@ export declare class Server {
      * @param res - Node.js ServerResponse
      * @returns New Request instance
      */
-    createRequest(req: IncomingMessage, res: ServerResponse): Request;
+    createRequest(req: IncomingMessage, res: ServerResponse): HttpRequest;
     /**
      * Creates a Response instance from Node.js request/response objects
      *
@@ -113,7 +113,7 @@ export declare class Server {
      * @param res - Node.js ServerResponse
      * @returns New Response instance
      */
-    createResponse(req: IncomingMessage, res: ServerResponse): Response;
+    createResponse(req: IncomingMessage, res: ServerResponse): HttpResponse;
     /**
      * Creates an HttpContext instance with request-specific logger
      *
@@ -122,7 +122,7 @@ export declare class Server {
      * @param resolver - Container resolver for dependency injection
      * @returns New HttpContext instance
      */
-    createHttpContext(request: Request, response: Response, resolver: ContainerResolver<any>): HttpContext;
+    createHttpContext(request: HttpRequest, response: HttpResponse, resolver: ContainerResolver<any>): HttpContext;
     /**
      * Gets the list of registered global middleware
      *

package/build/src/types/main.js

@@ -0,0 +1 @@
+export {};

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

@@ -30,6 +30,11 @@ export type CastableHeader = string | number | boolean | string[] | number[] | b
  * Configuration options for HTTP response handling and processing
  */
 export type ResponseConfig = {
+    /**
+     * Define a custom serializer to serialize the response body
+     * to a JSON string
+     */
+    serializeJSON(payload: unknown): string | undefined;
     /**
      * Whether or not to generate etags for responses. Etags can be
      * enabled/disabled when sending response as well.
@@ -51,4 +56,4 @@ export type ResponseConfig = {
 /**
  * A readable stream that can be piped to the response stream method
  */
-export type ResponseStream = Readable;
+export type ResponseStream = Readable | ReadableStream<any>;

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

@@ -4,6 +4,7 @@ import type { Constructor, LazyImport } from '@poppinss/utils/types';
 import type { ServerErrorHandler } from './server.ts';
 import type { HttpContext } from '../http_context/main.ts';
 import type { MiddlewareFn, ParsedGlobalMiddleware } from './middleware.ts';
+import { type ClientRouteJSON, type ClientRouteMatchItTokens } from '../client/types.ts';
 /**
  * Configuration for matching and casting route parameters
  */
@@ -16,16 +17,7 @@ export type RouteMatcher = {
 /**
  * Route token structure used internally by the matchit routing library
  */
-export type MatchItRouteToken = RouteMatcher & {
-    /** 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;
-};
+export type MatchItRouteToken = RouteMatcher & ClientRouteMatchItTokens;
 /**
  * Extracts method names from a controller class that accept HttpContext as first parameter
  */
@@ -120,20 +112,12 @@ export type RouteMatchers = {
 /**
  * Complete route definition with all metadata, handlers, and execution context
  */
-export type RouteJSON = {
+export type RouteJSON = Pick<ClientRouteJSON, 'name' | 'methods' | 'domain' | 'pattern'> & {
     /**
      * The execute function to execute the route middleware
      * and the handler
      */
     execute: (route: RouteJSON, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']) => any;
-    /**
-     * A unique name for the route
-     */
-    name?: string;
-    /**
-     * Route URI pattern
-     */
-    pattern: string;
     /**
      * Route handler
      */
@@ -150,14 +134,6 @@ export type RouteJSON = {
      * Tokens to be used to construct the route URL
      */
     tokens: MatchItRouteToken[];
-    /**
-     * HTTP methods, the route responds to.
-     */
-    methods: string[];
-    /**
-     * The domain for which the route is registered.
-     */
-    domain: string;
     /**
      * Matchers for route params.
      */

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

@@ -1,16 +1,5 @@
-/**
- * Types shared with the client. These should never import other types
- */
-import { type Prettify } from '@poppinss/utils/types';
-/**
- * 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;
-};
+import { type UrlFor, type LookupList, type URLOptions, type LookupListRoute, type RouteBuilderArguments } from '../client/types.ts';
+export { URLOptions, LookupListRoute, RouteBuilderArguments, LookupList, UrlFor };
 /**
  * Configuration options for signed URL generation helpers
  */
@@ -20,133 +9,6 @@ export type SignedURLOptions = URLOptions & {
     /** Purpose identifier for the signed URL */
     purpose?: string;
 };
-/**
- * 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 ? Prettify<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;
-/**
- * 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;
-    };
-};
-/**
- * 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;
-    };
-    /**
-     * 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;
-    };
-    /**
-     * 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;
-    };
-    /**
-     * 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;
-    };
-    /**
-     * 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;
-    };
-    /**
-     * 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;
-    };
-};
 /**
  * Utility type to extract routes for a specific HTTP method from the routes collection
  */

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/build/types-AUwURgIL.js

@@ -0,0 +1 @@
+export {};