tezx 3.0.10-beta → 3.0.12-beta

package/core/context.js

@@ -1,28 +1,28 @@
 import { fileExists, fileSize, getFileBuffer, readStream, } from "../utils/file.js";
 import { extensionExtract } from "../utils/low-level.js";
 import { defaultMimeType, mimeTypes } from "../utils/mimeTypes.js";
-import { determineContentTypeBody, newResponse } from "../utils/response.js";
+import { determineContentTypeBody, toString } from "../utils/response.js";
 import { TezXRequest } from "./request.js";
 export class Context {
     #status = 200;
-    #headers = { connection: "keep-alive" };
+    #headers;
     #req = null;
     #params = {};
     rawRequest;
     #args;
     #body;
+    url;
+    res;
     env = {};
     pathname;
     method;
-    constructor(req, options) {
-        this.#args = options?.args;
+    constructor(req, pathname, method, env, args) {
+        this.#args = args;
         this.rawRequest = req;
-        this.pathname = options?.pathname;
-        this.env = options?.env || {};
-        this.method = options?.method;
-    }
-    get url() {
-        return this.req.url;
+        this.url = req.url;
+        this.pathname = pathname;
+        this.env = env ?? {};
+        this.method = method;
     }
     get getStatus() {
         return this.#status;
@@ -30,44 +30,20 @@ export class Context {
     set setStatus(code) {
         this.#status = code;
     }
-    header(header) {
-        if (header) {
-            return this.#headers[header?.toLowerCase()];
-        }
-        return this.#headers;
-    }
-    set clearHeader(header) {
-        this.#headers = (header || {});
+    get headers() {
+        return this.res?.headers ?? (this.#headers ??= new Headers());
     }
     setHeader(key, value, options) {
-        let _key = key.toLowerCase();
-        let append = options?.append || _key == 'set-cookie';
-        if (!this.res) {
-            if (append && this.#headers[_key]) {
-                this.#headers[_key] += `, ${value}`;
-            }
-            else {
-                this.#headers[_key] = value;
-            }
-        }
-        else {
-            const resHeaders = this.res.headers;
-            if (append) {
-                resHeaders.append(_key, value);
-            }
-            else {
-                resHeaders.set(_key, value);
-            }
-        }
-        return this;
-    }
-    deleteHeader(key) {
+        if (!value)
+            return this;
         const _key = key.toLowerCase();
-        if (!this.res) {
-            delete this.#headers[_key];
+        const append = options?.append || _key === "set-cookie";
+        const target = this.res?.headers ?? (this.#headers ??= new Headers());
+        if (append) {
+            target.append(_key, value);
         }
         else {
-            this.res.headers.delete(_key);
+            target.set(_key, value);
         }
         return this;
     }
@@ -75,10 +51,7 @@ export class Context {
         this.#params = params;
     }
     get req() {
-        if (!this.#req) {
-            this.#req = new TezXRequest(this.rawRequest, this.method, this.pathname, this.#params);
-        }
-        return this.#req;
+        return (this.#req ??= new TezXRequest(this.rawRequest, this.method, this.pathname, this.#params));
     }
     get body() {
         return this.#body;
@@ -90,66 +63,93 @@ export class Context {
         this.#status = status;
         return this;
     };
+    #newResponse(body, type, init = {}) {
+        const headers = new Headers(this.#headers);
+        headers.set("Content-Type", type);
+        if (init.headers) {
+            for (const key in init.headers) {
+                const value = init.headers[key];
+                if (!value)
+                    continue;
+                if (key.toLowerCase() === "set-cookie") {
+                    headers.append(key, value);
+                }
+                else {
+                    headers.set(key, value);
+                }
+            }
+        }
+        return new Response(body, {
+            status: init.status ?? this.#status,
+            statusText: init.statusText,
+            headers,
+        });
+    }
     newResponse(body, init = {}) {
-        const headers = { ...this.#headers, ...init.headers };
-        const status = init.status || this.#status;
-        const statusText = init.statusText;
-        return new Response(body, { status, statusText, headers: headers });
+        const headers = new Headers(this.#headers);
+        if (init.headers) {
+            for (const key in init.headers) {
+                const value = init.headers[key];
+                if (!value) {
+                    continue;
+                }
+                if (key.toLowerCase() === "set-cookie") {
+                    headers.append(key, value);
+                }
+                else {
+                    headers.set(key, value);
+                }
+            }
+        }
+        return new Response(body, {
+            status: init.status ?? this.#status,
+            statusText: init.statusText,
+            headers,
+        });
     }
     text(content, init) {
-        return newResponse(content, "text/plain; charset=utf-8", init, this.#headers, this.#status);
+        return this.#newResponse(content, "text/plain; charset=utf-8", init);
     }
     html(strings, ...args) {
-        let html = strings;
-        if (Array.isArray(strings)) {
-            html = strings.reduce((result, str, i) => {
-                const value = args?.[i] ?? "";
-                return result + str + value;
-            }, "");
-            return newResponse(html, "text/html; charset=utf-8", {}, this.#headers, this.#status);
-        }
-        else {
-            let init = args?.[0];
-            return newResponse(html, "text/html; charset=utf-8", init, this.#headers, this.#status);
-        }
+        return this.#newResponse(toString(strings, args), "text/html; charset=utf-8", args?.[0]);
     }
-    xml(xml, init) {
-        return newResponse(xml, "text/xml; charset=utf-8", init, this.#headers, this.#status);
+    xml(strings, ...args) {
+        return this.#newResponse(toString(strings, args), "text/html; charset=utf-8", args?.[0]);
     }
     json(json, init) {
-        return newResponse(JSON.stringify(json), "application/json; charset=utf-8", init, this.#headers, this.#status);
+        return this.#newResponse(JSON.stringify(json), "application/json; charset=utf-8", init);
     }
     send(body, init) {
         let { body: _body, type } = determineContentTypeBody(body);
-        const contentType = init?.headers?.["Content-Type"] ||
-            init?.headers?.["content-type"] ||
+        const contentType = init?.headers?.["Content-Type"] ??
+            init?.headers?.["content-type"] ??
             type;
-        return newResponse(_body, contentType, {}, this.#headers, this.#status);
+        return this.#newResponse(_body, contentType, init);
     }
     redirect(url, status = 302) {
-        return new Response(null, {
-            status: status,
-            headers: { ...this.#headers, Location: url },
-        });
+        const headers = new Headers(this.#headers);
+        headers.set("Location", url);
+        return new Response(null, { status, headers });
     }
     async download(filePath, filename) {
         if (!(await fileExists(filePath)))
             throw Error("File not found");
-        let buf = await getFileBuffer(filePath);
-        return newResponse(buf, "application/octet-stream", {
-            status: 200,
-            headers: {
-                "Content-Disposition": `attachment; filename="${filename}"`,
-                "Content-Length": buf.byteLength.toString(),
-            }
-        }, this.#headers, this.#status);
+        const buf = await getFileBuffer(filePath);
+        const headers = {
+            "Content-Disposition": `attachment; filename="${filename}"`,
+            "Content-Length": buf.byteLength.toString(),
+        };
+        return this.#newResponse(buf, "application/octet-stream", {
+            status: this.#status,
+            headers,
+        });
     }
     async sendFile(filePath, init) {
         if (!(await fileExists(filePath)))
             throw Error("File not found");
         let size = await fileSize(filePath);
-        const ext = extensionExtract(filePath) || "";
-        const mimeType = mimeTypes[ext] || defaultMimeType;
+        const ext = extensionExtract(filePath);
+        const mimeType = mimeTypes[ext] ?? defaultMimeType;
         let fileStream = await readStream(filePath);
         let headers = {
             "Content-Type": mimeType,
@@ -157,10 +157,11 @@ export class Context {
             ...init?.headers,
         };
         let filename = init?.filename;
-        if (filename)
+        if (filename) {
             headers["Content-Disposition"] = `attachment; filename="${filename}"`;
+        }
         return this.newResponse(fileStream, {
-            status: init?.status || 200,
+            status: init?.status ?? this.#status,
             statusText: init?.statusText,
             headers,
         });

package/core/error.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Custom error type used throughout the Tezx application.
+ *
+ * Extends the built-in `Error` and carries an HTTP status code plus optional
+ * structured `details` payload (useful for validation errors, metadata, etc.).
+ *
+ * @example
+ * // Throw a 404
+ * throw TezXError.notFound("User not found", { userId });
+ *
+ * @example
+ * // Create and throw a custom status
+ * throw new TezXError("Something went wrong", 502);
+ *
+ * @class TezXError
+ * @extends Error
+ */
+export declare class TezXError extends Error {
+    /**
+     * HTTP status code representing the error (defaults to 500).
+     */
+    statusCode: number;
+    /**
+     * Optional additional details about the error (validation lists, meta, etc.).
+     */
+    details?: any;
+    /**
+     * Create an instance of TezXError.
+     *
+     * @param {string} message - Human readable error message.
+     * @param {number} [statusCode=500] - HTTP status code to associate with this error.
+     * @param {*} [details] - Optional additional error payload (e.g. validation errors).
+     */
+    constructor(message: string, statusCode?: number, details?: any);
+    /**
+     * Create a 400 Bad Request error.
+     *
+     * @param {string} [message="Bad Request"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static badRequest(message?: string, details?: any): TezXError;
+    /**
+     * Create a 401 Unauthorized error.
+     *
+     * @param {string} [message="Unauthorized"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static unauthorized(message?: string, details?: any): TezXError;
+    /**
+     * Create a 403 Forbidden error.
+     *
+     * @param {string} [message="Forbidden"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static forbidden(message?: string, details?: any): TezXError;
+    /**
+     * Create a 404 Not Found error.
+     *
+     * @param {string} [message="Resource Not Found"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static notFound(message?: string, details?: any): TezXError;
+    /**
+     * Create a 409 Conflict error.
+     *
+     * @param {string} [message="Conflict"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static conflict(message?: string, details?: any): TezXError;
+    /**
+     * Create a 500 Internal Server Error.
+     *
+     * @param {string} [message="Internal Server Error"]
+     * @param {*} [details]
+     * @returns {TezXError}
+     */
+    static internal(message?: string, details?: any): TezXError;
+    /**
+     * Convert the error into a JSON-serializable object that can be sent
+     * in HTTP responses or logged safely.
+     *
+     * @returns {{ error: boolean, message: string, statusCode: number, details: any }}
+     */
+    toJSON(): {
+        error: boolean;
+        message: string;
+        statusCode: number;
+        details: any;
+    };
+}

package/core/error.js

@@ -0,0 +1,37 @@
+export class TezXError extends Error {
+    statusCode;
+    details;
+    constructor(message, statusCode = 500, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        Object.setPrototypeOf(this, new.target.prototype);
+        Error.captureStackTrace(this, this.constructor);
+    }
+    static badRequest(message = "Bad Request", details) {
+        return new TezXError(message, 400, details);
+    }
+    static unauthorized(message = "Unauthorized", details) {
+        return new TezXError(message, 401, details);
+    }
+    static forbidden(message = "Forbidden", details) {
+        return new TezXError(message, 403, details);
+    }
+    static notFound(message = "Resource Not Found", details) {
+        return new TezXError(message, 404, details);
+    }
+    static conflict(message = "Conflict", details) {
+        return new TezXError(message, 409, details);
+    }
+    static internal(message = "Internal Server Error", details) {
+        return new TezXError(message, 500, details);
+    }
+    toJSON() {
+        return {
+            error: true,
+            message: this.message,
+            statusCode: this.statusCode,
+            details: this.details ?? null,
+        };
+    }
+}

package/core/request.d.ts

@@ -1,4 +1,4 @@
-import { ExtractParamsFromPath, ReqHeaderKey, HTTPMethod, NetAddr, RequestHeaders } from "../types/index.js";
+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.
  *
@@ -60,7 +60,7 @@ export declare class TezXRequest<Path extends string = any> {
      *
      * @returns {Record<string, any>} Query parameters.
      */
-    get query(): Record<string, any>;
+    get query(): Record<string, string | string[]>;
     /**
      * Parses the request body as plain text.
      *
@@ -71,9 +71,9 @@ export declare class TezXRequest<Path extends string = any> {
      * Parses the request body as JSON.
      *
      * @template T - Expected type of parsed JSON object.
-     * @returns {Promise<T | {}>} Parsed JSON or empty object if not application/json.
+     * @returns {Promise<T>} Parsed JSON or empty object if not application/json.
      */
-    json<T = any>(): Promise<T | {}>;
+    json<T extends Record<string, any>>(): Promise<T>;
     /**
      * Parses and returns the form data from the incoming HTTP request.
      *

package/core/request.js

@@ -14,22 +14,22 @@ export class TezXRequest {
     #headersCache;
     #queryCache;
     constructor(req, method, pathname, params) {
-        this.url = req.url || "";
-        this.params = params || {};
+        this.url = req.url;
+        this.params = params ?? {};
         this.method = method;
         this.#rawRequest = req;
-        this.pathname = pathname || "/";
+        this.pathname = pathname ?? "/";
     }
     header(header) {
         if (header) {
-            return this.#rawRequest.headers.get(header?.toLowerCase());
+            return this.#rawRequest.headers.get(header.toLowerCase());
         }
         if (this.#headersCache)
             return this.#headersCache;
         const obj = {};
-        for (const [key, value] of this.#rawRequest.headers.entries()) {
+        this.#rawRequest.headers.forEach((value, key) => {
             obj[key.toLowerCase()] = value;
-        }
+        });
         this.#headersCache = obj;
         return this.#headersCache;
     }

package/core/router.d.ts

@@ -1,19 +1,24 @@
 import { Callback, HandlerType, HTTPMethod, Middleware, RouteRegistry, ServeStatic } from "../types/index.js";
+/**
+ * Router configuration options.
+ */
 export type RouterConfig = {
     /**
      * Custom route registry instance used internally to store routes.
-     * Defaults to CombineRouteRegistry.
+     * If not provided, the router will use the default CombineRouteRegistry.
      */
     routeRegistry?: RouteRegistry;
     /**
-     * `env` allows you to define environment variables for the router.
-     * It is a record of key-value pairs where the key is the variable name
-     * and the value can be either a string or a number.
+     * `env` allows you to define environment variables for the router instance.
+     * Example: `{ NODE_ENV: "production", API_VERSION: 2 }`
      */
     env?: Record<string, string | number>;
     /**
-     * `basePath` sets the base path for the router. This is useful for grouping
-     * routes under a specific path prefix.
+     * `basePath` sets a base path prefix for the router. Useful to group routes
+     * under a common prefix (for example when mounting the router on a sub-path).
+     *
+     * - Example: `basePath: "/api/v1"` will prefix all registered routes with `/api/v1`.
+     * - Should not end with a trailing slash — the router will normalize it.
      */
     basePath?: string;
 };

package/core/router.js

@@ -1,5 +1,5 @@
-import { sanitizePathSplitBasePath } from "../utils/low-level.js";
 import { RadixRouter } from "../registry/RadixRouter.js";
+import { sanitizePathSplitBasePath } from "../utils/low-level.js";
 export class Router {
     env = {};
     router;
@@ -163,7 +163,9 @@ export class Router {
     }
     #routeAddTriNode(path, router) {
         this.env = { ...this.env, ...router.env };
-        if (this.router?.name && router.router?.name && this.router?.name !== router.router?.name) {
+        if (this.router?.name &&
+            router.router?.name &&
+            this.router?.name !== router.router?.name) {
             throw new Error(`Router name mismatch: expected "${this.router.name}", got "${router.router.name}"`);
         }
         if (!(router instanceof Router)) {

package/core/server.js

@@ -1,8 +1,8 @@
-import { colorText } from "../utils/colors.js";
 import { handleErrorResponse, notFoundResponse } from "../utils/response.js";
 import { getPathname } from "../utils/url.js";
 import { GlobalConfig } from "./config.js";
 import { Context } from "./context.js";
+import { TezXError } from "./error.js";
 import { Router } from "./router.js";
 export class TezX extends Router {
     #pathResolver;
@@ -24,88 +24,70 @@ export class TezX extends Router {
         this.#errorHandler = callback;
         return this;
     }
-    async #resolvePath(pathname) {
-        let resolvePath = pathname;
-        if (this.#pathResolver) {
-            resolvePath = await this.#pathResolver(pathname);
-            GlobalConfig.debugging.warn(`${colorText(" PATH RESOLVE ", "white")} ${colorText(pathname, "red")} ➞ ${colorText(resolvePath, "cyan")}`);
-        }
-        if (typeof resolvePath !== "string") {
-            throw new Error(`Path resolution failed: expected a string, got ${typeof resolvePath}`);
-        }
-        return resolvePath;
-    }
-    #chain(middlewares) {
-        if (!Array.isArray(middlewares)) {
-            throw new TypeError("Middleware stack must be an array!");
-        }
-        const len = middlewares.length;
-        return async function (ctx) {
-            let index = -1;
-            async function dispatch(i) {
-                if (i <= index) {
-                    throw new Error("next() called multiple times");
-                }
-                index = i;
-                if (i >= len)
-                    return;
+    async #chain(ctx, mLen, middlewares, hLen, handlers) {
+        let index = -1;
+        let res;
+        async function dispatch(i) {
+            if (i <= index)
+                throw new Error("next() called multiple times");
+            index = i;
+            if (i < mLen) {
                 const fn = middlewares[i];
-                if (typeof fn !== "function") {
-                    throw new TypeError(`Middleware at index ${i} must be a function`);
+                if (typeof fn !== "function")
+                    throw new TypeError(`Middleware[${i}] must be a function`);
+                res = (await fn(ctx, () => dispatch(i + 1)));
+                if (res !== undefined) {
+                    ctx.res = res;
                 }
-                const result = await fn(ctx, () => dispatch(i + 1));
-                if (result instanceof Response) {
-                    ctx.res = result;
+                return ctx.res;
+            }
+            const hi = i - mLen;
+            if (hi < hLen) {
+                const fn = handlers[hi];
+                if (typeof fn !== "function")
+                    throw new TypeError(`Handler[${hi}] must be a function`);
+                res = (await fn(ctx, () => dispatch(i + 1)));
+                if (res !== undefined) {
+                    ctx.res = res;
                 }
                 return ctx.res;
             }
-            await dispatch(0);
-            return ctx.res;
-        };
+        }
+        await dispatch(0);
+        return (ctx.res ??
+            (ctx.body !== undefined ? ctx.send(ctx.body) : this.#notFound(ctx)));
     }
     async #handleRequest(req, method, args) {
-        if (!(req instanceof Request)) {
+        if (!(req instanceof Request))
             throw new Error("Invalid request object provided to tezX server.");
-        }
-        const pathname = await this.#resolvePath(getPathname(req.url));
-        let ctx = new Context(req, {
-            pathname,
-            method,
-            env: this.env,
-            args,
-        });
+        const rawPath = getPathname(req.url);
+        const pathname = this.#pathResolver
+            ? await this.#pathResolver(rawPath)
+            : rawPath;
+        const ctx = new Context(req, pathname, method, this.env, args);
         try {
             const staticHandler = this.staticFile?.[`${method} ${pathname}`];
             if (staticHandler) {
                 return staticHandler(ctx);
             }
             const route = this.router.search(method, pathname);
-            if (!route || (route.handlers.length === 0 && route.middlewares.length === 0)) {
+            const mLen = route?.middlewares?.length;
+            const hLen = route?.handlers?.length;
+            if (!route || (hLen === 0 && mLen === 0)) {
                 return this.#notFound(ctx);
             }
             ctx.params = route.params;
-            if (route.handlers.length === 1 && route.middlewares.length === 0) {
-                const result = await route.handlers[0](ctx);
-                if (result)
-                    return result;
-                if (ctx.body !== undefined)
-                    return ctx.send(ctx.body);
-                return this.#notFound(ctx);
-            }
-            let res = await this.#chain([
-                ...route.middlewares,
-                ...route.handlers,
-            ])(ctx);
-            if (!res && ctx.body !== undefined) {
-                res = ctx.send(ctx.body);
+            if (hLen === 1 && mLen === 0) {
+                return ((await route.handlers[0](ctx)) ??
+                    (ctx.body !== undefined ? ctx.send(ctx.body) : this.#notFound(ctx)));
             }
-            if (!res) {
-                return this.#notFound(ctx);
-            }
-            return res;
+            return await this.#chain(ctx, mLen, route.middlewares, hLen, route.handlers);
         }
         catch (err) {
-            return this.#errorHandler(err, ctx);
+            if (!(err instanceof TezXError)) {
+                return this.#errorHandler?.(TezXError.internal(err?.message, err?.stack), ctx);
+            }
+            return this.#errorHandler?.(err, ctx);
         }
     }
     async serve(req, ...args) {

package/index.d.ts

@@ -1,15 +1,17 @@
+import { TezXError } from "./core/error.js";
 import { Router } from "./core/router.js";
 import { TezX } from "./core/server.js";
 export type { Context as BaseContext } from "./core/context.js";
-export type { NetAddr as AddressType, Callback, Ctx as Context, CookieOptions, ErrorHandler, FormDataOptions, HandlerType, HttpBaseResponse, HTTPMethod, Middleware, NextCallback, RequestHeaders, ResponseHeaders, ResponseInit, RouteMatchResult, RouteRegistry, Runtime, StaticFileArray, StaticServeOption, WebSocketCallback, WebSocketEvent, WebSocketOptions } from "./types/index.js";
+export type { NetAddr as AddressType, Callback, Ctx as Context, CookieOptions, FormDataOptions, HandlerType, HttpBaseResponse, HTTPMethod, Middleware, NextCallback, RequestHeaders, ResponseHeaders, ResponseInit, RouteMatchResult, RouteRegistry, Runtime, StaticFileArray, StaticServeOption, WebSocketCallback, WebSocketEvent, ReqHeaderKey, ResHeaderKey, ErrorHandler, ServeStatic, WebSocketOptions, } from "./types/index.js";
 export type { TezXConfig } from "./core/server.js";
 export type { TezXRequest } from "./core/request.js";
 export type { RouterConfig } from "./core/router.js";
-export { Router, TezX };
+export { Router, TezX, TezXError };
 export declare let version: string;
 declare const _default: {
     Router: typeof Router;
     TezX: typeof TezX;
     version: string;
+    TezXError: typeof TezXError;
 };
 export default _default;

package/index.js

@@ -1,9 +1,11 @@
+import { TezXError } from "./core/error.js";
 import { Router } from "./core/router.js";
 import { TezX } from "./core/server.js";
-export { Router, TezX };
-export let version = "3.0.10-beta";
+export { Router, TezX, TezXError };
+export let version = "3.0.12-beta";
 export default {
     Router,
     TezX,
     version,
+    TezXError,
 };