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

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

@@ -0,0 +1,203 @@
+/**
+ * Types shared with the client. These should never import other types
+ */
+import { type Prettify } from '@poppinss/utils/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 ? 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;
+/**
+ * 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,12 @@
+import {
+  createUrlBuilder
+} from "../../chunk-5PWHBE2E.js";
+import {
+  createURL,
+  findRoute
+} from "../../chunk-2QM3D5BN.js";
+export {
+  createURL,
+  createUrlBuilder,
+  findRoute
+};

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

@@ -1,37 +1,95 @@
 import type { Encryption } from '@adonisjs/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;
+    /**
+     * Create a new instance of CookieClient
+     *
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(encryption: Encryption);
     /**
      * Encrypt a key value pair to be sent in the cookie header
+     *
+     * @param key - The cookie key
+     * @param value - The value to encrypt
+     * @returns The encrypted cookie string or null if encryption fails
      */
     encrypt(key: string, value: any): string | null;
     /**
      * Sign a key value pair to be sent in the cookie header
+     *
+     * @param key - The cookie key
+     * @param value - The value to sign
+     * @returns The signed cookie string or null if signing fails
      */
     sign(key: string, value: any): string | null;
     /**
      * Encode a key value pair to be sent in the cookie header
+     *
+     * @param _ - Unused key parameter
+     * @param value - The value to encode
+     * @param stringify - Whether to stringify the value before encoding
+     * @returns The encoded cookie string or null if encoding fails
      */
     encode(_: string, value: any, stringify?: boolean): string | null;
     /**
      * Unsign a signed cookie value
+     *
+     * @param key - The cookie key
+     * @param value - The signed cookie value to unsign
+     * @returns The original value if valid signature, null otherwise
      */
     unsign(key: string, value: string): any;
     /**
      * Decrypt an encrypted cookie value
+     *
+     * @param key - The cookie key
+     * @param value - The encrypted cookie value to decrypt
+     * @returns The decrypted value or null if decryption fails
      */
     decrypt(key: string, value: string): any;
     /**
      * Decode an encoded cookie value
+     *
+     * @param _ - Unused key parameter
+     * @param value - The encoded cookie value to decode
+     * @param stringified - Whether the value was stringified during encoding
+     * @returns The decoded value or null if decoding fails
      */
     decode(_: 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
+     *
+     * @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,16 +1,29 @@
 import type { Encryption } from '@adonisjs/encryption';
 /**
  * Encrypt a value to be set as cookie
+ *
+ * @param key - The cookie key used for encryption
+ * @param value - The value to encrypt
+ * @param encryption - The encryption instance
+ * @returns The encrypted cookie string or null if value is null/undefined
  */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
 /**
  * Returns a boolean, if the unpack method from this module can attempt
  * to unpack encrypted value.
+ *
+ * @param encryptedValue - The encrypted value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(encryptedValue: string): boolean;
 /**
  * Attempts to unpack the encrypted cookie value. Returns null, when fails to do so.
  * Only call this method, when `canUnpack` returns true, otherwise runtime
  * exceptions can be raised.
+ *
+ * @param key - The cookie key used for decryption
+ * @param encryptedValue - The encrypted value to decrypt
+ * @param encryption - The encryption instance
+ * @returns The decrypted value or null if decryption fails
  */
 export declare function unpack(key: string, encryptedValue: string, encryption: Encryption): null | any;

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

@@ -1,15 +1,24 @@
 /**
  * Encodes a value into a base64 url encoded string to
  * be set as cookie
+ *
+ * @param value - The value to encode
+ * @returns The encoded cookie string or null if value is null/undefined
  */
 export declare function pack(value: any): null | string;
 /**
  * Returns true when this `unpack` method of this module can attempt
  * to unpack the encode value.
+ *
+ * @param encodedValue - The encoded value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(encodedValue: string): boolean;
 /**
  * Attempts to unpack the value by decoding it. Make sure to call, `canUnpack`
  * before calling this method
+ *
+ * @param encodedValue - The encoded value to decode
+ * @returns The decoded value or null if decoding fails
  */
 export declare function unpack(encodedValue: string): null | any;

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

@@ -2,15 +2,28 @@ import type { Encryption } from '@adonisjs/encryption';
 /**
  * Signs a value to be shared as a cookie. The signed output has a
  * hash to verify tampering with the original value
+ *
+ * @param key - The cookie key used for signing
+ * @param value - The value to sign
+ * @param encryption - The encryption instance
+ * @returns The signed cookie string or null if value is null/undefined
  */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
 /**
  * Returns a boolean, if the unpack method from this module can attempt
  * to unpack the signed value.
+ *
+ * @param signedValue - The signed value to check
+ * @returns True if the value can be unpacked by this module
  */
 export declare function canUnpack(signedValue: string): boolean;
 /**
  * Attempts to unpack the signed value. Make sure to call `canUnpack` before
  * calling this method.
+ *
+ * @param key - The cookie key used for verification
+ * @param signedValue - The signed value to verify and unpack
+ * @param encryption - The encryption instance
+ * @returns The original value or null if verification fails
  */
 export declare function unpack(key: string, signedValue: string, encryption: Encryption): null | any;

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

@@ -11,27 +11,45 @@ import type { Encryption } from '@adonisjs/encryption';
  */
 export declare class CookieParser {
     #private;
+    /**
+     * Create a new instance of CookieParser
+     *
+     * @param cookieHeader - The raw cookie header string from the request
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(cookieHeader: string, encryption: Encryption);
     /**
      * Attempts to decode a cookie by the name. When calling this method,
      * you are assuming that the cookie was just stringified in the first
      * place and not signed or encrypted.
+     *
+     * @param key - The cookie key to decode
+     * @param stringified - Whether the cookie value was stringified
+     * @returns The decoded cookie value or null if decoding fails
      */
     decode(key: string, stringified?: boolean): any | null;
     /**
      * Attempts to unsign a cookie by the name. When calling this method,
      * you are assuming that the cookie was signed in the first place.
+     *
+     * @param key - The cookie key to unsign
+     * @returns The original cookie value or null if unsigning fails
      */
     unsign(key: string): null | any;
     /**
      * Attempts to decrypt a cookie by the name. When calling this method,
      * you are assuming that the cookie was encrypted in the first place.
+     *
+     * @param key - The cookie key to decrypt
+     * @returns The decrypted cookie value or null if decryption fails
      */
     decrypt(key: string): null | any;
     /**
      * Returns an object of cookies key-value pair. Do note, the
      * cookies are not decoded, unsigned or decrypted inside this
      * list.
+     *
+     * @returns Raw cookies as key-value pairs
      */
     list(): Record<string, any>;
 }

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

@@ -7,6 +7,11 @@ import type { CookieOptions } from '../types/response.ts';
  */
 export declare class CookieSerializer {
     #private;
+    /**
+     * Create a new instance of CookieSerializer
+     *
+     * @param encryption - The encryption instance for cookie operations
+     */
     constructor(encryption: Encryption);
     /**
      * Encodes value as a plain cookie. By default, the plain value will be converted
@@ -18,11 +23,15 @@ export declare class CookieSerializer {
      *  serializer.encode('name', 'virk')
      *  serializer.encode('name', 'virk', { stringify: false })
      * ```
+     *
+     * @param key - The cookie key
+     * @param value - The value to encode
+     * @param options - Cookie encoding options
+     * @returns The serialized cookie string or null if encoding fails
      */
     encode(key: string, value: any, options?: Partial<CookieOptions & {
         /**
-         * @depreacted
-         * Instead use stringify option
+         * @depreacted Instead use stringify option
          */
         encode: boolean;
         stringify: boolean;
@@ -30,10 +39,20 @@ export declare class CookieSerializer {
     /**
      * Sign a key-value pair to a signed cookie. The signed value has a
      * verification hash attached to it to detect data tampering.
+     *
+     * @param key - The cookie key
+     * @param value - The value to sign
+     * @param options - Cookie options
+     * @returns The serialized signed cookie string or null if signing fails
      */
     sign(key: string, value: any, options?: Partial<CookieOptions>): string | null;
     /**
      * Encrypts a key-value pair to an encrypted cookie.
+     *
+     * @param key - The cookie key
+     * @param value - The value to encrypt
+     * @param options - Cookie options
+     * @returns The serialized encrypted cookie string or null if encryption fails
      */
     encrypt(key: string, value: any, options?: Partial<CookieOptions>): string | null;
 }

package/build/src/debug.d.ts

@@ -1,2 +1,15 @@
+/**
+ * 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("util").DebugLogger;
 export default _default;

package/build/src/define_config.d.ts

@@ -1,12 +1,28 @@
+import { type DeepPartial } from '@poppinss/utils/types';
 import type { ServerConfig } from './types/server.ts';
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
 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 { GetMiddlewareArgs, MiddlewareAsClass, ParsedGlobalMiddleware } from './types/middleware.ts';
+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;