tezx 2.0.11 → 3.0.0

package/core/request.d.ts

@@ -1,136 +1,96 @@
-import { ExtractParamsFromPath, FormDataOptions, HTTPMethod, NetAddr, PathType } from "../types/index.js";
-import type { UrlRef } from "../utils/url.js";
-import { TezXServeOptions } from "./server.js";
-export declare class Request<Path extends PathType = any> {
+import { ExtractParamsFromPath, HTTPMethod, NetAddr, ReqHeaderKey, RequestHeaders } from "../types/index.js";
+/**
+ * A wrapper around the raw HTTP request that provides convenient access to URL, headers, body parsing, and route parameters.
+ *
+ * @template Path - The route path string used to extract dynamic route parameters.
+ */
+export declare class TezXRequest<Path extends string = any> {
+    #private;
     /**
-     * Full request URL including protocol and query string
+     * Full request URL including protocol and query string.
      * @type {string}
      */
     readonly url: string;
     /**
-     * HTTP request method (GET, POST, PUT, DELETE, etc.)
+     * HTTP request method (e.g., GET, POST, PUT, DELETE).
      * @type {HTTPMethod}
      */
     readonly method: HTTPMethod;
     /**
-     * Request path without query parameters
+     * Request path without query parameters.
      * @type {string}
      */
     readonly pathname: string;
-    /** Parsed URL reference containing components like query parameters, pathname, etc. */
-    readonly urlRef: UrlRef;
-    /** Query parameters extracted from the URL */
-    readonly query: Record<string, any>;
-    protected rawRequest: any;
     /**
-     * Retrieve a parameter by name.
-     * @param name - The parameter name.
-     * @returns The parameter value if found, or undefined.
+     * Route parameters extracted from the path.
+     * @type {ExtractParamsFromPath<Path>}
      */
     readonly params: ExtractParamsFromPath<Path>;
     /**
-     * Represents the remote address details of a connected client.
+     * Remote address details of the connected client.
+     * @requires injectRemoteAddress middleware.
+     * @typedef {Object} NetAddr
+     * @property {string} [transport] - Transport protocol (e.g., "tcp", "udp").
+     * @property {"IPv4" | "IPv6" | "Unix"} [family] - Address family.
+     * @property {string} [hostname] - Hostname or IP address.
+     * @property {number} [port] - Port number.
+     * @type {NetAddr}
+     * @default {}
+     */
+    remoteAddress: NetAddr;
+    /**
+     * Creates an instance of TezXRequest.
      *
-     * @property {TransportType} [transport] - The transport protocol used (e.g., `"tcp"`, `"udp"`).
-     * @property {"IPv4" | "IPv6" | "Unix"} [family] - The address family, indicating whether the connection is over IPv4, IPv6, or a Unix socket.
-     * @property {string} [hostname] - The hostname or IP address of the remote client.
-     * @property {number} [port] - The remote client's port number.
-     * @default {{}}
+     * @param {Request} req - The raw Request object.
+     * @param {string} method - The HTTP method.
+     * @param {string} pathname - The request path without query parameters.
+     * @param {ExtractParamsFromPath<Path>} params - Route parameters extracted from the path.
+     */
+    constructor(req: Request, method: string, pathname: string, params: ExtractParamsFromPath<Path>);
+    /**
+     * Gets a single header value by name, or all headers as an object if no name is provided.
      *
-     * @example
-     * ```typescript
-     * ctx.req.remoteAddress
-     * ```
+     * @param {ReqHeaderKey} [header] - The header name.
+     * @returns {string | undefined | RequestHeaders} The header value or map of all headers.
      */
-    remoteAddress: NetAddr;
-    constructor({ params, method, req, options, }: {
-        method: string;
-        req: any;
-        params: Record<string, any>;
-        options: TezXServeOptions;
-    });
-    get headers(): {
-        /**
-         * Retrieves the first value of a specific header.
-         * @param key - Header name to search for.
-         * @returns The first header value or null if not found.
-         * @example
-         * get('content-type') // returns 'application/json'
-         */
-        get: (key: string) => string | null;
-        /**
-         * Checks if a header exists in the request.
-         * @param key - Header name to check for existence.
-         * @returns True if the header exists, false otherwise.
-         * @example
-         * has('Authorization') // returns true if 'Authorization' header exists
-         */
-        has: (key: string) => boolean;
-        /**
-         * Returns an iterator over all header entries.
-         * Each entry is a [key, value] pair where the value can be an array of strings.
-         * @returns HeadersIterator for iterating over header key-value pairs.
-         * @example
-         * for (let [key, value] of headers.entries()) {
-         *   console.log(key, value);
-         * }
-         */
-        entries: () => HeadersIterator<[string, string]>;
-        /**
-         * Returns an iterator over all header keys.
-         * This allows iteration over the names of all headers in the request.
-         * @returns HeadersIterator of header names.
-         * @example
-         * for (let key of headers.keys()) {
-         *   console.log(key);
-         * }
-         */
-        keys: () => HeadersIterator<string>;
-        /**
-         * Returns an iterator over all header values.
-         * This allows iteration over the values of all headers, with each value being an array of strings.
-         * @returns HeadersIterator<string> of header values.
-         * @example
-         * for (let value of headers.values()) {
-         *   console.log(value);
-         * }
-         */
-        values: () => HeadersIterator<string>;
-        /**
-         * Iterates over each header and executes a callback for every header found.
-         * @param callback - Function to execute for each header. Receives the value array and key.
-         * @example
-         * headers.forEach((key, value) => {
-         *   console.log(key, value);
-         * });
-         */
-        forEach: (callbackfn: (value: string, key: string, parent: Headers) => void) => void;
-        /**
-         * Converts headers to a JSON-safe plain object (only single string values).
-         * Multi-value headers are joined by commas.
-         * @returns A record of headers with string values.
-         */
-        toJSON(): Record<string, string>;
-    };
+    header(): RequestHeaders;
+    header(header: ReqHeaderKey): string | undefined;
+    /**
+     * Parses the query string from the URL into a key-value object.
+     *
+     * @returns {Record<string, any>} Query parameters.
+     */
+    get query(): Record<string, string | string[]>;
     /**
      * Parses the request body as plain text.
+     *
      * @returns {Promise<string>} The text content of the request body.
      */
-    text(): Promise<any>;
+    text(): Promise<string>;
     /**
      * Parses the request body as JSON.
-     * @returns {Promise<Record<string, any>>} The parsed JSON object.
-     * If the Content-Type is not 'application/json', it returns an empty object.
+     *
+     * @template T - Expected type of parsed JSON object.
+     * @returns {Promise<T>} Parsed JSON or empty object if not application/json.
      */
-    json(): Promise<any>;
+    json<T extends Record<string, any>>(): Promise<T>;
     /**
-     * Parses the request body based on Content-Type.
-     * Supports:
-     * - application/json → JSON parsing
-     * - application/x-www-form-urlencoded → URL-encoded form parsing
-     * - multipart/form-data → Multipart form-data parsing (for file uploads)
-     * @returns {Promise<Record<string, any>>} The parsed form data as an object.
-     * @throws {Error} If the Content-Type is missing or invalid.
+     * Parses and returns the form data from the incoming HTTP request.
+     *
+     * ✅ Supports:
+     * - `application/x-www-form-urlencoded`
+     * - `multipart/form-data`
+     *
+     * ⚠️ Throws:
+     * - If the `Content-Type` header is missing.
+     * - If the body has already been read/consumed elsewhere.
+     *
+     * 🧠 Internally caches the parsed `FormData` to prevent multiple reads.
+     *
+     * @returns {Promise<FormData>}
+     * A promise that resolves to a native `FormData` object.
+     *
+     * @throws {Error} If the content type is missing or the request body has already been consumed.
      */
-    formData(options?: FormDataOptions): Promise<Record<string, any>>;
+    formData(): Promise<FormData>;
 }

package/core/request.js

@@ -1,148 +1,96 @@
-import { sanitized } from "../utils/formData.js";
-import { urlParse } from "../utils/url.js";
-export class Request {
+import { url2query } from "../utils/url.js";
+import { TezXError } from "./error.js";
+export class TezXRequest {
     url;
     method;
     pathname;
-    urlRef = {
-        protocol: undefined,
-        origin: undefined,
-        hostname: undefined,
-        port: undefined,
-        href: undefined,
-        query: {},
-        pathname: "/",
-    };
-    query;
-    rawRequest;
+    #rawRequest;
     params = {};
     remoteAddress = {};
-    constructor({ params, method, req, options, }) {
-        let parse = urlParse(req.url);
-        let url = parse?.href;
-        this.remoteAddress = options?.connInfo?.remoteAddr;
-        this.url = url || "";
-        this.urlRef = parse;
+    #bodyConsumed = false;
+    #rawBodyArrayBuffer;
+    #cachedText;
+    #cachedJSON;
+    #cachedFormObject;
+    #headersCache;
+    #queryCache;
+    constructor(req, method, pathname, params) {
+        this.url = req.url;
+        this.params = params ?? {};
         this.method = method;
-        this.params = params;
-        this.rawRequest = req;
-        this.pathname = parse.pathname;
-        this.query = parse.query;
+        this.#rawRequest = req;
+        this.pathname = pathname ?? "/";
     }
-    get headers() {
-        let requestHeaders = this.rawRequest.headers;
-        return {
-            get: function get(key) {
-                return requestHeaders.get(key.toLowerCase());
-            },
-            has: function has(key) {
-                return requestHeaders.has(key.toLowerCase());
-            },
-            entries: function entries() {
-                return requestHeaders.entries();
-            },
-            keys: function keys() {
-                return requestHeaders.keys();
-            },
-            values: function values() {
-                return requestHeaders.values();
-            },
-            forEach: function forEach(callbackfn) {
-                return requestHeaders.forEach(callbackfn);
-            },
-            toJSON() {
-                const obj = {};
-                for (const [key, value] of requestHeaders.entries()) {
-                    obj[key] = value;
-                }
-                return obj;
-            },
-        };
+    header(header) {
+        if (header) {
+            return this.#rawRequest.headers.get(header.toLowerCase());
+        }
+        if (this.#headersCache)
+            return this.#headersCache;
+        const obj = {};
+        this.#rawRequest.headers.forEach((value, key) => {
+            obj[key.toLowerCase()] = value;
+        });
+        this.#headersCache = obj;
+        return this.#headersCache;
+    }
+    get query() {
+        return (this.#queryCache ??= url2query(this.url));
+    }
+    async #ensureRawBuffer() {
+        if (this.#bodyConsumed)
+            return;
+        this.#rawBodyArrayBuffer = await this.#rawRequest.arrayBuffer();
+        this.#bodyConsumed = true;
     }
     async text() {
-        return await this.rawRequest.text();
+        if (this.#cachedText !== undefined)
+            return this.#cachedText;
+        await this.#ensureRawBuffer();
+        this.#cachedText = new TextDecoder().decode(this.#rawBodyArrayBuffer);
+        return this.#cachedText;
+    }
+    get #contentType() {
+        const ct = this.#rawRequest.headers.get("content-type");
+        if (!ct)
+            return "";
+        return ct.split(";")[0].trim().toLowerCase();
     }
     async json() {
-        const contentType = this.rawRequest.headers.get("content-type") || "";
-        if (contentType.includes("application/json")) {
-            return await this.rawRequest.json();
-        }
-        else {
+        if (this.#cachedJSON !== undefined)
+            return this.#cachedJSON;
+        if (this.#contentType !== "application/json")
             return {};
-        }
-    }
-    async formData(options) {
-        const contentType = this.rawRequest.headers.get("content-type") || "";
-        if (!contentType) {
-            throw Error("Invalid Content-Type");
-        }
-        if (contentType.includes("application/json")) {
-            return await this.rawRequest.json();
-        }
-        else if (contentType.includes("application/x-www-form-urlencoded")) {
-            const formData = await this.rawRequest.formData();
-            const result = {};
-            for (const [key, value] of formData.entries()) {
-                result[key] = value;
-            }
-            return result;
-        }
-        else if (contentType.includes("multipart/form-data")) {
-            const boundaryMatch = contentType.match(/boundary=([^;]+)/);
-            if (!boundaryMatch) {
-                throw new Error("Boundary not found in multipart/form-data");
+        try {
+            if (!this.#bodyConsumed) {
+                this.#cachedJSON = await this.#rawRequest.json();
+                this.#bodyConsumed = true;
             }
-            const formData = await this.rawRequest.formData();
-            const result = {};
-            for (const [key, value] of formData.entries()) {
-                let val = value;
-                if (val instanceof File && typeof options == "object") {
-                    let filename = val.name;
-                    if (options?.sanitized) {
-                        filename = `${Date.now()}-${sanitized(filename)}`;
-                    }
-                    if (Array.isArray(options?.allowedTypes) &&
-                        !options.allowedTypes?.includes(val.type)) {
-                        throw new Error(`Invalid file type: "${val.type}". Allowed types: ${options.allowedTypes.join(", ")}`);
-                    }
-                    if (typeof options?.maxSize !== "undefined" &&
-                        val.size > options.maxSize) {
-                        throw new Error(`File size exceeds the limit: ${val.size} bytes (Max: ${options.maxSize} bytes)`);
-                    }
-                    if (typeof options?.maxFiles != "undefined" &&
-                        options.maxFiles == 0) {
-                        throw new Error(`Field "${key}" exceeds the maximum allowed file count of ${options.maxFiles}.`);
-                    }
-                    val = new File([await val.arrayBuffer()], filename, {
-                        type: val.type,
-                    });
-                }
-                if (result[key]) {
-                    if (Array.isArray(result[key])) {
-                        if (val instanceof File &&
-                            typeof options?.maxFiles != "undefined" &&
-                            result[key]?.length >= options.maxFiles) {
-                            throw new Error(`Field "${key}" exceeds the maximum allowed file count of ${options.maxFiles}.`);
-                        }
-                        result[key].push(val);
-                    }
-                    else {
-                        if (val instanceof File &&
-                            typeof options?.maxFiles != "undefined" &&
-                            options.maxFiles == 1) {
-                            throw new Error(`Field "${key}" exceeds the maximum allowed file count of ${options.maxFiles}.`);
-                        }
-                        result[key] = [result[key], val];
-                    }
-                }
-                else {
-                    result[key] = val;
-                }
+            else {
+                const txt = await this.text();
+                this.#cachedJSON = txt ? JSON.parse(txt) : {};
             }
-            return result;
         }
-        else {
-            return {};
+        catch {
+            this.#cachedJSON = {};
+        }
+        return this.#cachedJSON;
+    }
+    async formData() {
+        if (this.#cachedFormObject)
+            return this.#cachedFormObject;
+        const ct = this.#contentType;
+        if (!ct)
+            throw new TezXError("Missing Content-Type");
+        if (ct === "application/x-www-form-urlencoded" ||
+            ct === "multipart/form-data") {
+            if (this.#bodyConsumed) {
+                throw new TezXError("Multipart body already consumed elsewhere");
+            }
+            this.#cachedFormObject = (await this.#rawRequest.formData());
+            this.#bodyConsumed = true;
+            return this.#cachedFormObject;
         }
+        return this.#cachedFormObject;
     }
 }