@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/content-negotiation.ts

@@ -0,0 +1,116 @@
+/**
+ * Content Negotiation Utilities
+ *
+ * Pure functions for HTTP Accept header parsing and response type matching.
+ * Used by createRouter's previewMatch for content negotiation between
+ * RSC routes and response routes (JSON, text, image, stream, etc.).
+ */
+
+// Response type -> MIME type used for Accept header matching
+export const RESPONSE_TYPE_MIME: Record<string, string> = {
+  json: "application/json",
+  text: "text/plain",
+  xml: "application/xml",
+  html: "text/html",
+  md: "text/markdown",
+};
+
+// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
+export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
+  Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
+);
+
+export type NamedRouteEntry =
+  | string
+  | { path: string; search?: Record<string, string> };
+
+export function flattenNamedRoutes(
+  routeNames?: Record<string, NamedRouteEntry>,
+): Record<string, string> {
+  if (!routeNames) return {};
+  const flattened: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(routeNames)) {
+    flattened[name] = typeof entry === "string" ? entry : entry.path;
+  }
+  return flattened;
+}
+
+export interface AcceptEntry {
+  mime: string;
+  q: number;
+  order: number;
+}
+
+/**
+ * Parse an Accept header into a sorted array of MIME entries.
+ * Respects q-values (default 1.0) and uses client order as tiebreaker
+ * when q-values are equal (matching Express/Hono behavior).
+ */
+export function parseAcceptTypes(accept: string): AcceptEntry[] {
+  const entries: AcceptEntry[] = [];
+  const parts = accept.split(",");
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    const segments = part.split(";");
+    const mime = segments[0]!.trim().toLowerCase();
+    if (!mime) continue;
+    let q = 1.0;
+    for (let j = 1; j < segments.length; j++) {
+      const param = segments[j]!.trim();
+      if (param.startsWith("q=")) {
+        q = Math.max(0, Math.min(1, Number(param.slice(2)) || 0));
+      }
+    }
+    entries.push({ mime, q, order: i });
+  }
+  // Sort: highest q first, then lowest client order first (stable)
+  entries.sort((a, b) => b.q - a.q || a.order - b.order);
+  return entries;
+}
+
+// Sentinel response type for RSC routes in negotiation candidates
+export const RSC_RESPONSE_TYPE = "__rsc__";
+
+/**
+ * Pick the best negotiate variant by walking the client's sorted Accept list.
+ * For each accepted MIME type (in q-value/order priority), check if any
+ * candidate serves that type. Wildcards match the first candidate.
+ * Falls back to the first candidate if nothing matches.
+ */
+export function pickNegotiateVariant(
+  acceptEntries: AcceptEntry[],
+  candidates: Array<{ routeKey: string; responseType: string }>,
+): { routeKey: string; responseType: string } {
+  // Build a MIME -> candidate lookup for O(1) matching
+  const byCandidateMime = new Map<
+    string,
+    { routeKey: string; responseType: string }
+  >();
+  for (const c of candidates) {
+    const mime =
+      c.responseType === RSC_RESPONSE_TYPE
+        ? "text/html"
+        : RESPONSE_TYPE_MIME[c.responseType];
+    if (mime && !byCandidateMime.has(mime)) {
+      byCandidateMime.set(mime, c);
+    }
+  }
+
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    // Wildcard matches first candidate
+    if (entry.mime === "*/*") return candidates[0]!;
+    // Type wildcard (e.g. "text/*") -- match first candidate with that type
+    if (entry.mime.endsWith("/*")) {
+      const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
+      for (const [mime, candidate] of byCandidateMime) {
+        if (mime.startsWith(typePrefix + "/")) return candidate;
+      }
+      continue;
+    }
+    const match = byCandidateMime.get(entry.mime);
+    if (match) return match;
+  }
+  // No match -- use first candidate as default
+  return candidates[0]!;
+}

package/src/router/debug-manifest.ts

