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

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

@@ -0,0 +1,37 @@
+import { type ClientRouteMatchItTokens, type ClientRouteJSON, type URLOptions } from './types.ts';
+/**
+ * Finds a route by its identifier across domains.
+ *
+ * Searches for routes by name, pattern, or controller reference. When no domain
+ * is specified, searches across all domains. Supports legacy lookup strategies
+ * for backwards compatibility.
+ *
+ * @param domainsRoutes - Object mapping domain names to route arrays
+ * @param routeIdentifier - Route name, pattern, or controller reference to find
+ * @param domain - Optional domain to limit search scope
+ * @param method - Optional HTTP method to filter routes
+ * @param disableLegacyLookup - Whether to disable pattern and controller lookup
+ *
+ * @example
+ * ```ts
+ * const route = findRoute(routes, 'users.show', 'api', 'GET')
+ * const route2 = findRoute(routes, '/users/:id', undefined, 'GET')
+ * ```
+ */
+export declare function findRoute<Route extends ClientRouteJSON>(domainsRoutes: {
+    [domain: string]: Route[];
+}, routeIdentifier: string, domain?: string, method?: string, disableLegacyLookup?: boolean): null | Route;
+/**
+ * Makes URL for a given route pattern using its parsed tokens. The
+ * tokens could be generated using the "parseRoute" method.
+ *
+ * @param pattern - The route pattern
+ * @param tokens - Array of parsed route tokens
+ * @param searchParamsStringifier - Function to stringify query parameters
+ * @param params - Route parameters as array or object
+ * @param options - URL options
+ * @returns {string} The generated URL
+ */
+export declare function createURL(pattern: string, tokens: Pick<ClientRouteMatchItTokens, 'val' | 'type' | 'end'>[], searchParamsStringifier: (qs: Record<string, any>) => string, params?: any[] | {
+    [param: string]: any;
+}, options?: URLOptions): string;

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

@@ -2,50 +2,18 @@
  * Types shared with the client. These should never import other types
  */
 import { type Prettify } from '@poppinss/utils/types';
