@nextrush/router 3.0.7 → 4.0.0-beta.0

package/src/matching.ts

@@ -0,0 +1,240 @@
+/**
+ * @nextrush/router - Route Matching Engine
+ *
+ * The segment-trie lookup logic extracted from the `Router` class (T014,
+ * design.md D1). These are standalone pure functions taking the trie root and
+ * other needed state as explicit parameters — not methods — so the matching
+ * engine has no implicit dependency on broader `Router` instance state beyond
+ * what's passed in. `Router` becomes a thin delegating shell around these.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import type { HandlerEntry, TrieNode } from './segment-trie';
+
+/**
+ * Percent-decode an extracted param/wildcard value when `decode` is enabled.
+ * Fast-paths values with no `%`, and falls back to the raw value on malformed
+ * encoding (decodeURIComponent throws a URIError) so a bad request never crashes
+ * routing.
+ */
+export function decodeParam(value: string, decode: boolean): string {
+  if (!decode || !value.includes('%')) return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Return the path segment starting at `start`, up to the next `/` (or end).
+ * Scalar — no tuple array (the iterative walk tracks the next position itself).
+ * Used to recover an original-case param value from the original-case path at a
+ * position already validated against the (folded) lookup path, and by the
+ * {@link findNode} allowed-methods walk to scan segments off the lookup path.
+ */
+export function segmentAt(path: string, start: number): string {
+  const slashPos = path.indexOf('/', start);
+  return slashPos === -1 ? path.slice(start) : path.slice(start, slashPos);
+}
+
+/**
+ * True only when `path.toLowerCase()` is provably a no-op: every character is
+ * ASCII (`<= 0x7F`) and none is an ASCII uppercase letter (`A`–`Z`). Any
+ * non-ASCII byte is treated as UNCERTAIN (it could be uppercase like `Ü`), so
+ * this returns `false` and the caller folds — never skipping unicode case
+ * folding (design.md D3). This lets `normalizePathForMatch` skip the
+ * `toLowerCase()` allocation for the overwhelmingly common all-lowercase-ASCII
+ * request path while staying byte-identical to always folding.
+ */
+export function isProvablyLowerAscii(path: string): boolean {
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if ((c >= 0x41 && c <= 0x5a) || c > 0x7f) return false;
+  }
+  return true;
+}
+
+/**
+ * Structural match-time normalization WITHOUT case folding: collapse repeated
+ * slashes and strip a single trailing slash (unless `strict`). Split out of
+ * {@link normalizePathForMatch} so the case-fold decision and the structural
+ * pass are separable — `matchRoute` reuses this to build the original-case path
+ * only when a fold actually happened (HP-12), rather than running the full
+ * normalize twice.
+ */
+export function collapseAndStrip(path: string, strict: boolean): string {
+  let normalized = path;
+
+  // Fast-path: skip the regex when there are no double slashes (99%+ of requests).
+  if (normalized.includes('//')) {
+    normalized = normalized.replace(/\/+/g, '/');
+  }
+
+  // Non-strict mode treats a trailing slash as insignificant; strict keeps it.
+  if (!strict && normalized.length > 1 && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize a request path for segment-trie matching: fold case (unless
+ * `caseSensitive`), collapse repeated slashes, and strip a single trailing
+ * slash (unless `strict`). This is the one definition of the match-time
+ * normalization rules, shared by `matchRoute` (in `match-route.ts`) and
+ * {@link findAllowedMethods}.
+ *
+ * The `toLowerCase()` call is skipped when the path is provably case-stable
+ * ({@link isProvablyLowerAscii}) — byte-identical to always folding, but with
+ * no throwaway string on the common all-lowercase-ASCII path (HP-12 / D3).
+ *
+ * Query-string removal is intentionally NOT done here — it is caller-specific:
+ * `matchRoute` strips the query before calling, while `findAllowedMethods`
+ * receives an already query-free `ctx.path`. Pass `caseSensitive: true` to
+ * normalize while preserving case (used by `matchRoute` to build the
+ * original-case path from which param values are extracted).
+ *
+ * NOTE: registration-time normalization (`Router.normalizePath`) is a separate
+ * concern — it joins the router prefix, guarantees a leading slash, and never
+ * folds case — so it deliberately does not share this helper.
+ */
+export function normalizePathForMatch(
+  path: string,
+  caseSensitive: boolean,
+  strict: boolean
+): string {
+  const folded = caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase();
+  return collapseAndStrip(folded, strict);
+}
+
+/**
+ * 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.
+ */
+interface WalkFrame {
+  node: TrieNode;
+  pos: number;
+  stage: 0 | 1 | 2;
+  seg: string;
+  next: number;
+  bound: boolean;
+}
+
+/**
+ * Iterative, index-based segment-trie match (HP-11 / HP-13, design.md D4).
+ *
+ * Walks the trie with an EXPLICIT stack instead of recursion, so a pathological
+ * segment count cannot overflow the call stack (DoS safety) — behavior is
+ * otherwise byte-identical to the former recursive matcher: precedence is
+ * static > param > wildcard at each node, a partially-matching branch backtracks
+ * cleanly, and the first accepted terminal wins.
+ *
+ * Param/wildcard bindings are DEFERRED onto the caller-owned `bindNames` /
+ * `bindValues` stacks and popped on backtrack, so params are materialized ONCE
+ * on the accepted terminal by the caller (no eager bind + backtrack
+ * `Reflect.deleteProperty`, and no `Object.keys` post-loop — the caller reads
+ * the bind count). `decode` runs strictly on the already-split segment/remainder
+ * (design.md D9), so an encoded slash/dot decodes into the value only and can
+ * never create new path segments.
+ *
+ * `originalPath` (present only when case-folding actually occurred) supplies the
+ * original-case param value at the same position as the folded lookup path.
+ */
+export function matchNodeIndexed(
+  root: TrieNode,
+  path: string,
+  startPos: number,
+  bindNames: string[],
+  bindValues: string[],
+  method: HttpMethod,
+  decode: boolean,
+  originalPath?: string
+): HandlerEntry | null {
+  const stack: WalkFrame[] = [
+    { node: root, pos: startPos, stage: 0, seg: '', next: 0, bound: false },
+  ];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === undefined) break;
+
+    // Stage 0 — first visit: terminal checks, then try the static child.
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler; // accepted — bind stacks hold this path's params
+        stack.pop();
+        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;
+        stack.pop();
+        continue;
+      }
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(frame.seg);
+      if (staticChild) {
+        stack.push({ node: staticChild, pos: frame.next, stage: 0, seg: '', next: 0, bound: false });
+      }
+      continue;
+    }
+
+    // Stage 1 — static child (if any) has failed: try the param child, deferring
+    // its binding onto the shared stacks.
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      const paramChild = frame.node.paramChild;
+      if (paramChild) {
+        const paramName = paramChild.paramName;
+        if (paramName === undefined) return null; // degenerate param node → whole walk fails (as before)
+        const value =
+          originalPath !== undefined
+            ? decodeParam(segmentAt(originalPath, frame.pos), decode)
+            : decodeParam(frame.seg, decode);
+        bindNames.push(paramName);
+        bindValues.push(value);
+        frame.bound = true;
+        stack.push({ node: paramChild, pos: frame.next, stage: 0, seg: '', next: 0, bound: false });
+      }
+      continue;
+    }
+
+    // Stage 2 — param branch (if taken) failed: undo its deferred bind, then try
+    // the wildcard child (a terminal — it captures the original-case remainder).
+    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();
+    }
+    stack.pop();
+  }
+
+  return null;
+}

