@nextrush/router 3.0.7 → 4.0.0-beta.1

package/README.md

@@ -1,618 +1,376 @@
 # @nextrush/router
 
-> High-performance radix tree router for NextRush. O(k) route matching where k = path length, not route count.
+> The routing engine behind NextRush — a segment trie that matches a request to its handler in time proportional to the URL's depth, not the number of routes you've registered.
 
-## The Problem
+[![npm version](https://img.shields.io/npm/v/@nextrush/router.svg)](https://www.npmjs.com/package/@nextrush/router)
+[![downloads](https://img.shields.io/npm/dm/@nextrush/router.svg)](https://www.npmjs.com/package/@nextrush/router)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@nextrush/router.svg)](https://bundlephobia.com/package/@nextrush/router)
+[![types](https://img.shields.io/npm/types/@nextrush/router.svg)](https://www.npmjs.com/package/@nextrush/router)
+[![ESM only](https://img.shields.io/badge/module-ESM--only-blue.svg)](https://nodejs.org/api/esm.html)
+[![license](https://img.shields.io/npm/l/@nextrush/router.svg)](https://github.com/0xTanzim/nextRush/blob/main/LICENSE)
 
-Traditional array-based routers iterate through all routes to find a match. With 1,000 routes, that's 1,000 comparisons per request. Route order matters. Performance degrades linearly.
+|  |  |
+| --- | --- |
+| **Purpose** | Route matching for NextRush — resolve `METHOD path` to its handler |
+| **Package type** | Core |
+| **Status** | Stable ✅ |
+| **Included in `nextrush`?** | ✅ Yes — `createRouter` is re-exported from the meta package |
+| **Support tier** | Public — core (stable, semver-guarded) — see [ADR-0005](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md) |
+| **Maintenance** | Active |
+| **Runtime** | Universal — Node · Bun · Deno · Edge |
+| **Requires** | Node `>=22` · ESM-only · TypeScript `>=5.x` |
+| **Introduced** | `v3.0.0` |
 
-## How NextRush Approaches This
+## Highlights
 
-The router uses a **radix tree** (compressed prefix tree):
+- ✅ **No third-party dependencies** — depends only on `@nextrush/types` (types, erased at build)
+- ✅ **ESM-only**, tree-shakable, side-effect-free
+- ✅ **Fully typed** — strict TypeScript, zero `any`
+- 📦 Small, focused surface — the router and nothing else
 
-- Routes share common prefixes in the tree structure
-- Matching is O(k) where k is path length (typically 10-50 characters)
-- Route count doesn't affect matching speed
-- Memory efficient: shared prefixes stored once
+<details>
+<summary><strong>Table of contents</strong></summary>
 
-## Mental Model
+[The problem](#the-problem) · [When to use](#when-to-use) · [Installation](#installation) · [Quick start](#quick-start) · [Capabilities](#capabilities) · [Mental model](#mental-model) · [Common tasks](#common-tasks) · [API overview](#api-overview) · [Options](#options) · [Performance](#performance) · [Compatibility](#compatibility) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [Package relationships](#package-relationships) · [Architecture](#architecture) · [Resources](#resources)
 
-```
-Routes:
-  /users
-  /users/:id
-  /users/:id/posts
-  /products
-  /products/:id
-
-Tree:
-  /
-  ├── users
-  │   └── /:id
-  │       └── /posts
-  └── products
-      └── /:id
-```
+</details>
 
-When matching `/users/123/posts`:
+---
 
-1. Match `/` → found
-2. Match `users` → found
-3. Match `/:id` → captures `123`
-4. Match `/posts` → found
-5. Return handler + params
+## The problem
 
-## Installation
+The simplest router is a list: keep every route in an array and, on each request, walk the list until one matches. It works — until it doesn't. The cost of every request grows with the number of routes, and the *order* you register them in starts to change behavior.
 
-```bash
-pnpm add @nextrush/router
+```ts
+// TODAY, without a trie — a list router, O(n) in the route count:
+for (const route of routes) {
+  if (route.method === method && route.pattern.test(path)) {
+    return route; // 1,000 routes → up to 1,000 regex tests, every request
+  }
+}
 ```
 
-## Quick Start
-
-```typescript
-import { createApp } from '@nextrush/core';
-import { createRouter } from '@nextrush/router';
+A list router that's fast with 20 routes is measurably slower with 2,000, and the slowdown lands on your hottest code path — the one every request pays. `@nextrush/router` removes the route count from that equation.
 
-const app = createApp();
-const router = createRouter();
+## When to use
 
-router.get('/', (ctx) => {
-  ctx.json({ message: 'Home' });
-});
+`@nextrush/router` is the router built into NextRush; `createApp().route(...)` uses it under the hood. You reach for this package directly when you want to compose routing explicitly.
 
-router.get('/users/:id', (ctx) => {
-  ctx.json({ userId: ctx.params.id });
-});
+**Use `@nextrush/router` if:**
 
-app.route('/', router);
-app.listen(3000);
-```
+- ✓ You're building a NextRush app and want feature routers you can mount, group, and nest
+- ✓ You want matching cost to stay flat as your route table grows into the hundreds or thousands
+- ✓ You need named params (`/users/:id`), wildcards (`/files/*`), per-route and per-group middleware, or redirects
 
-## Features
+**Reach for something else if:**
 
-- **Radix Tree Algorithm**: O(k) lookup where k = path length
-- **Route Parameters**: Named parameters with `:param` syntax
-- **Wildcard Routes**: Catch-all with `*` parameter
-- **Route Groups**: Prefix-based grouping with middleware
-- **Method-Based Routing**: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
-- **Redirects**: Built-in redirect support with parameter interpolation
-- **Zero Dependencies**: Only depends on `@nextrush/types`
+- ✗ You just want the app-level shortcuts (`app.get(...)`) — those already use this router; import from [`nextrush`](../nextrush) instead
+- ✗ You need a standalone router for a non-NextRush framework — the `Router` speaks NextRush's `Context`/`Middleware` contracts from [`@nextrush/types`](../types)
 
-## Route Patterns
+---
 
-### Static Routes
+## Installation
 
-```typescript
-router.get('/api/users', handler);
-router.get('/api/posts', handler);
-router.get('/health', handler);
+```bash
+pnpm add @nextrush/router
+# npm i @nextrush/router · yarn add @nextrush/router · bun add @nextrush/router
 ```
 
-### Named Parameters
+> [!NOTE]
+> Already using `nextrush`? `createRouter` is re-exported from the meta package, so
+> `import { createRouter } from 'nextrush'` works without installing this directly. Install
+> `@nextrush/router` when you want to depend on it explicitly.
 
-```typescript
-// Single parameter
-router.get('/users/:id', (ctx) => {
-  ctx.json({ id: ctx.params.id });
-});
+## Quick start
 
-// Multiple parameters
-router.get('/users/:userId/posts/:postId', (ctx) => {
-  const { userId, postId } = ctx.params;
-  ctx.json({ userId, postId });
-});
-```
+```ts
+import { createApp, listen } from 'nextrush';
+import { createRouter } from '@nextrush/router';
 
-### Wildcard Routes
+const app = createApp();
+const users = createRouter();
 
-```typescript
-// Catch-all: captures everything after /files/
-router.get('/files/*', (ctx) => {
-  const filePath = ctx.params['*'];
-  ctx.json({ path: filePath });
-});
+users.get('/', (ctx) => ctx.json([{ id: 1, name: 'Ada' }]));
+users.get('/:id', (ctx) => ctx.json({ id: ctx.params.id }));
 
-// /files/docs/readme.md → ctx.params['*'] = 'docs/readme.md'
+app.route('/users', users); // mount the feature router
+listen(app, 8080);
 ```
 
-Wildcards must be at the end of the route. Everything after the `*` segment is captured.
-
-## HTTP Methods
+A `Router` is a self-contained bundle of routes you register in one place and mount wherever you need it — here every route lands under `/users`. That's the whole model: build small routers, compose them.
 
-```typescript
-router.get('/resource', handler);
-router.post('/resource', handler);
-router.put('/resource/:id', handler);
-router.patch('/resource/:id', handler);
-router.delete('/resource/:id', handler);
-router.head('/resource', handler);
-router.options('/resource', handler);
+## Capabilities
 
-// Register for all standard methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
-// TRACE and CONNECT are excluded for security reasons
-router.all('/any', handler);
+**Routing**
+- **Segment trie matching** — O(k) in path depth, not route count (see [Mental model](#mental-model))
+- **Named parameters** — `/users/:id`, multiple per path, original case preserved
+- **Wildcards** — `/files/*` captures the remainder into `ctx.params['*']`
+- **Route groups** — shared prefix + middleware, arbitrarily nestable
+- **Composition** — `mount()` / `use()` sub-routers; `app.route()` for Hono-style mounting
+- **Redirects** — `301`/`302`/`303`/`307`/`308` with param interpolation
+- **Method handling** — per-method shortcuts plus `allowedMethods()` for correct `405`/`Allow`
 
-// Register specific method dynamically
-router.route('GET', '/dynamic', handler);
-```
+**Performance**
+- **Static-route fast path** — routes with no params resolve through an O(1) hash map
+- **Compiled executors** — the middleware+handler chain is built once at registration, not per request
 
-## Route Groups
+**Developer experience**
+- **Introspection** — `getRoutes()` feeds `@nextrush/openapi` without touching the hot path
+- **Fully typed** — strict TypeScript, zero `any`; contracts shared via `@nextrush/types`
 
-Group routes with a common prefix:
+## Mental model
 
-```typescript
-const api = createRouter({ prefix: '/api/v1' });
+A segment trie is a tree keyed by **whole path segments** — `users`, `:id` — not by individual characters (that would be a radix tree; this is deliberately not one). Registering a route walks the tree segment by segment, creating nodes as needed. Matching walks the same tree, and the depth of the walk is the number of segments in the URL — so a thousand sibling routes cost the same as one.
 
-api.get('/users', listUsers); // GET /api/v1/users
-api.get('/users/:id', getUser); // GET /api/v1/users/:id
-api.post('/users', createUser); // POST /api/v1/users
+```text
+Routes registered:                 Trie built:
+  /users                             (root)
+  /users/:id                          ├── "users"        ← static child
+  /users/:id/posts                    │     └── :id       ← param child
+  /products                           │           └── "posts"
+  /products/:id                       └── "products"
+                                            └── :id
 
-app.route('/', api);
+Matching GET /users/123/posts:
+  root → "users" → :id (captures id="123") → "posts"  →  handler + { id: "123" }
 ```
 
-### Nested Groups
+**Rule:** static routes (no `:param`, no `*`) skip the walk entirely — they live in a method-nested hash map for an O(1) lookup.
 
-```typescript
-const router = createRouter();
+> [!TIP]
+> The full match lifecycle, the two-path design, and the executor-compilation trick are in
+> [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
-router.group('/api', (api) => {
-  api.group('/v1', (v1) => {
-    v1.get('/users', handler); // GET /api/v1/users
-    v1.get('/posts', handler); // GET /api/v1/posts
-  });
+---
 
-  api.group('/v2', (v2) => {
-    v2.get('/users', handler); // GET /api/v2/users
-  });
-});
-
-app.route('/', router);
-```
+## Common tasks
 
-### Group Middleware
+### Route parameters and wildcards
 
-Apply middleware to all routes in a group:
-
-```typescript
-const auth = async (ctx, next) => {
-  if (!ctx.get('Authorization')) {
-    ctx.status = 401;
-    ctx.json({ error: 'Unauthorized' });
-    return;
-  }
-  await next();
-};
+```ts
+router.get('/users/:userId/posts/:postId', (ctx) => {
+  const { userId, postId } = ctx.params; // both captured in one pass
+  ctx.json({ userId, postId });
+});
 
-router.group('/admin', [auth], (admin) => {
-  admin.get('/dashboard', getDashboard);
-  admin.get('/settings', getSettings);
+// Wildcard captures the remainder; must be the last segment.
+router.get('/files/*', (ctx) => {
+  ctx.json({ path: ctx.params['*'] }); // /files/docs/readme.md → "docs/readme.md"
 });
 ```
 
-## Route Middleware
+### Route and group middleware
 
-Apply middleware to specific routes:
-
-```typescript
-const auth = async (ctx, next) => {
-  if (!ctx.get('Authorization')) {
+```ts
+const auth: Middleware = async (ctx, next) => {
+  if (!ctx.get('authorization')) {
     ctx.status = 401;
-    ctx.json({ error: 'Unauthorized' });
-    return;
+    return ctx.json({ error: 'Unauthorized' });
   }
   await next();
 };
 
-// Single route with middleware
-router.get('/protected', auth, handler);
-
-// Multiple middleware
-router.get('/admin', auth, adminOnly, handler);
-```
-
-Middleware executes in order: `auth` → `adminOnly` → `handler`
+router.get('/protected', auth, (ctx) => ctx.json({ ok: true })); // per-route
 
-## Redirects
-
-Built-in support for HTTP redirects:
-
-```typescript
-// Permanent redirect (301)
-router.redirect('/old-page', '/new-page');
-
-// Temporary redirect (302)
-router.redirect('/temp', '/destination', 302);
-
-// Redirect to external URL
-router.redirect('/docs', 'https://docs.example.com');
-
-// With parameter interpolation
-router.redirect('/users/:id', '/profiles/:id');
-// /users/123 → redirects to /profiles/123
+router.group('/admin', [auth], (admin) => {                        // per-group
+  admin.get('/dashboard', (ctx) => ctx.json({ page: 'dashboard' }));
+});
 ```
 
-Supported status codes: `301`, `302`, `303`, `307`, `308`
-
-## Sub-Router Mounting
-
-Compose routers together using `mount()` or `use()`:
-
-### Using mount() (Recommended)
+Middleware runs in registration order, then the handler: `auth → handler`.
 
-```typescript
-const userRouter = createRouter();
-userRouter.get('/', listUsers);
-userRouter.get('/:id', getUser);
-userRouter.post('/', createUser);
+### Composing routers
 
-const postRouter = createRouter();
-postRouter.get('/', listPosts);
-postRouter.get('/:id', getPost);
+```ts
+const usersRouter = createRouter();
+usersRouter.get('/', listUsers);
+usersRouter.get('/:id', getUser);
 
 const api = createRouter();
-api.mount('/users', userRouter); // Clean explicit mounting
-api.mount('/posts', postRouter);
+api.mount('/users', usersRouter); // explicit; equivalent to use('/users', usersRouter)
 
-app.route('/api', api);
-// Results in: /api/users, /api/users/:id, /api/posts, /api/posts/:id
+app.route('/api', api); // → /api/users, /api/users/:id
 ```
 
-### Using use() (Classic Pattern)
+### Redirects and method handling
 
-The traditional `use()` method also works:
+```ts
+router.redirect('/old', '/new');            // 301 by default
+router.redirect('/users/:id', '/people/:id'); // param interpolation
+router.redirect('/legacy', '/v2', 308);     // 307/308 preserve the HTTP method
 
-```typescript
-const api = createRouter();
-api.use('/users', userRouter);
-api.use('/posts', postRouter);
-
-app.route('/api', api);
-// Or classic: app.use(api.routes());
-```
-
-### Direct App Mounting (Hono-Style)
-
-For the cleanest DX, mount routers directly on the app:
-
-```typescript
-import { createApp } from '@nextrush/core';
-
-const app = createApp();
-app.route('/users', userRouter); // No routes() call needed!
-app.route('/posts', postRouter);
-```
-
-## Allowed Methods
-
-Automatically handle 405 Method Not Allowed:
-
-```typescript
-app.route('/', router);
-app.use(router.allowedMethods());
-
-// GET /users → 200 OK (if GET handler exists)
-// POST /users (no POST handler) → 405 Method Not Allowed
-// OPTIONS /users → Returns allowed methods in Allow header
+app.use(router.allowedMethods()); // OPTIONS → Allow header; unknown method on a known path → 405
 ```
 
-## Router Options
+## API overview
 
-```typescript
-interface RouterOptions {
-  // Route prefix prepended to all routes
-  prefix?: string;
+The sealed public surface (ADR-0005). Advanced trie internals are exported for tooling but are not part of the everyday API.
 
-  // Case sensitive matching (default: false)
-  caseSensitive?: boolean;
+| Export | Signature | Since | Stability | Description |
+| ------ | --------- | ----- | --------- | ----------- |
+| `createRouter` | `(options?: RouterOptions) => Router` | `3.0.0` | Stable ✅ | Create a router instance. |
+| `Router` | `class` | `3.0.0` | Stable ✅ | The router class (see methods below). |
+| `endpoint` | `(metadata) => RouteEntry` | `3.1.0` | Stable ✅ | Attach inline route metadata (consumed by `getRoutes()` / OpenAPI). |
+| `createNode` | `(segment, type?) => TrieNode` | `3.0.0` | Advanced 🔧 | Build a trie node (tooling). |
+| `parseSegments` | `(path, caseSensitive?) => ParsedSegment[]` | `3.0.0` | Advanced 🔧 | Split a path into typed segments (tooling). |
+| `NodeType` | `const enum` | `3.0.0` | Advanced 🔧 | `STATIC` / `PARAM` / `WILDCARD`. |
+| `type Router` (as `RouterInterface`) · `RouterOptions` · `Route` · `RouteHandler` · `RouteMatch` · `Middleware` · `HttpMethod` | — | `3.0.0` | Stable ✅ | Re-exported contracts from [`@nextrush/types`](../types). |
+| `type TrieNode` · `HandlerEntry` · `ParsedSegment` · `RouteGroup` | — | `3.0.0` | Advanced 🔧 | Trie/group types. |
 
-  // Strict trailing slash handling (default: false)
-  strict?: boolean;
-}
+### `Router` methods
 
-const router = createRouter({
-  prefix: '/api/v1',
-  caseSensitive: false,
-  strict: false,
-});
-```
+| Method | Signature | Description |
+| ------ | --------- | ----------- |
+| `get` / `post` / `put` / `delete` / `patch` / `head` / `options` | `(path, ...entries: RouteEntry[]) => this` | Register a handler (+ optional per-route middleware) for one method. |
+| `all` | `(path, ...entries) => this` | Register for every standard method (GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS); one consolidated introspection row. |
+| `route` | `(method, path, ...entries) => this` | Register for a method chosen at runtime. |
+| `group` | `(prefix, callback)` or `(prefix, middleware[], callback) => this` | Register routes under a shared prefix (and optional middleware); nestable. |
+| `mount` | `(path, subRouter) => this` | Mount a sub-router at a prefix (explicit form of `use(path, subRouter)`). |
+| `use` | `(middleware)` · `(path, subRouter)` · `(subRouter) => this` | Add router-level middleware or mount a sub-router. |
+| `redirect` | `(from, to, status?: 301\|302\|303\|307\|308) => this` | Register a redirect (default `301`; `307`/`308` preserve the method). |
+| `match` | `(method, path) => RouteMatch \| null` | Resolve a request to its handler + params (used internally by `routes()`). |
+| `routes` | `() => Middleware` | The dispatch middleware to mount on the app (`app.use(router.routes())`). |
+| `allowedMethods` | `() => Middleware` | Middleware that answers `OPTIONS` and returns `405` for a known path + unknown method. |
+| `getRoutes` | `() => readonly RouteDefinition[]` | Introspection registry (doc/OpenAPI generation) — never read on the request path. |
+| `reset` | `() => void` | Clear all routes, middleware, and caches; makes the router reusable (tests, hot reload). |
 
-### Case Sensitivity
+## Options
 
-```typescript
-// Default: case-insensitive
-const router = createRouter();
-router.get('/Users', handler);
-router.match('GET', '/users'); // ✓ matches
-
-// Case-sensitive mode
-const router = createRouter({ caseSensitive: true });
-router.get('/Users', handler);
-router.match('GET', '/Users'); // ✓ matches
-router.match('GET', '/users'); // ✗ no match
+```ts
+const router = createRouter({ prefix: '/api/v1', caseSensitive: false, strict: false });
 ```
 
-### Trailing Slash
-
-```typescript
-// Default: trailing slashes are normalized
-router.get('/users', handler);
-router.match('GET', '/users'); // ✓ matches
-router.match('GET', '/users/'); // ✓ matches (normalized)
-```
+| Option | Type | Required | Default | Security-sensitive | Description |
+| ------ | ---- | -------- | ------- | ------------------ | ----------- |
+| `prefix` | `string` | No | `''` | — | Prepended to every route registered on this router. |
+| `caseSensitive` | `boolean` | No | `false` | — | When `false`, static segments are lowercased at registration and match case-insensitively. Parameter **names and values always preserve their original case.** |
+| `strict` | `boolean` | No | `false` | — | When `false`, a trailing slash is normalized away (`/users` and `/users/` match the same route). |
 
 ## Performance
 
-The radix tree router provides:
-
-- **O(k) Lookup**: Where k is the path length, not route count
-- **Memory Efficient**: Shared prefixes are stored once
-- **Fast Parameter Extraction**: Single-pass parsing
-
-### Benchmarks
-
-| Routes | Lookup Time |
-| ------ | ----------- |
-| 100    | ~0.02ms     |
-| 1,000  | ~0.02ms     |
-| 10,000 | ~0.02ms     |
-
-Route count doesn't affect lookup time significantly.
-
-## API Reference
-
-### `createRouter(options?)`
-
-Create a new router instance.
-
-```typescript
-function createRouter(options?: RouterOptions): Router;
-```
-
-**Parameters:**
-
-| Parameter | Type            | Required | Default | Description          |
-| --------- | --------------- | -------- | ------- | -------------------- |
-| `options` | `RouterOptions` | No       | `{}`    | Router configuration |
-
-**Options:**
-
-| Option          | Type      | Default | Description                           |
-| --------------- | --------- | ------- | ------------------------------------- |
-| `prefix`        | `string`  | `''`    | Path prefix for all routes            |
-| `caseSensitive` | `boolean` | `false` | Enable case-sensitive matching        |
-| `strict`        | `boolean` | `false` | Enable strict trailing slash handling |
-
-**Returns:** `Router` instance
-
-### Router Methods
-
-#### HTTP Method Shortcuts
+The router is designed so that **match cost tracks URL depth, not route count** — the property that matters as an app grows. Two mechanisms deliver it:
 
-```typescript
-router.get(path: string, ...handlers: RouteHandler[]): this
-router.post(path: string, ...handlers: RouteHandler[]): this
-router.put(path: string, ...handlers: RouteHandler[]): this
-router.delete(path: string, ...handlers: RouteHandler[]): this
-router.patch(path: string, ...handlers: RouteHandler[]): this
-router.head(path: string, ...handlers: RouteHandler[]): this
-router.options(path: string, ...handlers: RouteHandler[]): this
-router.all(path: string, ...handlers: RouteHandler[]): this
-router.route(method: HttpMethod, path: string, ...handlers: RouteHandler[]): this
-```
+- **Static routes** (no `:param` / `*`) resolve through a method-nested hash map — an O(1) lookup, with no per-request `` `${method} ${path}` `` key string allocated.
+- **Dynamic routes** walk the segment trie: O(k) where `k` is the number of path segments (typically a handful), regardless of how many routes are registered.
 
-#### `router.redirect(from, to, status?)`
+Per-route **executors are compiled once at registration**, not rebuilt per request, so dispatch allocates no middleware-chain closures on the hot path. A router with only static routes skips the trie walk entirely.
 
-Register a redirect route.
+> [!NOTE]
+> For reproducible throughput numbers on your own hardware, run the suite in
+> [`apps/benchmark`](https://github.com/0xTanzim/nextRush/tree/main/apps/benchmark). Published
+> figures are being re-measured on a hardened harness — see the
+> [root README's Performance note](https://github.com/0xTanzim/nextRush#performance) — so this
+> package documents the complexity characteristics, not point numbers.
 
-```typescript
-router.redirect(from: string, to: string, status?: 301 | 302 | 303 | 307 | 308): this
-```
+## Compatibility
 
-Default status is `301` (Moved Permanently). Status codes `307` and `308` register handlers for all standard HTTP methods (to preserve the original method). Other codes register GET and HEAD only.
+**Requirements**
 
-#### `router.group(prefix, middleware?, callback)`
+| Requirement | Version |
+| ----------- | ------- |
+| NextRush | `3.x` |
+| Node.js | `>=22` |
+| TypeScript | `>=5.x` |
 
-Create a route group with shared prefix and middleware.
+**Runtimes**
 
-```typescript
-router.group(prefix: string, callback: (router: Router) => void): this
-router.group(prefix: string, middleware: Middleware[], callback: (router: Router) => void): this
-```
+| Runtime | Supported | Notes |
+| ------- | --------- | ----- |
+| Node.js `>=22` | ✅ | ESM-only |
+| Bun / Deno / Edge | ✅ / ✅ / ✅ | Pure Web-standard logic — no runtime API used; parity held by `@nextrush/adapter-*` |
 
-#### `router.use(pathOrMiddleware, routerOrUndefined?)`
+**Integration**
+- **Peer dependencies:** `@nextrush/core` (optional) — only needed when you mount via `app.route()` / `app.use()`; the `Router` itself works standalone.
+- **Works with:** `@nextrush/core` (mounting), `@nextrush/openapi` (reads `getRoutes()`), any `@nextrush/*` middleware.
+- **Incompatible with:** none.
 
-Mount middleware or sub-router.
-
-```typescript
-router.use(middleware: Middleware): this
-router.use(path: string, subRouter: Router): this
-router.use(subRouter: Router): this
-```
-
-#### `router.mount(path, subRouter)`
-
-Mount a sub-router at a path prefix. Equivalent to `use(path, router)` with clearer intent.
-
-```typescript
-router.mount(path: string, subRouter: Router): this
-```
+> [!IMPORTANT]
+> NextRush is **ESM-only, permanently** — no CommonJS build. On Node `>=22`, CommonJS consumers
+> can `require()` this ESM package natively. See the
+> [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
 
-**Example:**
+---
 
-```typescript
-const api = createRouter();
-api.mount('/users', userRouter);
-api.mount('/posts', postRouter);
-```
+## Troubleshooting
 
-#### `router.match(method, path)`
+<details>
+<summary><strong><code>Error: Route conflict: GET /users is already registered</code></strong></summary>
 
-Match a route and return handler + params.
+**Cause:** the same method + path was registered twice — conflicts throw at registration time, not silently last-wins. **Fix:** register each method/path once; different methods on the same path are fine.
 
-```typescript
-router.match(method: HttpMethod, path: string): RouteMatch | null
+```ts
+router.get('/users', listUsers);
+router.post('/users', createUser); // ✅ different method — OK
+// router.get('/users', other);    // ❌ throws
 ```
 
-**Returns:**
+</details>
 
-```typescript
-interface RouteMatch {
-  handler: RouteHandler;
-  params: Record<string, string>;
-  middleware: Middleware[];
-}
-```
+<details>
+<summary><strong>My route isn't matched (404)</strong></summary>
 
-#### `router.reset()`
+**Cause:** the router was created but never mounted. **Fix:** mount it with `app.route(prefix, router)` (or `app.use(router.routes())`).
 
-Clear all registered routes, middleware, and internal state. Useful for testing or plugin teardown.
-
-```typescript
+```ts
 const router = createRouter();
 router.get('/users', handler);
-
-router.reset();
-// All routes, static route cache, middleware, param/wildcard children are cleared
-```
-
-> Calling `reset()` makes the router reusable — you can register fresh routes after resetting.
-
-#### `router.routes()`
-
-Get middleware function to mount on application.
-
-```typescript
-const middleware = router.routes();
-app.use(middleware);
-```
-
-#### `router.allowedMethods()`
-
-Get middleware that handles 405 responses and OPTIONS requests.
-
-```typescript
-app.use(router.allowedMethods());
-```
-
-## TypeScript Types
-
-```typescript
-import { createRouter, Router } from '@nextrush/router';
-
-import type {
-  HttpMethod,
-  Middleware,
-  Route,
-  RouteHandler,
-  RouteMatch,
-  Router as RouterInterface,
-  RouterOptions,
-} from '@nextrush/router';
-```
-
-## Common Patterns
-
-### RESTful Resource Routes
-
-```typescript
-const router = createRouter();
-
-// Users resource
-router.get('/users', listUsers);
-router.post('/users', createUser);
-router.get('/users/:id', getUser);
-router.put('/users/:id', updateUser);
-router.delete('/users/:id', deleteUser);
-
-app.route('/', router);
+app.route('/', router); // ← without this, nothing is matched
 ```
 
-### API Versioning
-
-```typescript
-const v1 = createRouter({ prefix: '/api/v1' });
-v1.get('/users', v1UsersHandler);
-
-const v2 = createRouter({ prefix: '/api/v2' });
-v2.get('/users', v2UsersHandler);
-
-app.route('/', v1);
-app.route('/', v2);
-```
-
-### Catch-All for SPA
-
-```typescript
-router.get('/api/*', apiHandler);
-
-// Serve SPA for all other routes
-router.get('/*', (ctx) => {
-  ctx.html(indexHtml);
-});
-```
+</details>
 
-## Common Mistakes
+<details>
+<summary><strong>A wildcard in the middle of a path doesn't work</strong></summary>
 
-### Forgetting to Mount Routes
+**Cause:** a wildcard captures the remainder of the path, so it's only valid as the **last** segment. **Fix:** put `*` at the end (`/files/*`), not in the middle (`/*/files`).
 
-```typescript
-// ❌ Routes not mounted
-const router = createRouter();
-router.get('/users', handler);
-// Missing: app.route('/api', router)
+</details>
 
-// ✅ Recommended: Use app.route()
-const router = createRouter();
-router.get('/users', handler);
-app.route('/api', router);
+## FAQ
 
-// ✅ Also works: Classic pattern
-app.use(router.routes());
-```
+**Can I use `@nextrush/router` without the rest of NextRush?**
+Yes. The `Router` depends only on the `Context`/`Middleware` type contracts from `@nextrush/types`. `@nextrush/core` is an *optional* peer — you need it only to mount via `app.route()`.
 
-### Parameter Name & Value Case
+**Is it really a "radix tree"?**
+No — and the distinction is deliberate. This is a **segment trie**: it branches on whole path segments (`users`, `:id`), not individual characters. A radix tree (character/prefix-compressed) is a different structure; an opt-in `@nextrush/router-radix` is explored in [RFC-015](https://github.com/0xTanzim/nextRush/blob/main/docs/RFC/runtime-adapters/015-router-radix.md), but the segment trie is the default.
 
-```typescript
-// Parameter names preserve their original case from route definition
-router.get('/users/:userId', (ctx) => {
-  // ✅ Original case is preserved
-  console.log(ctx.params.userId);
-});
+**Why ESM-only?**
+See the [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
 
-// Parameter values also preserve their original case
-// GET /users/JohnDoe → ctx.params.userId === 'JohnDoe' (not 'johndoe')
-```
+**Does it work on Bun, Deno, and Edge?**
+Yes. The matching logic uses only standard JavaScript — no `node:*` APIs — so it runs identically on every supported runtime; cross-runtime parity is enforced by `@nextrush/adapter-*` conformance tests.
 
-### Wildcard Placement
+---
 
-```typescript
-// ❌ Wildcard not at end (won't work as expected)
-router.get('/*/files', handler);
+## Package relationships
 
-// ✅ Wildcard at end
-router.get('/files/*', handler);
+```text
+                 depends on          @nextrush/types  (Context / Middleware / RouteMatch contracts)
+@nextrush/router ─────────────▶
+                 often used with     @nextrush/core   (mounts routers via app.route())
+                 usually used next   @nextrush/openapi (generates a spec from getRoutes())
 ```
 
-### Duplicate Route Registration
+- **Depends on:** [`@nextrush/types`](../types) — the shared `Context` / `Middleware` / `RouteMatch` contracts (types only, erased at build).
+- **Often used with:** [`@nextrush/core`](../core) — the `Application` that mounts routers via `app.route()`.
+- **Usually used next:** [`@nextrush/openapi`](../middleware/openapi) — turns `getRoutes()` into an OpenAPI document · [`@nextrush/validation`](../middleware/validation) · [`@nextrush/class`](../class) (decorator-based routing).
+- **Alternative:** an opt-in `@nextrush/router-radix` is explored in [RFC-015](https://github.com/0xTanzim/nextRush/blob/main/docs/RFC/runtime-adapters/015-router-radix.md) for very large static route tables; the segment trie is the default.
 
-```typescript
-// ❌ Throws an error — same method + path registered twice
-router.get('/users', handler1);
-router.get('/users', handler2);
-// Error: "Route conflict: GET /users is already registered"
+## Architecture
 
-// ✅ Different methods on the same path are fine
-router.get('/users', handler1);
-router.post('/users', handler2);
-```
+Maintaining or contributing to the router? The internal design — the two-path match, the segment
+trie and static map, executor compilation, the architectural invariants, and the decisions and
+trade-offs behind them (with diagrams) — is in **[`ARCHITECTURE.md`](./ARCHITECTURE.md)**. Design
+history: [RFC-015 (router-radix)](https://github.com/0xTanzim/nextRush/blob/main/docs/RFC/runtime-adapters/015-router-radix.md), [ADR-0005 (package tiers)](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md).
 
-## Error Behavior
+## Resources
 
-- **Duplicate routes**: Registering the same method + path throws immediately at registration time.
-- **Unmatched routes**: `routes()` middleware sets `ctx.status = 404` and calls `next()`, allowing downstream middleware like `allowedMethods()` to respond.
-- **Parameter name conflicts**: In development, a warning is logged when two routes define different parameter names at the same tree position. The first registered name takes precedence.
+- 📖 **Learn** — [Documentation](https://0xtanzim.github.io/nextRush/docs) · [Routing concept](https://0xtanzim.github.io/nextRush/docs/concepts/routing) · [Architecture](./ARCHITECTURE.md) · [RFCs](https://github.com/0xTanzim/nextRush/tree/main/docs/RFC)
+- 📝 **Changelog** — [CHANGELOG.md](./CHANGELOG.md)
+- 🧪 **Benchmarks** — [`apps/benchmark`](https://github.com/0xTanzim/nextRush/tree/main/apps/benchmark)
+- 🐛 **Report an issue** — [GitHub Issues](https://github.com/0xTanzim/nextRush/issues)
+- 🤝 **Contribute** — [CONTRIBUTING.md](https://github.com/0xTanzim/nextRush/blob/main/CONTRIBUTING.md)
 
-## License
+---
 
-MIT
+MIT © [Tanzim Hossain](https://github.com/0xTanzim)