@nextrush/router 3.0.7 → 4.0.0-beta.1

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,20 @@
  */
 
 // 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';
+// Canonical request path (RFC-029) — the single normalization owner shared by
+// the router's own match, mounted-router prefix tests, and any consumer that
+// needs to know "what path does the router treat this request as".
+export { canonicalizePath, hasDotSegment } from './canonicalize';
+export type { CanonicalPathResult } from './canonicalize';
+
+// 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,241 @@
+/**
+ * @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, NULL_PROTO } from './constants';
+import { matchNodeIndexed, collapseAndStrip, isProvablyLowerAscii } from './matching';
+import type { WalkPool } from './walk-pool';
+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[],
+  /**
+   * When `true`, `rawPath` is trusted as already the output of
+   * `canonicalizePath()` (same `caseSensitive`/`strict` options) — the fold
+   * and structural-collapse steps below are skipped entirely rather than
+   * re-derived. Only valid when the caller has actually run
+   * `canonicalizePath()` on this exact input first (F-10); the router's own
+   * `routes()` dispatch path is the only caller that does. Defaults to
+   * `false`, preserving every other caller's existing behavior — including
+   * `Router.match()`, which never canonicalizes first.
+   */
+  preNormalized = false,
+  /**
+   * When supplied, the param walk reuses this router instance's pooled
+   * `WalkFrame[]`/binding-array scratch space instead of allocating fresh
+   * arrays on this call (F-02, `reduce-router-match-allocations`). Omitted,
+   * `matchRoute` behaves exactly as before.
+   */
+  walkPool?: WalkPool
+): 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.
+  if (!preNormalized) {
+    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.
+  //
+  // F-10: when `preNormalized` is true, the caller already ran this exact
+  // fold+collapse via `canonicalizePath()` — trust `path` as both the
+  // normalized AND original-case string, skipping the fold+collapse
+  // re-derivation entirely rather than repeating work already done upstream.
+  let normalized: string;
+  let caseStable: boolean;
+  if (preNormalized) {
+    normalized = path;
+    caseStable = true;
+  } else {
+    caseStable = caseSensitive || isProvablyLowerAscii(path);
+    const folded = caseStable ? path : path.toLowerCase();
+    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`. Reused from the
+  // router's pool when supplied (F-02) instead of allocated fresh.
+  const bindNames: string[] = walkPool ? walkPool.bindNames : [];
+  const bindValues: string[] = walkPool ? walkPool.bindValues : [];
+  // A pooled bindNames/bindValues array persists across calls — clear any
+  // leftover entries from a prior match before this walk starts (the walk
+  // itself pops everything it pushes on a clean miss or match, but a defensive
+  // clear here costs nothing on the common empty case and closes any future
+  // edit that might leave a stale entry behind).
+  if (walkPool) {
+    bindNames.length = 0;
+    bindValues.length = 0;
+  }
+
+  const entry = matchNodeIndexed(
+    root,
+    normalized,
+    1, // Start after leading '/'
+    bindNames,
+    bindValues,
+    method,
+    decode,
+    originalPath,
+    walkPool
+  );
+  if (!entry) return null;
+
+  // Materialize params once on a bag whose prototype chain excludes
+  // `Object.prototype` (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`. Derived from
+  // `NULL_PROTO` rather than `Object.create(null)` so the object keeps V8 fast
+  // properties and handler reads stay inline-cacheable. 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_PROTO) 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.
+ *
+ * `walkPool` is the one field that is itself mutable (its contents, not the
+ * reference) — the reused `WalkFrame[]`/binding-array scratch space (F-02,
+ * `reduce-router-match-allocations`). It is `undefined` until the router has
+ * at least one param/wildcard route (no pool needed for a static-only router,
+ * per `createWalkPool(0)` never being called) and is rebuilt whenever the
+ * router's `maxDepth` grows past what the current pool was sized for — see
+ * `Router`'s own wiring, not this interface, for when that rebuild happens.
+ */
+export interface MatchState {
+  readonly root: TrieNode;
+  readonly staticRoutes: StaticRouteMap;
+  readonly caseSensitive: boolean;
+  readonly strict: boolean;
+  readonly decode: boolean;
+  readonly routerMiddleware: Middleware[];
+  walkPool?: WalkPool;
+}
+
+/**
+ * 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,
+  /**
+   * Forwarded to {@link matchRoute} — see its own doc comment for the
+   * caller contract. Defaults to `false`.
+   */
+  preNormalized = false
+): RouteMatch | null {
+  return matchRoute(
+    method,
+    path,
+    state.root,
+    state.staticRoutes,
+    hasParamRoutes,
+    state.caseSensitive,
+    state.strict,
+    state.decode,
+    state.routerMiddleware,
+    preNormalized,
+    state.walkPool
+  );
+}