@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.8a4d0430

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

@@ -60,7 +60,7 @@ export function invokeOnError<TEnv = any>(
   error: unknown,
   phase: ErrorPhase,
   context: InvokeOnErrorContext<TEnv>,
-  logPrefix: string = "Router"
+  logPrefix: string = "Router",
 ): void {
   if (!onError) return;
 
@@ -74,8 +74,8 @@ export function invokeOnError<TEnv = any>(
     phase,
     request: context.request,
     url: context.url,
-    pathname: context.url.pathname,
-    method: context.request.method,
+    pathname: context.url?.pathname,
+    method: context.request?.method,
     routeKey: context.routeKey,
     params: context.params,
     segmentId: context.segmentId,
@@ -112,7 +112,7 @@ export function invokeOnError<TEnv = any>(
  */
 export function findNearestErrorBoundary(
   entry: EntryData | null,
-  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
 ): ReactNode | ErrorBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -148,7 +148,7 @@ export function findNearestErrorBoundary(
  */
 export function findNearestNotFoundBoundary(
   entry: EntryData | null,
-  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
 ): ReactNode | NotFoundBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -172,7 +172,7 @@ export function findNearestNotFoundBoundary(
 export function createErrorInfo(
   error: unknown,
   segmentId: string,
-  segmentType: ErrorInfo["segmentType"]
+  segmentType: ErrorInfo["segmentType"],
 ): ErrorInfo {
   const isDev = process.env.NODE_ENV !== "production";
 
@@ -205,7 +205,7 @@ export function createErrorSegment(
   errorInfo: ErrorInfo,
   fallback: ReactNode | ErrorBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;
@@ -241,7 +241,7 @@ export function createNotFoundInfo(
   error: { message: string },
   segmentId: string,
   segmentType: NotFoundInfo["segmentType"],
-  pathname?: string
+  pathname?: string,
 ): NotFoundInfo {
   return {
     message: error.message,
@@ -259,7 +259,7 @@ export function createNotFoundSegment(
   notFoundInfo: NotFoundInfo,
   fallback: ReactNode | NotFoundBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;

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