-/**
- * Options accepted by "url" and "route" helper methods
- */
-export type URLOptions = {
-    qs?: Record<string, any>;
-    prefixUrl?: string;
-};
-/**
- * Options accepted by "signedUrl" and "signedRoute" helper methods
- */
-export type SignedURLOptions = URLOptions & {
-    expiresIn?: string | number;
-    purpose?: string;
-};
-/**
- * Returns params for a route identifier
- */
-export type RouteBuilderArguments<Routes, Method extends keyof Routes, Identifier extends keyof Routes[Method], Options extends any = URLOptions> = Routes extends LookupList ? Prettify<undefined extends Routes[Method][Identifier]['params'] ? [identifier: Identifier, params?: undefined, options?: Options] : [undefined] extends [Routes[Method][Identifier]['params']] ? [
-    identifier: Identifier,
-    params?: Routes[Method][Identifier]['params'] | Routes[Method][Identifier]['paramsTuple'],
-    options?: Options
-] : [
-    identifier: Identifier,
-    params: Routes[Method][Identifier]['params'] | Routes[Method][Identifier]['paramsTuple'],
-    options?: Options
-]> : never;
-/**
- * Shape of a route param matcher
- */
-export type RouteMatcher = {
-    match?: RegExp;
-    cast?: (value: string) => any;
-};
-/**
- * Route token stored by matchit library
- */
-export type MatchItRouteToken = RouteMatcher & {
+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;
 };
 /**
- * Representation of route shared with the client
+ * Complete route definition with all metadata, handlers, and execution context
  */
 export type ClientRouteJSON = {
     /**
@@ -57,23 +25,30 @@ export type ClientRouteJSON = {
      */
     pattern: string;
     /**
-     * HTTP methods, the route responds to.
+     * Route handler
      */
-    methods: string[];
+    handler?: unknown;
     /**
-     * Route domain
+     * Tokens to be used to construct the route URL
      */
-    domain: string;
+    tokens: ClientRouteMatchItTokens[];
     /**
-     * Reference to the route handler
+     * HTTP methods, the route responds to.
      */
-    handler: {
-        reference?: any;
-    } | Function;
+    methods: string[];
     /**
-     * Tokens to be used to construct the route URL
+     * The domain for which the route is registered.
      */
-    tokens: MatchItRouteToken[];
+    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
@@ -82,16 +57,39 @@ export type ClientRouteJSON = {
  * 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]: {
-        [identifier: string]: {
-            paramsTuple?: [...any[]];
-            params?: {
-                [name: string]: any;
-            };
-        };
+        /** 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
@@ -104,7 +102,7 @@ export type LookupList = {
  * 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<Routes, 'ALL', Identifier, Options>) => string) & {
+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.
@@ -114,9 +112,13 @@ export type UrlFor<Routes extends LookupList, Options extends any = URLOptions>
      * urlFor.get('users.store', [1]) // Error: Route not found GET@users/store
      * ```
      */
-    get<RouteIdentifier extends keyof Routes['GET'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'GET', RouteIdentifier, Options>): {
-        method: 'get';
+    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
@@ -127,9 +129,13 @@ export type UrlFor<Routes extends LookupList, Options extends any = URLOptions>
      * urlFor.post('users.show', [1]) // Error: Route not found POST@users.show
      * ```
      */
-    post<RouteIdentifier extends keyof Routes['POST'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'POST', RouteIdentifier, Options>): {
-        method: 'post';
+    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
@@ -140,9 +146,13 @@ export type UrlFor<Routes extends LookupList, Options extends any = URLOptions>
      * urlFor.put('users.show', [1]) // Error: Route not found PUT@users.show
      * ```
      */
-    put<RouteIdentifier extends keyof Routes['PUT'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'PUT', RouteIdentifier, Options>): {
-        method: 'put';
+    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
@@ -153,9 +163,13 @@ export type UrlFor<Routes extends LookupList, Options extends any = URLOptions>
      * urlFor.put('users.show', [1]) // Error: Route not found PATCH@users.show
      * ```
      */
-    patch<RouteIdentifier extends keyof Routes['PATCH'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'PATCH', RouteIdentifier, Options>): {
-        method: 'patch';
+    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
@@ -166,16 +180,24 @@ export type UrlFor<Routes extends LookupList, Options extends any = URLOptions>
      * urlFor.delete('users.show', [1]) // Error: Route not found DELETE@users.show
      * ```
      */
-    delete<RouteIdentifier extends keyof Routes['DELETE'] & string>(...[identifier, params, options]: RouteBuilderArguments<Routes, 'DELETE', RouteIdentifier, Options>): {
-        method: 'delete';
+    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<Routes, Method, RouteIdentifier, Options>): {
+    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

@@ -1,13 +1,15 @@
-import { type RouterClient } from './router.ts';
-import { type UrlFor, type LookupList, type URLOptions, type ClientRouteJSON, type MatchItRouteToken } from './types.ts';
-/**
- * Makes URL for a given route pattern. The route pattern could be an
- * identifier or an array of tokens.
- */
-export declare function createURL(identifier: string, tokens: Pick<MatchItRouteToken, 'val' | 'type' | 'end'>[], searchParamsStringifier: (qs: Record<string, any>) => string, params?: any[] | {
-    [param: string]: any;
-}, options?: URLOptions): string;
+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>(router: RouterClient<ClientRouteJSON>, searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes>;
+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

@@ -1,5 +1,5 @@
 import type { Encryption } from '@adonisjs/encryption';
-import type { CookieOptions } from '../types/response.js';
+import type { CookieOptions } from '../types/response.ts';
 /**
  * Cookies serializer is used to serialize a value to be set on the `Set-Cookie`
  * header. You can `encode`, `sign` on `encrypt` cookies using the serializer
@@ -7,6 +7,11 @@ import type { CookieOptions } from '../types/response.js';
  */
 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 { ServerConfig } from './types/server.js';
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
+import { type DeepPartial } from '@poppinss/utils/types';
+import type { ServerConfig } from './types/server.ts';
 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 {};