@@ -0,0 +1,72 @@
+import { type EntryData, getContext } from "../server/context";
+import { serializeManifest, type SerializedManifest } from "../debug.js";
+import { createRouteHelpers } from "../route-definition.js";
+import MapRootLayout from "../server/root-layout.js";
+import type { RouteEntry, TrailingSlashMode } from "../types";
+
+/**
+ * Build a serialized manifest from all route entries for debug inspection.
+ * Used by the `debugManifest()` method on the router instance.
+ */
+export async function buildDebugManifest<TEnv = any>(
+  routesEntries: RouteEntry<TEnv>[],
+): Promise<SerializedManifest> {
+  const manifest = new Map<string, EntryData>();
+
+  for (const entry of routesEntries) {
+    const Store = {
+      manifest,
+      namespace: `debug.M${entry.mountIndex}`,
+      parent: null as EntryData | null,
+      counters: {} as Record<string, number>,
+      mountIndex: entry.mountIndex,
+      patterns: new Map<string, string>(),
+      trailingSlash: new Map<string, TrailingSlashMode>(),
+    };
+
+    await getContext().runWithStore(
+      Store,
+      `debug.M${entry.mountIndex}`,
+      null,
+      async () => {
+        const helpers = createRouteHelpers();
+
+        // Wrap handler execution in root layout (same as loadManifest)
+        let promiseResult: Promise<any> | null = null;
+        helpers.layout(MapRootLayout, () => {
+          const result = entry.handler();
+          if (result instanceof Promise) {
+            promiseResult = result;
+            return [];
+          }
+          return result;
+        });
+
+        if (promiseResult !== null) {
+          const load = await (promiseResult as Promise<any>);
+          if (load && typeof load === "object" && "default" in load) {
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
+            }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
+          }
+        }
+      },
+    );
+  }
+
+  return serializeManifest(manifest);
+}

package/src/router/error-handling.ts

