@nextrush/router 3.0.6 → 4.0.0-beta.0

package/src/segment-trie.ts

@@ -0,0 +1,219 @@
+/**
+ * @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>;
+}
+
+/**
+ * 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,52 @@
+/**
+ * @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,
+  };
+}

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;
-}