package/src/middleware-adapter.ts

@@ -0,0 +1,59 @@
+/**
+ * @nextrush/router - Middleware Adaptation
+ *
+ * Router-level-middleware sealing logic extracted from the `Router` class
+ * (T014, design.md D3 — extracted after the matching-engine and composition
+ * splits left `router.ts` still over the 300-line ceiling).
+ *
+ * The tree-walk that re-compiles every handler's executor is structurally
+ * pure (it only mutates the `TrieNode`/`HandlerEntry` structures passed in,
+ * same shape as `copyRoutes` in `composition.ts`) — it doesn't touch
+ * `Router`-only state like `_sealed`, so it extracts cleanly. `routes()` and
+ * `allowedMethods()` stay on `Router`: both return closures that capture
+ * `this` (for `this.match`, `this.opts`, `this.root`) and are the router's
+ * actual public middleware-producing API, not internal tree mechanics.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import { compileExecutor, type StaticRouteMap, type TrieNode } from './segment-trie';
+import type { Middleware } from '@nextrush/types';
+
+/**
+ * Re-compile every route executor in the trie (plus the static-route hash
+ * map) to include router-level middleware ahead of each route's own
+ * middleware. Idempotency (guarding against a double seal) is the caller's
+ * responsibility — this function always re-walks and re-compiles.
+ */
+export function sealRouterMiddleware(
+  root: TrieNode,
+  staticRoutes: StaticRouteMap,
+  routerMiddleware: Middleware[]
+): void {
+  const routerMw = [...routerMiddleware];
+
+  const walk = (node: TrieNode): void => {
+    for (const [method, entry] of node.handlers) {
+      const combinedMw = [...routerMw, ...entry.middleware];
+      entry.executor = compileExecutor(entry.handler, combinedMw);
+      node.handlers.set(method, entry);
+    }
+    for (const [, child] of node.children) {
+      walk(child);
+    }
+    if (node.paramChild) walk(node.paramChild);
+    if (node.wildcardChild) walk(node.wildcardChild);
+  };
+
+  walk(root);
+
+  // Also update static route entries (method-nested map, HP-9).
+  for (const [, methodMap] of staticRoutes) {
+    for (const [key, entry] of methodMap) {
+      const combinedMw = [...routerMw, ...entry.middleware];
+      entry.executor = compileExecutor(entry.handler, combinedMw);
+      methodMap.set(key, entry);
+    }
+  }
+}