@@ -0,0 +1,287 @@
+/**
+ * Router Error Handling Utilities
+ *
+ * Error boundary and not-found boundary handling for RSC Router.
+ * Also includes the shared invokeOnError utility for error callback invocation.
+ */
+
+import type { ReactNode } from "react";
+import type { EntryData } from "../server/context";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  ErrorBoundaryHandler,
+  ErrorBoundaryFallbackProps,
+  NotFoundInfo,
+  NotFoundBoundaryHandler,
+  NotFoundBoundaryFallbackProps,
+  ErrorPhase,
+  OnErrorCallback,
+  OnErrorContext,
+} from "../types";
+
+/**
+ * Context required to invoke the onError callback.
+ * This is a subset of OnErrorContext that callers must provide.
+ */
+export interface InvokeOnErrorContext<TEnv = any> {
+  request: Request;
+  url: URL;
+  routeKey?: string;
+  params?: Record<string, string>;
+  segmentId?: string;
+  segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
+  loaderName?: string;
+  middlewareId?: string;
+  actionId?: string;
+  env?: TEnv;
+  isPartial?: boolean;
+  handledByBoundary?: boolean;
+  metadata?: Record<string, unknown>;
+  /** Request start time from performance.now() for duration calculation */
+  requestStartTime?: number;
+}
+
+/**
+ * Invoke the onError callback with comprehensive context.
+ * Catches any errors in the callback itself to prevent masking the original error.
+ *
+ * This is a shared utility used by both the router and RSC handler to ensure
+ * consistent error callback behavior across the codebase.
+ *
+ * @param onError - The onError callback to invoke (may be undefined)
+ * @param error - The error that occurred
+ * @param phase - The phase where the error occurred
+ * @param context - Additional context about the error
+ * @param logPrefix - Prefix for console.error messages (e.g., "Router" or "RSC")
+ */
+export function invokeOnError<TEnv = any>(
+  onError: OnErrorCallback<TEnv> | undefined,
+  error: unknown,
+  phase: ErrorPhase,
+  context: InvokeOnErrorContext<TEnv>,
+  logPrefix: string = "Router",
+): void {
+  if (!onError) return;
+
+  const errorObj = error instanceof Error ? error : new Error(String(error));
+  const duration = context.requestStartTime
+    ? performance.now() - context.requestStartTime
+    : undefined;
+
+  const errorContext: OnErrorContext<TEnv> = {
+    error: errorObj,
+    phase,
+    request: context.request,
+    url: context.url,
+    pathname: context.url?.pathname,
+    method: context.request?.method,
+    routeKey: context.routeKey,
+    params: context.params,
+    segmentId: context.segmentId,
+    segmentType: context.segmentType,
+    loaderName: context.loaderName,
+    middlewareId: context.middlewareId,
+    actionId: context.actionId,
+    env: context.env,
+    duration,
+    isPartial: context.isPartial,
+    handledByBoundary: context.handledByBoundary,
+    stack: errorObj.stack,
+    metadata: context.metadata,
+  };
+
+  try {
+    const result = onError(errorContext);
+    // If onError returns a promise, catch any rejections
+    if (result instanceof Promise) {
+      result.catch((callbackError) => {
+        console.error(`[${logPrefix}.onError] Callback error:`, callbackError);
+      });
+    }
+  } catch (callbackError) {
+    // Log but don't throw - we don't want callback errors to mask the original error
+    console.error(`[${logPrefix}.onError] Callback error:`, callbackError);
+  }
+}
+
+/**
+ * Find the nearest error boundary by walking up the entry chain
+ * Also checks sibling layouts (orphan layouts) for error boundaries
+ * Returns the first fallback found, or the default error boundary if configured
+ */
+export function findNearestErrorBoundary(
+  entry: EntryData | null,
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
+): ReactNode | ErrorBoundaryHandler | null {
+  let current: EntryData | null = entry;
+
+  while (current) {
+    // Check if this entry has error boundaries defined
+    if (current.errorBoundary && current.errorBoundary.length > 0) {
+      // Return the last error boundary (most recently defined takes precedence)
+      return current.errorBoundary[current.errorBoundary.length - 1];
+    }
+
+    // Check orphan layouts for error boundaries
+    // Orphan layouts are siblings that render alongside the main route chain
+    // They can define error boundaries that catch errors from routes in the same route group
+    // Check from first to last (first sibling takes precedence as the "outer" wrapper)
+    if (current.layout && current.layout.length > 0) {
+      for (const orphan of current.layout) {
+        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
+          return orphan.errorBoundary[orphan.errorBoundary.length - 1];
+        }
+      }
+    }
+
+    current = current.parent;
+  }
+
+  // Return default error boundary if configured
+  return defaultErrorBoundary || null;
+}
+
+/**
+ * Find the nearest notFound boundary by walking up the entry chain
+ * Returns the first fallback found, or the default notFound boundary if configured
+ */
+export function findNearestNotFoundBoundary(
+  entry: EntryData | null,
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
+): ReactNode | NotFoundBoundaryHandler | null {
+  let current: EntryData | null = entry;
+
+  while (current) {
+    // Check if this entry has notFound boundaries defined
+    if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
+      // Return the last notFound boundary (most recently defined takes precedence)
+      return current.notFoundBoundary[current.notFoundBoundary.length - 1];
+    }
+    current = current.parent;
+  }
+
+  // Return default notFound boundary if configured
+  return defaultNotFoundBoundary || null;
+}
+
+/**
+ * Create ErrorInfo from an error object
+ * Sanitizes error details in production
+ */
+export function createErrorInfo(
+  error: unknown,
+  segmentId: string,
+  segmentType: ErrorInfo["segmentType"],
+): ErrorInfo {
+  const isDev = process.env.NODE_ENV !== "production";
+
+  if (error instanceof Error) {
+    return {
+      message: isDev ? error.message : "An error occurred",
+      name: error.name,
+      code: (error as any).code,
+      stack: isDev ? error.stack : undefined,
+      cause: isDev ? error.cause : undefined,
+      segmentId,
+      segmentType,
+    };
+  }
+
+  // Non-Error thrown
+  return {
+    message: isDev ? String(error) : "An error occurred",
+    name: "Error",
+    segmentId,
+    segmentType,
+  };
+}
+
+/**
+ * Create an error segment with the fallback component
+ * Renders the fallback with error info and reset function
+ */
+export function createErrorSegment(
+  errorInfo: ErrorInfo,
+  fallback: ReactNode | ErrorBoundaryHandler,
+  entry: EntryData,
+  params: Record<string, string>,
+): ResolvedSegment {
+  // Determine the component to render
+  let component: ReactNode;
+
+  if (typeof fallback === "function") {
+    // ErrorBoundaryHandler - call with error info
+    const props: ErrorBoundaryFallbackProps = {
+      error: errorInfo,
+    };
+    component = fallback(props);
+  } else {
+    // Static ReactNode fallback
+    component = fallback;
+  }
+
+  // Error segment uses the same ID as the layout that has the error boundary
+  // The error boundary content replaces the layout's outlet content
+  return {
+    id: entry.shortCode,
+    namespace: entry.id,
+    type: "error",
+    index: 0,
+    component,
+    params,
+    error: errorInfo,
+  };
+}
+
+/**
+ * Create NotFoundInfo from a DataNotFoundError
+ */
+export function createNotFoundInfo(
+  error: { message: string },
+  segmentId: string,
+  segmentType: NotFoundInfo["segmentType"],
+  pathname?: string,
+): NotFoundInfo {
+  return {
+    message: error.message,
+    segmentId,
+    segmentType,
+    pathname,
+  };
+}
+
+/**
+ * Create a notFound segment with the fallback component
+ * Renders the fallback with not found info
+ */
+export function createNotFoundSegment(
+  notFoundInfo: NotFoundInfo,
+  fallback: ReactNode | NotFoundBoundaryHandler,
+  entry: EntryData,
+  params: Record<string, string>,
+): ResolvedSegment {
+  // Determine the component to render
+  let component: ReactNode;
+
+  if (typeof fallback === "function") {
+    // NotFoundBoundaryHandler - call with props
+    const props: NotFoundBoundaryFallbackProps = {
+      notFound: notFoundInfo,
+    };
+    component = fallback(props);
+  } else {
+    // Static ReactNode fallback
+    component = fallback;
+  }
+
+  return {
+    id: `${entry.shortCode}.notFound`,
+    namespace: entry.id,
+    type: "notFound",
+    index: 0,
+    component,
+    params,
+    notFoundInfo,
+  };
+}

