tezx 2.0.11 → 3.0.0

package/core/router.d.ts

@@ -1,58 +1,77 @@
-import { Callback, DuplicateMiddlewares, HTTPMethod, Middleware, PathType, StaticServeOption, UniqueMiddlewares } from "../types/index.js";
-import { Context } from "./context.js";
-import MiddlewareConfigure from "./MiddlewareConfigure.js";
+import { Callback, HandlerType, HTTPMethod, Middleware, RouteRegistry, ServeStatic } from "../types/index.js";
+/**
+ * Router configuration options.
+ */
 export type RouterConfig = {
     /**
-     * `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;
 };
-export declare class TrieRouter {
-    children: Map<string, TrieRouter>;
-    handlers: Map<HTTPMethod, {
-        callback: Callback<any>;
-        middlewares: UniqueMiddlewares | DuplicateMiddlewares;
-    }>;
-    pathname: string;
-    paramName: any;
-    isParam: boolean;
-    constructor(pathname?: string);
-}
-export type RouterHandler<T extends Record<string, any>> = {
-    callback: Callback<T>;
-    paramNames: string[];
-    regex: RegExp;
-    middlewares: UniqueMiddlewares | DuplicateMiddlewares;
-};
-export declare class Router<T extends Record<string, any> = {}> extends MiddlewareConfigure<T> {
+/**
+ * Router class responsible for managing HTTP routes, middlewares,
+ * and serving static files.
+ *
+ * @template T - Context state type, extended by route handlers.
+ */
+export declare class Router<T extends Record<string, any> = {}> {
     #private;
-    protected routers: Map<string, Map<HTTPMethod, RouterHandler<T>>>;
+    /** Environment variables accessible within this router */
     protected env: Record<string, string | number>;
-    protected triRouter: TrieRouter;
+    /** Internal route registry to hold all routes */
+    protected router?: RouteRegistry;
+    /** Array tracking registered routes and their handlers */
+    protected route: {
+        method: string;
+        pattern: string;
+        handlers: HandlerType;
+    }[];
+    /** Static file routes mapping */
+    protected staticFile: Record<string, Callback<any>>;
+    /** Base path prefix for all routes */
+    protected basePath: string;
+    /**
+     * Creates a new Router instance.
+     *
+     * @param config - Router configuration options
+     * @param config.basePath - Base path prefix for the router
+     * @param config.env - Environment variables for router
+     * @param config.routeRegistry - Custom route registry instance
+     */
     constructor({ basePath, env }?: RouterConfig);
     /**
-     * Serves static files from a specified directory.
+     * Registers static file routes to the application for serving files like HTML, CSS, JS, images, etc.
      *
-     * This method provides two overloads:
-     * 1. `static(route: string, folder: string, option?: StaticServeOption): this;`
-     *    - Serves static files from `folder` at the specified `route`.
-     * 2. `static(folder: string, option?: StaticServeOption): this;`
-     *    - Serves static files from `folder` at the root (`/`).
+     * This method maps routes to files defined in the `ServeStatic` object,
+     * and sets appropriate HTTP headers like `Cache-Control` and custom headers.
+     *
+     * @example
+     * ```ts
+     * import { serveStatic } from "tezx/bun"; // or "tezx/node"
+     *
+     * app.static(
+     *   serveStatic("public", {
+     *     cacheControl: "max-age=86400",
+     *     headers: {
+     *       "X-Powered-By": "TezX"
+     *     }
+     *   })
+     * );
+     * ```
      *
-     * @param {string} route - The base route to serve static files from (optional in overload).
-     * @param {string} folder - The folder containing the static files.
-     * @param {StaticServeOption} [option] - Optional settings for static file serving.
-     * @returns {this} Returns the current instance to allow method chaining.
+     * @param serveStatic - An object containing static file definitions and optional configuration.
+     * @returns The current instance for chaining.
      */
-    static(route: string, folder: string, option?: StaticServeOption): this;
-    static(folder: string, Option?: StaticServeOption): this;
+    static(serveStatic: ServeStatic): this;
     /**
      * Registers a GET route with optional middleware(s)
      * @param path - URL path pattern (supports route parameters)
@@ -62,158 +81,144 @@ export declare class Router<T extends Record<string, any> = {}> extends Middlewa
      * @example
      * // Simple GET route
      * app.get('/users', (ctx) => { ... });
-     *
-     * // With middleware
-     * app.get('/secure', authMiddleware, (ctx) => { ... });
-     * app.get(/^\/item\/(\d+)\/(edit|view)?\/?$/, (ctx) => { ... });
-     *
      * // With multiple middlewares
      * app.get('/admin', [authMiddleware, adminMiddleware], (ctx) => { ... });
      */
-    get<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    get<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    get<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
-    /**
-     * Registers a Server-Sent Events (SSE) route handler for the given path.
-     *
-     * This method sets up an HTTP GET route that sends real-time updates to the client
-     * over a persistent HTTP connection using the SSE protocol.
-     *
-     * ### Example:
-     * ```ts
-     * app.sse("/events", async (ctx) => {
-     *   const stream = new ReadableStream({
-     *     start(controller) {
-     *       controller.enqueue(new TextEncoder().encode("data: Hello\n\n"));
-     *       ctx.rawRequest?.signal?.addEventListener("abort", () => {
-     *          clearInterval(interval);
-     *          controller.close()
-     *        });
-     *     },
-     *   });
-     *
-     *   return ctx.send(stream, {
-     *     headers: {
-     *       "Content-Type": "text/event-stream",
-     *       "Cache-Control": "no-cache",
-     *       "Connection": "keep-alive",
-     *     },
-     *   });
-     * });
-     * ```
-     *
-     * @param {PathType} path - The route path for SSE (e.g. `/events`).
-     * @param {(ctx: Context) => any} handler - A handler function that returns a streamed response.
-     */
-    sse<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, handler: (ctx: Context<T & U, Path>) => any): void;
+    get<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    get<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    get<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers a POST route with optional middleware(s)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    post<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    post<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    post<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    post<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    post<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    post<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers a PUT route with optional middleware(s)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    put<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    put<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    put<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    put<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    put<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    put<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers a PATCH route with optional middleware(s)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    patch<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    patch<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    patch<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    patch<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    patch<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    patch<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers a DELETE route with optional middleware(s)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    delete<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    delete<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    delete<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    delete<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    delete<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    delete<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers an OPTIONS route (primarily for CORS preflight requests)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    options<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    options<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    options<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    options<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    options<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    options<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
      * Registers a HEAD route (returns headers only)
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
      */
-    head<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    head<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    head<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
-     * Registers a route that responds to all HTTP methods
+     * Register a route that responds to all HTTP methods.
+     *
      * @param path - URL path pattern
      * @param args - Handler callback or middleware(s) + handler
+     * @returns The Router instance for chaining
      */
-    all<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, callback: Callback<T & U, Path>): this;
-    all<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    all<U extends Record<string, any> = {}, Path extends PathType = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    all<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path>): this;
+    all<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    all<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
-     * Generic method registration for custom HTTP methods
-     * @param method - HTTP method name (e.g., 'PURGE')
-     * @param path - URL path pattern
-     * @param args - Handler callback or middleware(s) + handler
+     * Registers one or more HTTP method handlers for a given path.
      *
