@nextrush/router 3.0.7 → 4.0.0-beta.0

package/src/__tests__/router-audit.test.ts

@@ -0,0 +1,326 @@
+/**
+ * @nextrush/router - Comprehensive correctness & edge-case audit
+ *
+ * Proves routing correctness by exhaustive assertion, not assumption. Organized
+ * by audit phase. Tests that assert *actual* behavior of an unsupported feature
+ * (brace syntax, regex constraints, param decoding) are marked CHARACTERIZATION
+ * and documented in the audit report as limitations, not bugs.
+ */
+
+import type { HttpMethod, RouteHandler } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+const h = (): RouteHandler => vi.fn();
+
+describe('Router audit', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  // ── Phase 1: route path syntax ──────────────────────────────────────────
+  describe('phase 1 — path syntax support', () => {
+    it('supports the colon param syntax /users/:id', () => {
+      router.get('/users/:id', h());
+      expect(router.match('GET', '/users/42')?.params).toEqual({ id: '42' });
+    });
+
+    it('CHARACTERIZATION: brace syntax /users/{id} is a LITERAL static segment (not a param)', () => {
+      router.get('/users/{id}', h());
+      // Only the literal path matches; it does NOT capture a param.
+      expect(router.match('GET', '/users/{id}')).not.toBeNull();
+      expect(router.match('GET', '/users/{id}')?.params).toEqual({});
+      expect(router.match('GET', '/users/42')).toBeNull();
+    });
+
+    it('CHARACTERIZATION: regex constraint /:id(\\d+) is NOT a regex — the param is literally named "id(\\d+)"', () => {
+      router.get('/n/:id(\\d+)', h());
+      const m = router.match('GET', '/n/abc'); // matches any segment (no regex enforcement)
+      expect(m).not.toBeNull();
+      expect(m?.params).toHaveProperty('id(\\d+)');
+      expect(m?.params['id']).toBeUndefined();
+    });
+  });
+
+  // ── Phase 2: routing correctness ─────────────────────────────────────────
+  describe('phase 2 — correctness', () => {
+    it('matches the root route', () => {
+      router.get('/', h());
+      expect(router.match('GET', '/')).not.toBeNull();
+    });
+
+    it('matches static routes exactly', () => {
+      router.get('/a/b/c', h());
+      expect(router.match('GET', '/a/b/c')).not.toBeNull();
+      expect(router.match('GET', '/a/b')).toBeNull();
+      expect(router.match('GET', '/a/b/c/d')).toBeNull();
+    });
+
+    it('extracts multiple params', () => {
+      router.get('/:a/:b/:c', h());
+      expect(router.match('GET', '/1/2/3')?.params).toEqual({ a: '1', b: '2', c: '3' });
+    });
+
+    it('matches a param between static segments', () => {
+      router.get('/files/:name/download', h());
+      expect(router.match('GET', '/files/report.pdf/download')?.params).toEqual({
+        name: 'report.pdf',
+      });
+      expect(router.match('GET', '/files/report.pdf')).toBeNull();
+    });
+
+    it('captures the rest of the path with a wildcard', () => {
+      router.get('/static/*', h());
+      expect(router.match('GET', '/static/css/app.css')?.params['*']).toBe('css/app.css');
+      expect(router.match('GET', '/static/x')?.params['*']).toBe('x');
+    });
+
+    it('normalizes duplicate slashes', () => {
+      router.get('/a/b', h());
+      expect(router.match('GET', '/a//b')).not.toBeNull();
+      expect(router.match('GET', '//a///b')).not.toBeNull();
+    });
+
+    it('ignores a trailing slash in non-strict mode (default)', () => {
+      router.get('/users', h());
+      expect(router.match('GET', '/users/')).not.toBeNull();
+      router.get('/p/:id', h());
+      expect(router.match('GET', '/p/7/')?.params).toEqual({ id: '7' });
+    });
+
+    it('handles long param values', () => {
+      router.get('/x/:v', h());
+      const long = 'a'.repeat(5000);
+      expect(router.match('GET', `/x/${long}`)?.params.v).toBe(long);
+    });
+
+    it('handles a param value with dots and dashes', () => {
+      router.get('/v/:name', h());
+      expect(router.match('GET', '/v/my-file.tar.gz')?.params.name).toBe('my-file.tar.gz');
+    });
+
+    it('returns null for a completely unknown path', () => {
+      router.get('/known', h());
+      expect(router.match('GET', '/unknown/deep/path')).toBeNull();
+    });
+  });
+
+  // ── Phase 3: priority ────────────────────────────────────────────────────
+  describe('phase 3 — priority (static > param > wildcard)', () => {
+    it('prefers a static route over a param route', () => {
+      const staticH = h();
+      const paramH = h();
+      router.get('/users/:id', paramH);
+      router.get('/users/me', staticH);
+      expect(router.match('GET', '/users/me')?.handler).toBe(staticH);
+      expect(router.match('GET', '/users/42')?.handler).toBe(paramH);
+    });
+
+    it('prefers a param route over a wildcard', () => {
+      const paramH = h();
+      const wildH = h();
+      router.get('/a/*', wildH);
+      router.get('/a/:id', paramH);
+      expect(router.match('GET', '/a/x')?.handler).toBe(paramH);
+    });
+
+    it('backtracks: static subtree miss falls through to the param subtree', () => {
+      const meProfile = h();
+      const idPosts = h();
+      router.get('/users/me/profile', meProfile);
+      router.get('/users/:id/posts', idPosts);
+      // /users/me/posts must fall back to the :id branch (me is not a dead end)
+      expect(router.match('GET', '/users/me/posts')?.handler).toBe(idPosts);
+      expect(router.match('GET', '/users/me/profile')?.handler).toBe(meProfile);
+    });
+
+    it('is deterministic regardless of registration order', () => {
+      const r1 = createRouter();
+      r1.get('/users/me', h());
+      r1.get('/users/:id', h());
+      const r2 = createRouter();
+      r2.get('/users/:id', h());
+      r2.get('/users/me', h());
+      expect(r1.match('GET', '/users/me')).not.toBeNull();
+      expect(r2.match('GET', '/users/me')?.params).toEqual({});
+    });
+  });
+
+  // ── Phase 4: nested / deep routes ────────────────────────────────────────
+  describe('phase 4 — nested & deep routes', () => {
+    it('matches deeply nested param chains', () => {
+      router.get('/api/v1/orgs/:orgId/teams/:teamId/members/:memberId', h());
+      expect(
+        router.match('GET', '/api/v1/orgs/1/teams/2/members/3')?.params
+      ).toEqual({ orgId: '1', teamId: '2', memberId: '3' });
+    });
+
+    it('supports many sibling nested routes without ambiguity', () => {
+      router.get('/api/users', h());
+      router.get('/api/users/:id', h());
+      router.get('/api/users/:id/posts', h());
+      router.get('/api/users/:id/posts/:postId', h());
+      expect(router.match('GET', '/api/users')?.params).toEqual({});
+      expect(router.match('GET', '/api/users/9')?.params).toEqual({ id: '9' });
+      expect(router.match('GET', '/api/users/9/posts')?.params).toEqual({ id: '9' });
+      expect(router.match('GET', '/api/users/9/posts/5')?.params).toEqual({
+        id: '9',
+        postId: '5',
+      });
+    });
+  });
+
+  // ── Phase 6: query strings must not affect matching ──────────────────────
+  describe('phase 6 — query strings are ignored during matching', () => {
+    it('matches a static route with a query string', () => {
+      router.get('/users', h());
+      expect(router.match('GET', '/users?page=5')).not.toBeNull();
+    });
+
+    it('matches a param route and excludes the query from the param value', () => {
+      router.get('/users/:id', h());
+      expect(router.match('GET', '/users/42?expand=true')?.params).toEqual({ id: '42' });
+    });
+
+    it('matches the root route with a query string', () => {
+      router.get('/', h());
+      expect(router.match('GET', '/?a=1&b=2')).not.toBeNull();
+    });
+  });
+
+  // ── Phase 7: decoding & unicode ──────────────────────────────────────────
+  describe('phase 7 — decoding & unicode', () => {
+    it('matches unicode path segments (raw)', () => {
+      router.get('/u/:name', h());
+      expect(router.match('GET', '/u/josé')?.params.name).toBe('josé');
+      expect(router.match('GET', '/u/日本語')?.params.name).toBe('日本語');
+    });
+
+    it('percent-encoded params are DECODED by default (raw available via decode:false)', () => {
+      router.get('/u/:name', h());
+      expect(router.match('GET', '/u/hello%20world')?.params.name).toBe('hello world');
+
+      const raw = createRouter({ decode: false });
+      raw.get('/u/:name', h());
+      expect(raw.match('GET', '/u/hello%20world')?.params.name).toBe('hello%20world');
+    });
+  });
+
+  // ── Phase 8: HTTP methods ────────────────────────────────────────────────
+  describe('phase 8 — HTTP methods', () => {
+    it('registers and matches all standard methods', () => {
+      const methods: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+      for (const m of methods) {
+        const r = createRouter();
+        r.all('/x', h());
+        expect(r.match(m, '/x')).not.toBeNull();
+      }
+    });
+
+    it('distinguishes the same path by method', () => {
+      const getH = h();
+      const postH = h();
+      router.get('/r', getH);
+      router.post('/r', postH);
+      expect(router.match('GET', '/r')?.handler).toBe(getH);
+      expect(router.match('POST', '/r')?.handler).toBe(postH);
+      expect(router.match('DELETE', '/r')).toBeNull();
+    });
+
+    it('reports allowed methods for a path (via the public allowedMethods() middleware)', async () => {
+      router.get('/r', h());
+      router.post('/r', h());
+      const ctx = {
+        method: 'OPTIONS',
+        path: '/r',
+        status: 404,
+        set: vi.fn(),
+      } as unknown as import('@nextrush/types').Context;
+      await router.allowedMethods()(ctx, async () => {});
+      expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+      expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('POST'));
+      expect(ctx.set).not.toHaveBeenCalledWith('Allow', expect.stringContaining('DELETE'));
+    });
+  });
+
+  // ── Phase 9: large scale ─────────────────────────────────────────────────
+  describe('phase 9 — large scale', () => {
+    it('stays correct with 1000 mixed static/param routes', () => {
+      for (let i = 0; i < 1000; i++) {
+        router.get(`/r${i}/static`, h());
+        router.get(`/r${i}/:id`, h());
+      }
+      expect(router.match('GET', '/r0/static')?.params).toEqual({});
+      expect(router.match('GET', '/r500/:id'.replace(':id', 'abc'))?.params).toEqual({ id: 'abc' });
+      expect(router.match('GET', '/r999/xyz')?.params).toEqual({ id: 'xyz' });
+      expect(router.match('GET', '/r1000/nope')).toBeNull();
+    });
+  });
+
+  // ── Phase 10: failure cases ──────────────────────────────────────────────
+  describe('phase 10 — failure & graceful handling', () => {
+    it('throws a clear error on duplicate route registration', () => {
+      router.get('/dup', h());
+      expect(() => router.get('/dup', h())).toThrow(/already registered|conflict/i);
+    });
+
+    it('throws a clear error on conflicting param names at the same position', () => {
+      router.get('/u/:id', h());
+      expect(() => router.get('/u/:name/x', h())).toThrow(/param name conflict/i);
+    });
+
+    it('treats an empty path as the root route', () => {
+      router.get('', h());
+      expect(router.match('GET', '/')).not.toBeNull();
+    });
+
+    it('throws a clear TypeError for a non-string path', () => {
+      expect(() => router.get(null as unknown as string, h())).toThrow(TypeError);
+      expect(() => router.get(undefined as unknown as string, h())).toThrow(TypeError);
+      expect(() => router.get(123 as unknown as string, h())).toThrow(TypeError);
+    });
+
+    it('requires at least one handler', () => {
+      expect(() => router.get('/no-handler')).toThrow(/at least one handler/i);
+    });
+  });
+
+  // ── Phase 12: historical routing bugs from other frameworks ──────────────
+  describe('phase 12 — hardening against known routing bugs', () => {
+    it('does not confuse a param value with a similarly-named static route', () => {
+      router.get('/search', h());
+      router.get('/:term', h());
+      expect(router.match('GET', '/search')?.params).toEqual({}); // static wins
+      expect(router.match('GET', '/anything')?.params).toEqual({ term: 'anything' });
+    });
+
+    it('does not leak params across non-matching branches (backtracking cleanup)', () => {
+      router.get('/a/:x/b', h());
+      router.get('/a/fixed', h());
+      // /a/fixed matches the static branch and must NOT carry an :x param
+      expect(router.match('GET', '/a/fixed')?.params).toEqual({});
+    });
+
+    it('handles adjacent params without a static separator', () => {
+      router.get('/:a/:b', h());
+      expect(router.match('GET', '/x/y')?.params).toEqual({ a: 'x', b: 'y' });
+      expect(router.match('GET', '/x')).toBeNull();
+    });
+
+    it('wildcard does not swallow a more specific static sibling', () => {
+      const wild = h();
+      const exact = h();
+      router.get('/assets/*', wild);
+      router.get('/assets/favicon.ico', exact);
+      expect(router.match('GET', '/assets/favicon.ico')?.handler).toBe(exact);
+      expect(router.match('GET', '/assets/img/logo.png')?.handler).toBe(wild);
+    });
+
+    it('does not match a prefix of a longer static route', () => {
+      router.get('/api/users/list', h());
+      expect(router.match('GET', '/api/users')).toBeNull();
+      expect(router.match('GET', '/api')).toBeNull();
+    });
+  });
+});

