@bepalo/router 1.8.27 → 1.10.31

package/README.md

@@ -17,13 +17,41 @@ Please refer to the [change-log](CHANGELOG.md).
 
 ## Docs
 
-- [Framework](docs/router-framework.md).
+### -> [Router](docs/router.md)
+
+### -> [Router Framework](docs/router-framework.md) [new]
+
+## ✨ Features
+
+- ⚡ **High Performance** - Built on a radix tree for O(k) route matching (where k is path length)
+- 📦 **Optional file-based framework** - extends the `Router` to load routes from files and folders.
+- 🎯 **Flexible Routing Engine** - Support for path parameters, wildcards (`*`, `.*`, `**`, `.**`), and all HTTP methods
+- 🎭 **Multiple Handler Types** - Filters, hooks, afters, handlers, fallbacks, and catchers
+- 🔌 **Middleware Pipeline** - Chain multiple handlers with early exit capability
+- 🛡️ **Error Handling** - Built-in error catching with contextual error handlers
+- 🔄 **Method-Based Routing** - Separate routing trees for each HTTP method
+- 📦 **Local Dependencies** - Minimal Dependencies — Only internal @bepalo packages
+- 🌐 **Runtime Agnostic** - Works with Bun, Deno, Node.js, and other runtimes
+- 🔧 **TypeScript Ready** - Full type definitions included
+- 🧩 **Composable Router Architecture** - Append one router to another with a path prefix.
+- 🛠️ **Provided Helper Utilities** - Built-in response helpers (json, html, parseBody, upload, etc.)
+- 🛠️ **Provided Middleware Utilities** - CORS, rate limiting, authentication helpers
+- 🔐 **Normalized pathname option** - An option to normalize pathnames.
+
+## Design goals
+
+- Server independent routing. `Request` -(handlers)-> `Response`.
+- Predictable, deterministic route matching and pipeline flow.
+- Composable: small routers can be appended under prefixes.
+- Low overhead and streaming-friendly to support large uploads and proxies.
+- Explicit, type-safe context passing for handlers (CTX types).
 
 ## 📑 Table of Contents
 
 1. [🏆 @bepalo/router](#-bepalorouter)
 2. [✨ Features](#-features)
-3. [🚀 Get Started](#-get-started)
+3. [✨ Design goals](#design-goals)
+4. [🚀 Get Started](#-get-started)
    - [📥 Installation](#-installation)
    - [📦 Basic Usage](#-basic-usage)
    - [Example](#example)
@@ -31,10 +59,10 @@ Please refer to the [change-log](CHANGELOG.md).
      - [Bun](#bun)
      - [Deno](#deno)
      - [Nodejs](#nodejs)
-4. [📚 Core Concepts](#-core-concepts)
+5. [📚 Core Concepts](#-core-concepts)
    - [Handler Types & Execution Order](#handler-types--execution-order)
    - [Router Context](#router-context)
-5. [📖 API Reference](#-api-reference)
+6. [📖 API Reference](#-api-reference)
    - [Router Class](#router-class)
      - [Constructor](#constructor)
      - [Configuration Options](#configuration-options)
@@ -49,27 +77,11 @@ Please refer to the [change-log](CHANGELOG.md).
      - [Path Patterns](#path-patterns)
      - [Route Priority](#route-priority)
      - [Router Composition Example](#router-composition-example)
-6. [🎯 Performance](#-performance)
+7. [🎯 Performance](#-performance)
    - [Comparison with Other Routers](#comparison-with-other-routers)
-7. [📄 License](#-license)
-8. [🕊️ Thanks and Enjoy](#-thanks-and-enjoy)
-9. [💖 Be a Sponsor](#-be-a-sponsor)
-
-## ✨ Features
-
-- ⚡ **High Performance** - Built on a radix tree for O(k) route matching (where k is path length)
-- 🎯 **Flexible Routing Engine** - Support for path parameters, wildcards (`*`, `.*`, `**`, `.**`), and all HTTP methods
-- 🎭 **Multiple Handler Types** - Filters, hooks, afters, handlers, fallbacks, and catchers
-- 🔌 **Middleware Pipeline** - Chain multiple handlers with early exit capability
-- 🛡️ **Error Handling** - Built-in error catching with contextual error handlers
-- 🔄 **Method-Based Routing** - Separate routing trees for each HTTP method
-- 📦 **Local Dependencies** - Minimal Dependencies — Only internal @bepalo packages
-- 🌐 **Runtime Agnostic** - Works with Bun, Deno, Node.js, and other runtimes
-- 🔧 **TypeScript Ready** - Full type definitions included
-- 🧩 **Composable Router Architecture** - Append one router to another with a path prefix.
-- 🛠️ **Built-in Helper Utilities** - Built-in response helpers (json, html, parseBody, upload, etc.)
-- 🔐 **Middleware Integration** - CORS, rate limiting, authentication helpers
-- 🔐 **Normalized pathname option** - An option to normalize pathnames.
+8. [📄 License](#-license)
+9. [🕊️ Thanks and Enjoy](#-thanks-and-enjoy)
+10. [💖 Be a Sponsor](#-be-a-sponsor)
 
 ## 🚀 Get Started
 
@@ -91,9 +103,6 @@ yarn add @bepalo/router
 
 ```ts
 // Import directly using the URL:
-
-import { Router } from "npm:@bepalo/router";
-// or
 import { Router } from "jsr:@bepalo/router";
 ```
 
@@ -103,36 +112,50 @@ import { Router } from "jsr:@bepalo/router";
 import {
   Router,
   text,
+  html,
   json,
   type CTXBody,
   parseBody,
-  type CTXUpload,
-  parseUploadStreaming,
 } from "@bepalo/router";
 // } from "jsr:@bepalo/router"; // for deno
 
 // Create a router instance
-const router = new Router();
+const router = new Router({
+  defaultHeaders: () => [
+    ["X-Powered-By", "@bepalo/router"],
+    ["Date", new Date().toUTCString()]
+  ],
+  defaultCatcher: (req, { error }) => {
+    console.error("Error:", error);
+    return status(500);
+  }
+});
 
 // Simple GET route
 router.handle("GET /", () => text("Hello World!"));
 
 // Route with parameters
-router.handle("GET /users/:id", (req, ctx) => json({ userId: ctx.params.id }));
+router.handle("GET /users/:id",
+  (req, { params }) => json({ userId: ctx.params.id })
+);
 
 // POST route with JSON response
-router.handle("POST /users", async (req) => {
-  const body = await req.json();
-  return json({ created: true, data: body }, { status: 201 });
-});
+router.handle<CTXBody>("POST /users", [
+  parseBody({ accept: ["application/json"], maxSize: 2048 }),
+  async (req, { body }) => {
+    return json({ created: true, data: body }, { status: 201 });
+  }
+]);
 
-// 404 fallback
-router.fallback("*", () => status(404));
+// Custom fallback handler
+router.fallback("GET /.**",
+  () => html(`<h2>404: Not Found!</h2>`, { status: 404 })
+);
 
-// Error handler
-router.catch("*", (req, ctx) => {
-  console.error("Error:", ctx.error);
-  return status(500, "Something Went Wrong");
+// Custom error handler
+router.catch("ALL /api/**", (req, { error }) => {
+  console.error("API Error:", error);
+  return json({ error: error.message }, { status: 500 });
 });
 
 // Start server (Bun example)
@@ -140,6 +163,7 @@ Bun.serve({
   port: 3000,
   fetch: (req) => router.respond(req),
 });
+console.log("Server running at http://localhost:3000");
 
 // Start server (Deno example)
 Deno.serve(
@@ -150,7 +174,38 @@ Deno.serve(
   router.respond.bind(router),
 );
 
-console.log("Server running at http://localhost:3000");
+```
+
+## 📚 Core Concepts
+
+### Handler Types & Execution Order
+
+The router processes requests in this specific order:
+
+    1. Hooks (router.hook()) - Pre-processing, responses are ignored
+
+    2. Filters (router.filter()) - Request validation/authentication
+
+    3. Handlers (router.handle()) - Main request processing
+
+    4. Fallbacks (router.fallback()) - When no handler matches
+
+    5. Afters (router.after()) - Post-processing, responses are ignored
+
+    6. Catchers (router.catch()) - Error handling
+
+### Router Context
+
+Each handler receives a context object and they can be extended as needed.
+
+```ts
+interface RouterContext {
+  params: Record<string, string>; // Route parameters
+  headers: Headers; // Response headers
+  response?: Response; // Final response
+  error?: Error; // Uncertain error
+  found: { ...: boolean }; // which handler types were found
+}
 ```
 
 ### Example
@@ -286,21 +341,12 @@ router.fallback("GET /api/.**", () =>
 );
 
 // Error handling
-router.catch(
-  [
-    "GET /api/.**",
-    "POST /api/.**",
-    "PUT /api/.**",
-    "PATCH /api/.**",
-    "DELETE /api/.**",
-  ],
-  [
-    (req, ctx) => {
-      console.error("APIError:", ctx.error);
-      return json({ error: "Something went wrong" }, { status: 500 });
-    },
-  ],
-);
+router.catch("CRUD /api/.**", [
+  (req, ctx) => {
+    console.error("APIError:", ctx.error);
+    return json({ error: "Something went wrong" }, { status: 500 });
+  },
+]);
 
 // Start server
 Bun.serve({
@@ -321,7 +367,7 @@ console.log("Server listening on http://localhost:3000");
 #### Bun
 
 ```js
-// Bun example
+// Serving using Bun
 Bun.serve({
   port: 3000,
   async fetch(req, server) {
@@ -335,7 +381,7 @@ console.log("Server running at http://localhost:3000");
 #### Deno
 
 ```js
-// Deno example
+// Serving using Deno
 Deno.serve(
   {
     port: 3000,
@@ -356,7 +402,7 @@ Deno.serve(
 #### Nodejs
 
 ```js
-// Node.js compatibility example (uses Fetch bridge; not optimized)
+// Serving using Node.js
 http
   .createServer(async (req, res) => {
     const url = new URL(req.url || "/", `http://${req.headers.host}`);
@@ -404,445 +450,6 @@ http
   .listen(3000, () => console.log("Server running on port 3000"));
 ```
 
-## 📚 Core Concepts
-
-### Handler Types & Execution Order
-
-The router processes requests in this specific order:
-
-    1. Hooks (router.hook()) - Pre-processing, responses are ignored
-
-    2. Filters (router.filter()) - Request validation/authentication
-
-    3. Handlers (router.handle()) - Main request processing
-
-    4. Fallbacks (router.fallback()) - When no handler matches
-
-    5. Afters (router.after()) - Post-processing, responses are ignored
-
-    6. Catchers (router.catch()) - Error handling
-
-### Router Context
-
-Each handler receives a context object with:
-
-```ts
-interface RouterContext {
-  params: Record<string, string>; // Route parameters
-  headers: Headers; // Response headers
-  address?: SocketAddress | null; // Client address
-  response?: Response; // Final response
-  error?: Error; // Caught error
-  found: {
-    hooks: boolean; // Whether hooks were found
-    afters: boolean; // Whether afters were found
-    filters: boolean; // Whether filters were found
-    handlers: boolean; // Whether handlers were found
-    fallbacks: boolean; // Whether fallbacks were found
-    catchers: boolean; // Whether catchers were found
-  };
-}
-```
-
-## 📖 API Reference
-
-### Router Class
-
-#### Constructor
-
-```ts
-new Router<Context>(config?: RouterConfig<Context>)
-```
-
-#### Configuration Options:
-
-```ts
-interface RouterConfig<Context extends RouterContext> {
-  defaultHeaders?: Array<[string, string]>; // Default response headers
-  defaultCatcher?: Handler<Context>; // Global error handler
-  defaultFallback?: Handler<Context>; // Global fallback handler
-  enable?: HandlerEnable; // Handler types enable/disable
-  normalizeTrailingSlash?: boolean; // treat '/abc/' and '/abc' as the same
-}
-```
-
-#### Handler Registration Methods
-
-All methods support method chaining and return the router instance. However `Response` type responses from hooks and afters are ignored unlike the rest.
-
-```ts
-// Register a hook (pre-processing)
-router.hook(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-
-// Register a filter (request validation)
-router.filter(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-
-// Register a main handler
-router.handle(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-
-// Register a fallback handler (404)
-router.fallback(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-
-// Register an error catcher
-router.catch(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-
-// Register an after handler (post-processing)
-router.after(
-  urls: "*" | MethodPath | MethodPath[],
-  pipeline: Handler<Context> | Pipeline<Context>,
-  options?: HandlerOptions
-)
-```
-
-#### Handler Options:
-
-```ts
-interface HandlerOptions {
-  overwrite?: boolean; // Allow overriding existing routes (default: false)
-}
-```
-
-#### Router Composition
-
-```ts
-// Append another router with a prefix. Does not merge router configurations
-router.append(
-  baseUrl: `/${string}`,
-  router: Router<Context>,
-  options?: HandlerOptions
-)
-```
-
-#### Request Processing
-
-```ts
-// Process a request
-router.respond(
-  req: Request,
-  context?: Partial<Context>
-): Promise<Response>
-```
-
-#### Helper Functions
-
-```ts
-import {
-  Status, // Status enum
-  status, // HTTP status response
-  redirect, // Redirect response with location header set
-  forward, // forward to other path within the router.
-  text, // Plain text response
-  html, // HTML response
-  json, // JSON response
-  blob, // Blob response
-  octetStream, // Octet-stream response
-  formData, // FormData response
-  usp, // URLSearchParams response
-  send, // Smart response (auto-detects content type)
-  setCookie, // Set cookie header
-  clearCookie, // Clear cookie
-  type CTXCookie,
-  parseCookie, // Cookie parser
-  type CTXBody,
-  parseBody, // Body parser
-  type CTXUpload,
-  parseUploadStreaming, // multi-part-form-data and file upload stream parser
-} from "@bepalo/router";
-
-const router = new Router();
-
-// Usage examples
-router.handle("GET /text", () => text("Hello World"));
-router.handle("GET /html", () => html("<h1>Title</h1>"));
-router.handle("GET /json", () => json({ data: "value" }));
-router.handle("GET /status", () => status(Status._204_NoContent, null)); // No Content
-router.handle("GET /intro.mp4", () => blob(Bun.file("./intro.mp4")));
-router.handle("GET /download", () => octetStream(Bun.file("./intro.mp4")));
-
-router.handle("GET /new-location", () => html("GET new-location"));
-// router.handle("POST /new-location", () => html("POST new-location"));
-router.handle<CTXBody>("POST /new-location", [
-  parseBody({ once: true, clone: true }),
-  (req, { body }) => console.log(body),
-  forward("/new-location2"),
-]);
-router.handle<CTXBody>("POST /new-location2", [
-  parseBody({ once: true, clone: false }),
-  (req, { body }) => console.log(body),
-  () => html("POST new-location2"),
-]);
-router.handle("GET /redirected", () => redirect("/new-location"));
-router.handle("GET /forwarded", forward("/new-location"));
-// this would set the headers:
-// "x-forwarded-path": "/forwarded"
-// "x-original-path": "/forwarded"
-router.handle<CTXBody>("PUT /forwarded-with-new-method", [
-  parseBody({ once: true, clone: true }),
-  (req, { body }) => console.log(body),
-  forward("/new-location", { method: "POST" }),
-]);
-// this would set the headers:
-// "x-forwarded-method": "PUT"
-// "x-forwarded-path": "/new-location"
-// "x-original-path": "/forwarded-with-new-method"
-router.handle("GET /forwarded-conditional", function (this: Router, req, ctx) {
-  if (req.headers.get("authorization"))
-    return forward("/new-location").bind(this)(req, ctx);
-  // or return forward("/new-location").apply(this, [req, ctx]);
-  // NOTE: be careful when binding instance `router` instead of `this`
-  //   as it might be called from a different router due to append.
-  return status(Status._401_Unauthorized);
-});
-
-router.handle<CTXCookie>("GET /cookie", [
-  parseCookie(),
-  (req, { cookie }) => json({ cookie }),
-]);
-
-router.handle<CTXBody>("POST /cookie", [
-  parseBody(),
-  (req, { body }) => {
-    return status(Status._200_OK, "OK", {
-      // or `, undefined, {` and the status text will be set
-      headers: [
-        ...Object.entries(body).map(([name, value]) =>
-          setCookie(name, String(value), {
-            path: "/",
-            expires: Time.after(5).minutes.fromNow()._ms,
-          }),
-        ),
-      ],
-    });
-  },
-]);
-
-router.handle("DELETE /cookie/:name", [
-  (req, ctx) =>
-    status(Status._200_OK, undefined, {
-      headers: [clearCookie(ctx.params.name, { path: "/" })],
-    }),
-]);
-
-// be sure to create ./upload folder for this example
-router.handle<CTXUpload>("POST /upload", [
-  (req, ctx) => {
-    let file: Bun.BunFile;
-    let fileWriter: Bun.FileSink;
-    return parseUploadStreaming({
-      allowedTypes: ["image/jpeg"],
-      maxFileSize: 5 * 1024 * 1024,
-      maxTotalSize: 5 * 1024 * 1024 + 1024,
-      maxFields: 1,
-      maxFiles: 1,
-      // uploadIdGenerator: () =>
-      //   `upload_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
-      async onUploadStart(uploadId, totalSize) {
-        console.log("onUploadStart", { uploadId, totalSize });
-      },
-      async onError(uploadId, error) {
-        console.error("onError", uploadId, error);
-      },
-      async onFileError(uploadId, fieldName, fileName, error) {
-        console.error("onFileError", uploadId, error);
-      },
-      async onField(uploadId, fieldName, value) {
-        console.log("onField", { uploadId, fieldName, value });
-      },
-      async onFileStart(uploadId, fieldName, fileName, contentType) {
-        console.log("onFileStart", {
-          uploadId,
-          fieldName,
-          fileName,
-          contentType,
-        });
-        const ext = fileName.substring(fileName.lastIndexOf("."));
-        const customFilename = uploadId + ext;
-        file = Bun.file("./uploads/" + customFilename);
-        fileWriter = file.writer();
-        return {
-          customFilename,
-          // metadata
-        };
-      },
-      async onFileChunk(uploadId, fieldName, fileName, chunk, offset, isLast) {
-        const chunkSize = chunk.byteLength;
-        console.log("onFileChunk", { uploadId, chunkSize, offset, isLast });
-        fileWriter.write(chunk);
-      },
-      async onFileComplete(
-        uploadId,
-        fieldName,
-        fileName,
-        fileSize,
-        customFilename,
-        metadata,
-      ) {
-        console.log("onFileComplete", {
-          uploadId,
-          fieldName,
-          fileName,
-          fileSize,
-          customFilename,
-          metadata,
-        });
-        if (fileWriter) {
-          fileWriter.end();
-        }
-      },
-      async onUploadComplete(uploadId, success) {
-        console.log("onUploadComplete", { uploadId, success });
-      },
-    })(req, ctx);
-  },
-  (req, { uploadId, fields, files }) => {
-    console.log({ uploadId, fields, files });
-    return status(Status._200_OK);
-  },
-]);
-```
-
-#### Provided Middleware
-
-```ts
-import {
-  type CTXCookie,
-  type CTXBody,
-  type CTXAuth,
-  type CTXUpload,
-  parseCookie, // Cookie parser
-  parseBody, // Body parser
-  parseUploadStreaming, // multi-part-form-data and file upload stream parser
-  cors, // CORS middleware
-  limitRate, // Rate limiting
-  authenticate, // Generic authentication middleware
-  authorize, // Generic authorization middleware
-  authBasic, // Basic authentication
-  authAPIKey, // API key authentication
-  authJWT, // JWT authentication
-} from "@bepalo/router";
-```
-
-### 🔧 Advanced Usage
-
-#### Pipeline (Multiple Handlers)
-
-```js
-router.handle("POST /api/users", [
-  // Middleware 1: Parse body
-  async (req, ctx) => {
-    const body = await req.json();
-    ctx.body = body;
-  },
-
-  // Middleware 2: Validate
-  (req, ctx) => {
-    if (!ctx.body.email) {
-      return text("Email is required", { status: 400 });
-    }
-  },
-
-  // Handler: Process request
-  async (req, ctx) => {
-    const user = await db.users.create(ctx.body);
-    return json(user, { status: 201 });
-  },
-]);
-```
-
-### Path Patterns
-
-```js
-// Named parameters
-router.handle("GET /users/:id", handler); // Matches: /users/123
-
-// Single segment wildcard
-router.handle("GET /files/*", handler); // Matches: /files/a, /files/b
-
-// Single segment wildcard including current path (must be at end)
-router.handle("GET /files/.*", handler); // Matches: /files, /files/a, /files/b
-
-// Multi-segment wildcard (must be at end)
-router.handle("GET /docs/**", handler); // Matches: /docs/a, /docs/a/b/c
-
-// Multi-segment wildcard including current path (must be at end)
-router.handle("GET /docs/.**", handler); // Matches: /docs, /docs/a, /docs/a/b/c
-
-// Mixed patterns
-router.handle("GET /api/:version/*/details", handler); // /api/v1/users/details
-
-// All method-paths
-router.handle("*", handler); // GET/POST/PUT/etc /.**
-```
-
-### Route Priority
-
-Routes are matched in this order of priority:
-
-    1. Exact path matches
-
-    2. Path parameters (:id) and Single segment wildcards (*, .*)
-
-    3. Multi-segment wildcards (**, .**)
-
-### Router Composition Example
-
-```js
-// User API routes
-const userAPIRouter = new Router();
-userAPIRouter.handle("GET /", () => json({ user: {} }));
-userAPIRouter.handle <
-  CTXBody >
-  ("POST /",
-  [
-    parseBody(),
-    async (req, { body }) => {
-      return json({ success: true, data: body }, { status: 201 });
-    },
-  ]);
-
-// Session API routes
-const sessionAPIRouter = new Router();
-sessionAPIRouter.handle("GET /", () => json({ session: {} }));
-sessionAPIRouter.handle("POST /", [
-  parseBody(),
-  async (req, { body }) => {
-    return json({ success: true, data: body }, { status: 201 });
-  },
-]);
-
-// API v1 router
-const v1APIRouter = new Router();
-v1APIRouter.handle("GET /status", () => json({ version: "1.0", status: "ok" }));
-
-// Composition is useful for defining routes in multiple files
-//  and appending them in other routes.
-v1APIRouter.append("/user", userAPIRouter);
-v1APIRouter.append("/session", sessionAPIRouter);
-
-const mainRouter = new Router();
-mainRouter.append("/api/v1", v1APIRouter);
-```
-
 ## 🎯 Performance
 
 The router uses a radix tree (trie) data structure for route matching, providing: