tezx 2.0.11 → 3.0.0

package/core/context.d.ts

@@ -1,215 +1,260 @@
-import { CookieOptions, HTTPMethod, PathType, ResponseHeaders } from "../types/index.js";
-import { State } from "../utils/state.js";
-import { Request as RequestParser } from "./request.js";
-import { TezXServeOptions } from "./server.js";
-export declare class Context<T extends Record<string, any> = {}, Path extends PathType = any> {
+import { HttpBaseResponse, ResHeaderKey, ResponseInit } from "../types/index.js";
+import { TezXRequest } from "./request.js";
+export declare class Context<TEnv extends Record<string, any> = {}, TPath extends string = any> {
     #private;
     [key: string]: any;
+    /**
+     * The original Request object from the underlying platform (e.g., Node.js, Deno).
+     * Contains all headers and body data.
+     * @type {Request}
+     */
     rawRequest: Request;
     /**
-     * Environment variables and configuration
-     * @type {object}
+     * The URL associated with the current context.
+     *
+     * This is a read-only string representing the resource location or endpoint.
+     */
+    readonly url: string;
+    /**
+     * The native Response object associated with this context, if available.
+     *
+     * This property is set when a response has been created or is being manipulated directly.
+     * It may be undefined if the response has not yet been constructed.
+     *
+     * @type {Response | undefined}
+     * @remarks
+     * - When present, headers and status should be set directly on this object.
+     * - When undefined, internal header and status management is used.
      */
-    env: Record<string, any> & T;
+    res?: Response;
     /**
-     * Parser for handling and manipulating HTTP headers
-     * @type {Headers}
+     * Environment variables or shared state accessible in context.
+     * @type {Record<string, any> & TEnv}
      */
-    headers: Headers;
+    env: Record<string, any> & TEnv;
     /**
-     * Request path without query parameters
+     * Request pathname (URL path without domain).
+     * @readonly
      * @type {string}
      */
     readonly pathname: string;
     /**
-     * Full request URL including protocol and query string
+     * HTTP request method (e.g., GET, POST).
+     * @readonly
      * @type {string}
      */
-    readonly url: string;
+    readonly method: string;
     /**
-     * HTTP request method (GET, POST, PUT, DELETE, etc.)
-     * @type {HTTPMethod}
+     * Creates a new context instance.
+     *
+     * @param {Request} req - The native Request object.
+     * @param {ContextOptions<TEnv>} options - Context options including pathname, method, env, params, and args.
      */
-    readonly method: HTTPMethod;
+    constructor(req: Request, pathname: string, method: string, env: Record<string, any> & TEnv, args: any[]);
     /**
-     * Public state container for application data
-     * state storage for middleware and plugins
-     * @type {State}
+     * Gets the current HTTP status code.
+     * @returns {number} The HTTP status code.
      */
-    state: State;
-    protected readonly resBody?: BodyInit | null;
-    constructor(req: any, options: TezXServeOptions);
+    get getStatus(): number;
     /**
-     * Appends or set a value to an existing header or creates a new one.
-     * @param key - Header name.
-     * @param value - Value to append.
-     * @default {append:false}
+     * Sets the HTTP status code.
+     * @param {number} code - The HTTP status code.
      */
-    header(key: string, value: string, options?: {
-        append?: true;
-    }): this;
-    header(key: string, value: string | string[], options?: {
-        append?: false;
-    }): this;
+    set setStatus(code: number);
     /**
-     * Cookie handling utility with get/set/delete operations
-     * @returns {{
-     *  get: (name: string) => string | undefined,
-     *  all: () => Record<string, string>,
-     *  delete: (name: string, options?: CookieOptions) => void,
-     *  set: (name: string, value: string, options?: CookieOptions) => void
-     * }} Cookie handling interface
-     */
-    get cookies(): {
-        /**
-         * Get a specific cookie by name.
-         * @param {string} cookie - The name of the cookie to retrieve.
-         * @returns {string | undefined} - The cookie value or undefined if not found.
-         */
-        get: (cookie: string) => string;
-        /**
-         * Get all cookies as an object.
-         * @returns {Record<string, string>} - An object containing all cookies.
-         */
-        all: () => Record<string, string>;
-        /**
-         * Delete a cookie by setting its expiration to the past.
-         * @param {string} name - The name of the cookie to delete.
-         * @param {CookieOptions} [options] - Additional cookie options.
-         */
-        delete: (name: string, options?: CookieOptions) => void;
-        /**
-         * Set a new cookie with the given name, value, and options.
-         * @param {string} name - The name of the cookie.
-         * @param {string} value - The value of the cookie.
-         * @param {CookieOptions} [options] - Additional options like expiration.
-         */
-        set: (name: string, value: string, options?: CookieOptions) => void;
-    };
+     * Access the response headers.
+     *
+     * @remarks
+     * This returns the native {@link Headers} object associated with the response.
+     * It gives you full control over reading, setting, appending, and deleting headers
+     * using the standard Web Headers API.
+     *
+     * @example
+     * ```ts
+     * // Get a header value
+     * const contentType = ctx.headers.get("content-type")
+     *
+     * // Set or overwrite a header
+     * ctx.headers.set("x-powered-by", "tezx")
+     *
+     * // Append multiple values
+     * ctx.headers.append("set-cookie", "id=123")
+     * ctx.headers.append("set-cookie", "token=xyz")
+     *
+     * // Iterate all headers
+     * for (const [key, value] of ctx.headers.entries()) {
+     *   console.log(key, value)
+     * }
+     * ```
+     *
+     * @returns {Headers} The response headers object.
+     */
+    get headers(): Headers;
     /**
-     * Sends a JSON response.
-     * @param body - The response data.
-     * @param status - (Optional) HTTP status code (default: 200).
-     * @param headers - (Optional) Additional response headers.
-     * @returns Response object with JSON data.
-     */
-    json(body: object, status?: number, headers?: ResponseHeaders): Response;
-    json(body: object, headers?: ResponseHeaders): Response;
-    json(body: object, status?: number): Response;
-    /**
-     * Sends a response with any content type.
-     * Automatically determines content type if not provided.
-     * @param body - The response body.
-     * @param status - (Optional) HTTP status code.
-     * @param headers - (Optional) Additional response headers.
-     * @returns Response object.
-     */
-    send(body: any, status?: number, headers?: ResponseHeaders): Response;
-    send(body: any, headers?: ResponseHeaders): Response;
-    send(body: any, status?: number): Response;
+     * Sets or appends a header to the response.
+     *
+     * @param {string} key - Header name (e.g., "Content-Type").
+     * @param {string} value - Header value to set or append.
+     * @param {Object} [options] - Options to modify behavior.
+     * @param {boolean} [options.append=false] - If true, appends instead of overwriting.
+     * @returns {this} The context instance for chaining.
+     *
+     * @example
+     * ctx.setHeader("X-Custom", "Value");
+     * ctx.setHeader("Cache-Control", "no-cache", { append: true });
+     */
+    setHeader(key: ResHeaderKey, value: string, options?: {
+        append?: boolean;
+    }): this;
+    protected set params(params: Record<string, any>);
     /**
-     * Sends an HTML response.
-     * @param strings - The HTML content as a string. Supports `both template literals` and plain string input..
-     * @param status - (Optional) HTTP status code (default: 200).
-     * @param headers - (Optional) Additional response headers.
-     * @returns Response object with HTML data.
+     * Gets the wrapped request object (`TezXRequest`).
+     *
+     * Lazily initializes the wrapped request on first access.
+     *
+     * @returns {TezXRequest<TPath>} The wrapped request.
      */
-    html(strings: readonly string[], ...values: any[]): Response;
-    html(strings: string, status?: number, headers?: ResponseHeaders): Response;
-    html(strings: string, headers?: ResponseHeaders): Response;
-    html(strings: string, status?: number): Response;
+    get req(): TezXRequest<TPath>;
     /**
-     * Sends a plain text response.
-     * @param data - The text content.
-     * @param status - (Optional) HTTP status code (default: 200).
-     * @param headers - (Optional) Additional response headers.
-     * @returns Response object with plain text data.
+     * Gets the response body.
+     * @returns {*} The response body.
      */
-    text(data: string, status?: number, headers?: ResponseHeaders): Response;
-    text(data: string, headers?: ResponseHeaders): Response;
-    text(data: string, status?: number): Response;
+    get body(): any;
     /**
-     * Sends an XML response.
-     * @param data - The XML content.
-     * @param status - (Optional) HTTP status code (default: 200).
-     * @param headers - (Optional) Additional response headers.
-     * @returns Response object with XML data.
+     * Sets the response body.
+     * @param {*} value - The response body.
      */
-    xml(data: string, status?: number, headers?: ResponseHeaders): Response;
-    xml(data: string, headers?: ResponseHeaders): Response;
-    xml(data: string, status?: number): Response;
+    set body(value: any);
     /**
-     * HTTP status code..
-     * @param status - number.
-     * @returns Response object with context all method.
+     * Sets the HTTP response status code.
+     *
+     * @param {number} status - HTTP status code to set (e.g., 200, 404).
+     * @returns {this} The current context instance for method chaining.
+     *
+     * @example
+     * ctx.status(404).text("Not found");
      */
     status: (status: number) => this;
-    set setStatus(status: number);
-    get getStatus(): number;
     /**
-     * Redirects to a given URL.
-     * @param url - The target URL.
-     * @param status - (Optional) HTTP status code (default: 302).
-     * @returns Response object with redirect.
+     * Protected helper method to create a Response or PlainResponse
+     * based on runtime environment (Node.js or Web).
+     *
+     * @param {BodyInit | null} body - Response body content.
+     * @param {ResponseInit} [init] - Response initialization options.
+     * @returns {HttpBaseResponse} Response object suitable for runtime.
+     * @protected
      */
-    redirect(url: string, status?: number): Response;
+    newResponse(body: BodyInit | null, init?: ResponseInit): Response;
     /**
-     * Handles file downloads.
-     * @param filePath - The path to the file.
-     * @param fileName - The name of the downloaded file.
-     * @returns Response object for file download.
+     * Sends a plain text response.
+     *
+     * Automatically sets Content-Type to `text/plain; charset=utf-8`.
+     *
+     * @param {string} content - The plain text content.
+     * @param {ResponseInit} [init] - Optional response init.
+     * @returns {HttpBaseResponse} The response object.
      */
-    download(filePath: string, fileName: string): Promise<Response>;
+    text(content: string, init?: ResponseInit): HttpBaseResponse;
     /**
-     * Serves a file to the client.
-     * @param filePath - Absolute or relative path to the file.
-     * @param fileName - (Optional) The name of the send file.
-     * @param headers - (Optional) Additional headers.
-     * @returns Response object with the file stream.
+     * Sends an HTML response.
+     *
+     * Supports both:
+     * - Simple string: `ctx.html("<h1>Hello</h1>")`
+     * - Template literal: `ctx.html`<h1>${title}</h1>``
+     *
+     * Minimizes intermediate string allocations for lower GC overhead.
+     *
+     * @param {string | readonly string[]} strings - HTML string or template literal array.
+     * @param {...any[]} args - Values for template literals or a ResponseInit object if using a string.
+     * @returns {HttpBaseResponse} Constructed HTML response.
      */
-    sendFile(filePath: string, fileName?: string, headers?: ResponseHeaders): Promise<Response>;
-    sendFile(filePath: string, headers?: ResponseHeaders): Promise<Response>;
-    sendFile(filePath: string, fileName?: string): Promise<Response>;
+    html(strings: string, init?: ResponseInit): HttpBaseResponse;
+    html(strings: readonly string[], ...values: any[]): HttpBaseResponse;
     /**
-     * Getter that creates a standardized Request object from internal state
-     * @returns {Request} - Normalized request object combining:
-     * - Raw platform-specific request
-     * - Parsed headers
-     * - Route parameters
+     * Sends an XML response.
+     *
+     * Supports both:
+     * - Simple string: `ctx.xml("<note><to>User</to></note>")`
+     * - Template literal: `ctx.xml`<note><to>${user}</to></note>``
+     *
+     * Minimizes intermediate string allocations for lower GC overhead.
+     *
+     * @param {string | readonly string[]} strings - XML string or template literal array.
+     * @param {...any[]} args - Values for template literals or a ResponseInit object if using a string.
+     * @returns {HttpBaseResponse} Constructed XML response.
+     */
+    xml(strings: string, init?: ResponseInit): HttpBaseResponse;
+    xml(strings: readonly string[], ...values: any[]): HttpBaseResponse;
+    /**
+     * Sends a JSON response.
+     *
+     * Automatically sets Content-Type to `application/json; charset=utf-8`.
+     *
+     * @param {object} json - JSON-serializable object.
+     * @param {ResponseInit} [init] - Optional response init overrides.
+     * @returns {HttpBaseResponse} A JSON response object.
      *
      * @example
-     * // Get standardized request
-     * const request = ctx.req;
-     * // Access route params
-     * const id = request.params.get('id');
+     * ctx.json({ success: true });
      */
-    get req(): RequestParser<Path>;
-    protected set params(params: Record<string, any>);
+    json(json: object, init?: ResponseInit): HttpBaseResponse;
     /**
-     * Set response body to be passed between middlewares or returned as final output.
+     * Sends a response with automatic content type detection.
      *
-     * 🔄 Use-case:
-     * - Middleware or route handlers can set this value to share data.
-     * - If no explicit Response is returned (e.g., `ctx.json()` or `new Response()`),
-     *   then this body will be auto-wrapped into a `Response` by the framework.
+     * Uses `determineContentTypeBody` utility to infer Content-Type.
      *
-     * ⚠️ Note:
-     * Always use `return next()` or an explicit return like `return ctx.json(...)`
-     * to ensure proper flow control and response resolution.
+     * @param {*} body - Response body.
+     * @param {ResponseInit} [init] - Optional response init.
+     * @returns {HttpBaseResponse} The response object.
+     */
+    send(body: any, init?: ResponseInit): HttpBaseResponse;
+    /**
+     * Sends an HTTP redirect response to the specified URL.
      *
-     * @param body - The response content (string, object, etc).
+     * @param {string} url - Target URL to redirect to.
+     * @param {number} [status=302] - Redirect HTTP status code.
+     * @returns {Response} A native redirect response.
+     *
+     * @example
+     * ctx.redirect("/login", 301);
      */
-    set body(body: any);
+    redirect(url: string, status?: number): Response;
     /**
-     * Get the current response body.
+     * Sends a file as a downloadable response.
+     *
+     * @param {string} filePath - Absolute file path on the server.
+     * @param {string} filename - Filename to present to the client.
+     * @returns {Promise<HttpBaseResponse>} Response that triggers download.
      *
-     * 🧠 Use-case:
-     * - Allows middleware or route handler to access any pre-set data
-     *   from earlier in the middleware chain.
-     * - Common for situations where response is deferred or centrally handled.
+     * @throws {Error} If file is not found.
      *
-     * @returns The currently stored response body.
+     * @example
+     * await ctx.download("/files/report.pdf", "report.pdf");
      */
-    get body(): any;
-    protected get params(): Record<string, any>;
+    download(filePath: string, filename: string): Promise<HttpBaseResponse>;
+    /**
+     * Sends a file as a stream response.
+     *
+     * Automatically sets appropriate `Content-Type` and `Content-Length`.
+     * Adds `Content-Disposition` if filename is provided.
+     *
+     * @param {string} filePath - Absolute path to the file.
+     * @param {Object} [init] - Response options and optional download filename.
+     * @param {string} [init.filename] - Name to suggest for download.
+     * @returns {Promise<HttpBaseResponse>} A streamable file response.
+     *
+     * @throws {Error} If the file does not exist.
+     *
+     * @example
+     * await ctx.sendFile("/path/to/image.png");
+     */
+    sendFile(filePath: string, init?: ResponseInit & {
+        filename?: string;
+    }): Promise<HttpBaseResponse>;
+    /**
+     *@property bun [server]
+     *@property deno [connInfo]
+     *@property node [res, server]
+     */
+    protected get args(): any;
 }