tezx 2.0.11 → 3.0.0

package/core/router.js

@@ -1,28 +1,14 @@
-import { addBaseToRegex, compileRegexRoute } from "../utils/regexRouter.js";
-import { getFiles } from "../utils/staticFile.js";
-import { sanitizePathSplit, wildcardOrOptionalParamRegex, } from "../utils/url.js";
-import { GlobalConfig } from "./config.js";
-import MiddlewareConfigure, { TriMiddleware, } from "./MiddlewareConfigure.js";
-export class TrieRouter {
-    children = new Map();
-    handlers = new Map();
-    pathname;
-    paramName;
-    isParam = false;
-    constructor(pathname = "/") {
-        this.children = new Map();
-        this.pathname = pathname;
-    }
-}
-export class Router extends MiddlewareConfigure {
-    routers = new Map();
+import { sanitizePathSplitBasePath } from "../utils/low-level.js";
+import { TezXError } from "./error.js";
+export class Router {
     env = {};
-    triRouter;
+    router;
+    route = [];
+    staticFile = Object.create(null);
+    basePath;
     constructor({ basePath = "/", env = {} } = {}) {
-        super(basePath);
         this.basePath = basePath;
         this.env = { ...env };
-        this.triRouter = new TrieRouter(basePath);
         this.get = this.get.bind(this);
         this.post = this.post.bind(this);
         this.put = this.put.bind(this);
@@ -31,57 +17,30 @@ export class Router extends MiddlewareConfigure {
         this.addRouter = this.addRouter.bind(this);
         this.group = this.group.bind(this);
     }
-    static(...args) {
-        let route = "";
-        let dir;
-        let options = {};
-        switch (args.length) {
-            case 3:
-                [route, dir, options] = args;
-                break;
-            case 2:
-                if (typeof args[1] === "object") {
-                    [dir, options] = args;
-                }
-                else {
-                    [route, dir] = args;
-                }
-                break;
-            case 1:
-                [dir] = args;
-                break;
-            default:
-                throw new Error(`\x1b[1;31m404 Not Found\x1b[0m \x1b[1;32mInvalid arguments\x1b[0m`);
+    static(serveStatic) {
+        if (Array.isArray(serveStatic?.files)) {
+            serveStatic?.files.forEach((r) => {
+                this.staticFile[`GET ${r?.route}`] = (ctx) => {
+                    if (serveStatic?.options?.cacheControl) {
+                        ctx.setHeader("Cache-Control", serveStatic?.options.cacheControl);
+                    }
+                    let headers = serveStatic?.options?.headers;
+                    if (headers) {
+                        for (const key in headers) {
+                            let value = headers?.[key];
+                            ctx.headers.set(key, value);
+                        }
+                    }
+                    return ctx.sendFile(r.fileSource);
+                };
+            });
         }
-        getFiles(dir, route, this, options);
         return this;
     }
     get(path, ...args) {
         this.#registerRoute("GET", path, ...args);
         return this;
     }
-    sse(path, handler) {
-        this.get(path, async (ctx) => {
-            let res = await handler(ctx);
-            const headersMap = {};
-            if (res instanceof Response) {
-                for (const [key, value] of res.headers.entries()) {
-                    headersMap[key.toLowerCase()] = value;
-                }
-                res = res.body;
-            }
-            const headers = {
-                ...headersMap,
-                "content-type": "text/event-stream",
-                "cache-control": "no-cache",
-                connection: "keep-alive",
-            };
-            return new Response(res, {
-                status: 200,
-                headers,
-            });
-        });
-    }
     post(path, ...args) {
         this.#registerRoute("POST", path, ...args);
         return this;
@@ -102,27 +61,26 @@ export class Router extends MiddlewareConfigure {
         this.#registerRoute("OPTIONS", path, ...args);
         return this;
     }
-    head(path, ...args) {
-        this.#registerRoute("HEAD", path, ...args);
-        return this;
-    }
     all(path, ...args) {
         this.#registerRoute("ALL", path, ...args);
         return this;
     }
-    addRoute(method, path, ...args) {
-        this.#registerRoute(method, path, ...args);
+    when(methods, path, ...args) {
+        const methodList = Array.isArray(methods) ? methods : [methods];
+        for (const method of methodList) {
+            this.#registerRoute(method.toUpperCase(), path, ...args);
+        }
         return this;
     }
     addRouter(path, router) {
-        return this.#routeAddTriNode(path, router);
+        return this.#addRouterInstance(path, router);
     }
     group(prefix, callback) {
         const router = new Router({
             basePath: prefix,
         });
         callback(router);
-        this.#routeAddTriNode("/", router);
+        this.#addRouterInstance("/", router);
         return this;
     }
     use(...args) {
@@ -159,15 +117,26 @@ export class Router extends MiddlewareConfigure {
         else if (args[0] instanceof Router) {
             router = args[0];
         }
-        this.#addRouteMiddleware(path, middlewares);
+        if (middlewares?.length) {
+            this.#addRoute("ALL", path, middlewares);
+        }
         if (router && router instanceof Router) {
             this.addRouter(path, router);
         }
         return this;
     }
+    #addRoute(method, path, handlers) {
+        let pattern = `/${sanitizePathSplitBasePath(this.basePath, path).join("/")}`;
+        this.router?.addRoute(method, pattern, handlers);
+        this.route.push({
+            method: method,
+            pattern: pattern,
+            handlers: handlers,
+        });
+    }
     #registerRoute(method, path, ...args) {
         if (args.length === 0) {
-            throw new Error("At least one handler is required.");
+            throw new TezXError("At least one handler is required.");
         }
         let middlewares = [];
         let callback;
@@ -184,289 +153,21 @@ export class Router extends MiddlewareConfigure {
             callback = args[0];
         }
         if (typeof callback !== "function") {
-            throw new Error("Route callback function is missing or invalid.");
+            throw new TezXError("Route callback function is missing or invalid.");
         }
         if (!middlewares.every((middleware) => typeof middleware === "function")) {
-            throw new Error("Middleware must be a function or an array of functions.");
-        }
-        this.#addRoute(method, path, callback, middlewares);
-    }
-    #addRoute(method, path, callback, middlewares) {
-        let finalMiddleware = middlewares;
-        if (!GlobalConfig.allowDuplicateMw) {
-            finalMiddleware = new Set(middlewares);
-        }
-        if (path instanceof RegExp) {
-            let regex = addBaseToRegex(this.basePath, path);
-            let regexPath = `regex://${regex?.source}`;
-            let handler = this.routers.get(regexPath);
-            if (!handler) {
-                handler = new Map();
-                handler.set(method, {
-                    callback: callback,
-                    paramNames: [],
-                    regex: regex,
-                    middlewares: finalMiddleware,
-                });
-                return this.routers.set(regexPath, handler);
-            }
-            if (!GlobalConfig.overwriteMethod && handler.has(method))
-                return;
-            return handler.set(method, {
-                callback: callback,
-                paramNames: [],
-                regex: regex,
-                middlewares: finalMiddleware
-            });
-        }
-        const parts = sanitizePathSplit(this.basePath, path);
-        let p = parts.join("/");
-        if (wildcardOrOptionalParamRegex.test(`/${p}`)) {
-            let strPath = `string://${p}`;
-            let { paramNames, regex } = compileRegexRoute(parts);
-            let handler = this.routers.get(strPath);
-            if (!handler) {
-                handler = new Map();
-                handler.set(method, {
-                    callback: callback,
-                    regex: regex,
-                    paramNames: paramNames,
-                    middlewares: finalMiddleware,
-                });
-                return this.routers.set(strPath, handler);
-            }
-            if (!GlobalConfig.overwriteMethod && handler.has(method))
-                return;
-            return handler.set(method, {
-                callback: callback,
-                regex: regex,
-                paramNames: paramNames,
-                middlewares: finalMiddleware
-            });
-        }
-        let node = this.triRouter;
-        for (const part of parts) {
-            if (part.startsWith(":")) {
-                if (!node.children.has(":")) {
-                    node.children.set(":", new TrieRouter());
-                }
-                node = node.children.get(":");
-                node.isParam = true;
-                if (!node.paramName) {
-                    node.paramName = part.slice(1);
-                }
-            }
-            else {
-                if (!node.children.has(part)) {
-                    node.children.set(part, new TrieRouter());
-                }
-                node = node.children.get(part);
-            }
+            throw new TezXError("Middleware must be a function or an array of functions.");
         }
-        if (!GlobalConfig.overwriteMethod && node.handlers.has(method))
-            return;
-        node.handlers.set(method, {
-            callback: callback,
-            middlewares: finalMiddleware,
-        });
-        node.pathname = `/${p}`;
-    }
-    #addRouteMiddleware(path, middlewareFunctions) {
-        this.addMiddleware(path, middlewareFunctions);
+        this.#addRoute(method, path, [...middlewares, callback]);
     }
-    #routeAddTriNode(path, router) {
+    #addRouterInstance(path, router) {
         this.env = { ...this.env, ...router.env };
         if (!(router instanceof Router)) {
-            throw new Error("Router instance is required.");
-        }
-        const parts = sanitizePathSplit(this.basePath, path);
-        if (router.routers.size) {
-            for (const [segment, handlers] of router.routers) {
-                if (segment.indexOf("string://") == 0) {
-                    let pattern = segment.replace(/^string:\/\//, "");
-                    let joined = [...parts, pattern].join("/");
-                    let strPath = `string://${joined}`;
-                    if (this.routers.has(strPath)) {
-                        const baseRouter = this.routers.get(strPath);
-                        for (const [method, handler] of handlers) {
-                            let { regex, paramNames } = baseRouter?.get(method);
-                            handler.regex = regex;
-                            handler.paramNames = paramNames;
-                            if (!GlobalConfig.overwriteMethod && baseRouter.has(method))
-                                continue;
-                            baseRouter.set(method, handler);
-                        }
-                    }
-                    else {
-                        let h = new Map();
-                        for (const [method, { callback, middlewares }] of handlers) {
-                            let { paramNames, regex } = compileRegexRoute(joined);
-                            h.set(method, {
-                                callback: callback,
-                                middlewares: middlewares,
-                                paramNames,
-                                regex
-                            });
-                        }
-                        this.routers.set(strPath, h);
-                    }
-                }
-                else {
-                    let pattern = segment.replace("regex://", "");
-                    let base = parts?.join("/");
-                    let regex = addBaseToRegex(base, new RegExp(pattern));
-                    let regexPath = `regex://${regex.source}`;
-                    if (this.routers.has(regexPath)) {
-                        const baseRouter = this.routers.get(regexPath);
-                        for (const [method, handler] of handlers) {
-                            handler.regex = regex;
-                            handler.paramNames = [];
-                            if (!GlobalConfig.overwriteMethod && baseRouter.has(method))
-                                continue;
-                            baseRouter.set(method, handler);
-                        }
-                    }
-                    else {
-                        let h = new Map();
-                        for (const [method, { callback, middlewares }] of handlers) {
-                            h.set(method, {
-                                callback: callback,
-                                middlewares: middlewares,
-                                paramNames: [],
-                                regex
-                            });
-                        }
-                        this.routers.set(regexPath, h);
-                    }
-                }
-            }
-        }
-        let rootNode = this.triRouter;
-        let rootMiddlewares = this.triMiddlewares;
-        if (parts.length == 0) {
-            this.#addMiddlewareHandlerIDsTriNode(rootNode, rootMiddlewares, router);
-        }
-        else {
-            for (const part of parts) {
-                if (part.startsWith(":")) {
-                    if (!rootNode.children.has(":")) {
-                        rootNode.children.set(":", new TrieRouter());
-                    }
-                    rootNode = rootNode.children.get(":");
-                    rootNode.isParam = true;
-                    if (!rootNode.paramName) {
-                        rootNode.paramName = part.slice(1);
-                    }
-                }
-                else {
-                    if (!rootNode.children.has(part)) {
-                        rootNode.children.set(part, new TrieRouter());
-                    }
-                    rootNode = rootNode.children.get(part);
-                }
-            }
-            for (const part of parts) {
-                if (part.startsWith("*")) {
-                    if (!rootMiddlewares.children.has("*")) {
-                        rootMiddlewares.children.set("*", new TriMiddleware());
-                    }
-                    rootMiddlewares = rootMiddlewares.children.get("*");
-                }
-                else if (part.startsWith(":")) {
-                    const isOptional = part?.endsWith("?");
-                    if (isOptional) {
-                        rootMiddlewares.isOptional = isOptional;
-                        continue;
-                    }
-                    if (!rootMiddlewares.children.has(":")) {
-                        rootMiddlewares.children.set(":", new TriMiddleware());
-                    }
-                    rootMiddlewares = rootMiddlewares.children.get(":");
-                }
-                else {
-                    if (!rootMiddlewares.children.has(part)) {
-                        rootMiddlewares.children.set(part, new TriMiddleware());
-                    }
-                    rootMiddlewares = rootMiddlewares.children.get(part);
-                }
-            }
-            this.#addMiddlewareHandlerIDsTriNode(rootNode, rootMiddlewares, router);
-        }
-    }
-    #addMiddlewareHandlerIDsTriNode(rootNode, rootMiddlewares, router) {
-        function addSubRouter(children, node) {
-            let rtN = node;
-            for (const element of children) {
-                const pathSegment = element[0];
-                const subRouter = element[1];
-                if (rtN.children.has(pathSegment)) {
-                    let findNode = rtN.children.get(pathSegment);
-                    for (const [method, handlers] of subRouter.handlers) {
-                        if (!GlobalConfig.overwriteMethod && node.handlers.has(method))
-                            return;
-                        findNode.handlers.set(method, handlers);
-                    }
-                    if (subRouter.children.size) {
-                        addSubRouter(subRouter.children, findNode);
-                    }
-                }
-                else {
-                    rtN.children.set(pathSegment, subRouter);
-                }
-            }
-        }
-        let routerNode = router.triRouter;
-        const routerMiddlewares = router.triMiddlewares;
-        for (const [method, handlers] of routerNode.handlers) {
-            if (!GlobalConfig.overwriteMethod) {
-                rootNode.handlers.set(method, handlers);
-                continue;
-            }
-            if (!rootNode.handlers.has(method)) {
-                rootNode.handlers.set(method, handlers);
-            }
-        }
-        if (routerNode.children.size > 0) {
-            addSubRouter(routerNode.children, rootNode);
-        }
-        function addMiddleware(children, node) {
-            let n = node;
-            for (const [path, middlewareNode] of children) {
-                if (n.children.has(path)) {
-                    let findNode = n.children.get(path);
-                    if (GlobalConfig.allowDuplicateMw) {
-                        findNode.middlewares.push(...middlewareNode.middlewares);
-                    }
-                    else {
-                        for (const mw of middlewareNode.middlewares) {
-                            if (findNode.middlewares.has(mw)) {
-                                middlewareNode.middlewares.delete(mw);
-                            }
-                            findNode.middlewares.add(mw);
-                        }
-                    }
-                    if (middlewareNode.children.size) {
-                        addMiddleware(middlewareNode.children, findNode);
-                    }
-                }
-                else {
-                    n.children.set(path, middlewareNode);
-                }
-            }
-        }
-        if (GlobalConfig.allowDuplicateMw) {
-            rootMiddlewares.middlewares.push(...routerMiddlewares.middlewares);
-        }
-        else {
-            for (const mw of routerMiddlewares.middlewares) {
-                if (rootMiddlewares.middlewares.has(mw)) {
-                    routerMiddlewares.middlewares.delete(mw);
-                }
-                rootMiddlewares.middlewares.add(mw);
-            }
-        }
-        if (routerMiddlewares.children.size > 0) {
-            addMiddleware(routerMiddlewares.children, rootMiddlewares);
+            throw new TezXError("Router instance is required.");
         }
+        router.route.forEach((r) => {
+            this.#addRoute(r?.method, `/${sanitizePathSplitBasePath(path, r?.pattern).join("/")}`, r?.handlers);
+        });
+        Object.assign(this.staticFile, router.staticFile);
     }
 }

package/core/server.d.ts

@@ -1,33 +1,6 @@
-import { ConnAddress, HTTPMethod, Middleware } from "../types/index.js";
-import { Context } from "./context.js";
+import { Callback, ErrorHandler, RouteRegistry } from "../types/index.js";
 import { Router, RouterConfig } from "./router.js";
-export type TezXServeOptions = {
-    connInfo: ConnAddress;
-};
 export type TezXConfig = {
-    /**
-     * `allowDuplicateMw` determines whether duplicate middleware functions
-     * are allowed in the router.
-     *
-     * - When `true`: The same middleware can be added multiple times.
-     * - When `false`: Ensures each middleware is registered only once
-     *   per route or application context.
-     *
-     * @default false
-     */
-    allowDuplicateMw?: boolean;
-    /**
-     * `overwriteMethod` controls whether existing route handlers
-     * should be overwritten when a new handler for the same
-     * HTTP method and path is added.
-     *
-     * - When `true`: The new handler replaces the existing one.
-     * - When `false`: Prevents overwriting, ensuring that the
-     *   first registered handler remains active.
-     *
-     * @default true
-     */
-    overwriteMethod?: boolean;
     /**
      * 🔄 Hook to transform or normalize the incoming request pathname before routing.
      *
@@ -47,6 +20,11 @@ export type TezXConfig = {
      * @returns The transformed or resolved path used for routing (e.g., `/api/users`)
      */
     onPathResolve?: (pathname: string) => string;
+    /**
+     * Custom route registry instance used internally to store routes.
+     * If not provided, the router will use the default CombineRouteRegistry.
+     */
+    routeRegistry?: RouteRegistry;
     /**
      * Enables or disables debugging for the middleware.
      * When set to `true`, detailed debug logs will be output,
@@ -56,16 +34,99 @@ export type TezXConfig = {
      */
     debugMode?: boolean;
 } & RouterConfig;
+/**
+ * TezX is an ultra-fast, flexible request router and server handler.
+ * It supports plug-and-play for Bun, and Node runtimes.
+ *
+ * @template T - The environment object shared across requests.
+ *
+ * @example
+ * ```ts
+ * const app = new TezX();
+ *
+ * app.get("/hello", (ctx) => ctx.text("Hello TezX"));
+ * bunAdapter(app).listen();
+ * ```
+ */
 export declare class TezX<T extends Record<string, any> = {}> extends Router<T> {
     #private;
-    constructor({ basePath, env, debugMode, onPathResolve, allowDuplicateMw, overwriteMethod, }?: TezXConfig);
-    protected findRoute(method: HTTPMethod, pathname: string): {
-        callback: any;
-        middlewares: Middleware<T>[];
-        params: Record<string, null | string>;
-    } | null;
-    serve(req: Request, options: TezXServeOptions): Promise<Response | {
-        websocket: (props: any) => any;
-        ctx: Context;
-    }>;
+    /** Internal route registry to hold all routes */
+    protected router?: RouteRegistry;
+    constructor({ basePath, env, debugMode, onPathResolve, routeRegistry, }?: TezXConfig);
+    /**
+     * Register a custom 404 (not found) handler.
+     *
+     * @param callback - Function to handle unmatched routes.
+     * @returns The current TezX instance (for chaining).
+     *
+     * @example
+     * app.notFound((ctx) => ctx.status(404).text("Oops! Page not found."));
+     */
+    notFound(callback: Callback<T>): this;
+    /**
+     * Register a global error handler for uncaught route errors.
+     *
+     * @param callback - Function to handle thrown exceptions or failed routes.
+     * @returns The current TezX instance (for chaining).
+     *
+     * @example
+     * app.onError((err, ctx) => {
+     *   return ctx.status(500).text("Server crashed!");
+     * });
+     */
+    onError(callback: ErrorHandler<T>): this;
+    /**
+     * Main request handler compatible with multiple runtimes (Node.js, Deno, Bun).
+     *
+     * This function can be passed directly to native HTTP servers to handle incoming requests.
+     *
+     * ### Usage examples:
+     *
+     * #### Bun
+     * ```ts
+     * // Simple usage with Bun's built-in HTTP server
+     * app.serve(request, server);
+     *
+     * // Or with WebSocket support (required for ws handling)
+     * Bun.serve({
+     *   port: 3001,
+     *   reusePort: true, // enables SO_REUSEPORT for clustering
+     *   fetch: app.serve,
+     *   websocket: wsHandlers()
+     * });
+     * ```
+     *
+     * #### Deno
+     * ```ts
+     * // Using Deno’s serve method with connection info
+     * serve((req, connInfo) => app.serve(req, connInfo));
+     *
+     * // Or using Deno’s built-in Deno.serve with options
+     * Deno.serve({ port: 8080 }, app.serve);
+     * ```
+     *
+     * #### Node.js
+     * ```ts
+     * import { createServer } from "http";
+     * import { mountTezXOnNode } from "tezx/node";
+     *
+     * // Option 1: Manually convert and forward request/response
+     * const response = await app.serve(toWebRequest(req, req.method), req, res, server);
+     *
+     * // Option 2: Use provided utility to mount TezX app onto native HTTP server
+     * const server = createServer();
+     * mountTezXOnNode(app, server);
+     * server.listen(3000);
+     * ```
+     *
+     * @param {Request} req - Native Fetch API Request object.
+     * @param {...any} args - Runtime-specific arguments such as connection info (Deno), server instances, or response objects.
+     * @returns {Promise<Response>} The final response to be sent back to the client or the result of WebSocket handlers.
+     *
+     * @example
+     * ```ts
+     * const response = await app.serve(new Request("http://localhost/hello"));
+     * ```
+     */
+    serve(req: Request, ...args: any[]): Promise<Response>;
 }