@adonisjs/http-server 8.0.0-next.4 → 8.0.0-next.6

package/build/src/request.d.ts

@@ -15,25 +15,42 @@ import type { HttpContext } from './http_context/main.ts';
  */
 export declare class Request extends Macroable {
     #private;
+    /** Native Node.js incoming message instance */
     request: IncomingMessage;
+    /** Native Node.js server response instance */
     response: ServerResponse;
     /**
-     * Parsed URL with query string stored as a string.
+     * Parsed URL with query string stored as a string and decode flag
      */
     parsedUrl: {
+        /** The pathname portion of the URL */
         pathname: string;
+        /** The query string portion of the URL */
         query: string;
+        /** Flag indicating whether parameters should be decoded */
         shouldDecodeParam: boolean;
     };
     /**
-     * The ctx will be set by the context itself. It creates a circular
-     * reference
+     * HTTP context reference - creates a circular reference when set by the context
      */
     ctx?: HttpContext;
-    constructor(request: IncomingMessage, response: ServerResponse, encryption: Encryption, config: RequestConfig, qsParser: Qs);
+    /**
+     * Creates a new Request instance wrapping the native Node.js HTTP request
+     * @param request - Native Node.js incoming message instance
+     * @param response - Native Node.js server response instance
+     * @param encryption - Encryption module for cookie and URL signing
+     * @param config - Request configuration options
+     * @param qsParser - Query string parser instance
+     */
+    constructor(
+    /** Native Node.js incoming message instance */
+    request: IncomingMessage, 
+    /** Native Node.js server response instance */
+    response: ServerResponse, encryption: Encryption, config: RequestConfig, qsParser: Qs);
     /**
      * Returns the request id from the `x-request-id` header. The
      * header is untouched, if it already exists.
+     * @returns The request ID or undefined if not found/generated
      */
     id(): string | undefined;
     /**
@@ -43,44 +60,57 @@ export declare class Request extends Macroable {
      *
      * This method is supposed to be invoked by the body parser and must be called only
      * once. For further mutations make use of `updateBody` method.
+     * @param body - Parsed request body data
+     * @returns {void}
      */
     setInitialBody(body: Record<string, any>): void;
     /**
      * Update the request body with new data object. The `all` property
      * will be re-computed by merging the query string and request
      * body.
+     * @param body - New request body data to set
+     * @returns {void}
      */
     updateBody(body: Record<string, any>): void;
     /**
      * Update the request raw body. Bodyparser sets this when unable to parse
      * the request body or when request is multipart/form-data.
+     * @param rawBody - Raw request body as string
+     * @returns {void}
      */
     updateRawBody(rawBody: string): void;
     /**
      * Update the query string with the new data object. The `all` property
      * will be re-computed by merging the query and the request body.
+     * @param data - New query string data to set
+     * @returns {void}
      */
     updateQs(data: Record<string, any>): void;
     /**
      * Returns route params
+     * @returns {Record<string, any>} Object containing route parameters
      */
     params(): Record<string, any>;
     /**
      * Returns the query string object by reference
+     * @returns {Record<string, any>} Object containing parsed query string parameters
      */
     qs(): Record<string, any>;
     /**
      * Returns reference to the request body
+     * @returns {Record<string, any>} Object containing parsed request body
      */
     body(): Record<string, any>;
     /**
      * Returns reference to the merged copy of request body
      * and query string
+     * @returns {Record<string, any>} Object containing merged request body and query parameters
      */
     all(): Record<string, any>;
     /**
      * Returns reference to the merged copy of original request
      * query string and body
+     * @returns {Record<string, any>} Object containing original merged request data
      */
     original(): Record<string, any>;
     /**
@@ -88,6 +118,7 @@ export declare class Request extends Macroable {
      *
      * Ideally you must be dealing with the parsed body accessed using [[input]], [[all]] or
      * [[post]] methods. The `raw` body is always a string.
+     * @returns {string | null} Raw request body as string or null if not set
      */
     raw(): string | null;
     /**
@@ -101,6 +132,9 @@ export declare class Request extends Macroable {
      * // with default value
      * request.input('username', 'virk')
      * ```
+     * @param key - Key to lookup in request data
+     * @param defaultValue - Default value when key is not found
+     * @returns Value from request data or default value
      */
     input(key: string, defaultValue?: any): any;
     /**
@@ -113,6 +147,9 @@ export declare class Request extends Macroable {
      * // with default value
      * request.param('id', 1)
      * ```
+     * @param key - Parameter key to lookup
+     * @param defaultValue - Default value when parameter is not found
+     * @returns Value from route parameters or default value
      */
     param(key: string, defaultValue?: any): any;
     /**
@@ -122,6 +159,8 @@ export declare class Request extends Macroable {
      * ```js
      * request.except(['_csrf'])
      * ```
+     * @param keys - Array of keys to exclude from the result
+     * @returns {Record<string, any>} Object with all request data except specified keys
      */
     except(keys: string[]): Record<string, any>;
     /**
@@ -131,6 +170,8 @@ export declare class Request extends Macroable {
      * ```js
      * request.only(['username', 'age'])
      * ```
+     * @param keys - Array of keys to include in the result
+     * @returns {{ [K in T]: any }} Object with only the specified keys from request data
      */
     only<T extends string>(keys: T[]): {
         [K in T]: any;
@@ -144,6 +185,7 @@ export declare class Request extends Macroable {
      * ```js
      * request.intended()
      * ```
+     * @returns {string} Original HTTP method from the request
      */
     intended(): string;
     /**
@@ -159,15 +201,20 @@ export declare class Request extends Macroable {
      * ```js
      * request.method()
      * ```
+     * @returns {string} HTTP method (potentially spoofed)
      */
     method(): string;
     /**
      * Returns a copy of headers as an object
+     * @returns {IncomingHttpHeaders} Object containing all HTTP headers
      */
     headers(): IncomingHttpHeaders;
     /**
      * Returns value for a given header key. The default value is
      * used when original value is `undefined`.
+     * @param key - Header name to lookup
+     * @param defaultValue - Default value when header is not found
+     * @returns {string | undefined} Header value or default value if not found
      */
     header(key: string, defaultValue?: any): string | undefined;
     /**
@@ -200,6 +247,7 @@ export declare class Request extends Macroable {
      * ```
      *
      * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     * @returns {string} Client IP address
      */
     ip(): string;
     /**
@@ -219,6 +267,7 @@ export declare class Request extends Macroable {
      * ```
      *
      * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     * @returns {string[]} Array of IP addresses from most to least trusted
      */
     ips(): string[];
     /**
@@ -240,12 +289,14 @@ export declare class Request extends Macroable {
      * ```
      *
      * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     * @returns {string} Request protocol ('http' or 'https')
      */
     protocol(): string;
     /**
      * Returns a boolean telling if request is served over `https`
      * or not. Check [[protocol]] method to know how protocol is
      * fetched.
+     * @returns {boolean} True if request is served over HTTPS
      */
     secure(): boolean;
     /**
@@ -264,6 +315,7 @@ export declare class Request extends Macroable {
      * ```
      *
      * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     * @returns {string | null} Request host or null if not found
      */
     host(): string | null;
     /**
@@ -282,6 +334,7 @@ export declare class Request extends Macroable {
      * ```
      *
      * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     * @returns {string | null} Request hostname (without port) or null if not found
      */
     hostname(): string | null;
     /**
@@ -289,16 +342,19 @@ export declare class Request extends Macroable {
      * returned if [[hostname]] is `null` or is an IP address.
      *
      * Also `www` is not considered as a subdomain
+     * @returns {string[]} Array of subdomains (excluding www)
      */
     subdomains(): string[];
     /**
      * Returns a boolean telling, if request `X-Requested-With === 'xmlhttprequest'`
      * or not.
+     * @returns {boolean} True if request is an AJAX request
      */
     ajax(): boolean;
     /**
      * Returns a boolean telling, if request has `X-Pjax` header
      * set or not
+     * @returns {boolean} True if request is a PJAX request
      */
     pjax(): boolean;
     /**
@@ -311,6 +367,8 @@ export declare class Request extends Macroable {
      * // include query string
      * request.url(true)
      * ```
+     * @param includeQueryString - Whether to include query string in the URL
+     * @returns {string} Request pathname, optionally with query string
      */
     url(includeQueryString?: boolean): string;
     /**
@@ -324,10 +382,14 @@ export declare class Request extends Macroable {
      * // include query string
      * request.completeUrl(true)
      * ```
+     * @param includeQueryString - Whether to include query string in the URL
+     * @returns {string} Complete URL including protocol and host
      */
     completeUrl(includeQueryString?: boolean): string;
     /**
      * Find if the current HTTP request is for the given route or the routes
+     * @param routeIdentifier - Route name, pattern, or handler reference to match
+     * @returns {boolean} True if the request matches any of the given route identifiers
      */
     matchesRoute(routeIdentifier: string | string[]): boolean;
     /**
@@ -357,6 +419,8 @@ export declare class Request extends Macroable {
      *  // process XML
      * }
      * ```
+     * @param types - Array of content types to match against
+     * @returns {string | null} Best matching content type or null if no match
      */
     is(types: string[]): string | null;
     /**
@@ -379,6 +443,8 @@ export declare class Request extends Macroable {
      *     // decide yourself
      * }
      * ```
+     * @param types - Array of types to match against Accept header
+     * @returns {T | null} Best matching accept type or null if no match
      */
     accepts<T extends string>(types: T[]): T | null;
     /**
@@ -387,6 +453,7 @@ export declare class Request extends Macroable {
      *
      * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
      * docs too.
+     * @returns {string[]} Array of accepted types in preference order
      */
     types(): string[];
     /**
@@ -409,6 +476,8 @@ export declare class Request extends Macroable {
      *     return view.render('about', { lang: 'en' })
      * }
      * ```
+     * @param languages - Array of languages to match against Accept-Language header
+     * @returns {T | null} Best matching language or null if no match
      */
     language<T extends string>(languages: T[]): T | null;
     /**
@@ -417,6 +486,7 @@ export declare class Request extends Macroable {
      *
      * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
      * docs too.
+     * @returns {string[]} Array of accepted languages in preference order
      */
     languages(): string[];
     /**
@@ -437,6 +507,8 @@ export declare class Request extends Macroable {
      *     // make ISO-8859-1 friendly response
      * }
      * ```
+     * @param charsets - Array of charsets to match against Accept-Charset header
+     * @returns {T | null} Best matching charset or null if no match
      */
     charset<T extends string>(charsets: T[]): T | null;
     /**
@@ -445,6 +517,7 @@ export declare class Request extends Macroable {
      *
      * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
      * docs too.
+     * @returns {string[]} Array of accepted charsets in preference order
      */
     charsets(): string[];
     /**
@@ -455,18 +528,22 @@ export declare class Request extends Macroable {
      *
      * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
      * docs too.
+     * @param encodings - Array of encodings to match against Accept-Encoding header
+     * @returns {T | null} Best matching encoding or null if no match
      */
     encoding<T extends string>(encodings: T[]): T | null;
     /**
-     * Return the charsets that the request accepts, in the order of the
+     * Return the encodings that the request accepts, in the order of the
      * client's preference (most preferred first).
      *
      * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
      * docs too.
+     * @returns {string[]} Array of accepted encodings in preference order
      */
     encodings(): string[];
     /**
      * Returns a boolean telling if request has body
+     * @returns {boolean} True if request contains a body
      */
     hasBody(): boolean;
     /**
@@ -492,30 +569,44 @@ export declare class Request extends Macroable {
      *   response.send(responseBody)
      * }
      * ```
+     * @returns {boolean} True if client cache is fresh (should return 304)
      */
     fresh(): boolean;
     /**
      * Opposite of [[fresh]]
+     * @returns {boolean} True if client cache is stale (should send new response)
      */
     stale(): boolean;
     /**
      * Returns all parsed and signed cookies. Signed cookies ensures
      * that their value isn't tampered.
+     * @returns {{ [key: string]: any }} Object containing all parsed cookies
      */
-    cookiesList(): Record<string, any>;
+    cookiesList(): {
+        [key: string]: any;
+    };
     /**
      * Returns value for a given key from signed cookies. Optional
      * defaultValue is returned when actual value is undefined.
+     * @param key - Cookie name to lookup
+     * @param defaultValue - Default value when cookie is not found
+     * @returns Cookie value or default value if not found
      */
     cookie(key: string, defaultValue?: string): any;
     /**
-     * Returns value for a given key from signed cookies. Optional
+     * Returns value for a given key from encrypted cookies. Optional
      * defaultValue is returned when actual value is undefined.
+     * @param key - Cookie name to lookup
+     * @param defaultValue - Default value when cookie is not found
+     * @returns Decrypted cookie value or default value if not found
      */
     encryptedCookie(key: string, defaultValue?: string): any;
     /**
      * Returns value for a given key from unsigned cookies. Optional
      * defaultValue is returned when actual value is undefined.
+     * @param key - Cookie name to lookup
+     * @param options - Options object with defaultValue and encoded flag
+     * @returns Plain cookie value or default value if not found
      */
     plainCookie(key: string, options?: {
         defaultValue?: string;
@@ -523,12 +614,15 @@ export declare class Request extends Macroable {
     }): any;
     plainCookie(key: string, defaultValue?: string, encoded?: boolean): any;
     /**
-     * Returns a boolean telling if a signed url as a valid signature
+     * Returns a boolean telling if a signed url has a valid signature
      * or not.
+     * @param purpose - Optional purpose for signature verification
+     * @returns {boolean} True if the signed URL has a valid signature
      */
     hasValidSignature(purpose?: string): boolean;
     /**
      * Serializes request to JSON format
+     * @returns Object representation of the request
      */
     serialize(): {
         id: string | undefined;
@@ -539,13 +633,16 @@ export declare class Request extends Macroable {
         headers: IncomingHttpHeaders;
         method: string;
         protocol: string;
-        cookies: Record<string, any>;
+        cookies: {
+            [key: string]: any;
+        };
         hostname: string | null;
         ip: string;
         subdomains: Record<string, any>;
     };
     /**
      * toJSON copy of the request
+     * @returns JSON representation of the request
      */
     toJSON(): {
         id: string | undefined;
@@ -556,7 +653,9 @@ export declare class Request extends Macroable {
         headers: IncomingHttpHeaders;
         method: string;
         protocol: string;
-        cookies: Record<string, any>;
+        cookies: {
+            [key: string]: any;
+        };
         hostname: string | null;
         ip: string;
         subdomains: Record<string, any>;