@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/segment-trie.ts

@@ -0,0 +1,227 @@
+/**
+ * @nextrush/router - Segment Trie Node
+ *
+ * Internal segment trie implementation for high-performance route matching.
+ * Segments are split by `/` and matched one trie level per segment for O(k)
+ * lookups where k is path length.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Context, HttpMethod, Middleware, RouteHandler } from '@nextrush/types';
+
+/**
+ * Node type enumeration
+ */
+export const enum NodeType {
+  /** Static path segment: /users */
+  STATIC = 0,
+  /** Named parameter: /:id */
+  PARAM = 1,
+  /** Wildcard: /* */
+  WILDCARD = 2,
+}
+
+/**
+ * Segment trie node
+ */
+export interface TrieNode {
+  /** Path segment for this node */
+  segment: string;
+  /** Node type */
+  type: NodeType;
+  /** Static child nodes keyed by whole path segment (e.g. `users`), not the first character */
+  children: Map<string, TrieNode>;
+  /** Parameter name if this is a param node */
+  paramName?: string;
+  /** Handlers keyed by HTTP method */
+  handlers: Map<HttpMethod, HandlerEntry>;
+  /** Wildcard child if any */
+  wildcardChild?: TrieNode;
+  /** Parameter child if any */
+  paramChild?: TrieNode;
+}
+
+/**
+ * Handler entry with middleware and pre-compiled executor
+ */
+export interface HandlerEntry {
+  handler: RouteHandler;
+  middleware: Middleware[];
+  /** Pre-compiled executor for fast dispatch (no closure per request) */
+  executor?: (ctx: Context) => Promise<void>;
+  /**
+   * `true` only for a `HEAD` entry derived from a `GET` registration
+   * (RFC 9110 §9.3.2). A derived entry is replaced by an explicit `HEAD`
+   * registration instead of reporting a route conflict, is absent from
+   * `getRoutes()`, and is skipped when copying routes into a parent router —
+   * which re-derives it from the `GET` it copies.
+   */
+  autoHead: boolean;
+}
+
+/**
+ * Method-nested static-route fast-path map (HP-9): the OUTER map selects an
+ * inner map by HTTP method, the INNER map probes by the trailing-slash-
+ * normalized path. This replaces the former `Map<"METHOD path", HandlerEntry>`
+ * so a static lookup no longer builds a `` `${method} ${path}` `` key string per
+ * request — it selects the inner map by `method` and probes by the raw path.
+ */
+export type StaticRouteMap = Map<HttpMethod, Map<string, HandlerEntry>>;
+
+/**
+ * No-op next function - reusable, zero allocation
+ * Caches the resolved Promise to avoid per-call allocation
+ * @internal
+ */
+const RESOLVED_PROMISE = Promise.resolve();
+export const NOOP_NEXT = (): Promise<void> => RESOLVED_PROMISE;
+
+/**
+ * Compile an executor for a route handler with middleware
+ * This creates the executor ONCE at registration time, not per-request
+ * @internal
+ */
+export function compileExecutor(
+  handler: RouteHandler,
+  middleware: Middleware[]
+): (ctx: Context) => Promise<void> {
+  const len = middleware.length;
+
+  // FAST PATH: No middleware — direct handler call, no extra async frame (NF-1).
+  if (len === 0) {
+    return (ctx: Context): Promise<void> => {
+      // `setNext(NOOP_NEXT)` is LOAD-BEARING, not redundant (NF-4a): it
+      // terminates the middleware chain at the handler so a handler that calls
+      // `ctx.next()` is a safe no-op and cannot leak into app-level middleware
+      // mounted AFTER the router (the general `compose` dispatch wires ctx._next
+      // to advance into that middleware before running the router).
+      if (ctx.setNext) ctx.setNext(NOOP_NEXT);
+      try {
+        // `Promise.resolve(...)` — NOT `x instanceof Promise ? x : RESOLVED` — so
+        // a non-Promise THENABLE return is adopted (its async work awaited), not
+        // dropped: byte-identical to the former `await handler(...)`, minus the
+        // async form's internal microtask hop. A native promise is returned as-is
+        // (`Promise.resolve(p) === p`); a void return yields a resolved promise.
+        return Promise.resolve(handler(ctx, NOOP_NEXT));
+      } catch (err) {
+        // Self-contained "never throw synchronously" contract, identical to the
+        // len >= 1 branch: a sync throw becomes a rejection; a non-Error is wrapped.
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+  }
+
+  // Middleware present: guarded recursive dispatch. This mirrors core `compose()`
+  // so per-route middleware behave identically to application middleware:
+  //  - `ctx.next()` (modern) and the `(ctx, next)` argument advance the SAME chain
+  //    (ctx.setNext is wired before each layer),
+  //  - a synchronous throw is turned into a rejected promise (proper propagation),
+  //  - calling next() more than once in a layer rejects with a clear error.
+  return (ctx: Context): Promise<void> => {
+    let index = -1;
+
+    const dispatch = (i: number): Promise<void> => {
+      if (i <= index) {
+        return Promise.reject(new Error('next() called multiple times'));
+      }
+      index = i;
+
+      if (i < len) {
+        const mw = middleware[i];
+        if (mw === undefined) return Promise.reject(new Error('middleware length mismatch'));
+        const next = (): Promise<void> => dispatch(i + 1);
+        if (ctx.setNext) ctx.setNext(next);
+        try {
+          return Promise.resolve(mw(ctx, next));
+        } catch (err) {
+          return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+
+      // Final handler. A handler calling next() is a safe no-op.
+      if (ctx.setNext) ctx.setNext(NOOP_NEXT);
+      try {
+        return Promise.resolve(handler(ctx, NOOP_NEXT));
+      } catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+
+    return dispatch(0);
+  };
+}
+
+/**
+ * Create a new segment trie node
+ */
+export function createNode(segment: string, type: NodeType = NodeType.STATIC): TrieNode {
+  return {
+    segment,
+    type,
+    children: new Map(),
+    handlers: new Map(),
+  };
+}
+
+/**
+ * Reset a trie node to its empty state — clears children/handlers and drops the
+ * param/wildcard branches. Used by `Router.reset()` for test isolation and
+ * hot-reload re-registration.
+ */
+export function clearNode(node: TrieNode): void {
+  node.children.clear();
+  node.handlers.clear();
+  node.paramChild = undefined;
+  node.wildcardChild = undefined;
+}
+
+/**
+ * Parse path segments
+ * Splits path into segments and identifies param/wildcard types
+ *
+ * @param path - Route path to parse
+ * @param caseSensitive - If false, lowercase static segments for case-insensitive matching
+ */
+export function parseSegments(path: string, caseSensitive = true): ParsedSegment[] {
+  const normalized = path.startsWith('/') ? path.slice(1) : path;
+  if (normalized === '') return [];
+
+  const parts = normalized.split('/');
+  const segments: ParsedSegment[] = [];
+
+  for (const part of parts) {
+    if (part.startsWith(':')) {
+      // Preserve the original parameter name case
+      const paramName = part.slice(1);
+      segments.push({
+        segment: part, // Preserve original case — param nodes match any segment
+        type: NodeType.PARAM,
+        paramName, // Keep original case
+      });
+    } else if (part === '*') {
+      segments.push({
+        segment: '*',
+        type: NodeType.WILDCARD,
+      });
+      break; // Wildcard must be last
+    } else {
+      segments.push({
+        segment: caseSensitive ? part : part.toLowerCase(),
+        type: NodeType.STATIC,
+      });
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Parsed segment structure
+ */
+export interface ParsedSegment {
+  segment: string;
+  type: NodeType;
+  paramName?: string;
+}

package/src/state.ts

@@ -0,0 +1,53 @@
+/**
+ * @nextrush/router - Router State Construction
+ *
+ * Pure builders for the `Router`'s resolved options and its memoized state
+ * struct, extracted from the constructor (design.md D2) so `Router` stays a
+ * thin shell that delegates even its own initialization.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Middleware, RouteDefinition, RouterOptions } from '@nextrush/types';
+import type { StaticRouteMap, TrieNode } from './segment-trie';
+import type { RegistrationState } from './registration';
+import type { MatchState } from './match-route';
+
+/** Apply defaults to user-supplied router options. */
+export function resolveRouterOptions(options: RouterOptions): Required<RouterOptions> {
+  return {
+    prefix: options.prefix ?? '',
+    caseSensitive: options.caseSensitive ?? false,
+    strict: options.strict ?? false,
+    decode: options.decode ?? true,
+  };
+}
+
+/**
+ * Build the state struct the extracted registration/matching functions read.
+ *
+ * @remarks
+ * Every field is a stable reference for the router's lifetime, so the caller
+ * memoizes this once — `reset()` mutates the referenced structures in place, it
+ * never reassigns them. A single struct satisfies both `RegistrationState`
+ * (what `addRoute` reads) and `MatchState` (what `resolveMatch` reads).
+ */
+export function createRouterState(
+  root: TrieNode,
+  opts: Required<RouterOptions>,
+  staticRoutes: StaticRouteMap,
+  routeDefinitions: RouteDefinition[],
+  routerMiddleware: Middleware[]
+): RegistrationState & MatchState {
+  return {
+    root,
+    staticRoutes,
+    routeDefinitions,
+    caseSensitive: opts.caseSensitive,
+    strict: opts.strict,
+    decode: opts.decode,
+    routerMiddleware,
+    maxDepth: 0,
+  };
+}

package/src/walk-pool.ts

@@ -0,0 +1,208 @@
+/**
+ * @nextrush/router - Reused walk-frame pool (F-02, `reduce-router-match-allocations`)
+ *
+ * Split out of `matching.ts` once the pool implementation pushed it over the
+ * 300-line file cap — same reasoning `match-route.ts`'s own extraction used.
+ * Holds the pooled scratch structure and its indexed-cursor variant of the
+ * tree walk; `matching.ts`'s `matchNodeIndexed` delegates here when a pool is
+ * supplied and keeps its own fresh-allocation behavior otherwise.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import type { HandlerEntry, TrieNode } from './segment-trie';
+import { decodeParam, segmentAt } from './matching';
+
+/**
+ * One node in the iterative walk's explicit stack. `stage` is a small state
+ * machine (0 = extract + try static, 1 = try param, 2 = try wildcard/backtrack)
+ * so a single frame can be revisited on backtrack without recursion. `bound`
+ * records whether this frame pushed a deferred param binding, so backtracking
+ * can pop it without an object-property delete.
+ */
+export interface WalkFrame {
+  node: TrieNode;
+  pos: number;
+  stage: 0 | 1 | 2;
+  seg: string;
+  next: number;
+  bound: boolean;
+}
+
+/**
+ * Per-router-instance reused scratch space for the tree walk — the
+ * `WalkFrame[]` stack and the `bindNames`/`bindValues` binding arrays,
+ * pre-sized to the deepest currently registered route
+ * (`RegistrationState.maxDepth`) instead of allocated fresh on every
+ * `matchNodeIndexed` call.
+ *
+ * Safe under the router's synchronous-walk invariant only: a request path
+ * can never make the walk descend past `maxDepth` (a mismatched segment
+ * backtracks — the depth cursor decrements — rather than growing past the
+ * pool), and the walk never awaits mid-frame, so no two in-flight matches on
+ * the same router instance can observe each other's frames. See the
+ * `router` capability's "Reused internal walk state is never shared across
+ * concurrent in-flight matches" requirement.
+ */
+export interface WalkPool {
+  frames: WalkFrame[];
+  bindNames: string[];
+  bindValues: string[];
+}
+
+/**
+ * Build a `WalkPool` sized to hold `maxDepth` matched segments. The walk's
+ * frame at index 0 always represents the trie ROOT itself (mirroring the
+ * unpooled walk's `stack[0] = { node: root, ... }`), so a route with
+ * `maxDepth` segments needs `maxDepth + 1` frames — one for the root plus one
+ * per descended segment. Called once when a router's `maxDepth` grows
+ * (registration time), never per-request.
+ */
+export function createWalkPool(maxDepth: number): WalkPool {
+  const frames: WalkFrame[] = [];
+  for (let i = 0; i < maxDepth + 1; i++) {
+    frames.push({
+      node: undefined as unknown as TrieNode,
+      pos: 0,
+      stage: 0,
+      seg: '',
+      next: 0,
+      bound: false,
+    });
+  }
+  return { frames, bindNames: [], bindValues: [] };
+}
+
+/**
+ * Pooled variant of `matchNodeIndexed` — same stage-machine, same precedence,
+ * same backtrack semantics, byte-identical results — but indexes into
+ * `pool.frames` by depth (mutating each pre-allocated frame in place) instead
+ * of `push`/`pop`-ing fresh frame objects onto a fresh array. `depth` is a
+ * local cursor, never shared across calls; only the underlying frame OBJECTS
+ * are reused. Safe only because the walk never awaits mid-frame and a
+ * mismatched segment decrements `depth` (backtrack) rather than growing past
+ * `pool.frames.length` (bounded by the router's `maxDepth` at registration
+ * time — see {@link createWalkPool}).
+ */
+export function matchNodeIndexedPooled(
+  root: TrieNode,
+  path: string,
+  startPos: number,
+  bindNames: string[],
+  bindValues: string[],
+  method: HttpMethod,
+  decode: boolean,
+  pool: WalkPool,
+  originalPath?: string
+): HandlerEntry | null {
+  const { frames } = pool;
+  let depth = 0;
+  const first = frames[0];
+  if (first === undefined) return null; // maxDepth 0 — no param routes registered, nothing to walk
+  first.node = root;
+  first.pos = startPos;
+  first.stage = 0;
+  first.seg = '';
+  first.next = 0;
+  first.bound = false;
+
+  while (depth >= 0) {
+    const frame = frames[depth];
+    if (frame === undefined) break;
+
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        depth--;
+        continue;
+      }
+      const slashPos = path.indexOf('/', frame.pos);
+      if (slashPos === -1) {
+        frame.seg = path.slice(frame.pos);
+        frame.next = path.length;
+      } else {
+        frame.seg = path.slice(frame.pos, slashPos);
+        frame.next = slashPos + 1;
+      }
+      if (frame.seg === '') {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        depth--;
+        continue;
+      }
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(frame.seg);
+      if (staticChild) {
+        depth++;
+        const next = frames[depth];
+        if (next === undefined) {
+          // Should be unreachable — pool sized to maxDepth — but fail closed
+          // (treat as a miss) rather than write past the pooled array.
+          depth--;
+          continue;
+        }
+        next.node = staticChild;
+        next.pos = frame.next;
+        next.stage = 0;
+        next.seg = '';
+        next.next = 0;
+        next.bound = false;
+      }
+      continue;
+    }
+
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      const paramChild = frame.node.paramChild;
+      if (paramChild) {
+        const paramName = paramChild.paramName;
+        if (paramName === undefined) return null;
+        const value =
+          originalPath !== undefined
+            ? decodeParam(segmentAt(originalPath, frame.pos), decode)
+            : decodeParam(frame.seg, decode);
+        bindNames.push(paramName);
+        bindValues.push(value);
+        frame.bound = true;
+        depth++;
+        const next = frames[depth];
+        if (next === undefined) {
+          bindNames.pop();
+          bindValues.pop();
+          frame.bound = false;
+          depth--;
+          continue;
+        }
+        next.node = paramChild;
+        next.pos = frame.next;
+        next.stage = 0;
+        next.seg = '';
+        next.next = 0;
+        next.bound = false;
+      }
+      continue;
+    }
+
+    if (frame.bound) {
+      bindNames.pop();
+      bindValues.pop();
+      frame.bound = false;
+    }
+    const wildcardChild = frame.node.wildcardChild;
+    if (wildcardChild) {
+      const src = originalPath ?? path;
+      bindNames.push('*');
+      bindValues.push(decodeParam(src.slice(frame.pos), decode));
+      const handler = wildcardChild.handlers.get(method);
+      if (handler) return handler;
+      bindNames.pop();
+      bindValues.pop();
+    }
+    depth--;
+  }
+
+  return null;
+}

package/src/radix-tree.ts

@@ -1,184 +0,0 @@
-/**
- * @nextrush/router - Segment Trie Node
- *
- * Internal segment trie implementation for high-performance route matching.
- * Uses a compressed trie structure for O(k) lookups where k is path length.
- *
- * @packageDocumentation
- * @internal
- */
-
-import type { Context, HttpMethod, Middleware, RouteHandler } from '@nextrush/types';
-
-/**
- * Node type enumeration
- */
-export const enum NodeType {
-  /** Static path segment: /users */
-  STATIC = 0,
-  /** Named parameter: /:id */
-  PARAM = 1,
-  /** Wildcard: /* */
-  WILDCARD = 2,
-}
-
-/**
- * Radix tree node
- */
-export interface RadixNode {
-  /** Path segment for this node */
-  segment: string;
-  /** Node type */
-  type: NodeType;
-  /** Children nodes keyed by first character */
-  children: Map<string, RadixNode>;
-  /** Parameter name if this is a param node */
-  paramName?: string;
-  /** Handlers keyed by HTTP method */
-  handlers: Map<HttpMethod, HandlerEntry>;
-  /** Wildcard child if any */
-  wildcardChild?: RadixNode;
-  /** Parameter child if any */
-  paramChild?: RadixNode;
-}
-
-/**
- * Handler entry with middleware and pre-compiled executor
- */
-export interface HandlerEntry {
-  handler: RouteHandler;
-  middleware: Middleware[];
-  /** Pre-compiled executor for fast dispatch (no closure per request) */
-  executor?: (ctx: Context) => Promise<void>;
-}
-
-/**
- * No-op next function - reusable, zero allocation
- * Caches the resolved Promise to avoid per-call allocation
- * @internal
- */
-const RESOLVED_PROMISE = Promise.resolve();
-export const NOOP_NEXT = (): Promise<void> => RESOLVED_PROMISE;
-
-/**
- * Compile an executor for a route handler with middleware
- * This creates the executor ONCE at registration time, not per-request
- * @internal
- */
-export function compileExecutor(
-  handler: RouteHandler,
-  middleware: Middleware[]
-): (ctx: Context) => Promise<void> {
-  const len = middleware.length;
-
-  // FAST PATH: No middleware - direct handler call
-  if (len === 0) {
-    return async (ctx: Context) => {
-      await handler(ctx, NOOP_NEXT);
-    };
-  }
-
-  // FAST PATH: Single middleware
-  if (len === 1) {
-    const mw = middleware[0];
-    if (mw === undefined) throw new Error('middleware length mismatch');
-    return async (ctx: Context) => {
-      await mw(ctx, async () => {
-        await handler(ctx, NOOP_NEXT);
-      });
-    };
-  }
-
-  // FAST PATH: Two middleware (very common)
-  if (len === 2) {
-    const mw0 = middleware[0];
-    const mw1 = middleware[1];
-    if (mw0 === undefined || mw1 === undefined) throw new Error('middleware length mismatch');
-    return async (ctx: Context) => {
-      await mw0(ctx, async () => {
-        await mw1(ctx, async () => {
-          await handler(ctx, NOOP_NEXT);
-        });
-      });
-    };
-  }
-
-  // General case: Build recursive dispatch
-  // Note: This closure is created ONCE at registration, not per request
-  return async (ctx: Context): Promise<void> => {
-    let index = 0;
-
-    const dispatch = async (): Promise<void> => {
-      if (index < len) {
-        const mw = middleware[index++];
-        if (mw === undefined) throw new Error('middleware length mismatch');
-        await mw(ctx, dispatch);
-      } else {
-        await handler(ctx, NOOP_NEXT);
-      }
-    };
-
-    await dispatch();
-  };
-}
-
-/**
- * Create a new radix node
- */
-export function createNode(segment: string, type: NodeType = NodeType.STATIC): RadixNode {
-  return {
-    segment,
-    type,
-    children: new Map(),
-    handlers: new Map(),
-  };
-}
-
-/**
- * Parse path segments
- * Splits path into segments and identifies param/wildcard types
- *
- * @param path - Route path to parse
- * @param caseSensitive - If false, lowercase static segments for case-insensitive matching
- */
-export function parseSegments(path: string, caseSensitive = true): ParsedSegment[] {
-  const normalized = path.startsWith('/') ? path.slice(1) : path;
-  if (normalized === '') return [];
-
-  const parts = normalized.split('/');
-  const segments: ParsedSegment[] = [];
-
-  for (const part of parts) {
-    if (part.startsWith(':')) {
-      // Preserve the original parameter name case
-      const paramName = part.slice(1);
-      segments.push({
-        segment: part, // Preserve original case — param nodes match any segment
-        type: NodeType.PARAM,
-        paramName, // Keep original case
-      });
-    } else if (part === '*') {
-      segments.push({
-        segment: '*',
-        type: NodeType.WILDCARD,
-      });
-      break; // Wildcard must be last
-    } else {
-      segments.push({
-        segment: caseSensitive ? part : part.toLowerCase(),
-        type: NodeType.STATIC,
-      });
-    }
-  }
-
-  return segments;
-}
-
-/**
- * Parsed segment structure
- */
-export interface ParsedSegment {
-  segment: string;
-  type: NodeType;
-  paramName?: string;
-}