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

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

@@ -1,15 +1,37 @@
 import Macroable from '@poppinss/macroable';
 import type { Application } from '@adonisjs/application';
 import type { Constructor, LazyImport, OneOrMore } from '@poppinss/utils/types';
-import { type RouteMatcher } from '../client/types.ts';
-import type { MiddlewareFn, ParsedNamedMiddleware, ParsedGlobalMiddleware } from '../types/middleware.js';
-import type { RouteFn, RouteJSON, RouteMatchers, StoreRouteMiddleware, GetControllerHandlers } from '../types/route.js';
+import type { MiddlewareFn, ParsedNamedMiddleware, ParsedGlobalMiddleware } from '../types/middleware.ts';
+import type { RouteFn, RouteJSON, RouteMatcher, RouteMatchers, 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;
+    /**
+     * Creates a new Route instance
+     * @param app - The AdonisJS application instance
+     * @param routerMiddleware - Array of global middleware registered on the router
+     * @param options - Configuration options for the route
+     */
     constructor(app: Application<any>, routerMiddleware: ParsedGlobalMiddleware[], options: {
         pattern: string;
         methods: string[];
@@ -34,6 +56,8 @@ export declare class Route<Controller extends Constructor<any> = any> extends Ma
     /**
      * Define prefix for the route. Calling this method multiple times
      * applies multiple prefixes in the reverse order.
+     * @param prefix - The prefix to add to the route
+     * @returns Current Route instance for method chaining
      */
     prefix(prefix: string): this;
     /**
@@ -50,7 +74,7 @@ export declare class Route<Controller extends Constructor<any> = any> extends Ma
      */
     use(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
     /**
-     * @alias use
+     * Alias for {@link Route.use}
      */
     middleware(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
     /**

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

@@ -1,14 +1,11 @@
 import type { Encryption } from '@adonisjs/encryption';
-import { type RouterClient } from '../client/router.ts';
-import { type UrlFor, type LookupList, type ClientRouteJSON, type SignedURLOptions, type MatchItRouteToken } from '../client/types.ts';
-/**
- * Makes signed URL for a given route pattern. The route pattern could be an
- * identifier or an array of tokens.
- */
-export declare function createSignedURL(identifier: string, tokens: MatchItRouteToken[], searchParamsStringifier: (qs: Record<string, any>) => string, encryption: Encryption, params?: any[] | {
-    [param: string]: any;
-}, options?: SignedURLOptions): string;
+import { type Router } from './main.ts';
+import { type UrlFor, type LookupList, type SignedURLOptions } from '../types/url_builder.ts';
 /**
  * Creates the URLBuilder helper for making signed URLs
+ * @param router - The router instance
+ * @param encryption - Encryption service for signing URLs
+ * @param searchParamsStringifier - Function to stringify query string parameters
+ * @returns URL builder function for creating signed URLs
  */
-export declare function createSignedUrlBuilder<Routes extends LookupList>(router: RouterClient<ClientRouteJSON>, encryption: Encryption, searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes, SignedURLOptions>;
+export declare function createSignedUrlBuilder<Routes extends LookupList>(router: Router, encryption: Encryption, searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes, SignedURLOptions>;

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

@@ -1,5 +1,4 @@
-import type { RouteJSON, MatchedRoute, StoreRoutesTree } from '../types/route.js';
-import { type MatchItRouteToken } from '../client/types.ts';
+import type { RouteJSON, MatchedRoute, StoreRoutesTree, MatchItRouteToken } from '../types/route.ts';
 /**
  * Store class is used to store a list of routes, along side with their tokens
  * to match the URLs.
@@ -45,6 +44,8 @@ export declare class RoutesStore {
      *   }
      * })
      * ```
+     * @param route - The route to add to the store
+     * @returns Current RoutesStore instance for method chaining
      */
     add(route: RouteJSON): this;
     /**
@@ -55,6 +56,11 @@ export declare class RoutesStore {
      * 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: string, method: string, shouldDecodeParam: boolean, domain?: {
         tokens: MatchItRouteToken[];
@@ -62,6 +68,8 @@ export declare class RoutesStore {
     }): null | MatchedRoute;
     /**
      * Match hostname against registered domains.
+     * @param hostname - The hostname to match
+     * @returns Array of matched domain tokens
      */
     matchDomain(hostname?: string | null): MatchItRouteToken[];
 }

package/build/src/server/factories/middleware_handler.d.ts

@@ -1,8 +1,17 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { NextFn } from '@poppinss/middleware/types';
-import type { HttpContext } from '../../http_context/main.js';
-import { type ParsedGlobalMiddleware } from '../../types/middleware.js';
+import type { HttpContext } from '../../http_context/main.ts';
+import { type ParsedGlobalMiddleware } from '../../types/middleware.ts';
 /**
- * The middleware handler invokes the middleware functions.
+ * Creates a middleware execution handler that invokes middleware functions with tracing support
+ *
+ * This factory function returns a middleware execution handler that:
+ * - Executes middleware with debug logging
+ * - Provides distributed tracing through tracing channels
+ * - Passes the container resolver, HTTP context, and next function to middleware
+ *
+ * @param resolver - Container resolver for dependency injection
+ * @param ctx - HTTP context containing request/response data
+ * @returns Middleware execution function
  */
 export declare function middlewareHandler(resolver: ContainerResolver<any>, ctx: HttpContext): (fn: ParsedGlobalMiddleware, next: NextFn) => Promise<any>;

package/build/src/server/factories/route_finder.d.ts

@@ -1,10 +1,20 @@
 import type { ContainerResolver } from '@adonisjs/fold';
-import type { Router } from '../../router/main.js';
-import type { HttpContext } from '../../http_context/main.js';
-import type { ServerErrorHandler } from '../../types/server.js';
+import type { Router } from '../../router/main.ts';
+import type { HttpContext } from '../../http_context/main.ts';
+import type { ServerErrorHandler } from '../../types/server.ts';
 /**
- * The route finder is executed after the server middleware stack.
- * It looks for a matching route and executes the route middleware
- * stack.
+ * Creates a route finder function that matches HTTP requests to registered routes
+ *
+ * This factory function returns a route handler that:
+ * - Matches incoming requests against registered routes
+ * - Extracts route parameters and subdomains
+ * - Executes the matched route's handler and middleware
+ * - Throws E_ROUTE_NOT_FOUND error for unmatched requests
+ *
+ * @param router - Router instance containing registered routes
+ * @param resolver - Container resolver for dependency injection
+ * @param ctx - HTTP context containing request/response data
+ * @param errorResponder - Error handler for route execution errors
+ * @returns Route execution function
  */
 export declare function routeFinder(router: Router, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']): () => any;

package/build/src/server/factories/write_response.d.ts

@@ -1,6 +1,13 @@
-import type { HttpContext } from '../../http_context/main.js';
+import type { HttpContext } from '../../http_context/main.ts';
 /**
- * Writes the response to the socket. The "finish" method can
- * raise error when unable to serialize the response.
+ * Creates a response writer function that finalizes HTTP responses with error handling
+ *
+ * This factory function returns a response finalizer that:
+ * - Calls the response.finish() method to send the response
+ * - Catches serialization errors and sends a 500 error response
+ * - Logs fatal errors for debugging and monitoring
+ *
+ * @param ctx - HTTP context containing the response to finalize
+ * @returns Response finalization function
  */
 export declare function writeResponse(ctx: HttpContext): () => void;

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

@@ -6,81 +6,135 @@ import type { Application } from '@adonisjs/application';
 import type { EmitterLike } from '@adonisjs/events/types';
 import { type ContainerResolver } from '@adonisjs/fold';
 import type { ServerResponse, IncomingMessage, Server as HttpServer } from 'node:http';
-import type { MiddlewareAsClass, ParsedGlobalMiddleware } from '../types/middleware.js';
-import type { ServerConfig, HttpServerEvents, ErrorHandlerAsAClass, TestingMiddlewarePipeline } from '../types/server.js';
-import { Request } from '../request.js';
-import { Response } from '../response.js';
-import { Router } from '../router/main.js';
-import { HttpContext } from '../http_context/main.js';
+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 { Router } from '../router/main.ts';
+import { HttpContext } from '../http_context/main.ts';
 /**
- * The HTTP server implementation to handle incoming requests and respond using the
- * registered routes.
+ * The Server class provides the core HTTP server implementation for AdonisJS.
+ *
+ * It handles incoming HTTP requests by processing them through middleware pipelines,
+ * routing them to appropriate handlers, and managing response generation. The server
+ * supports custom error handling, middleware registration, and various Node.js HTTP
+ * server configurations.
+ *
+ * @example
+ * ```ts
+ * const server = new Server(app, encryption, emitter, logger, config)
+ * server.use([AuthMiddleware, CorsMiddleware])
+ * server.errorHandler(() => import('./error_handler.ts'))
+ * await server.boot()
+ *
+ * http.createServer(server.handle.bind(server))
+ * ```
  */
 export declare class Server {
     #private;
     /**
-     * Check if the server has already been booted
+     * Indicates whether the server has completed its boot process
      */
     get booted(): boolean;
     /**
-     * Know if async local storage is enabled or not.
+     * Indicates whether async local storage is enabled for request context
      */
     get usingAsyncLocalStorage(): boolean;
+    /**
+     * 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: Application<any>, encryption: Encryption, emitter: EmitterLike<HttpServerEvents>, logger: Logger, config: ServerConfig);
     /**
-     * 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: MiddlewareAsClass[]): TestingMiddlewarePipeline;
     /**
-     * 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: LazyImport<MiddlewareAsClass>[]): 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: LazyImport<ErrorHandlerAsAClass>): 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
      */
     boot(): Promise<void>;
     /**
-     * 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: HttpServer | HttpsServer): void;
     /**
-     * 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(): HttpServer<typeof IncomingMessage, typeof ServerResponse> | HttpsServer<typeof IncomingMessage, typeof ServerResponse> | undefined;
     /**
-     * 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(): 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: IncomingMessage, res: ServerResponse): Request;
     /**
-     * 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: IncomingMessage, res: ServerResponse): Response;
     /**
-     * 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: Request, response: Response, resolver: ContainerResolver<any>): HttpContext;
     /**
-     * Returns a list of server middleware stack
+     * Gets the list of registered global middleware
+     *
+     * @returns Array of parsed global middleware
      */
     getMiddlewareList(): ParsedGlobalMiddleware[];
     /**
-     * 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: IncomingMessage, res: ServerResponse): Promise<any>;
 }

package/build/src/tracing_channels.d.ts

@@ -1,13 +1,13 @@
 import diagnostics_channel from 'node:diagnostics_channel';
-import type { MiddlewareTracingData } from './types/tracing_channels.js';
+import type { MiddlewareTracingData, HTTPRequestTracingData, RouteHandlerTracingData } from './types/tracing_channels.ts';
 /**
  * Traces every HTTP request handled by the {@link Server} class.
  */
-export declare const httpRequest: diagnostics_channel.TracingChannel<"adonisjs:http.request", import("./http_context/main.ts").HttpContext>;
+export declare const httpRequest: diagnostics_channel.TracingChannel<"adonisjs.http.request", HTTPRequestTracingData>;
 /**
  * Traces middleware executed during the HTTP request
  */
-export declare const httpMiddleware: diagnostics_channel.TracingChannel<"adonisjs:http.middleware", MiddlewareTracingData>;
+export declare const httpMiddleware: diagnostics_channel.TracingChannel<"adonisjs.http.middleware", MiddlewareTracingData>;
 /**
  * Traces the exception handler that converts errors into HTTP responses
  */
@@ -15,7 +15,7 @@ export declare const httpExceptionHandler: diagnostics_channel.TracingChannel<"a
 /**
  * Traces route handler executed during the HTTP request
  */
-export declare const httpRouteHandler: diagnostics_channel.TracingChannel<"adonisjs:http.route.handler", import("./types/route.ts").RouteJSON>;
+export declare const httpRouteHandler: diagnostics_channel.TracingChannel<"adonisjs.http.route.handler", RouteHandlerTracingData>;
 /**
  * Traces non-stream and non-file download responses written by the AdonisJS
  * response class

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

@@ -3,5 +3,5 @@ export * from './route.ts';
 export * from './server.ts';
 export * from './request.ts';
 export * from './response.ts';
-export * from '../client/types.ts';
+export * from './url_builder.ts';
 export * from './middleware.ts';

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

@@ -1,70 +1,95 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { NextFn } from '@poppinss/middleware/types';
 import type { Constructor, LazyImport } from '@poppinss/utils/types';
-import type { HttpContext } from '../http_context/main.js';
+import type { HttpContext } from '../http_context/main.ts';
+export { NextFn };
 /**
- * Middleware represented as a class
+ * Middleware represented as a class constructor that implements a handle method
  */
 export type MiddlewareAsClass = Constructor<{
     handle: (ctx: HttpContext, next: NextFn, args?: any) => any;
 }>;
 /**
- * Check if a union has undefined or null
+ * Utility type to check if a union type includes undefined or null values
  */
 type HasUndefined<T> = T extends NonNullable<T> ? true : false;
 /**
- * Returns the arguments accepted by the middleware's handle method
+ * Extracts and returns the argument types accepted by a middleware's handle method
+ * Returns an empty array if no args, otherwise returns the args type as a tuple
  */
 export type GetMiddlewareArgs<Middleware extends MiddlewareAsClass> = Parameters<InstanceType<Middleware>['handle']>[2] extends undefined ? [] : HasUndefined<Parameters<InstanceType<Middleware>['handle']>[2]> extends true ? [Parameters<InstanceType<Middleware>['handle']>[2]] : [Parameters<InstanceType<Middleware>['handle']>[2]?];
 /**
- * The middleware defined as a function on the router or the server
+ * Middleware defined as a function that accepts HTTP context and next function
  */
 export type MiddlewareFn = (ctx: HttpContext, next: NextFn) => any;
 /**
- * Parsed global middleware
+ * Representation of a parsed global middleware with its metadata and execution handler
  */
 export type ParsedGlobalMiddleware = {
+    /** Optional name for the middleware */
     name?: string;
+    /** Reference to the middleware class or lazy import */
     reference: LazyImport<MiddlewareAsClass> | MiddlewareAsClass;
+    /** Handler function that executes the middleware */
     handle: (resolver: ContainerResolver<any>, ...args: [ctx: HttpContext, next: NextFn, params?: any]) => any;
 };
 /**
- * Parsed named middleware
+ * Representation of a parsed named middleware with its metadata, arguments and execution handler
  */
 export type ParsedNamedMiddleware = {
+    /** Name identifier for the middleware */
     name: string;
+    /** Reference to the middleware class or lazy import */
     reference: LazyImport<MiddlewareAsClass> | MiddlewareAsClass;
+    /** Handler function that executes the middleware */
     handle: ParsedGlobalMiddleware['handle'];
+    /** Arguments to pass to the middleware */
     args: any;
 };
 /**
- * Info node representing a middleware handler
+ * Information node describing different types of middleware handlers and their metadata
  */
 export type MiddlewareHandlerInfo = {
+    /** Type identifier for closure middleware */
     type: 'closure';
+    /** Name of the closure middleware */
     name: string;
 } | {
+    /** Type identifier for named middleware */
     type: 'named';
+    /** Name of the named middleware */
     name: string;
+    /** Arguments to pass to the middleware */
     args: any | undefined;
+    /** Method name on the middleware class */
     method: string;
+    /** Module name or file path for the middleware */
     moduleNameOrPath: string;
 } | {
+    /** Type identifier for global middleware */
     type: 'global';
+    /** Optional name for the global middleware */
     name?: string | undefined;
+    /** Method name on the middleware class */
     method: string;
+    /** Module name or file path for the middleware */
     moduleNameOrPath: string;
 };
 /**
- * Info node representing route handler
+ * Information node describing different types of route handlers and their metadata
  */
 export type RouteHandlerInfo = {
+    /** Type identifier for closure route handler */
     type: 'closure';
+    /** Name of the closure handler */
     name: string;
+    /** Optional arguments for the closure */
     args?: string;
 } | {
+    /** Type identifier for controller route handler */
     type: 'controller';
+    /** Method name on the controller class */
     method: string;
+    /** Module name or file path for the controller */
     moduleNameOrPath: string;
 };
-export {};

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

@@ -1,4 +1,8 @@
+/**
+ * Configuration options for query string parsing and stringification
+ */
 export type QSParserConfig = {
+    /** Configuration options for parsing query strings */
     parse: {
         /**
          * Nesting depth till the parameters should be parsed.
@@ -33,6 +37,7 @@ export type QSParserConfig = {
          */
         comma: boolean;
     };
+    /** Configuration options for stringifying query objects */
     stringify: {
         /**
          * URI encode the stringified query string

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

@@ -1,5 +1,5 @@
 /**
- * Shape of the request config
+ * Configuration options for HTTP request handling and processing
  */
 export type RequestConfig = {
     /**

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

@@ -1,25 +1,33 @@
 import { type Readable } from 'node:stream';
 /**
- * Cookie options can that can be set on the response
+ * Configuration options for HTTP cookies that can be set on the response
  */
 export type CookieOptions = {
+    /** Domain name for the cookie */
     domain: string;
+    /** Expiration date for the cookie or function that returns the date */
     expires: Date | (() => Date);
+    /** Whether the cookie should be accessible only through HTTP(S) */
     httpOnly: boolean;
+    /** Maximum age of the cookie in seconds or as a string */
     maxAge: number | string;
+    /** URL path for which the cookie is valid */
     path: string;
+    /** SameSite attribute to control cross-site request behavior */
     sameSite: boolean | 'lax' | 'none' | 'strict';
+    /** Whether the cookie should only be sent over HTTPS */
     secure: boolean;
+    /** Whether the cookie should be partitioned (optional) */
     partitioned?: boolean;
+    /** Priority level for the cookie (optional) */
     priority?: 'low' | 'medium' | 'high';
 };
 /**
- * Types from which response header can be casted to a
- * string
+ * Types that can be cast to a string for HTTP response headers
  */
 export type CastableHeader = string | number | boolean | string[] | number[] | boolean[];
 /**
- * Config accepted by response the class
+ * Configuration options for HTTP response handling and processing
  */
 export type ResponseConfig = {
     /**
@@ -36,11 +44,11 @@ export type ResponseConfig = {
      */
     jsonpCallbackName: string;
     /**
-     * Options to set cookies
+     * Default options to apply when setting cookies
      */
     cookie: Partial<CookieOptions>;
 };
 /**
- * Stream that can be piped to the "response.stream" method
+ * A readable stream that can be piped to the response stream method
  */
 export type ResponseStream = Readable;