package/src/__tests__/router-edge-cases.test.ts

@@ -90,10 +90,10 @@ describe('Router Edge Cases', () => {
       expect(match?.params.filename).toBe('document.pdf');
     });
 
-    it('should extract URL-encoded special characters', () => {
+    it('should decode URL-encoded special characters by default', () => {
       router.get('/search/:query', vi.fn());
       const match = router.match('GET', '/search/hello%20world');
-      expect(match?.params.query).toBe('hello%20world');
+      expect(match?.params.query).toBe('hello world');
     });
 
     it('should extract parameters with plus signs', () => {

package/src/__tests__/router.test.ts

@@ -34,6 +34,22 @@ function createMockContext(overrides: Partial<Context> = {}): Context {
   } as Context;
 }
 
+/**
+ * Mock context whose setNext/next behave like a real adapter context:
+ * `setNext` stores the next fn and `ctx.next()` invokes it. Used to exercise the
+ * modern `ctx.next()` middleware syntax through the router executor.
+ */
+function createNextAwareContext(overrides: Partial<Context> = {}): Context {
+  let stored: () => Promise<void> = () => Promise.resolve();
+  return createMockContext({
+    setNext: (fn: () => Promise<void>) => {
+      stored = fn;
+    },
+    next: () => stored(),
+    ...overrides,
+  });
+}
+
 describe('Router', () => {
   let router: Router;
 
@@ -105,6 +121,22 @@ describe('Router', () => {
       }
     });
 
+    it('should register .all() as a single route-table entry, not one per method (T016)', () => {
+      const handler: RouteHandler = vi.fn();
+      router.all('/any', handler);
+
+      const routes = router.getRoutes();
+      const anyRoutes = routes.filter((r) => r.path === '/any');
+
+      // The introspection registry (getRoutes()) must show exactly ONE entry
+      // for an .all() route, not one row per HTTP method — this is the
+      // observable, spec-mandated behavior change (T016). Matching behavior
+      // (every method still dispatches correctly) is covered separately by
+      // 'should register all methods with .all()' above and is unaffected.
+      expect(anyRoutes).toHaveLength(1);
+      expect(anyRoutes[0]?.isAnyMethod).toBe(true);
+    });
+
     it('should allow method chaining', () => {
       const result = router.get('/a', vi.fn()).post('/b', vi.fn()).put('/c', vi.fn());
 
@@ -160,11 +192,11 @@ describe('Router', () => {
       expect(match?.params).toEqual({ userId: '1', postId: '2' });
     });
 
-    it('should handle URL-encoded parameters', () => {
+    it('should decode URL-encoded parameters by default', () => {
       router.get('/search/:query', vi.fn());
 
       const match = router.match('GET', '/search/hello%20world');
-      expect(match?.params).toEqual({ query: 'hello%20world' });
+      expect(match?.params).toEqual({ query: 'hello world' });
     });
   });
 
@@ -317,6 +349,104 @@ describe('Router', () => {
     });
   });
 
+  describe('ctx.next() modern middleware syntax', () => {
+    it('runs a single per-route middleware that uses ctx.next()', async () => {
+      const order: number[] = [];
+      const mw = async (ctx: Context) => {
+        order.push(1);
+        await ctx.next();
+      };
+      const handler: RouteHandler = async () => {
+        order.push(2);
+      };
+      router.get('/one', mw, handler);
+
+      const ctx = createNextAwareContext({ method: 'GET', path: '/one' });
+      await router.routes()(ctx, async () => {});
+
+      expect(order).toEqual([1, 2]);
+    });
+
+    it('runs two per-route middleware that use ctx.next()', async () => {
+      const order: number[] = [];
+      const mw0 = async (ctx: Context) => {
+        order.push(1);
+        await ctx.next();
+      };
+      const mw1 = async (ctx: Context) => {
+        order.push(2);
+        await ctx.next();
+      };
+      const handler: RouteHandler = async () => {
+        order.push(3);
+      };
+      router.get('/two', mw0, mw1, handler);
+
+      const ctx = createNextAwareContext({ method: 'GET', path: '/two' });
+      await router.routes()(ctx, async () => {});
+
+      expect(order).toEqual([1, 2, 3]);
+    });
+
+    it('runs a chain of 5 per-route middleware that use ctx.next() (general path)', async () => {
+      const order: number[] = [];
+      const layers = [1, 2, 3, 4, 5].map((n) => async (ctx: Context) => {
+        order.push(n);
+        await ctx.next();
+      });
+      const handler: RouteHandler = async () => {
+        order.push(6);
+      };
+      router.get('/five', ...layers, handler);
+
+      const ctx = createNextAwareContext({ method: 'GET', path: '/five' });
+      await router.routes()(ctx, async () => {});
+
+      expect(order).toEqual([1, 2, 3, 4, 5, 6]);
+    });
+
+    it('lets ctx.next() middleware observe side effects of every layer (all headers set)', async () => {
+      const headers: Record<string, string> = {};
+      const setHeader = (name: string, value: string) => (ctx: Context) => {
+        headers[name] = value;
+        return ctx.next();
+      };
+      router.get(
+        '/headers',
+        setHeader('X-A', '1'),
+        setHeader('X-B', '2'),
+        setHeader('X-C', '3'),
+        async (ctx: Context) => ctx.json({ ok: true })
+      );
+
+      const ctx = createNextAwareContext({ method: 'GET', path: '/headers' });
+      await router.routes()(ctx, async () => {});
+
+      expect(headers).toEqual({ 'X-A': '1', 'X-B': '2', 'X-C': '3' });
+    });
+
+    it('interoperates with the traditional (ctx, next) signature in the same chain', async () => {
+      const order: number[] = [];
+      const modern = async (ctx: Context) => {
+        order.push(1);
+        await ctx.next();
+      };
+      const traditional = async (_ctx: Context, next: () => Promise<void>) => {
+        order.push(2);
+        await next();
+      };
+      const handler: RouteHandler = async () => {
+        order.push(3);
+      };
+      router.get('/mixed', modern, traditional, handler);
+
+      const ctx = createNextAwareContext({ method: 'GET', path: '/mixed' });
+      await router.routes()(ctx, async () => {});
+
+      expect(order).toEqual([1, 2, 3]);
+    });
+  });
+
   describe('route groups', () => {
     it('should create a group with prefix', () => {
       router.group('/api', (r) => {
@@ -447,6 +577,22 @@ describe('Router', () => {
       expect(router.match('POST', '/api/any')).not.toBeNull();
       expect(router.match('PUT', '/api/any')).not.toBeNull();
     });
+
+    it('should register a group\'s .all() as a single route-table entry, not one per method (T016)', () => {
+      // GroupRouter.all() forwards through _addGroupRoute rather than
+      // Router.all() directly — a second, independent call site for the same
+      // 7-registrations bug, found during T016's own implementation (not a
+      // pre-planned test) and fixed alongside Router.all() itself.
+      router.group('/api', (r) => {
+        r.all('/any', vi.fn());
+      });
+
+      const routes = router.getRoutes();
+      const anyRoutes = routes.filter((r) => r.path === '/api/any');
+
+      expect(anyRoutes).toHaveLength(1);
+      expect(anyRoutes[0]?.isAnyMethod).toBe(true);
+    });
   });
 
   describe('redirect', () => {

package/src/__tests__/static-map-reset.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @nextrush/router - HP-9 static-map reset contract
+ *
+ * The differential golden (`match-differential.test.ts`) already pins the
+ * behavior-preserving HP-9 scenarios that live on a freshly-built router:
+ * static-over-trie precedence, method-miss, trailing-slash, `all()`, and the
+ * prefix/mount/group registration flows. The one contract it CANNOT cover —
+ * because it always builds fresh routers — is that `reset()` fully clears the
+ * (now method-nested) static map with no ghost entries. This file pins that.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {
+  /* no-op */
+};
+
+describe('HP-9 — reset() clears the method-nested static map fully', () => {
+  it('clears static entries across every method and leaves no ghost matches', () => {
+    const router = createRouter();
+    router.get('/a', noop);
+    router.post('/a', noop);
+    router.get('/b/c', noop);
+    router.put('/b/c', noop);
+
+    expect(router.match('GET', '/a')).not.toBeNull();
+    expect(router.match('POST', '/a')).not.toBeNull();
+    expect(router.match('PUT', '/b/c')).not.toBeNull();
+
+    router.reset();
+
+    // Every method's inner map must be gone — no ghost entries.
+    expect(router.match('GET', '/a')).toBeNull();
+    expect(router.match('POST', '/a')).toBeNull();
+    expect(router.match('GET', '/b/c')).toBeNull();
+    expect(router.match('PUT', '/b/c')).toBeNull();
+  });
+
+  it('allows re-registering the same static routes after reset without a conflict throw', () => {
+    const router = createRouter();
+    router.get('/x', noop);
+    router.reset();
+
+    // A lingering inner-map entry would make this throw "Route conflict".
+    expect(() => router.get('/x', noop)).not.toThrow();
+    expect(router.match('GET', '/x')).not.toBeNull();
+  });
+});

package/src/composition.ts

@@ -0,0 +1,75 @@
+/**
+ * @nextrush/router - Router Composition
+ *
+ * Sub-router mounting/copying logic extracted from the `Router` class (T014,
+ * design.md D3 — extracted after the matching-engine split left `router.ts`
+ * still over the 300-line ceiling).
+ *
+ * `copyRoutes`'s tree walk is structurally pure (segments/prefix/middleware are
+ * all explicit parameters), but its side effect — registering the copied route —
+ * needs `Router.addRoute`, a private method. Rather than reach into `Router`
+ * internals or promote `addRoute` to `public` (a public-API change out of scope
+ * for this refactor), the effect is injected explicitly as an `addRoute`
+ * callback parameter. `use`/`mount`/`mountRouter` stay on `Router` itself:
+ * they return `this` for fluent chaining and read `Router` instance state
+ * (`root`, `routerMiddleware`) that isn't naturally expressible as function
+ * parameters without more ceremony than the win justifies.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod, Middleware, RouteHandler } from '@nextrush/types';
+import type { TrieNode } from './segment-trie';
+
+/** Callback signature matching `Router['addRoute']` — injected, not imported. */
+export type AddRouteFn = (
+  method: HttpMethod,
+  path: string,
+  handlers: RouteHandler[],
+  middleware: Middleware[]
+) => void;
+
+/**
+ * Recursively copy routes from one router's trie into another via the
+ * supplied `addRoute` callback.
+ */
+export function copyRoutes(
+  node: TrieNode,
+  prefix: string,
+  segments: string[],
+  subRouterMiddleware: Middleware[],
+  addRoute: AddRouteFn
+): void {
+  // Copy handlers at this node
+  for (const [method, entry] of node.handlers) {
+    const path = prefix + '/' + segments.join('/');
+    // Prepend sub-router middleware so it runs before the route's own middleware
+    const combined =
+      subRouterMiddleware.length > 0
+        ? [...subRouterMiddleware, ...entry.middleware]
+        : entry.middleware;
+    addRoute(method, path || '/', [entry.handler], combined);
+  }
+
+  // Copy static children
+  for (const [, child] of node.children) {
+    copyRoutes(child, prefix, [...segments, child.segment], subRouterMiddleware, addRoute);
+  }
+
+  // Copy param child
+  if (node.paramChild) {
+    copyRoutes(
+      node.paramChild,
+      prefix,
+      [...segments, node.paramChild.segment],
+      subRouterMiddleware,
+      addRoute
+    );
+  }
+
+  // Copy wildcard child
+  if (node.wildcardChild) {
+    copyRoutes(node.wildcardChild, prefix, [...segments, '*'], subRouterMiddleware, addRoute);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,25 @@
+/**
+ * @nextrush/router - Shared internal constants
+ *
+ * A leaf module that imports nothing, so any router module can depend on it
+ * without risking an import cycle. This is the resolution of the former
+ * `EMPTY_PARAMS` duplication: the constant was previously copied across modules
+ * to dodge a `router.ts` <-> `match-route.ts` cycle, which a dependency-free
+ * leaf module makes impossible by construction.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+/**
+ * Frozen, null-prototype empty params object for matches with no path
+ * parameters (static-map hits and successful walks that bound no `:param`/`*`).
+ *
+ * Shared as a single instance to avoid allocating a fresh object per request on
+ * the hot path. Null-prototype so callers can never read an inherited
+ * `Object.prototype` key as if it were a route param; frozen so the shared
+ * instance can never be mutated by a handler.
+ */
+export const EMPTY_PARAMS: Record<string, string> = Object.freeze(
+  Object.create(null) as Record<string, string>
+);