@nextrush/router 3.0.7 → 4.0.0-beta.0

package/src/dispatch.ts

@@ -0,0 +1,117 @@
+/**
+ * @nextrush/router - Dispatch Middleware Generation
+ *
+ * The two app-facing `Middleware` factories extracted from the `Router` class
+ * (design.md D2 — finishing T014's split along the same seam: the composition,
+ * matching-engine, and sealing clusters were already extracted; this is the
+ * dispatch/allowed-methods generation cluster).
+ *
+ * Both closures are structurally pure — every value they read (the `match`
+ * function, the trie root, the case-sensitivity/strict flags) is passed in
+ * explicitly rather than captured off `this`, so they carry no hidden
+ * dependency on `Router` beyond their parameters (same principle as the
+ * matching-engine extraction, design.md D1). `Router.routes()` and
+ * `Router.allowedMethods()` stay as thin public methods that supply that
+ * state and return these closures.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Context, HttpMethod, Middleware, RouteMatch } from '@nextrush/types';
+import { NOOP_NEXT, type TrieNode } from './segment-trie';
+import { findAllowedMethods } from './find-node';
+
+/**
+ * Shared resolved promise for the no-`next` miss path (NF-1). Reused rather than
+ * allocating a fresh `Promise.resolve()` per miss, mirroring the router's
+ * existing `NOOP_NEXT`/`RESOLVED_PROMISE` sentinels.
+ */
+const RESOLVED: Promise<void> = Promise.resolve();
+
+/**
+ * Build the router's primary dispatch middleware.
+ *
+ * On each request it resolves the route via the injected `match` function,
+ * sets `ctx.params`, and runs the pre-compiled executor (which already bakes
+ * in any router-level middleware). A miss sets `ctx.status = 404` and yields
+ * to the next middleware so `allowedMethods()`/a 404 handler can act.
+ *
+ * @param match - Route resolver, supplied by `Router.match` so this factory
+ *   never touches `Router` internals directly.
+ */
+export function createRoutesMiddleware(
+  match: (method: HttpMethod, path: string) => RouteMatch | null
+): Middleware {
+  return (ctx: Context, next?: () => Promise<void>): Promise<void> => {
+    const routeMatch = match(ctx.method, ctx.path);
+
+    if (!routeMatch) {
+      // No route matched — set 404 so allowedMethods()/notFoundHandler() can act,
+      // then forward to the next middleware (the allowedMethods fall-through).
+      ctx.status = 404;
+      return next ? next() : RESOLVED;
+    }
+
+    ctx.params = routeMatch.params;
+
+    // NF-1: forward the executor's promise DIRECTLY instead of `await`-ing it in
+    // an extra `async` frame. The executor already returns a `Promise<void>`,
+    // converts synchronous throws to rejections, and terminates the chain at the
+    // handler, so ordering, rejection propagation, and the `setNext(NOOP_NEXT)`
+    // guard are unchanged — one state machine + one microtask hop removed. A
+    // synchronous throw from `match()` itself is still converted to a rejection
+    // by the composer's `try/catch` that wraps this middleware call.
+    return routeMatch.executor
+      ? routeMatch.executor(ctx)
+      : // Fallback (no pre-compiled executor — shouldn't happen): wrap so a void
+        // or thenable return still yields a Promise<void> and never a sync throw.
+        Promise.resolve(routeMatch.handler(ctx, NOOP_NEXT));
+  };
+}
+
+/**
+ * Build the allowed-methods middleware.
+ *
+ * Runs after the dispatch middleware: if the request was a 404, it does a
+ * single tree walk to collect every method registered for the path. An
+ * `OPTIONS` request gets a `200` with an `Allow` header; any other method
+ * gets a `405` with `Allow`. If no method is registered for the path it
+ * leaves the 404 untouched.
+ *
+ * @param root - Trie root to walk for allowed methods.
+ * @param caseSensitive - Router case-sensitivity option.
+ * @param strict - Router strict-trailing-slash option.
+ */
+export function createAllowedMethodsMiddleware(
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): Middleware {
+  return async (ctx: Context, next?: () => Promise<void>): Promise<void> => {
+    if (next) {
+      await next();
+    }
+
+    if (ctx.status !== 404) return;
+
+    // Single tree walk to find all allowed methods instead of N×match()
+    const allowed = findAllowedMethods(ctx.path, root, caseSensitive, strict);
+
+    if (allowed.length === 0) return;
+
+    const allowHeader = allowed.join(', ');
+
+    // If OPTIONS request, respond with allowed methods
+    if (ctx.method === 'OPTIONS') {
+      ctx.status = 200;
+      ctx.set('Allow', allowHeader);
+      ctx.body = '';
+      return;
+    }
+
+    // Otherwise, return 405 Method Not Allowed
+    ctx.status = 405;
+    ctx.set('Allow', allowHeader);
+  };
+}

