@nextrush/router 4.0.0-beta.0 → 4.0.0-beta.1

package/src/registration.ts

@@ -39,12 +39,22 @@ import {
 import { mergeContributions, readContribution } from './route-metadata';
 import { createRedirectHandler, type RedirectStatus } from './redirect';
 
-/** Registration state `addRoute` reads, threaded explicitly. */
+/**
+ * Registration state `addRoute` reads and writes, threaded explicitly.
+ *
+ * `maxDepth` is the deepest registered route's segment count seen so far —
+ * used to size the reused walk-frame pool (`reduce-router-match-allocations`)
+ * without guessing a constant. It only ever grows: a request path can never
+ * make the tree walk descend past the trie's own real depth (a mismatched
+ * segment backtracks rather than pushing a new frame), so this stays a
+ * registration-time-only figure, never influenced by request traffic.
+ */
 export interface RegistrationState {
   readonly root: TrieNode;
   readonly caseSensitive: boolean;
   readonly staticRoutes: StaticRouteMap;
   readonly routeDefinitions: RouteDefinition[];
+  maxDepth: number;
 }
 
 /**
@@ -81,6 +91,24 @@ export function normalizeRegistrationPath(path: string, prefix: string, strict:
   return normalized.startsWith('/') ? normalized : '/' + normalized;
 }
 
+/**
+ * Insert one entry into the method-nested static-route fast-path map,
+ * creating the per-method inner map on first use.
+ */
+function setStaticEntry(
+  staticRoutes: StaticRouteMap,
+  method: HttpMethod,
+  key: string,
+  entry: HandlerEntry
+): void {
+  let methodMap = staticRoutes.get(method);
+  if (!methodMap) {
+    methodMap = new Map<string, HandlerEntry>();
+    staticRoutes.set(method, methodMap);
+  }
+  methodMap.set(key, entry);
+}
+
 /**
  * Insert one route into the segment trie, updating every side structure
  * (static-route fast-path map, introspection registry) that
@@ -115,6 +143,10 @@ export function addRoute(
 ): boolean {
   const segments = parseSegments(normalized, state.caseSensitive);
 
+  if (segments.length > state.maxDepth) {
+    state.maxDepth = segments.length;
+  }
+
   let node = state.root;
 
   for (const seg of segments) {
@@ -182,10 +214,14 @@ export function addRoute(
     handler: finalHandler,
     middleware: combinedMiddleware,
     executor,
+    autoHead: false,
   };
 
-  // Detect duplicate route registration
-  if (node.handlers.has(method)) {
+  // Detect duplicate route registration. A derived HEAD entry is not a
+  // duplicate — an explicit `router.head()` replaces it, in either
+  // registration order.
+  const existing = node.handlers.get(method);
+  if (existing && !(method === 'HEAD' && existing.autoHead)) {
     throw new Error(
       `Route conflict: ${method} ${normalized} is already registered. ` +
         'Remove the duplicate or use a different path.'
@@ -199,14 +235,30 @@ export function addRoute(
   // case-sensitive) path — so matching selects the inner map by method and
   // probes by the raw path with no per-request key-string concatenation.
   const hasParams = segments.some((s) => s.type === NodeType.PARAM || s.type === NodeType.WILDCARD);
-  if (!hasParams) {
-    const normalizedKey = state.caseSensitive ? normalized : normalized.toLowerCase();
-    let methodMap = state.staticRoutes.get(method);
-    if (!methodMap) {
-      methodMap = new Map<string, HandlerEntry>();
-      state.staticRoutes.set(method, methodMap);
+  const staticKey = hasParams
+    ? undefined
+    : state.caseSensitive
+      ? normalized
+      : normalized.toLowerCase();
+  if (staticKey !== undefined) {
+    setStaticEntry(state.staticRoutes, method, staticKey, handlerEntry);
+  }
+
+  // RFC 9110 §9.3.2: HEAD is GET without a body, so a GET registration answers
+  // HEAD too — matching Fastify/Express/Koa/Hono. Derived at registration time,
+  // so request dispatch is unchanged. An explicit HEAD already registered for
+  // this path wins and is never overwritten.
+  if (method === 'GET' && !node.handlers.has('HEAD')) {
+    const derived: HandlerEntry = {
+      handler: finalHandler,
+      middleware: combinedMiddleware,
+      executor,
+      autoHead: true,
+    };
+    node.handlers.set('HEAD', derived);
+    if (staticKey !== undefined) {
+      setStaticEntry(state.staticRoutes, 'HEAD', staticKey, derived);
     }
-    methodMap.set(normalizedKey, handlerEntry);
   }
 
   // Record in the introspection registry (side structure — never touched by

package/src/router.ts

@@ -22,6 +22,7 @@ import { clearNode, createNode, type StaticRouteMap, type TrieNode } from './seg
 import { type RedirectStatus } from './redirect';
 import { runRouteGroup, type RouteGroup } from './group-router';
 import { resolveMatch, type MatchState } from './match-route';
+import { createWalkPool } from './walk-pool';
 import { copyRoutes } from './composition';
 import { sealRouterMiddleware as sealRouterMiddlewareImpl } from './middleware-adapter';
 import {
@@ -33,6 +34,10 @@ import {
 } from './registration';
 import { createAllowedMethodsMiddleware, createRoutesMiddleware } from './dispatch';
 import { createRouterState, resolveRouterOptions } from './state';
+import { canonicalizePath } from './canonicalize';
+
+/** '/'.charCodeAt(0) — used by {@link Router.matchesMountPrefix}'s boundary check. */
+const SLASH_CHAR_CODE = 0x2f;
 
 /** Inline route metadata declaration — re-exported from its own module (RT-3). */
 export { endpoint } from './route-metadata';
@@ -62,6 +67,14 @@ export class Router {
   /** Whether router-level middleware has already been sealed into executors (audit RT-7) */
   private _sealed = false;
 
+  /**
+   * Single-entry memo for {@link matchesMountPrefix}'s canonicalization of the
+   * mount prefix, which is fixed at registration time. Declared as two fields
+   * rather than an object so a miss stores without allocating.
+   */
+  private _prefixMemoRaw: string | undefined = undefined;
+  private _prefixMemoCanonical = '';
+
   /** Memoized state the extracted registration/matching functions read (see {@link createRouterState}). */
   private readonly state: RegistrationState & MatchState;
 
@@ -96,9 +109,15 @@ export class Router {
       );
     }
     const normalized = normalizeRegistrationPath(path, this.opts.prefix, this.opts.strict);
+    const depthBefore = this.state.maxDepth;
     if (addRouteImpl(method, normalized, entries, middleware, this.state, recordIntrospection)) {
       this.hasParamRoutes = true;
     }
+    // Rebuild the pool only when maxDepth actually grew (F-02) — a cheap,
+    // registration-time-only check; never runs per-request.
+    if (this.state.maxDepth > depthBefore) {
+      this.state.walkPool = createWalkPool(this.state.maxDepth);
+    }
   }
 
   get(path: string, ...entries: RouteEntry[]): this {
@@ -215,6 +234,50 @@ export class Router {
     return resolveMatch(this.state, this.hasParamRoutes, method, path);
   }
 
+  /**
+   * Test whether `path` falls under `prefix` using this router's OWN
+   * canonicalization (case folding per `caseSensitive`, structural
+   * normalization) — the mount-boundary counterpart to {@link match}, so a
+   * router mounted via `Application.route()` is tested with the identical
+   * rule it dispatches with (RFC-029, task 3.8). Implements the optional
+   * `Routable.matchesMountPrefix` contract from `@nextrush/core`.
+   *
+   * @param path - The full request path being tested for this mount.
+   * @param prefix - The normalized mount prefix (leading `/`, no trailing `/`).
+   * @returns The path's remainder past the prefix (e.g. `/users` for a
+   *   `/ADMIN/Users` request mounted at `/admin`), or `undefined` when `path`
+   *   is not under `prefix` per this router's canonicalization.
+   */
+  matchesMountPrefix(path: string, prefix: string): string | undefined {
+    const canonical = canonicalizePath(path, this.opts.caseSensitive, this.opts.strict);
+    if (canonical.rejected) return undefined;
+
+    // The prefix is fixed at registration time, so canonicalizing it on every
+    // request is pure waste — it was ~150 ns of the ~557 ns each mounted router
+    // added to dispatch. Memoized rather than precomputed at `route()` time so
+    // the `Routable.matchesMountPrefix` contract still accepts any prefix
+    // string from any caller. One entry is enough: a router is normally mounted
+    // once, and a second prefix only costs a miss.
+    let canonicalPrefix: string;
+    if (this._prefixMemoRaw === prefix) {
+      canonicalPrefix = this._prefixMemoCanonical;
+    } else {
+      canonicalPrefix = canonicalizePath(prefix, this.opts.caseSensitive, this.opts.strict).path;
+      this._prefixMemoRaw = prefix;
+      this._prefixMemoCanonical = canonicalPrefix;
+    }
+
+    const prefixLen = canonicalPrefix.length;
+    if (!canonical.path.startsWith(canonicalPrefix)) return undefined;
+
+    const hasCharAfterPrefix = prefixLen < canonical.path.length;
+    if (hasCharAfterPrefix && canonical.path.charCodeAt(prefixLen) !== SLASH_CHAR_CODE) {
+      return undefined;
+    }
+
+    return canonical.path.slice(prefixLen) || '/';
+  }
+
   /**
    * Return the router's dispatch middleware — mount this on the application.
    * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#routerroutes | README: router.routes()}
@@ -226,7 +289,17 @@ export class Router {
       this._sealed = true;
       sealRouterMiddlewareImpl(this.root, this.staticRoutes, this.routerMiddleware);
     }
-    return createRoutesMiddleware((method, path) => this.match(method, path));
+    // F-10: the internal closure calls `resolveMatch` directly with
+    // `preNormalized: true` rather than going through the public `this.match()`
+    // — this is the one call path where the caller (`createRoutesMiddleware`)
+    // has already run `canonicalizePath()` on `path`, so `matchRoute`'s own
+    // fold+collapse re-derivation is skippable. `Router.match()` itself is
+    // untouched and still defaults to `false` for every other caller.
+    return createRoutesMiddleware(
+      (method, path) => resolveMatch(this.state, this.hasParamRoutes, method, path, true),
+      this.opts.caseSensitive,
+      this.opts.strict
+    );
   }
 
   /**
@@ -263,6 +336,11 @@ export class Router {
     // Clear the introspection registry too, or getRoutes()/OpenAPI would emit
     // ghost routes after a reset (audit RT-1).
     this.routeDefinitions.length = 0;
+    // Reset the walk-frame pool sizing too (F-02) — otherwise maxDepth would
+    // keep reporting a since-cleared route's depth, and the pool would stay
+    // needlessly oversized for whatever gets registered next.
+    this.state.maxDepth = 0;
+    this.state.walkPool = undefined;
     this._sealed = false;
   }
 

package/src/segment-trie.ts

@@ -51,6 +51,14 @@ export interface HandlerEntry {
   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;
 }
 
 /**

package/src/state.ts

@@ -48,5 +48,6 @@ export function createRouterState(
     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;
+}