package/src/router/find-match.ts

@@ -0,0 +1,158 @@
+import { tryTrieMatch } from "./trie-matching.js";
+import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import {
+  findMatch as findRouteMatch,
+  isLazyEvaluationNeeded,
+  type RouteMatchResult,
+} from "./pattern-matching.js";
+import type { MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+
+export interface FindMatchDeps<TEnv = any> {
+  routesEntries: RouteEntry<TEnv>[];
+  evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
+  routerId: string;
+}
+
+/**
+ * Create a findMatch function bound to router state.
+ * Includes single-entry cache to avoid redundant matching within the same request.
+ */
+export function createFindMatch<TEnv = any>(
+  deps: FindMatchDeps<TEnv>,
+): (pathname: string, ms?: MetricsStore) => RouteMatchResult<TEnv> | null {
+  // Single-entry cache for findMatch to avoid redundant matching within the same request.
+  // previewMatch and match both call findMatch with the same pathname — this ensures
+  // the route matching work (which may check thousands of routes) only happens once.
+  let lastFindMatchPathname: string | null = null;
+  let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
+
+  // Wrapper for findMatch that uses routesEntries
+  // Handles lazy evaluation by evaluating lazy entries on first match.
+  // Phase 1: try O(path_length) trie match.
+  // Phase 2: fall back to regex iteration.
+  return function findMatch(
+    pathname: string,
+    ms?: MetricsStore,
+  ): RouteMatchResult<TEnv> | null {
+    // Return cached result if same pathname (avoids double-match per request)
+    if (lastFindMatchPathname === pathname) {
+      return lastFindMatchResult;
+    }
+
+    // Helper to push sub-metrics
+    const pushMetric = ms
+      ? (label: string, start: number) => {
+          ms.metrics.push({
+            label,
+            duration: performance.now() - start,
+            startTime: start - ms.requestStart,
+          });
+        }
+      : undefined;
+
+    // Phase 1: Try trie match (O(path_length))
+    // Prefer per-router trie (isolated) over global trie (merged).
+    const routeTrie = getRouterTrie(deps.routerId) ?? getRouteTrie();
+    if (routeTrie) {
+      const trieStart = performance.now();
+      const trieResult = tryTrieMatch(routeTrie, pathname);
+      pushMetric?.("match:trie", trieStart);
+
+      if (trieResult) {
+        // Find the RouteEntry that contains this route.
+        // Multiple entries can share the same staticPrefix (e.g., several
+        // include("/", patterns) calls all produce staticPrefix=""). Evaluate
+        // each candidate and pick the one whose routes include the matched key.
+        const entryStart = performance.now();
+        let entry: RouteEntry<TEnv> | undefined;
+        let fallbackEntry: RouteEntry<TEnv> | undefined;
+
+        for (const e of deps.routesEntries) {
+          if (e.staticPrefix !== trieResult.sp) continue;
+          if (!fallbackEntry) fallbackEntry = e;
+          deps.evaluateLazyEntry(e);
+          if (
+            e.routes &&
+            trieResult.routeKey in (e.routes as Record<string, unknown>)
+          ) {
+            entry = e;
+            break;
+          }
+        }
+
+        // If no entry had the route in its routes map, use the first matching
+        // entry as fallback (handles main entry with inline routes not yet
+        // reflected in its routes object).
+        if (!entry) entry = fallbackEntry;
+
+        // If entry not found (nested include not yet discovered), evaluate parent
+        if (!entry) {
+          const parent = deps.routesEntries.find(
+            (e) =>
+              trieResult.sp.startsWith(e.staticPrefix) &&
+              e.staticPrefix !== trieResult.sp,
+          );
+          if (parent) {
+            const lazyStart = performance.now();
+            deps.evaluateLazyEntry(parent);
+            pushMetric?.("match:lazy-eval", lazyStart);
+          }
+          entry = deps.routesEntries.find(
+            (e) => e.staticPrefix === trieResult.sp,
+          );
+        }
+        pushMetric?.("match:entry-resolve", entryStart);
+
+        if (entry) {
+          lastFindMatchPathname = pathname;
+          lastFindMatchResult = {
+            entry,
+            routeKey: trieResult.routeKey,
+            params: trieResult.params,
+            optionalParams: new Set(trieResult.optionalParams || []),
+            redirectTo: trieResult.redirectTo,
+            ancestry: trieResult.ancestry,
+            ...(trieResult.pr ? { pr: true } : {}),
+            ...(trieResult.pt ? { pt: true } : {}),
+            ...(trieResult.responseType
+              ? { responseType: trieResult.responseType }
+              : {}),
+            ...(trieResult.negotiateVariants
+              ? { negotiateVariants: trieResult.negotiateVariants }
+              : {}),
+            ...(trieResult.rscFirst ? { rscFirst: true } : {}),
+          };
+          return lastFindMatchResult;
+        }
+      }
+    }
+
+    // Phase 2: Fall back to existing matching (regex iteration)
+    const regexStart = performance.now();
+    let result = findRouteMatch(pathname, deps.routesEntries);
+
+    // If we hit a lazy entry that needs evaluation, evaluate and retry.
+    // Cap iterations to prevent infinite loops from pathological nesting.
+    const MAX_LAZY_ITERATIONS = 100;
+    let iterations = 0;
+    while (isLazyEvaluationNeeded(result)) {
+      if (++iterations > MAX_LAZY_ITERATIONS) {
+        console.error(
+          `[@rangojs/router] Exceeded ${MAX_LAZY_ITERATIONS} lazy evaluation iterations ` +
+            `for pathname "${pathname}". This likely indicates circular lazy includes.`,
+        );
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
+      }
+      deps.evaluateLazyEntry(result.lazyEntry);
+      result = findRouteMatch(pathname, deps.routesEntries);
+    }
+    pushMetric?.("match:regex-fallback", regexStart);
+
+    lastFindMatchPathname = pathname;
+    lastFindMatchResult = result;
+    return result;
+  };
+}