tezx 2.0.11 → 3.0.0

package/types/index.d.ts

@@ -1,27 +1,178 @@
-export type DuplicateMiddlewares = Middleware<any>[];
-export type UniqueMiddlewares = Set<Middleware<any>>;
+/**
+ * Type definition for WebSocket event handlers.
+ * @template T - The type of data expected by the handler
+ * @param {WebSocket} ws - The WebSocket instance
+ * @param {T} [data] - Optional data associated with the event
+ * @returns {Promise<void> | void}
+ */
+type WebSocketHandler<T = any> = (ws: WebSocket, data?: T) => Promise<void> | void;
+/**
+ * Defines all supported WebSocket event handlers.
+ */
+export type WebSocketEvent = {
+    /**
+     * Triggered when the WebSocket connection is successfully opened.(make sure it support in node)
+     */
+    open?: WebSocketHandler;
+    /**
+     * Triggered when a message is received from the client.
+     * Supports `string`, `Buffer`, or `ArrayBuffer` payloads.
+     */
+    message?: WebSocketHandler<string | Buffer | ArrayBuffer>;
+    /**
+     * Triggered when the WebSocket connection is closed.
+     * Provides the close code and reason.
+     */
+    close?: WebSocketHandler<{
+        code: number;
+        reason: string;
+    }>;
+    /**
+     * Triggered when an error occurs during the WebSocket lifecycle.
+     * Not supported in Bun.
+     */
+    error?: WebSocketHandler<Error | any>;
+    /**
+     * Triggered when the socket drain event occurs.
+     * Not supported in Deno and Node.
+     */
+    drain?: WebSocketHandler;
+    /**
+     * Triggered when a ping frame is received from the client.
+     * Not supported in Deno.
+     */
+    ping?: WebSocketHandler<Buffer>;
+    /**
+     * Triggered when a pong frame is received from the client.
+     * Not supported in Deno.
+     */
+    pong?: WebSocketHandler<Buffer>;
+};
+/**
+ * Callback function that returns WebSocket event handlers based on context.
+ * @param {Context} ctx - The request context
+ * @returns {WebSocketEvent} - Object containing WebSocket event handlers
+ */
+export type WebSocketCallback = (ctx: Context) => WebSocketEvent;
+/**
+ * Dynamic options for configuring WebSocket behavior across different runtimes.
+ */
+export type WebSocketOptions = {
+    /**
+     * Called when an error occurs during the upgrade process.
+     */
+    onUpgradeError?: (err: TezXError, ctx: Context) => HttpBaseResponse;
+};
+/**
+ * Represents a string key used for HTTP headers.
+ */
+export type ReqHeaderKey = RequestHeader | (string & {});
+/**
+ * Represents a string key used for HTTP headers.
+ */
+export type ResHeaderKey = ResponseHeader | (string & {});
+/**
+ * Represents a collection of HTTP response headers as key-value pairs.
+ * Keys and values are strings.
+ */
+export interface ResponseHeaders extends Partial<Record<ResHeaderKey, string>> {
+    [key: string]: string | undefined;
+}
+/**
+ * Represents a collection of HTTP request headers as key-value pairs.
+ * Keys and values are strings.
+ */
+export interface RequestHeaders extends Partial<Record<ReqHeaderKey, string>> {
+    [key: string]: string | undefined;
+}
+/**
+ * Options for initializing a Response object.
+ */
+export interface ResponseInit {
+    /**
+     * HTTP status code, e.g. 200, 404, 500.
+     * Optional; defaults to 200 if not specified.
+     */
+    status?: number;
+    /**
+     * Optional HTTP status text corresponding to the status code,
+     * e.g., "OK", "Not Found".
+     */
+    statusText?: string;
+    /**
+     * Additional HTTP response headers to include in the response.
+     */
+    headers?: ResponseHeaders;
+}
+/**
+ * Options for setting HTTP cookies.
+ */
 export interface CookieOptions {
+    /** Expiration date of the cookie. */
     expires?: Date;
+    /** URL path the cookie is valid for. */
     path?: string;
+    /** Max age of the cookie in seconds. */
     maxAge?: number;
+    /** Domain the cookie is valid for. */
     domain?: string;
+    /** Whether the cookie is only sent over HTTPS. */
     secure?: boolean;
+    /** Whether the cookie is inaccessible to JavaScript's `Document.cookie` API. */
     httpOnly?: boolean;
+    /** Controls cross-site request behavior. One of "Strict", "Lax", or "None". */
     sameSite?: "Strict" | "Lax" | "None";
 }