package/src/find-node.ts

@@ -0,0 +1,125 @@
+/**
+ * @nextrush/router - Method-agnostic trie walk (allowed-methods / 405 path)
+ *
+ * `findNode` + `findAllowedMethods` were split out of `matching.ts` when the
+ * iterative rewrite of `findNode` (HP-17, OpenSpec change
+ * `router-context-final-cleanup`) pushed that file past the 300-line ceiling.
+ * They form one cohesive concern — resolving the *node* for a path regardless
+ * of HTTP method, to answer OPTIONS/405 — distinct from `matching.ts`'s
+ * method-aware handler match (`matchNodeIndexed`) and its normalization
+ * primitives, which are reused here via import (`segmentAt`,
+ * `normalizePathForMatch`).
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import { normalizePathForMatch, segmentAt } from './matching';
+import type { TrieNode } from './segment-trie';
+
+/**
+ * One node in {@link findNode}'s explicit-stack walk. `stage` is a small state
+ * machine (0 = extract segment + try static, 1 = try param, 2 = try
+ * wildcard/backtrack) so a single frame can be revisited on backtrack without
+ * recursion. `next` is the start position of the following segment, captured
+ * once in stage 0 and reused when descending into the param branch.
+ */
+interface FindFrame {
+  node: TrieNode;
+  pos: number;
+  stage: 0 | 1 | 2;
+  next: number;
+}
+
+/**
+ * Walk the trie to find the node matching a path (ignoring HTTP method), the
+ * method-agnostic walker used by {@link findAllowedMethods} for the 405/OPTIONS
+ * path (design.md D3 / HP-17).
+ *
+ * Walks with an EXPLICIT stack instead of recursion — mirroring
+ * `matchNodeIndexed` — so a pathological segment count cannot overflow the call
+ * stack (the same DoS class HP-11 closed for the match path). Behavior is
+ * byte-identical to the former recursive walker: precedence is static > param >
+ * wildcard at each node, a partially-matching branch backtracks cleanly, the
+ * wildcard child is a terminal (it captures the remainder), and the first
+ * accepted terminal wins. The scalar {@link segmentAt} scan is reused so the
+ * traversal shares one segment-extraction helper rather than duplicating it.
+ *
+ * `path` is the already-normalized lookup path; `startPos` skips the leading
+ * `/` (callers pass `1`, matching `matchNodeIndexed`).
+ */
+export function findNode(root: TrieNode, path: string, startPos: number): TrieNode | null {
+  const stack: FindFrame[] = [{ node: root, pos: startPos, stage: 0, next: 0 }];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) break;
+
+    // Stage 0 — first visit: terminal check, then try the static child.
+    if (frame.stage === 0) {
+      // Whole path consumed at this node → it is the matching node.
+      if (frame.pos >= path.length) {
+        return frame.node;
+      }
+      const seg = segmentAt(path, frame.pos);
+      // An empty segment means the path is exhausted here (e.g. a strict-mode
+      // trailing slash) — treat this node as the terminal, as the recursive
+      // walk did after `split('/').filter(Boolean)` dropped empty segments.
+      if (seg === '') {
+        return frame.node;
+      }
+      // `segmentAt` already scanned to the next `/`; derive the following
+      // position from the segment length (no second indexOf) — a slash follows
+      // iff the segment ended before the path did.
+      const segEnd = frame.pos + seg.length;
+      frame.next = segEnd < path.length ? segEnd + 1 : path.length;
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(seg);
+      if (staticChild) {
+        stack.push({ node: staticChild, pos: frame.next, stage: 0, next: 0 });
+      }
+      continue;
+    }
+
+    // Stage 1 — static child (if any) failed: try the param child.
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      if (frame.node.paramChild) {
+        stack.push({ node: frame.node.paramChild, pos: frame.next, stage: 0, next: 0 });
+      }
+      continue;
+    }
+
+    // Stage 2 — static and param branches exhausted: the wildcard child is a
+    // terminal (matches the remainder). Otherwise this branch fails; backtrack.
+    if (frame.node.wildcardChild) {
+      return frame.node.wildcardChild;
+    }
+    stack.pop();
+  }
+
+  return null;
+}
+
+/**
+ * Find all HTTP methods registered for a given path via a single tree walk.
+ * `caseSensitive`/`strict` (formerly `this.opts.*`) and `root` (formerly
+ * `this.root`) are threaded explicitly.
+ */
+export function findAllowedMethods(
+  path: string,
+  root: TrieNode,
+  caseSensitive: boolean,
+  strict: boolean
+): HttpMethod[] {
+  const normalized = normalizePathForMatch(path, caseSensitive, strict);
+
+  // Walk from position 1 to skip the leading '/', matching `matchNodeIndexed`'s
+  // start offset. The iterative `findNode` scans segments off the path in place,
+  // so no `split('/')` array is allocated here.
+  const node = findNode(root, normalized, 1);
+  if (!node || node.handlers.size === 0) return [];
+
+  return Array.from(node.handlers.keys());
+}