-     * @example
-     * // Register custom method
-     * server.addRoute('PURGE', '/cache', purgeHandler);
+     * Supports three overloads:
+     *
+     * 1. A single callback:
+     *    app.when("GET", "/path", callback)
+     *
+     * 2. A middleware and a callback:
+     *    app.when("GET", "/path", middleware, callback)
+     *
+     * 3. An array of middlewares and a callback:
+     *    app.when("GET", "/path", [middleware1, middleware2], callback)
+     *
+     * @template U - Additional context to be merged into the main context
+     * @template Path - The string literal type of the route path
+     *
+     * @param {HTTPMethod | HTTPMethod[]} methods - One or more HTTP methods like 'GET', 'POST', etc.
+     * @param {Path} path - The route path (e.g., '/login')
+     * @param {...(Middleware<T & U, Path> | Middleware<T & U, Path>[] | Callback<T & U, Path>)} args - Middleware(s) and final callback
+     *
+     * @returns {this} Returns the app instance for chaining
      */
-    addRoute<U extends Record<string, any> = {}, Path extends PathType = any>(method: HTTPMethod, path: Path, callback: Callback<T & U, Path>): this;
-    addRoute<U extends Record<string, any> = {}, Path extends PathType = any>(method: HTTPMethod, path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
-    addRoute<U extends Record<string, any> = {}, Path extends PathType = any>(method: HTTPMethod, path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
+    when<U extends Record<string, any> = {}, Path extends string = any>(methods: HTTPMethod | HTTPMethod[], path: Path, callback: Callback<T & U, Path>): this;
+    when<U extends Record<string, any> = {}, Path extends string = any>(methods: HTTPMethod | HTTPMethod[], path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path>): this;
+    when<U extends Record<string, any> = {}, Path extends string = any>(methods: HTTPMethod | HTTPMethod[], path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path>): this;
     /**
-     * Mount a sub-router at specific path prefix
-     * @param path - Base path for the sub-router
+     * Mount another Router instance at a given base path.
+     *
+     * Useful for modular route organization.
+     *
+     * @param path - Base path prefix to mount the sub-router
      * @param router - Router instance to mount
-     * @returns Current instance for chaining
+     * @returns The current Router instance for chaining
      *
      * @example
      * const apiRouter = new Router();
-     * apiRouter.get('/users', () => { ... });
-     * server.addRouter('/api', apiRouter);
+     * apiRouter.get('/users', userHandler);
+     * router.addRouter('/api', apiRouter);
      */
     addRouter<U extends Record<string, any> = {}, Path extends string = any>(path: Path, router: Router<T | U | any>): void;
     /**
-     * Create route group with shared path prefix
+     * Create a route group with shared path prefix.
+     *
+     * Provides a scoped Router instance to define routes under a common prefix.
+     *
      * @param prefix - Path prefix for the group
-     * @param callback - Function that receives group-specific router
-     * @returns Current router instance for chaining
+     * @param callback - Function receiving the scoped Router
+     * @returns The current Router instance for chaining
      *
      * @example
-     * app.group('/v1', (group) => {
+     * router.group('/v1', (group) => {
      *   group.get('/users', v1UserHandler);
      * });
      */
     group<U extends Record<string, any> = {}, Prefix extends string = any>(prefix: Prefix, callback: (group: Router<T & U>) => void): this;
     /**
-     * Register middleware with flexible signature
-     * @overload
-     * @param path - Optional path to scope middleware
-     * @param middlewares - Middleware(s) to register
-     * @param [callback] - Optional sub-router or handler
+     * Register middleware(s) optionally scoped by path.
+     *
+     * Supports multiple overloads for flexibility:
+     * - `use(middleware)`
+     * - `use([middleware1, middleware2])`
+     * - `use(path, middleware)`
+     * - `use(path, [middleware1, middleware2])`
+     * - `use(path, middleware, callbackOrRouter)`
+     *
+     * @param args - Path (optional), middleware(s), and optional handler or sub-router
+     * @returns The current Router instance for chaining
      */
-    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path> | Router<T & U | any>): this;
-    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path> | Router<T & U | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
     use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>[]): this;
     use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, middlewares: Middleware<T & U, Path>): this;
-    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path> | Router<T & U | any>): this;
-    use<U extends Record<string, any> = {}, Path extends string = any>(middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path> | Router<T & U | any>): this;
-    use<U extends Record<string, any> = {}, Path extends string = any>(middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path> | Router<T & U | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(path: Path, callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(middlewares: Middleware<T & U, Path>[], callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(middleware: Middleware<T & U, Path>, callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
     use<U extends Record<string, any> = {}, Path extends string = any>(middlewares: Middleware<T & U, Path>[]): this;
     use<U extends Record<string, any> = {}, Path extends string = any>(middleware: Middleware<T & U, Path>): this;
-    use<U extends Record<string, any> = {}, Path extends string = any>(callback: Callback<T & U, Path> | Router<T & U | any>): this;
+    use<U extends Record<string, any> = {}, Path extends string = any>(callback: Callback<T & U, Path> | Router<(T & U) | any>): this;
 }