@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/router/timeout.ts

@@ -0,0 +1,148 @@
+/**
+ * Router Timeout
+ *
+ * Types, resolution logic, and helpers for request-level timeouts.
+ * Timeouts wrap action execution and render-start phases with
+ * a Promise.race mechanism, returning 504 on expiry.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RouterTimeouts {
+  /** Timeout for server action execution (ms). */
+  actionMs?: number;
+  /** Timeout for initial render/response production (ms). */
+  renderStartMs?: number;
+  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  streamIdleMs?: number;
+}
+
+export type TimeoutPhase = "action" | "render-start" | "stream-idle";
+
+export interface TimeoutContext<TEnv = any> {
+  phase: TimeoutPhase;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routeKey?: string;
+  actionId?: string;
+  durationMs: number;
+}
+
+export type OnTimeoutCallback<TEnv = any> = (
+  ctx: TimeoutContext<TEnv>,
+) => Response | Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// Internal resolved form
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTimeouts {
+  actionMs: number | undefined;
+  renderStartMs: number | undefined;
+  streamIdleMs: number | undefined;
+}
+
+/**
+ * Merge the `timeout` shorthand with the structured `timeouts` object.
+ *
+ * - `timeout` applies to `actionMs` and `renderStartMs` (NOT `streamIdleMs`).
+ * - Explicit `timeouts.*` values override the shorthand.
+ * - Returns `undefined` for any phase that has no configured value.
+ */
+export function resolveTimeouts(
+  timeout?: number,
+  timeouts?: RouterTimeouts,
+): ResolvedTimeouts {
+  return {
+    actionMs: timeouts?.actionMs ?? timeout ?? undefined,
+    renderStartMs: timeouts?.renderStartMs ?? timeout ?? undefined,
+    streamIdleMs: timeouts?.streamIdleMs ?? undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class RouterTimeoutError extends Error {
+  override name = "RouterTimeoutError" as const;
+  phase: TimeoutPhase;
+  durationMs: number;
+
+  constructor(phase: TimeoutPhase, durationMs: number) {
+    super(
+      `Request timed out during ${phase} after ${Math.round(durationMs)}ms`,
+    );
+    this.phase = phase;
+    this.durationMs = durationMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Race helper
+// ---------------------------------------------------------------------------
+
+type TimeoutResult<T> =
+  | { result: T; timedOut: false }
+  | { timedOut: true; durationMs: number };
+
+/**
+ * Race an operation against a deadline.
+ *
+ * Returns a discriminated union so callers handle the timeout case
+ * without try/catch. Non-timeout errors from the operation re-throw.
+ *
+ * When `timeoutMs` is `undefined` or `<= 0`, the operation runs
+ * without any deadline (pass-through).
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number | undefined,
+  phase: TimeoutPhase,
+): Promise<TimeoutResult<T>> {
+  if (timeoutMs == null || timeoutMs <= 0) {
+    return { result: await operation, timedOut: false };
+  }
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout>;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new RouterTimeoutError(phase, performance.now() - start));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([operation, timeoutPromise]);
+    clearTimeout(timer!);
+    return { result, timedOut: false };
+  } catch (error) {
+    clearTimeout(timer!);
+    if (error instanceof RouterTimeoutError) {
+      return { timedOut: true, durationMs: error.durationMs };
+    }
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default response
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the default 504 response for a timed-out request.
+ * Includes `X-Rango-Timeout-Phase` header for observability.
+ */
+export function createDefaultTimeoutResponse(phase: TimeoutPhase): Response {
+  return new Response("Request timed out", {
+    status: 504,
+    headers: {
+      "Content-Type": "text/plain;charset=utf-8",
+      "X-Rango-Timeout-Phase": phase,
+    },
+  });
+}

package/src/router/trie-matching.ts

@@ -0,0 +1,244 @@
+/**
+ * Runtime Trie Matching
+ *
+ * Walks the pre-built trie by path segments in O(path_length) time.
+ * Falls back to null when no match is found (caller uses regex fallback).
+ */
+
+import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+
+export interface TrieMatchResult {
+  /** Route name */
+  routeKey: string;
+  /** Static prefix of the matched entry */
+  sp: string;
+  /** Matched route params */
+  params: Record<string, string>;
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
+  optionalParams?: string[];
+  /** Ancestry shortCodes for layout pruning */
+  ancestry: string[];
+  /** Redirect target if trailing slash requires it */
+  redirectTo?: string;
+  /** Route has pre-rendered data available */
+  pr?: true;
+  /** Passthrough: handler kept for live fallback on unknown params */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  responseType?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  /** RSC-first: RSC route was defined before response-type variants */
+  rscFirst?: true;
+}
+
+/**
+ * Try to match a pathname against the trie.
+ * Returns null if no match found (caller should fall back to regex).
+ */
+export function tryTrieMatch(
+  trie: TrieNode | null,
+  pathname: string,
+): TrieMatchResult | null {
+  if (!trie) return null;
+
+  // Split pathname into segments, filtering empty strings from leading/trailing slashes
+  const pathnameHasTrailingSlash =
+    pathname.length > 1 && pathname.endsWith("/");
+  const normalizedPath = pathnameHasTrailingSlash
+    ? pathname.slice(0, -1)
+    : pathname;
+
+  // Handle root path
+  if (normalizedPath === "" || normalizedPath === "/") {
+    if (trie.r) {
+      return validateAndBuild(
+        trie.r,
+        [],
+        undefined,
+        pathname,
+        pathnameHasTrailingSlash,
+      );
+    }
+    return null;
+  }
+
+  // Remove leading slash and split
+  const segments = normalizedPath.slice(1).split("/");
+
+  // Try exact match with normalized path (no trailing slash)
+  const result = walkTrie(trie, segments, 0, []);
+  if (result) {
+    return validateAndBuild(
+      result.leaf,
+      result.paramValues,
+      result.wildcardValue,
+      pathname,
+      pathnameHasTrailingSlash,
+    );
+  }
+
+  return null;
+}
+
+interface WalkResult {
+  leaf: TrieLeaf;
+  paramValues: string[];
+  wildcardValue?: string;
+}
+
+/**
+ * Walk the trie by segments with priority: static > param > wildcard.
+ * Uses backtracking to try all possible matches.
+ */
+function walkTrie(
+  node: TrieNode,
+  segments: string[],
+  index: number,
+  paramValues: string[],
+): WalkResult | null {
+  // All segments consumed: check for terminal
+  if (index === segments.length) {
+    if (node.r) {
+      return { leaf: node.r, paramValues: [...paramValues] };
+    }
+    return null;
+  }
+
+  const segment = segments[index];
+  const staticChild = node.s?.[segment];
+
+  // Priority 1: Static match
+  if (staticChild) {
+    const result = walkTrie(staticChild, segments, index + 1, paramValues);
+    if (result) return result;
+  }
+
+  // Priority 2: Suffix-param match (e.g., :productId.html)
+  if (node.xp) {
+    for (const suffix in node.xp) {
+      if (segment.endsWith(suffix) && segment.length > suffix.length) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // Priority 3: Param match
+  if (node.p) {
+    paramValues.push(segment);
+    const result = walkTrie(node.p.c, segments, index + 1, paramValues);
+    paramValues.pop();
+    if (result) return result;
+  }
+
+  // Priority 4: Wildcard match (consumes rest)
+  if (node.w) {
+    const rest = joinRemainingSegments(segments, index);
+    return {
+      leaf: node.w,
+      paramValues: [...paramValues],
+      wildcardValue: rest,
+    };
+  }
+
+  return null;
+}
+
+function joinRemainingSegments(segments: string[], start: number): string {
+  if (start >= segments.length) return "";
+
+  let rest = segments[start]!;
+  for (let i = start + 1; i < segments.length; i++) {
+    rest += "/" + segments[i]!;
+  }
+  return rest;
+}
+
+/**
+ * Post-match: validate constraints and handle trailing slash logic.
+ */
+function validateAndBuild(
+  leaf: TrieLeaf,
+  paramValues: string[],
+  wildcardValue: string | undefined,
+  originalPathname: string,
+  pathnameHasTrailingSlash: boolean,
+): TrieMatchResult | null {
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
+  const params: Record<string, string> = {};
+  if (leaf.pa) {
+    for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
+    }
+  }
+
+  // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
+  if (wildcardValue !== undefined && "pn" in leaf) {
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
+  }
+
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
+  if (leaf.cv) {
+    for (const paramName in leaf.cv) {
+      const allowed = leaf.cv[paramName]!;
+      const value = params[paramName];
+      if (value !== undefined && value !== "" && !allowed.includes(value)) {
+        return null;
+      }
+    }
+  }
+
+  // Optional params that weren't matched are left absent from `params` so
+  // `ctx.params.locale` reads as `undefined`, matching the
+  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
+  // internal consumers — the constraint check above and `reverse()` —
+  // already treat missing/undefined as the absent form.
+
+  // Trailing slash handling
+  const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
+  let redirectTo: string | undefined;
+
+  if (
+    tsMode === "always" &&
+    !pathnameHasTrailingSlash &&
+    originalPathname !== "/"
+  ) {
+    redirectTo = originalPathname + "/";
+  } else if (tsMode === "never" && pathnameHasTrailingSlash) {
+    redirectTo = originalPathname.slice(0, -1);
+  }
+
+  const result: TrieMatchResult = {
+    routeKey: leaf.n,
+    sp: leaf.sp,
+    params,
+    ancestry: leaf.a,
+  };
+
+  if (leaf.op) result.optionalParams = leaf.op;
+  if (redirectTo) result.redirectTo = redirectTo;
+  if (leaf.pr) result.pr = true;
+  if (leaf.pt) result.pt = true;
+  if (leaf.rt) result.responseType = leaf.rt;
+  if (leaf.nv) result.negotiateVariants = leaf.nv;
+  if (leaf.rf) result.rscFirst = true;
+
+  return result;
+}

package/src/router/types.ts

@@ -5,12 +5,21 @@
  */
 
 import type { ReactNode } from "react";
-import type { EntryData } from "../server/context";
 import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+} from "../server/context";
+import type {
+  ErrorInfo,
+  ErrorPhase,
+  LoaderDataResult,
   ResolvedSegment,
   HandlerContext,
+  InternalHandlerContext,
   ErrorBoundaryHandler,
   NotFoundBoundaryHandler,
+  ShouldRevalidateFn,
 } from "../types";
 
 /**
@@ -43,15 +52,89 @@ export type ActionContext = {
 
 /**
  * Dependencies passed to segment resolution functions
- * These are created within createRSCRouter and passed to extracted utilities
+ * These are created within createRouter and passed to extracted utilities
  */
 export interface RouterDependencies<TEnv> {
   findNearestErrorBoundary: (
-    entry: EntryData | null
+    entry: EntryData | null,
+  ) => ReactNode | ErrorBoundaryHandler | null;
+  findNearestNotFoundBoundary: (
+    entry: EntryData | null,
+  ) => ReactNode | NotFoundBoundaryHandler | null;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted segment resolution functions.
+ * These are the closure-bound helpers that cannot be imported directly.
+ */
+export interface SegmentResolutionDeps<TEnv = any> {
+  wrapLoaderPromise: <T>(
+    promise: Promise<T>,
+    entry: EntryData,
+    segmentId: string,
+    pathname: string,
+    errorContext?: {
+      request: Request;
+      url: URL;
+      routeKey?: string;
+      params?: Record<string, string>;
+      env?: TEnv;
+      isPartial?: boolean;
+      requestStartTime?: number;
+    },
+  ) => Promise<LoaderDataResult<T>>;
+  trackHandler: <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ) => Promise<T>;
+  findNearestErrorBoundary: (
+    entry: EntryData | null,
   ) => ReactNode | ErrorBoundaryHandler | null;
   findNearestNotFoundBoundary: (
-    entry: EntryData | null
+    entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
+  callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  /**
+   * Router-level default for the per-segment `transition({ viewTransition })`
+   * flag, from createRouter({ viewTransition }). Resolved into each segment's
+   * transition config during resolution (only `false` is stamped) so the render
+   * gate reads the boundary decision off the segment on both server and client.
+   * Undefined is treated as "auto" (wrap).
+   */
+  viewTransitionDefault?: "auto" | false;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted intercept resolution functions.
+ */
+export interface InterceptResolutionDeps<TEnv = any> {
+  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
+  evaluateInterceptWhen: (
+    intercept: InterceptEntry,
+    selectorContext: InterceptSelectorContext | null,
+    isAction: boolean,
+  ) => boolean;
+}
+
+/**
+ * Dependencies injected from createRouter closure into extracted match API functions.
+ */
+export interface MatchApiDeps<TEnv = any> {
+  findMatch: (pathname: string, ms?: any) => any;
+  getMetricsStore: () => any;
+  findInterceptForRoute: (
+    routeKey: string,
+    parentEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext | null,
+    isAction: boolean,
+  ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  callOnError: SegmentResolutionDeps<TEnv>["callOnError"];
+  findNearestErrorBoundary: SegmentResolutionDeps<TEnv>["findNearestErrorBoundary"];
+  getRouteMap: () => Record<string, string>;
 }
 
 /**

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}