package/src/group-router.ts

@@ -0,0 +1,208 @@
+/**
+ * @nextrush/router - Route Groups
+ *
+ * A route group applies a shared path prefix and middleware to a set of routes
+ * registered inside a callback. Extracted from `router.ts` (audit RT-3) and
+ * given a real public type (audit RT-6): `router.group()` callbacks receive a
+ * {@link RouteGroup}, not a mis-cast `Router`.
+ *
+ * @packageDocumentation
+ */
+
+import { HTTP_METHODS, type HttpMethod, type Middleware, type RouteHandler } from '@nextrush/types';
+import { createRedirectHandler, type RedirectStatus } from './redirect';
+
+/**
+ * The subset of the parent router a group needs to register routes into.
+ *
+ * @remarks
+ * Declared as an interface (rather than importing `Router`) so `group-router.ts`
+ * and `router.ts` don't form an import cycle. `Router` satisfies it structurally
+ * via its `_addGroupRoute` method.
+ */
+export interface GroupRouterHost {
+  _addGroupRoute(
+    method: HttpMethod,
+    path: string,
+    handlers: RouteHandler[],
+    groupMiddleware: Middleware[],
+    recordIntrospection?: boolean
+  ): void;
+  /** Record a single any-method introspection row (T016) — see `Router._pushAnyMethodRouteDefinition`. */
+  _pushAnyMethodRouteDefinition(path: string): void;
+}
+
+/**
+ * The object passed to a `router.group(prefix, callback)` callback.
+ *
+ * @remarks
+ * Exposes only the route-registration surface that is valid inside a group —
+ * intentionally NOT the full {@link Router} (no `mount`/`use`/`reset`), which is
+ * why the previous `as unknown as Router` cast was a lie (audit RT-6).
+ */
+export interface RouteGroup {
+  get(path: string, ...handlers: RouteHandler[]): this;
+  post(path: string, ...handlers: RouteHandler[]): this;
+  put(path: string, ...handlers: RouteHandler[]): this;
+  delete(path: string, ...handlers: RouteHandler[]): this;
+  patch(path: string, ...handlers: RouteHandler[]): this;
+  head(path: string, ...handlers: RouteHandler[]): this;
+  options(path: string, ...handlers: RouteHandler[]): this;
+  all(path: string, ...handlers: RouteHandler[]): this;
+  redirect(from: string, to: string, status?: RedirectStatus): this;
+  group(
+    prefix: string,
+    middlewareOrCallback: Middleware[] | ((router: RouteGroup) => void),
+    callback?: (router: RouteGroup) => void
+  ): this;
+}
+
+/**
+ * Collects routes under a shared prefix + middleware and forwards them to the
+ * parent router. Implements {@link RouteGroup}.
+ */
+export class GroupRouter implements RouteGroup {
+  private readonly parent: GroupRouterHost;
+  private readonly prefix: string;
+  private readonly middleware: Middleware[];
+
+  constructor(parent: GroupRouterHost, prefix: string, middleware: Middleware[]) {
+    this.parent = parent;
+    this.prefix = prefix;
+    this.middleware = middleware;
+  }
+
+  private fullPath(path: string): string {
+    // Handle root path in group
+    if (path === '/' || path === '') {
+      return this.prefix;
+    }
+    // Combine prefix and path
+    const cleanPrefix = this.prefix.endsWith('/') ? this.prefix.slice(0, -1) : this.prefix;
+    const cleanPath = path.startsWith('/') ? path : '/' + path;
+    return cleanPrefix + cleanPath;
+  }
+
+  get(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('GET', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  post(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('POST', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  put(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('PUT', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  delete(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('DELETE', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  patch(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('PATCH', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  head(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('HEAD', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  options(path: string, ...handlers: RouteHandler[]): this {
+    this.parent._addGroupRoute('OPTIONS', this.fullPath(path), handlers, this.middleware);
+    return this;
+  }
+
+  /**
+   * Register a route matching every HTTP method under a single introspection
+   * entry, mirroring `Router.all()` (T016) — a group's `.all()` must not
+   * regress to the pre-T016 one-row-per-method shape just because
+   * registration is routed through `_addGroupRoute` instead of `addRoute`
+   * directly.
+   */
+  all(path: string, ...handlers: RouteHandler[]): this {
+    for (const method of HTTP_METHODS) {
+      this.parent._addGroupRoute(method, this.fullPath(path), handlers, this.middleware, false);
+    }
+    this.parent._pushAnyMethodRouteDefinition(this.fullPath(path));
+    return this;
+  }
+
+  /**
+   * Register a redirect within the group (uses the shared redirect handler,
+   * audit RT-4 — no more naive replaceAll param substitution).
+   */
+  redirect(from: string, to: string, status: RedirectStatus = 301): this {
+    const redirectHandler = createRedirectHandler(to, status);
+
+    this.parent._addGroupRoute('GET', this.fullPath(from), [redirectHandler], this.middleware);
+    this.parent._addGroupRoute('HEAD', this.fullPath(from), [redirectHandler], this.middleware);
+
+    return this;
+  }
+
+  /**
+   * Nested group support — combines this group's prefix + middleware with the
+   * nested group's.
+   */
+  group(
+    prefix: string,
+    middlewareOrCallback: Middleware[] | ((router: RouteGroup) => void),
+    callback?: (router: RouteGroup) => void
+  ): this {
+    runRouteGroup(
+      this.parent,
+      this.fullPath(prefix),
+      middlewareOrCallback,
+      callback,
+      this.middleware
+    );
+    return this;
+  }
+}
+
+/**
+ * Resolve a `group()` call's `(middleware[], callback)` | `(callback)` overload
+ * and run the callback against a fresh {@link GroupRouter} bound to `host`.
+ *
+ * @remarks
+ * Shared by `Router.group()` and the nested `GroupRouter.group()` so the
+ * overload handling and the "throw when a middleware array has no callback"
+ * guard have a single definition.
+ *
+ * @param host - Parent router the group registers routes into.
+ * @param prefix - Fully-resolved path prefix for the group.
+ * @param middlewareOrCallback - Either the group middleware array or the callback.
+ * @param callback - The callback, required when a middleware array is passed.
+ * @param inheritedMiddleware - Middleware from an enclosing group, prepended
+ *   ahead of this group's own (empty for a top-level `Router.group()`).
+ */
+export function runRouteGroup(
+  host: GroupRouterHost,
+  prefix: string,
+  middlewareOrCallback: Middleware[] | ((router: RouteGroup) => void),
+  callback: ((router: RouteGroup) => void) | undefined,
+  inheritedMiddleware: Middleware[] = []
+): void {
+  let middleware: Middleware[] = [];
+  let cb: (router: RouteGroup) => void;
+
+  if (Array.isArray(middlewareOrCallback)) {
+    middleware = middlewareOrCallback;
+    if (!callback) {
+      throw new Error('Callback function is required when providing middleware array');
+    }
+    cb = callback;
+  } else {
+    cb = middlewareOrCallback;
+  }
+
+  const combined =
+    inheritedMiddleware.length > 0 ? [...inheritedMiddleware, ...middleware] : middleware;
+  cb(new GroupRouter(host, prefix, combined));
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * @nextrush/router - High-Performance Router for NextRush
  *
- * This package provides a radix tree based router with:
+ * This package provides a segment trie based router with:
  * - O(k) route matching where k is path length
  * - Named parameters (/users/:id)
  * - Wildcard routes (/files/*)
@@ -13,11 +13,14 @@
  */
 
 // Router
-export { createRouter, Router } from './router';
+export { createRouter, endpoint, Router } from './router';
 
-// Radix tree internals (for advanced usage)
-export { createNode, NodeType, parseSegments } from './radix-tree';
-export type { HandlerEntry, ParsedSegment, RadixNode } from './radix-tree';
+// Route groups
+export type { RouteGroup } from './group-router';
+
+// Segment trie internals (for advanced usage)
+export { createNode, NodeType, parseSegments } from './segment-trie';
+export type { HandlerEntry, ParsedSegment, TrieNode } from './segment-trie';
 
 // Re-export relevant types
 export type {

package/src/match-route.ts

@@ -0,0 +1,178 @@
+/**
+ * @nextrush/router - Top-Level Route Match Orchestration
+ *
+ * `matchRoute` was originally part of `matching.ts` (the lookup-primitives
+ * module: `decodeParam`/`extractSegment`/`findNode`/`findAllowedMethods`/
+ * `matchNodeIndexed`), but `matching.ts` was approaching the 300-line ceiling
+ * itself once `matchRoute` moved in — this file separates the top-level
+ * "match a request" orchestration (query-strip, normalize, static fast-path,
+ * tree-walk delegation, param post-processing) from the lower-level lookup
+ * primitives it calls into.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod, Middleware, RouteMatch } from '@nextrush/types';
+import { EMPTY_PARAMS } from './constants';
+import { matchNodeIndexed, collapseAndStrip, isProvablyLowerAscii } from './matching';
+import type { StaticRouteMap, TrieNode } from './segment-trie';
+
+/**
+ * Match a route and return the full {@link RouteMatch} in a SINGLE allocation
+ * (design.md D1 / HP-10).
+ *
+ * `matchRoute` builds the final `RouteMatch` — including `middleware:
+ * routerMiddleware` — directly at each return site, so `Router.match()` gets
+ * one object per matched request instead of a bare result later re-wrapped by
+ * `resolveMatch`. `routerMiddleware` is threaded in as a parameter (its
+ * contents are never read here — only attached by reference), preserving the
+ * "no implicit `Router` state" property of the earlier extraction while
+ * removing the duplicate wrapper object.
+ *
+ * Every other piece of `Router` state it reads (`root`, `staticRoutes`,
+ * `hasParamRoutes`, the option flags) is read-only here (no mutation, unlike
+ * `addRoute` in `registration.ts`), so it is threaded as plain parameters.
+ */
+export function matchRoute(
+  method: HttpMethod,
+  rawPath: string,
+  root: TrieNode,
+  staticRoutes: StaticRouteMap,
+  hasParamRoutes: boolean,
+  caseSensitive: boolean,
+  strict: boolean,
+  decode: boolean,
+  routerMiddleware: Middleware[]
+): RouteMatch | null {
+  let path = rawPath;
+  // Query string must not affect path matching (RFC 3986 §3.4). Strip it here,
+  // before normalization, so both the lookup path and extracted param values
+  // exclude it. This strip is caller-specific: `findAllowedMethods` receives an
+  // already query-free `ctx.path`, so the shared `normalizePathForMatch` does
+  // not strip — only `matchRoute` does.
+  const queryIdx = path.indexOf('?');
+  if (queryIdx !== -1) path = path.slice(0, queryIdx);
+
+  // HP-12: decide case-stability ONCE. When the path is provably case-stable
+  // (case-sensitive router, or an all-lowercase-ASCII path), folding is a no-op
+  // and the original-case path equals the normalized one — so we skip both the
+  // `toLowerCase()` allocation and the second original-case normalize pass.
+  const caseStable = caseSensitive || isProvablyLowerAscii(path);
+  const folded = caseStable ? path : path.toLowerCase();
+  const normalized = collapseAndStrip(folded, strict);
+
+  // FAST PATH: O(1) static route lookup (no tree traversal). Method-nested map
+  // (HP-9): select the inner map by method, then probe by the normalized path —
+  // no per-request `${method} ${path}` key-string allocation. For static routes
+  // a trailing slash is irrelevant, so always strip it for the probe.
+  const methodMap = staticRoutes.get(method);
+  if (methodMap) {
+    const staticKey =
+      normalized.length > 1 && normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+    const staticEntry = methodMap.get(staticKey);
+    if (staticEntry) {
+      return {
+        handler: staticEntry.handler,
+        params: EMPTY_PARAMS,
+        middleware: routerMiddleware,
+        executor: staticEntry.executor,
+      };
+    }
+  }
+
+  // Only walk tree if we have param/wildcard routes
+  if (!hasParamRoutes) return null;
+
+  // Original-case (query-stripped) path so extracted param values keep their
+  // casing while lookup uses the lowercased `normalized`. Needed ONLY when a
+  // fold actually happened (HP-12): when case-stable, `normalized` already IS
+  // the original-case structure, so the walk extracts from it and no second
+  // normalize pass runs.
+  const originalPath = caseStable ? undefined : collapseAndStrip(path, strict);
+
+  // Deferred param binding (HP-11): the walk records the accepted path's
+  // `:param`/`*` bindings onto these parallel stacks (pushed on descent, popped
+  // on backtrack) so params are materialized ONCE here on the accepted terminal
+  // — no eager bind + backtrack `Reflect.deleteProperty`.
+  const bindNames: string[] = [];
+  const bindValues: string[] = [];
+
+  const entry = matchNodeIndexed(
+    root,
+    normalized,
+    1, // Start after leading '/'
+    bindNames,
+    bindValues,
+    method,
+    decode,
+    originalPath
+  );
+  if (!entry) return null;
+
+  // Materialize params once on a null-prototype object (design.md D8): a param
+  // named `__proto__`/`constructor`/`prototype` binds as an OWN key with no
+  // prototype mutation, and no inherited member is visible on `ctx.params`. The
+  // bind count replaces the former `Object.keys` post-loop (HP-13); zero binds
+  // returns the shared frozen `EMPTY_PARAMS`.
+  const count = bindNames.length;
+  let params: Record<string, string>;
+  if (count === 0) {
+    params = EMPTY_PARAMS;
+  } else {
+    params = Object.create(null) as Record<string, string>;
+    for (let i = 0; i < count; i++) {
+      const name = bindNames[i];
+      const value = bindValues[i];
+      if (name !== undefined && value !== undefined) params[name] = value;
+    }
+  }
+
+  return {
+    handler: entry.handler,
+    params,
+    middleware: routerMiddleware,
+    executor: entry.executor,
+  };
+}
+
+/**
+ * Stable router state `resolveMatch` reads on every request. All fields are
+ * fixed references for the router's lifetime, so the caller memoizes this once
+ * rather than rebuilding it per request.
+ */
+export interface MatchState {
+  readonly root: TrieNode;
+  readonly staticRoutes: StaticRouteMap;
+  readonly caseSensitive: boolean;
+  readonly strict: boolean;
+  readonly decode: boolean;
+  readonly routerMiddleware: Middleware[];
+}
+
+/**
+ * Resolve a request to a full {@link RouteMatch}. Thin delegator to
+ * {@link matchRoute}, which now builds the final `RouteMatch` (incl.
+ * `state.routerMiddleware`) in one allocation — so this no longer wraps a
+ * result in a second object (HP-10). `Router.match()` is a one-line delegator
+ * to this. `hasParamRoutes` is passed separately from `state` because it is
+ * the one piece of router state that flips after construction.
+ */
+export function resolveMatch(
+  state: MatchState,
+  hasParamRoutes: boolean,
+  method: HttpMethod,
+  path: string
+): RouteMatch | null {
+  return matchRoute(
+    method,
+    path,
+    state.root,
+    state.staticRoutes,
+    hasParamRoutes,
+    state.caseSensitive,
+    state.strict,
+    state.decode,
+    state.routerMiddleware
+  );
+}