package/src/redirect.ts

@@ -0,0 +1,97 @@
+/**
+ * @nextrush/router - Redirect Handler Compilation
+ *
+ * Single, shared redirect implementation used by both `Router.redirect()` and
+ * route groups (audit RT-4). Previously the group variant used a naive
+ * `replaceAll(':key', value)` that could mis-substitute overlapping param names
+ * and re-scanned the string per request; this precompiles the target template
+ * once and only substitutes route-style `:param` slots (a `:` at position 0 or
+ * preceded by `/`), so `https://` and other literal colons are never touched.
+ *
+ * @packageDocumentation
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+
+/** HTTP redirect status codes supported by `redirect()`. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+
+/**
+ * Precompile a redirect target into alternating literal / param-name parts.
+ *
+ * @param to - Target path/URL, possibly containing `:param` placeholders.
+ * @returns A parts array (`[literal, paramName, literal, …]`) when `to` has
+ *   route-style params, otherwise `undefined` (a static target).
+ */
+export function compileRedirectTarget(to: string): string[] | undefined {
+  const parts: string[] = [];
+  let pos = 0;
+  let found = false;
+
+  while (pos < to.length) {
+    let idx = -1;
+    for (let i = pos; i < to.length; i++) {
+      if (to[i] === ':' && (i === 0 || to[i - 1] === '/') && i + 1 < to.length && to[i + 1] !== '/') {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) break;
+
+    found = true;
+    parts.push(to.slice(pos, idx)); // literal before ':'
+    const end = to.indexOf('/', idx + 1);
+    if (end === -1) {
+      parts.push(to.slice(idx + 1)); // param name (rest of string)
+      pos = to.length;
+    } else {
+      parts.push(to.slice(idx + 1, end)); // param name
+      pos = end;
+    }
+  }
+
+  if (found) {
+    parts.push(to.slice(pos)); // trailing literal
+    return parts;
+  }
+  return undefined;
+}
+
+/**
+ * Build the redirect route handler for a `to`/`status` pair. Substitutes any
+ * `:param` placeholders from `ctx.params` using the precompiled template.
+ *
+ * @param to - Target path/URL.
+ * @param status - Redirect status code.
+ * @returns A {@link RouteHandler} that sets `Location` and the status.
+ */
+export function createRedirectHandler(to: string, status: RedirectStatus): RouteHandler {
+  const compiledParts = compileRedirectTarget(to);
+
+  return (ctx: Context) => {
+    let targetPath: string;
+
+    if (compiledParts) {
+      const params = ctx.params;
+      const head = compiledParts[0];
+      if (head === undefined) {
+        targetPath = to;
+      } else {
+        let result = head;
+        for (let i = 1; i < compiledParts.length - 1; i += 2) {
+          const paramKey = compiledParts[i];
+          const tail = compiledParts[i + 1];
+          if (paramKey === undefined || tail === undefined) break;
+          result += (params[paramKey] ?? '') + tail;
+        }
+        targetPath = result;
+      }
+    } else {
+      targetPath = to;
+    }
+
+    ctx.status = status;
+    ctx.set('Location', targetPath);
+    ctx.body = '';
+  };
+}

package/src/registration.ts

@@ -0,0 +1,291 @@
+/**
+ * @nextrush/router - Route Registration
+ *
+ * Trie-insertion logic extracted from the `Router` class (T014, design.md D2 —
+ * D2 keeps HTTP-verb shortcuts (`get`/`post`/etc.) on `Router` itself, but
+ * explicitly permits extracting their shared internal, `addRoute`, "if
+ * `addRoute` itself is large enough to warrant it." At 116 lines and the
+ * highest cyclomatic/cognitive complexity in the file, it is.
+ *
+ * `addRoute` touches five pieces of `Router` instance state (the trie root,
+ * `caseSensitive`, the `hasParamRoutes` flag, the static-route hash map, and
+ * the introspection registry) as both reads and writes. All five are threaded
+ * explicitly rather than read/written through an implicit `this`, so this
+ * function has no hidden dependency on `Router` beyond what's passed in —
+ * same principle as the matching-engine extraction (design.md D1).
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import { HTTP_METHODS } from '@nextrush/types';
+import type {
+  HttpMethod,
+  MetadataContribution,
+  Middleware,
+  RouteDefinition,
+  RouteEntry,
+  RouteHandler,
+} from '@nextrush/types';
+import {
+  compileExecutor,
+  createNode,
+  NodeType,
+  parseSegments,
+  type HandlerEntry,
+  type StaticRouteMap,
+  type TrieNode,
+} from './segment-trie';
+import { mergeContributions, readContribution } from './route-metadata';
+import { createRedirectHandler, type RedirectStatus } from './redirect';
+
+/** Registration state `addRoute` reads, threaded explicitly. */
+export interface RegistrationState {
+  readonly root: TrieNode;
+  readonly caseSensitive: boolean;
+  readonly staticRoutes: StaticRouteMap;
+  readonly routeDefinitions: RouteDefinition[];
+}
+
+/**
+ * Normalize a route path at registration time: join the router prefix,
+ * collapse duplicate slashes, drop a trailing slash in non-strict mode, and
+ * guarantee a leading slash.
+ *
+ * @remarks
+ * This is registration-time normalization — it joins the router `prefix` and
+ * never case-folds (case handling belongs to trie insertion / matching). It is
+ * a distinct concern from `normalizePathForMatch` in `matching.ts`, which
+ * normalizes an *incoming request* path for lookup; both were extracted from
+ * `Router` to keep each single-definition (design.md D2/D3).
+ */
+export function normalizeRegistrationPath(path: string, prefix: string, strict: boolean): string {
+  // Handle prefix with trailing slash and path with leading slash
+  let joinedPrefix = prefix;
+  if (joinedPrefix.endsWith('/') && path.startsWith('/')) {
+    joinedPrefix = joinedPrefix.slice(0, -1);
+  }
+
+  let normalized = joinedPrefix + path;
+
+  // Fast-path: skip regex when no double slashes (99%+ of requests)
+  if (normalized.includes('//')) {
+    normalized = normalized.replace(/\/+/g, '/');
+  }
+
+  // For non-strict mode during registration, remove trailing slash
+  if (!strict && normalized.length > 1 && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized.startsWith('/') ? normalized : '/' + normalized;
+}
+
+/**
+ * Insert one route into the segment trie, updating every side structure
+ * (static-route fast-path map, introspection registry) that
+ * `Router.match`/`Router.getRoutes` depend on.
+ *
+ * @param normalized - Already-normalized path (caller applies `Router`'s own
+ *   prefix/strict-mode normalization before calling this — normalization
+ *   itself stays a `Router` method since it only touches `opts`, not the trie).
+ * @param recordIntrospection - When `false`, skips pushing this call's row
+ *   into `state.routeDefinitions` while still inserting the concrete
+ *   per-method trie handler (matching is completely unaffected either way).
+ *   `Router.all()` (T016) sets this to `false` on each of its 7 per-method
+ *   `addRoute` calls, then pushes exactly one consolidated
+ *   `isAnyMethod: true` row itself — so an any-method route yields a single
+ *   `getRoutes()` entry instead of one row per enumerated method, without
+ *   touching how any individual method is matched. Every other call site
+ *   (`get`/`post`/etc., `redirect`, sub-router mounting) omits this parameter
+ *   and keeps the original one-row-per-call behavior unchanged.
+ * @returns `true` if the registered route has a param or wildcard segment —
+ *   the caller (`Router.addRoute`) uses this to flip its own `hasParamRoutes`
+ *   flag. Returned rather than mutated through `state` because it's a
+ *   primitive: a struct field can't carry a boolean mutation back to the
+ *   caller by reference the way `root`/`staticRoutes`/`routeDefinitions` do.
+ */
+export function addRoute(
+  method: HttpMethod,
+  normalized: string,
+  entries: RouteEntry[],
+  middleware: Middleware[],
+  state: RegistrationState,
+  recordIntrospection = true
+): boolean {
+  const segments = parseSegments(normalized, state.caseSensitive);
+
+  let node = state.root;
+
+  for (const seg of segments) {
+    if (seg.type === NodeType.PARAM) {
+      if (!node.paramChild) {
+        node.paramChild = createNode(seg.segment, NodeType.PARAM);
+        node.paramChild.paramName = seg.paramName;
+      } else if (node.paramChild.paramName !== seg.paramName) {
+        // Same position, different param names — this silently loses one name
+        // at runtime (params[newName] is undefined), so fail fast at
+        // registration rather than warn (audit RT-5). Also removes the
+        // process.env / console.warn usage that was here.
+        throw new Error(
+          `Route param name conflict at "${normalized}": ":${String(seg.paramName)}" ` +
+            `conflicts with existing ":${String(node.paramChild.paramName)}" at the same ` +
+            `position. Use the same param name for this segment across all routes.`
+        );
+      }
+      node = node.paramChild;
+    } else if (seg.type === NodeType.WILDCARD) {
+      node.wildcardChild ??= createNode('*', NodeType.WILDCARD);
+      node = node.wildcardChild;
+      break; // Wildcard must be last
+    } else {
+      const key = seg.segment;
+      let child = node.children.get(key);
+      if (!child) {
+        child = createNode(seg.segment, NodeType.STATIC);
+        node.children.set(key, child);
+      }
+      node = child;
+    }
+  }
+
+  // Partition entries: functions are behavior (inline middleware + the final
+  // handler); pure markers (endpoint()) contribute metadata only and never
+  // execute. Every entry may also carry a metadata contribution (e.g. a
+  // function like validate() that both runs and contributes its schema).
+  const functions: Middleware[] = [];
+  const contributions: MetadataContribution[] = [];
+  for (const routeEntry of entries) {
+    const contribution = readContribution(routeEntry);
+    if (contribution) contributions.push(contribution);
+    if (typeof routeEntry === 'function') functions.push(routeEntry);
+  }
+
+  // Combine functions into a single handler with inline middleware
+  const combinedMiddleware = [...middleware];
+  const finalHandler: RouteHandler | undefined = functions[functions.length - 1];
+
+  if (!finalHandler) {
+    throw new Error('At least one handler is required');
+  }
+
+  // Inline middleware = every function before the last
+  for (let i = 0; i < functions.length - 1; i++) {
+    const fn = functions[i];
+    if (fn) combinedMiddleware.push(fn);
+  }
+
+  // Pre-compile executor at registration time (not per-request!)
+  const executor = compileExecutor(finalHandler, combinedMiddleware);
+
+  const handlerEntry: HandlerEntry = {
+    handler: finalHandler,
+    middleware: combinedMiddleware,
+    executor,
+  };
+
+  // Detect duplicate route registration
+  if (node.handlers.has(method)) {
+    throw new Error(
+      `Route conflict: ${method} ${normalized} is already registered. ` +
+        'Remove the duplicate or use a different path.'
+    );
+  }
+
+  node.handlers.set(method, handlerEntry);
+
+  // Populate static route hash map for O(1) lookup. Method-nested (HP-9): the
+  // outer map is keyed by method, the inner by the (lowercased, unless
+  // 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);
+    }
+    methodMap.set(normalizedKey, handlerEntry);
+  }
+
+  // Record in the introspection registry (side structure — never touched by
+  // request dispatch). key is the canonical `${METHOD} ${pathPattern}`. Skipped
+  // when the caller is consolidating multiple addRoute calls into a single row
+  // itself (Router.all(), T016) — the concrete trie handler above is still
+  // inserted regardless, so matching for this method is unaffected.
+  if (recordIntrospection) {
+    state.routeDefinitions.push({
+      key: `${method} ${normalized}`,
+      method,
+      path: normalized,
+      metadata: mergeContributions(contributions),
+    });
+  }
+
+  return hasParams;
+}
+
+/**
+ * Callback signature matching `Router['addRoute']` (the validating/
+ * normalizing wrapper, not the extracted `addRoute` above) — injected so
+ * `registerRedirect` doesn't need `Router` instance access, same pattern as
+ * `copyRoutes`'s `AddRouteFn` in `composition.ts`.
+ */
+export type RegisterRouteFn = (method: HttpMethod, path: string, entries: RouteEntry[]) => void;
+
+/**
+ * Register a redirect route from one path to another across every HTTP
+ * method the target status code requires (GET/HEAD always; POST/PUT/PATCH/
+ * DELETE additionally for 307/308, which must preserve the original method).
+ *
+ * Extracted from `Router.redirect()` — thematically closer to "register N
+ * routes for one call" than to composition or matching, and, like
+ * `copyRoutes`, only needs `addRoute` injected rather than full `Router`
+ * instance access.
+ */
+export function registerRedirect(
+  from: string,
+  to: string,
+  status: RedirectStatus,
+  addRoute: RegisterRouteFn
+): void {
+  const redirectHandler = createRedirectHandler(to, status);
+
+  // Register for common methods. 307/308 preserve the original method,
+  // so register all standard methods for those status codes.
+  addRoute('GET', from, [redirectHandler]);
+  addRoute('HEAD', from, [redirectHandler]);
+  if (status === 307 || status === 308) {
+    addRoute('POST', from, [redirectHandler]);
+    addRoute('PUT', from, [redirectHandler]);
+    addRoute('PATCH', from, [redirectHandler]);
+    addRoute('DELETE', from, [redirectHandler]);
+  }
+}
+
+/**
+ * Push a single consolidated any-method (`isAnyMethod: true`) introspection
+ * row (T016) into the registry.
+ *
+ * @remarks
+ * `Router.all()` / `GroupRouter.all()` insert one concrete per-method trie
+ * handler each (so every method still matches) with `recordIntrospection`
+ * off, then call this exactly once — so `getRoutes()` yields a single row per
+ * `.all()`/`@All()` route instead of one row per enumerated HTTP method,
+ * without changing how any individual method is matched.
+ *
+ * @param routeDefinitions - The router's introspection registry to append to.
+ * @param normalized - The already-normalized route path.
+ */
+export function pushAnyMethodDefinition(
+  routeDefinitions: RouteDefinition[],
+  normalized: string
+): void {
+  routeDefinitions.push({
+    key: `${HTTP_METHODS[0]} ${normalized}`,
+    method: HTTP_METHODS[0],
+    path: normalized,
+    isAnyMethod: true,
+  });
+}