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

package/build/src/redirect.d.ts

@@ -2,40 +2,112 @@ import type { IncomingMessage } from 'node:http';
 import type { Qs } from './qs.ts';
 import type { Response } from './response.ts';
 import type { Router } from './router/main.ts';
-import type { RoutesList, URLOptions, GetRoutesForMethod, RouteBuilderArguments } from './types/url_builder.ts';
+import type { RoutesList, LookupList, URLOptions, GetRoutesForMethod, RouteBuilderArguments } from './types/url_builder.ts';
 /**
- * Exposes the API to construct redirect routes
+ * Provides a fluent API for constructing HTTP redirect responses.
+ *
+ * The Redirect class allows you to build redirects with custom status codes,
+ * query string forwarding, and route-based URL generation. It supports both
+ * direct URL redirects and route-based redirects using registered route names.
+ *
+ * @example
+ * ```ts
+ * // Basic redirect
+ * return response.redirect('https://example.com')
+ *
+ * // Redirect to a route
+ * return response.redirect().toRoute('users.show', { id: 1 })
+ *
+ * // Redirect with status code and query string
+ * return response.redirect()
+ *   .status(301)
+ *   .withQs({ utm_source: 'newsletter' })
+ *   .toPath('/dashboard')
+ * ```
  */
 export declare class Redirect {
     #private;
+    /**
+     * Creates a new Redirect instance for handling HTTP redirects
+     * @param request - Node.js incoming HTTP request
+     * @param response - AdonisJS response instance
+     * @param router - AdonisJS router instance
+     * @param qs - Query string parser instance
+     */
     constructor(request: IncomingMessage, response: Response, router: Router, qs: Qs);
     /**
-     * Set a custom status code.
+     * Sets a custom HTTP status code for the redirect response
+     * @param statusCode - HTTP status code to use (e.g., 301, 302, 307)
+     * @returns {this} The Redirect instance for method chaining
      */
     status(statusCode: number): this;
     /**
-     * Clearing query string values added using the
-     * "withQs" method
+     * Clears any query string values previously added using the withQs method
+     * @returns {this} The Redirect instance for method chaining
      */
     clearQs(): this;
     /**
-     * Define query string for the redirect. Not passing
-     * any value will forward the current request query
-     * string.
+     * Forwards the current request's query string to the redirect URL
+     *
+     * Use this overload when you want to preserve all existing query parameters
+     * from the current request in the redirect URL.
+     *
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * // If current URL is '/search?q=hello&page=2'
+     * response.redirect().withQs().toPath('/results')
+     * // Redirects to: '/results?q=hello&page=2'
+     * ```
      */
     withQs(): this;
+    /**
+     * Adds multiple query string parameters to the redirect URL
+     *
+     * Use this overload when you want to add several query parameters at once
+     * using an object with key-value pairs.
+     *
+     * @param values - Object containing query parameter names and values
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * response.redirect().withQs({ page: 1, sort: 'name' }).toPath('/users')
+     * // Redirects to: '/users?page=1&sort=name'
+     * ```
+     */
     withQs(values: Record<string, any>): this;
+    /**
+     * Adds a single query string parameter to the redirect URL
+     *
+     * Use this overload when you want to add just one query parameter
+     * with a specific name and value.
+     *
+     * @param name - The query parameter name
+     * @param value - The query parameter value
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * response.redirect().withQs('success', 'true').toPath('/dashboard')
+     * // Redirects to: '/dashboard?success=true'
+     * ```
+     */
     withQs(name: string, value: any): this;
     /**
-     * Redirect to the previous path.
+     * Redirects to the previous path using the Referer header
+     * Falls back to '/' if no referrer is found
      */
     back(): void;
     /**
-     * Redirect the request using a route identifier.
+     * Redirects to a route using its identifier (name, pattern, or handler reference)
+     * @param args - Route identifier, parameters, and options for URL building
      */
-    toRoute<Identifier extends keyof GetRoutesForMethod<'GET'> & string>(...args: RouteBuilderArguments<RoutesList, Identifier, 'GET', URLOptions>): void;
+    toRoute<Identifier extends keyof GetRoutesForMethod<RoutesList, 'GET'> & string>(...args: RoutesList extends LookupList ? RouteBuilderArguments<Identifier, RoutesList['GET'][Identifier], URLOptions> : []): void;
     /**
-     * Redirect the request using a path.
+     * Redirects to a specific URL path
+     * @param url - Target URL path for redirection
      */
     toPath(url: string): void;
 }

package/build/src/request.d.ts

@@ -15,25 +15,49 @@ 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);
     /**
-     * Returns the request id from the `x-request-id` header. The
-     * header is untouched, if it already exists.
+     * 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.
+     *
+     * If the header doesn't exist and request ID generation is enabled,
+     * a new UUID will be generated and added to the request headers.
+     *
+     * @example
+     * ```ts
+     * const requestId = request.id()
+     * console.log(requestId) // '550e8400-e29b-41d4-a716-446655440000'
+     * ```
      */
     id(): string | undefined;
     /**
@@ -43,44 +67,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 +125,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 +139,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 +154,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 +166,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 +177,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 +192,7 @@ export declare class Request extends Macroable {
      * ```js
      * request.intended()
      * ```
+     * @returns {string} Original HTTP method from the request
      */
     intended(): string;
     /**
@@ -159,15 +208,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 +254,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 +274,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 +296,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 +322,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 +341,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 +349,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 +374,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 +389,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 +426,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 +450,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 +460,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 +483,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 +493,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 +514,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 +524,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 +535,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 +576,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 +621,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 +640,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 +660,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>;