Radix Router

RadixRouter is a high-performance HTTP router using a radix tree for fast, memory-efficient route matching. It supports static, dynamic, optional, and wildcard routes, with middleware stacking and router composition for modular applications.

Key Features

Static Routes: /users
Dynamic Parameters: /users/:id
Optional Parameters: /users/:id?
Wildcards: /files/*path
Middleware Stacking: Global & route-specific
Router Composition: Merge sub-routers for maintainability

Usage

Initialize Router

import { RadixRouter } from "tezx/registry";

const router = new RadixRouter();

Add Routes

router.addRoute("GET", "/hello", [(ctx) => ctx.text("Hello World")]);

router.addRoute("GET", "/user/:id?", [
  (ctx) => ctx.text(`User ID: ${ctx.params.id ?? "Guest"}`),
]);

router.addRoute("GET", "/files/*path", [serveFileHandler]);

Supports static, dynamic (:id), optional (:id?), and wildcard (*path) segments.

Search Routes

const match = router.search("GET", "/user/123");
await match.handlers[0](ctx); // Executes matched handler

Return Structure:

{
  method: "GET",
  params: { id: "123" },
  middlewares: [...],
  handlers: [...],
}

⚡ Matching Priority

Static segments (/users)
Dynamic segments (/users/:id)
Optional segments (/users/:id?)
Wildcard segments (/files/*path)

Backtracking ensures optional segments fallback gracefully.

Performance (Updated Benchmark)

RadixRouter.search()
Total ops:       1,200,000
Total time:      170.72 ms
Avg per op:      142.26 ns (0.142 µs)
Throughput:      7,029,244 ops/sec

Extremely fast and suitable for high-traffic, low-latency applications.

🛠 Types

export type RouteMatchResult<T extends Record<string, any> = any> = {
  /**
   * The HTTP method of the matched route (e.g., "GET", "POST").
   */
  method: HTTPMethod;

  /**
   * The middleware functions that will be executed for this route.
   */
  match: Middleware<T>[];

  /**
   * An object containing route parameters extracted from the URL.
   * The values can be strings, null (for optional params), or undefined.
   */
  params: Record<string, string | null | undefined>;
};

interface RouteRegistry {
  name: string;
  addRoute<T>(method: HTTPMethod, path: string, handler: HandlerType<T>): void;
  search(method: HTTPMethod, path: string): RouteMatchResult<T>;
}

Radix Router

On this page