-export type AdapterType = "bun" | "deno" | "node";
-export type ResponseHeaders = Record<string, string>;
+/**
+ * Represents the supported runtime adapter types.
+ */
+export type Runtime = "bun" | "deno" | "node";
 import { Context } from "../core/context.js";
+import { TezXError } from "../core/error.js";
+import { RequestHeader, ResponseHeader } from "./headers.js";
+/**
+ * Options to customize static file serving behavior.
+ */
 export type StaticServeOption = {
+    /** Optional cache-control header value for static files, e.g. "max-age=3600". */
     cacheControl?: string;
+    /** Additional HTTP headers to set on static file responses. */
     headers?: ResponseHeaders;
+    /**
+     * Allowed file extensions to serve.
+     * If provided, only files with these extensions will be served.
+     * Example: ["html", "css", "js", "png"]
+     */
+    extensions?: string[];
+};
+/**
+ * Represents the list of static files and their corresponding route paths.
+ */
+export type StaticFileArray = {
+    /** Absolute path to the static file on the file system. */
+    fileSource: string;
+    /** Public route (URL path) where the file will be served. */
+    route: string;
+}[];
+/**
+ * Represents a static file configuration to be served by the server.
+ */
+export type ServeStatic = {
+    /**
+     * Array of static files and their corresponding route paths.
+     */
+    files: StaticFileArray;
+    /**
+     * Optional settings to control caching, headers, and allowed extensions.
+     */
+    options?: StaticServeOption;
 };
 type ExtractParam<Path extends string> = Path extends `${infer _Start}:${infer Param}/${infer Rest}` ? Param extends `${infer Name}?` ? {
-    [K in Name]?: string;
+    [K in Name]?: string | null;
 } & ExtractParam<`/${Rest}`> : {
     [K in Param]: string;
 } & ExtractParam<`/${Rest}`> : Path extends `${infer _Start}:${infer Param}` ? Param extends `${infer Name}?` ? {
-    [K in Name]?: string;
+    [K in Name]?: string | null;
 } : {
     [K in Param]: string;
 } : {};
@@ -31,29 +182,178 @@ type ExtractWildcard<Path extends string> = Path extends `${string}*${infer Wild
     [K in Wildcard]: string;
 } : {};
 export type ExtractRouteParams<Path extends string> = ExtractParam<Path> & ExtractWildcard<Path> & Record<string, string>;
-export type ExtractParamsFromPath<Path extends PathType> = (Path extends string ? ExtractRouteParams<Path> : {}) & Record<string, string>;
-export type NextCallback = () => Promise<any>;
-export type CallbackReturn = Promise<Response> | Response;
-export type ctx<T extends Record<string, any> = {}, Path extends PathType = any> = Context<T, Path> & T;
-export type Callback<T extends Record<string, any> = {}, Path extends PathType = any> = (ctx: ctx<T, Path>) => CallbackReturn;
-export type Middleware<T extends Record<string, any> = {}, Path extends PathType = any> = (ctx: ctx<T, Path>, next: NextCallback) => Promise<Response | void> | Response | NextCallback;
-export type PathType = string | RegExp;
-export type FormDataOptions = {
-    maxSize?: number;
-    allowedTypes?: string[];
+export type ExtractParamsFromPath<Path extends string> = (Path extends string ? ExtractRouteParams<Path> : {}) & Record<string, string>;
+/**
+ * A function that continues the middleware chain.
+ *
+ * @returns A Promise that resolves when the next middleware completes.
+ */
+export type NextCallback = () => Promise<void>;
+/**
+ * Represents a base HTTP response.
+ * It can either be a `Response` object or a `Promise` resolving to a `Response`.
+ */
+export type HttpBaseResponse = Response | Promise<Response>;
+/**
+ * The context object (`ctx`) passed to all handlers and middleware.
+ *
+ * @template T - Custom environment or app-level data.
+ * @template Path - Type of the route path (optional).
+ */
+export type Ctx<T extends Record<string, any> = {}, Path extends string = any> = Context<T, Path> & T & {
+    [key: string]: any;
+};
+/**
+ * A callback (handler) for a route.
+ *
+ * @template T - Context data type.
+ * @template Path - Type of the route path.
+ *
+ * @param ctx - The context object for the request.
+ * @returns An HTTP response or a promise that resolves to an HTTP response.
+ */
+export type Callback<T extends Record<string, any> = {}, Path extends string = any> = (ctx: Ctx<T, Path>) => HttpBaseResponse;
+/**
+ * Middleware function type used in TezX.
+ * Similar to Koa-style middleware with `next()` chaining.
+ *
+ * @template T - Context data type.
+ * @template Path - Type of the route path.
+ *
+ * @param ctx - The context object.
+ * @param next - A callback to call the next middleware in the chain.
+ * @returns An HTTP response, a promise, or a call to `next()`.
+ */
+export type Middleware<T extends Record<string, any> = {}, Path extends string = any> = (ctx: Ctx<T, Path>, next: NextCallback) => HttpBaseResponse | Promise<HttpBaseResponse | void> | NextCallback;
+/**
+ * Error handler function type.
+ *
+ * @template T - Context data type.
+ *
+ * @param err - The error that was thrown.
+ * @param ctx - The context object where the error occurred.
+ * @returns An HTTP response or a promise that resolves to an HTTP response.
+ */
+export type ErrorHandler<T extends Record<string, any> = {}> = (err: TezXError, ctx: Ctx<T>) => HttpBaseResponse;
+/**
+ * Configuration options for parsing and validating multipart/form-data.
+ */
+export interface FormDataOptions {
+    /**
+     * If true, apply basic sanitization to incoming text fields.
+     */
     sanitized?: boolean;
+    /**
+     * Whitelisted MIME types for uploaded files (e.g. ["image/jpeg", "image/png"]).
+     */
+    allowedTypes?: string[];
+    /**
+     * Maximum **per-file** size in bytes.
+     */
+    maxSize?: number;
+    /**
+     * Maximum number of files allowed **per field**.
+     */
     maxFiles?: number;
-};
+    /**
+     * Maximum **combined** size of all uploaded files in bytes.
+     */
+    maxTotalSize?: number;
+    /**
+     * Maximum length of a **single text field** (in characters/bytes, depending on your parser).
+     */
+    maxFieldSize?: number;
+}
+/**
+ * Supported low-level transport types for network addresses.
+ */
 type TransportType = "tcp" | "udp" | "unix" | "pipe" | "unixpacket";
+/**
+ * A normalized network address description.
+ */
 export type NetAddr = {
+    /** Transport protocol used by the connection. */
     transport?: TransportType;
+    /** Address family. */
     family?: "IPv4" | "IPv6" | "Unix";
+    /** The IP/Unix path/etc. */
     address?: string;
+    /** TCP/UDP port number (if applicable). */
     port?: number;
 };
+/**
+ * Connection address metadata holding both local and remote endpoints.
+ */
 export type ConnAddress = {
+    /** Remote peer address information. */
     remoteAddr: NetAddr;
+    /** Local server address information. */
     localAddr: NetAddr;
 };
-export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH" | "HEAD" | "ALL" | "TRACE" | "CONNECT" | string;
+/**
+ * List of built-in, first-class supported HTTP methods.
+ * "ALL" can be used to register a handler for every method.
+ */
+export declare const httpMethod: readonly ["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH", "HEAD", "ALL", "TRACE", "CONNECT"];
+/**
+ * HTTP method type. Extensible to support custom verb strings.
+ */
+export type HTTPMethod = (typeof httpMethod)[number] | (string & {});
+/**
+ * The result returned when searching for a route match.
+ *
+ * @template T - The type of the request context environment.
+ */
+export type RouteMatchResult<T extends Record<string, any> = any> = {
+    /**
+     * The HTTP method of the matched route (e.g., "GET", "POST").
+     */
+    method: HTTPMethod;
+    /**
+     * The middleware functions that will be executed for this route.
+     */
+    middlewares: Middleware<T>[];
+    /**
+     * The final route handlers (callbacks or middlewares) to be executed.
+     */
+    handlers: HandlerType<T>;
+    /**
+     * An object containing route parameters extracted from the URL.
+     * The values can be strings, null (for optional params), or undefined.
+     */
+    params: Record<string, string | null | undefined>;
+};
+/**
+ * The array type containing route handlers and middlewares for a route.
+ *
+ * @template T - The type of the request context environment.
+ */
+export type HandlerType<T extends Record<string, any> = any> = (Callback<T> | Middleware<T>)[];
+/**
+ * Interface representing a router.
+ *
+ * @template T - The type of the handler.
+ */
+export interface RouteRegistry {
+    /**
+     * The name of the router.
+     */
+    name: string;
+    /**
+     * Registers a route or middleware for a specific HTTP method.
+     *
+     * @param method - HTTP method (e.g., "GET", "POST", or "ALL" for middleware)
+     * @param path - Route path (e.g., "/users", "/api")
+     * @param handlers - Array of middleware or callback handlers
+     */
+    addRoute<T extends Record<string, any> = any>(method: HTTPMethod, path: string, handler: HandlerType<T>): void;
+    /**
+     * Find a route based on the given method and path.
+     *
+     * @param method - The HTTP method (e.g., 'get', 'post').
+     * @param path - The path to match.
+     * @returns The result of the match.
+     */
+    search(method: HTTPMethod, path: string): RouteMatchResult;
+}
 export {};

package/types/index.js

@@ -1 +1,12 @@
-export {};
+export const httpMethod = [
+    "GET",
+    "POST",
+    "PUT",
+    "DELETE",
+    "OPTIONS",
+    "PATCH",
+    "HEAD",
+    "ALL",
+    "TRACE",
+    "CONNECT",
+];

package/utils/buffer.d.ts

@@ -0,0 +1 @@
+export declare function base64Decode(base64: string): string;

package/utils/buffer.js

@@ -0,0 +1,14 @@
+export function base64Decode(base64) {
+    const pad = base64.length % 4;
+    if (pad)
+        base64 += "=".repeat(4 - pad);
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(base64, "base64").toString("utf-8");
+    }
+    else if (typeof atob === "function") {
+        return new TextDecoder().decode(Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)));
+    }
+    else {
+        throw new Error("Base64 decode not supported in this environment");
+    }
+}

package/utils/colors.d.ts

@@ -1,3 +1,14 @@
+/**
+ * ANSI escape codes for terminal text formatting and colors.
+ *
+ * These codes can be used to style console output with colors,
+ * bold, underline, and background colors.
+ *
+ * @constant {Record<string, string>}
+ *
+ * @example
+ * console.log(COLORS.red, "This text is red", COLORS.reset);
+ */
 export declare const COLORS: {
     reset: string;
     bold: string;
@@ -18,5 +29,18 @@ export declare const COLORS: {
     bgMagenta: string;
     bgCyan: string;
     bgWhite: string;
+    orange: string;
+    bgOrange: string;
 };
+/**
+ * Wraps the given text with ANSI color codes for terminal styling.
+ *
+ * @param {string | number} text - The text or number to be colored.
+ * @param {keyof typeof COLORS} color - The color key from the COLORS object.
+ * @returns {string} The input text wrapped with the specified ANSI color code and reset code.
+ *
+ * @example
+ * console.log(colorText("Hello World", "red"));
+ * // Output: (red colored "Hello World" in terminal)
+ */
 export declare function colorText(text: string | number, color: keyof typeof COLORS): string;

package/utils/colors.js

@@ -18,6 +18,8 @@ export const COLORS = {
     bgMagenta: "\x1b[45m",
     bgCyan: "\x1b[46m",
     bgWhite: "\x1b[47m",
+    orange: "\x1b[38;2;255;88;30m",
+    bgOrange: "\x1b[48;2;255;88;30m",
 };
 export function colorText(text, color) {
     return `${COLORS[color]}${text}${COLORS.reset}`;

package/utils/cookie.d.ts

@@ -0,0 +1,55 @@
+import { Context } from "../core/context.js";
+import { CookieOptions } from "../types/index.js";
+/**
+ * Get the value of a specific cookie by name from the request context.
+ *
+ * @param {Context} ctx - The context containing the request.
+ * @param {string} name - The name of the cookie to retrieve.
+ * @returns {string | undefined} The cookie value if found, otherwise undefined.
+ *
+ * @example
+ * ```ts
+ * const sessionId = getCookie(ctx,"session_id");
+ * ```
+ */
+export declare function getCookie(ctx: Context, name: string): string | undefined;
+/**
+ * Parse all cookies from the request's "cookie" header into an object.
+ *
+ * @param {Context} ctx - The context containing the request.
+ * @returns {Record<string, string>} An object mapping cookie names to their decoded values.
+ *
+ * @example
+ * ```ts
+ * const cookies = allCookies(ctx);
+ * console.log(cookies["session_id"]);
+ * ```
+ */
+export declare function allCookies(ctx: Context): Record<string, string>;
+/**
+ * Set a cookie in the response headers.
+ *
+ * @param {Context} ctx - The context containing the response.
+ * @param {string} name - The name of the cookie to set.
+ * @param {string} value - The cookie value.
+ * @param {CookieOptions} [options] - Optional cookie settings like `maxAge`, `path`, `secure`, etc.
+ *
+ * @example
+ * ```ts
+ * setCookie(ctx, "session_id", "abc123", { httpOnly: true, maxAge: 3600 });
+ * ```
+ */
+export declare function setCookie(ctx: Context, name: string, value: string, options?: CookieOptions): void;
+/**
+ * Delete a cookie by setting its expiration date in the past.
+ *
+ * @param {Context} ctx - The context containing the response.
+ * @param {string} name - The name of the cookie to delete.
+ * @param {CookieOptions} [options] - Optional settings such as `path` to ensure proper deletion.
+ *
+ * @example
+ * ```ts
+ * deleteCookie(ctx, "session_id");
+ * ```
+ */
+export declare function deleteCookie(ctx: Context, name: string, options?: CookieOptions): void;

package/utils/cookie.js

@@ -0,0 +1,53 @@
+export function getCookie(ctx, name) {
+    return allCookies(ctx)?.[name];
+}
+export function allCookies(ctx) {
+    const cookieHeader = ctx.req.header("cookie");
+    const cookies = {};
+    if (!cookieHeader)
+        return cookies;
+    let start = 0;
+    let sep = -1;
+    const len = cookieHeader.length;
+    for (let i = 0; i <= len; i++) {
+        const ch = cookieHeader.charCodeAt(i) || 59;
+        if (ch === 61 && sep === -1) {
+            sep = i;
+        }
+        else if (ch === 59 || i === len) {
+            if (sep > -1) {
+                const key = cookieHeader.slice(start, sep).trim();
+                const value = cookieHeader.slice(sep + 1, i).trim();
+                cookies[key] = decodeURIComponent(value);
+            }
+            start = i + 1;
+            sep = -1;
+        }
+    }
+    ctx.cookies = cookies;
+    return cookies;
+}
+export function setCookie(ctx, name, value, options) {
+    ctx.setHeader("Set-Cookie", `${name}=${value}; ${serializeOptions(options ?? {})}`);
+}
+export function deleteCookie(ctx, name, options) {
+    ctx.setHeader("Set-Cookie", `${name}=; ${serializeOptions({ ...options, maxAge: 0, expires: new Date(0) })}`);
+}
+function serializeOptions(options) {
+    const parts = [];
+    if (options.maxAge)
+        parts.push(`Max-Age=${options.maxAge}`);
+    if (options.expires)
+        parts.push(`Expires=${options.expires.toUTCString()}`);
+    if (options.path)
+        parts.push(`Path=${options.path}`);
+    if (options.domain)
+        parts.push(`Domain=${options.domain}`);
+    if (options.secure)
+        parts.push(`Secure`);
+    if (options.httpOnly)
+        parts.push(`HttpOnly`);
+    if (options.sameSite)
+        parts.push(`SameSite=${options.sameSite}`);
+    return parts.join("; ");
+}

package/utils/file.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Check asynchronously if a file exists at the given path.
+ * Supports Node.js, Bun, and Deno runtimes.
+ *
+ * @param {string} path - The file path to check.
+ * @returns {Promise<boolean>} - Resolves to true if file exists, false otherwise.
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Asynchronously reads the entire file content as a Uint8Array.
+ * Supports Node.js, Bun, and Deno runtimes.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<Uint8Array>} - Resolves to the file buffer.
+ * @throws Will throw an error if the runtime is unsupported.
+ */
+export declare function getFileBuffer(path: string): Promise<Uint8Array>;
+/**
+ * Creates a readable stream for the given file path.
+ * Supports Node.js, Bun, and Deno runtimes.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<ReadableStream>} - Resolves to a ReadableStream of the file content.
+ * @throws Will throw an error if the runtime is unsupported.
+ */
+export declare function readStream(path: string): Promise<ReadableStream>;
+/**
+ * Asynchronously retrieves the size of a file in bytes.
+ * Supports Node.js, Bun, and Deno runtimes.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<{size: number, mtime: Date}>} - Resolves to the file size in bytes.
+ */
+export declare function fileSize(path: string): Promise<{
+    mtime: Date;
+    size: number;
+}>;
+export declare function etagDigest(algo: string | undefined, data: any): Promise<string>;