@rangojs/router 0.0.0-experimental.63 → 0.0.0-experimental.64

package/src/router/match-api.ts

@@ -36,7 +36,14 @@ import {
   setRequestContextPrevRouteKey,
 } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 import { debugLog, debugWarn } from "./logging.js";
+import {
+  resolveRoute,
+  ensureFullRouteSnapshot,
+  type RouteSnapshot,
+} from "./route-snapshot.js";
+import { resolveNavigation } from "./navigation-snapshot.js";
 
 /**
  * Create match context for full requests (document/SSR).
@@ -52,54 +59,36 @@ export async function createMatchContextForFull<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const matched = deps.findMatch(pathname, metricsStore);
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
-  }
+  // Full renders always resolve fresh with isSSR: true because loadManifest
+  // keys its cache on isSSR and stamps Store.isSSR for downstream behavior.
+  const result = await resolveRoute<TEnv>(pathname, {
+    findMatch: (p) => deps.findMatch(p, metricsStore),
+    metricsStore,
+    isSSR: true,
+  });
 
-  if (!matched) {
+  if (!result) {
     throw new RouteNotFoundError(`No route matched for ${pathname}`, {
       cause: { pathname, method: request.method },
     });
   }
 
-  if (matched.redirectTo) {
+  if (result.type === "redirect") {
     return {
       type: "redirect",
-      redirectUrl: matched.redirectTo + url.search,
+      redirectUrl: result.redirectTo + url.search,
     };
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    true,
-  );
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
-    });
-  }
+  const snapshot = result.snapshot;
 
-  if (manifestEntry.type === "route" && manifestEntry.isPassthrough === true) {
+  const { matched } = snapshot;
+
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
     matched.pt = true;
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -131,14 +120,6 @@ export async function createMatchContextForFull<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
-  }
-
   return {
     request,
     url: cleanUrl,
@@ -151,12 +132,10 @@ export async function createMatchContextForFull<TEnv>(
     prevParams: {},
     prevMatch: null,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName: matched.routeKey.includes(".")
-      ? matched.routeKey.split(".").pop()!
-      : matched.routeKey,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
@@ -172,16 +151,16 @@ export async function createMatchContextForFull<TEnv>(
       segments: { path: [], ids: [] },
       toRouteName:
         matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-          ? matched.routeKey
+          ? (matched.routeKey as DefaultRouteName)
           : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: true,
   };
 }
@@ -201,100 +180,85 @@ export async function createMatchContextForPartial<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const clientSegmentIds =
-    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
-  const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl =
-    request.headers.get("X-RSC-Router-Client-Path") ||
-    request.headers.get("Referer");
-  const interceptSourceUrl = request.headers.get(
-    "X-RSC-Router-Intercept-Source",
-  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
 
   // HMR: clear manifest cache so stale handler references are discarded
-  if (request.headers.get("X-RSC-HMR")) {
+  if (isHmr) {
     clearManifestCache();
   }
 
-  if (!previousUrl) {
-    return null;
-  }
-
-  let prevUrl: URL;
-  try {
-    prevUrl = new URL(previousUrl, url.origin);
-  } catch {
-    return null;
-  }
+  // Reuse the classified snapshot when available and not invalidated by HMR.
+  // classifyRequest already called resolveRoute(lite) with isSSR=false, which
+  // matches the partial path. On HMR, discard to pick up manifest changes.
+  const classifiedRoute = isHmr
+    ? undefined
+    : getRequestContext()?._classifiedRoute;
+
+  // Time route matching. On the reuse path, only nav findMatch calls are new
+  // (current-route findMatch and manifest-loading were already timed during
+  // classifyRequest via its metricsStore). On the fresh path, all findMatch
+  // calls are measured together.
+  const routeMatchStart = metricsStore ? performance.now() : 0;
 
-  let interceptContextUrl: URL;
-  try {
-    interceptContextUrl = interceptSourceUrl
-      ? new URL(interceptSourceUrl, url.origin)
-      : prevUrl;
-  } catch {
-    interceptContextUrl = prevUrl;
-  }
+  let snapshot: RouteSnapshot<TEnv>;
+  if (classifiedRoute && classifiedRoute.manifestEntry) {
+    snapshot = ensureFullRouteSnapshot(classifiedRoute);
+  } else {
+    const result = await resolveRoute<TEnv>(pathname, {
+      findMatch: (p) => deps.findMatch(p, metricsStore),
+      metricsStore,
+      isSSR: false,
+      skipRouteMatchMetric: true,
+    });
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const prevMatch = deps.findMatch(prevUrl.pathname);
-  const prevParams = prevMatch?.params || {};
-  const interceptContextMatch = interceptSourceUrl
-    ? deps.findMatch(interceptContextUrl.pathname)
-    : prevMatch;
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
 
-  const matched = deps.findMatch(pathname, metricsStore);
+    if (result.type === "redirect") {
+      return null;
+    }
 
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
+    snapshot = result.snapshot;
   }
 
-  if (!matched) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method, previousUrl },
-    });
-  }
+  const { matched } = snapshot;
 
-  if (matched.redirectTo) {
-    return null;
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
+    matched.pt = true;
   }
 
-  if (prevMatch && prevMatch.entry !== matched.entry && !matched.pr) {
-    debugLog("matchPartial", "route group changed", {
-      from: prevMatch.routeKey,
-      to: matched.routeKey,
-    });
+  // Navigation state (prev + intercept-source findMatch calls)
+  const nav = resolveNavigation(request, url, matched.routeKey, {
+    findMatch: deps.findMatch,
+  });
+  if (!nav) {
+    return null;
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    false,
-  );
+  // Push route-matching metric. On the fresh path this covers all findMatch
+  // calls (current + prev + intercept-source). On the reuse path, current-route
+  // findMatch was already timed during classification, so this only covers
+  // the nav lookups (prev + intercept-source).
   if (metricsStore) {
+    const isReuse = !!classifiedRoute;
     metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
+      label: isReuse ? "route-matching:nav" : "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
     });
   }
 
-  if (manifestEntry.type === "route" && manifestEntry.isPassthrough === true) {
-    matched.pt = true;
+  if (nav.prevMatch && nav.prevMatch.entry !== matched.entry && !matched.pr) {
+    debugLog("matchPartial", "route group changed", {
+      from: nav.prevMatch.routeKey,
+      to: matched.routeKey,
+    });
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -311,9 +275,8 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt === true,
   );
 
-  const clientSegmentSet = new Set(clientSegmentIds);
   debugLog("matchPartial", "client segments", {
-    segments: Array.from(clientSegmentSet),
+    segments: Array.from(nav.clientSegmentSet),
   });
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -331,100 +294,78 @@ export async function createMatchContextForPartial<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const isSameRouteNavigation = !!(
-    interceptContextMatch && interceptContextMatch.routeKey === matched.routeKey
-  );
-
-  if (interceptSourceUrl) {
+  if (nav.hasInterceptSource) {
     debugLog("matchPartial.intercept", "intercept context detected", {
       currentUrl: pathname,
-      interceptSource: interceptSourceUrl,
-      contextRoute: interceptContextMatch?.routeKey,
+      interceptSource: nav.interceptContextUrl.href,
+      contextRoute: nav.interceptContextMatch?.routeKey,
       currentRoute: matched.routeKey,
-      sameRouteNavigation: isSameRouteNavigation,
+      sameRouteNavigation: nav.isSameRouteNavigation,
     });
   }
 
-  const localRouteName = matched.routeKey.includes(".")
-    ? matched.routeKey.split(".").pop()!
-    : matched.routeKey;
-
-  const filteredSegmentIds = clientSegmentIds.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
-  const effectiveFromUrl = interceptSourceUrl ? interceptContextUrl : prevUrl;
-  const effectiveFromMatch = interceptSourceUrl
-    ? interceptContextMatch
-    : prevMatch;
-
   // Store previous route key on the request context for revalidation
   // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
   // see the intercept origin route, not the plain previous URL route.
-  setRequestContextPrevRouteKey(effectiveFromMatch?.routeKey);
+  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
 
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: effectiveFromUrl,
+    from: nav.effectiveFromUrl,
     to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: effectiveFromUrl.pathname.split("/").filter(Boolean),
-      ids: filteredSegmentIds,
+      path: nav.effectiveFromUrl.pathname.split("/").filter(Boolean),
+      ids: nav.filteredSegmentIds,
     },
     fromRouteName:
-      effectiveFromMatch?.routeKey &&
-      !isAutoGeneratedRouteName(effectiveFromMatch.routeKey)
-        ? effectiveFromMatch.routeKey
+      nav.effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(nav.effectiveFromMatch.routeKey)
+        ? (nav.effectiveFromMatch.routeKey as DefaultRouteName)
         : undefined,
     toRouteName:
       matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-        ? matched.routeKey
+        ? (matched.routeKey as DefaultRouteName)
         : undefined,
   };
   const isAction = !!actionContext;
 
-  const clientHasInterceptSegments = [...clientSegmentSet].some((id) =>
+  const clientHasInterceptSegments = [...nav.clientSegmentSet].some((id) =>
     id.includes(".@"),
   );
   const skipInterceptForAction = isAction && !clientHasInterceptSegments;
   const interceptResult =
-    isSameRouteNavigation || skipInterceptForAction
+    nav.isSameRouteNavigation || skipInterceptForAction
       ? null
       : findInterceptForRoute(
           matched.routeKey,
-          manifestEntry.parent,
+          snapshot.manifestEntry.parent,
           interceptSelectorContext,
           isAction,
         ) ||
-        (localRouteName !== matched.routeKey
+        (snapshot.localRouteName !== matched.routeKey
           ? findInterceptForRoute(
-              localRouteName,
-              manifestEntry.parent,
+              snapshot.localRouteName,
+              snapshot.manifestEntry.parent,
               interceptSelectorContext,
               isAction,
             )
           : null);
 
+  // Make a mutable copy of clientSegmentSet so we can delete entries
+  // for same-route navigation forcing
+  const clientSegmentSet = new Set(nav.clientSegmentSet);
+
   if (
-    isSameRouteNavigation &&
-    manifestEntry.type === "route" &&
-    interceptSourceUrl
+    nav.isSameRouteNavigation &&
+    snapshot.manifestEntry.type === "route" &&
+    nav.hasInterceptSource
   ) {
     debugLog("matchPartial.intercept", "forcing route segment render", {
-      segmentId: manifestEntry.shortCode,
+      segmentId: snapshot.manifestEntry.shortCode,
     });
-    clientSegmentSet.delete(manifestEntry.shortCode);
-  }
-
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
+    clientSegmentSet.delete(snapshot.manifestEntry.shortCode);
   }
 
   const isIntercept = !!interceptResult;
@@ -434,31 +375,31 @@ export async function createMatchContextForPartial<TEnv>(
     url: cleanUrl,
     pathname,
     env,
-    clientSegmentIds,
+    clientSegmentIds: nav.clientSegmentIds,
     clientSegmentSet,
-    stale,
-    prevUrl,
-    prevParams,
-    prevMatch,
+    stale: nav.stale,
+    prevUrl: nav.prevUrl,
+    prevParams: nav.prevParams,
+    prevMatch: nav.prevMatch,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
     metricsStore,
     Store,
-    interceptContextMatch,
+    interceptContextMatch: nav.interceptContextMatch,
     interceptSelectorContext,
-    isSameRouteNavigation,
+    isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept,
     actionContext,
     isAction,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: false,
   };
 }

package/src/router/navigation-snapshot.ts

@@ -0,0 +1,182 @@
+/**
+ * Navigation Snapshot
+ *
+ * Pure data type representing the navigation-specific state for partial requests.
+ * Consolidates the header parsing, previous-route matching, intercept-context
+ * detection, and segment ID filtering that previously lived inline in
+ * createMatchContextForPartial (match-api.ts).
+ *
+ * resolveNavigation() is the factory: given a request + URL + current route key,
+ * it returns a NavigationSnapshot (or null if no previous URL).
+ */
+
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Snapshot of navigation state for a partial (navigation/action) request.
+ *
+ * Contains the "where are we coming from?" data: previous route, intercept
+ * source, client segment state, and derived flags.
+ */
+export interface NavigationSnapshot {
+  /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
+  prevUrl: URL;
+  /** Params from the previous route match */
+  prevParams: Record<string, string>;
+  /** Previous route match result (null if prev URL doesn't match any route) */
+  prevMatch: RouteMatchResult | null;
+
+  /** URL used as intercept context source */
+  interceptContextUrl: URL;
+  /** Route match for the intercept context URL */
+  interceptContextMatch: RouteMatchResult | null;
+
+  /** Raw segment IDs the client currently has */
+  clientSegmentIds: string[];
+  /** Set version for O(1) lookup */
+  clientSegmentSet: Set<string>;
+  /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
+  filteredSegmentIds: string[];
+
+  /** Whether client considers its cache stale */
+  stale: boolean;
+
+  /** Whether the intercept context route is the same as the current route */
+  isSameRouteNavigation: boolean;
+
+  /** Effective "from" URL (intercept source URL when present, else prevUrl) */
+  effectiveFromUrl: URL;
+  /** Effective "from" match (intercept source match when present, else prevMatch) */
+  effectiveFromMatch: RouteMatchResult | null;
+
+  /** Whether an intercept source header was present */
+  hasInterceptSource: boolean;
+
+  /** Whether an HMR request header was present */
+  isHmr: boolean;
+}
+
+export interface ResolveNavigationDeps {
+  findMatch: (pathname: string) => RouteMatchResult | null;
+}
+
+/**
+ * Resolve navigation state from a partial request.
+ *
+ * Returns null if no previous URL is available (required for partial navigation).
+ *
+ * @param request - The incoming HTTP request
+ * @param url - Parsed URL of the request
+ * @param currentRouteKey - Route key of the current (target) route match
+ * @param deps - Dependencies (findMatch)
+ */
+export function resolveNavigation(
+  request: Request,
+  url: URL,
+  currentRouteKey: string,
+  deps: ResolveNavigationDeps,
+): NavigationSnapshot | null {
+  // Parse client state from RSC request params/headers
+  const clientSegmentIds =
+    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
+  const stale = url.searchParams.get("_rsc_stale") === "true";
+  const previousUrl =
+    request.headers.get("X-RSC-Router-Client-Path") ||
+    request.headers.get("Referer");
+  const interceptSourceUrl = request.headers.get(
+    "X-RSC-Router-Intercept-Source",
+  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
+
+  if (!previousUrl) {
+    return null;
+  }
+
+  // Parse previous URL
+  let prevUrl: URL;
+  try {
+    prevUrl = new URL(previousUrl, url.origin);
+  } catch {
+    return null;
+  }
+
+  // Parse intercept context URL
+  let interceptContextUrl: URL;
+  try {
+    interceptContextUrl = interceptSourceUrl
+      ? new URL(interceptSourceUrl, url.origin)
+      : prevUrl;
+  } catch {
+    interceptContextUrl = prevUrl;
+  }
+
+  // Match previous and intercept context routes
+  const prevMatch = deps.findMatch(prevUrl.pathname);
+  const prevParams = prevMatch?.params || {};
+  const interceptContextMatch = interceptSourceUrl
+    ? deps.findMatch(interceptContextUrl.pathname)
+    : prevMatch;
+
+  // Derived state
+  const isSameRouteNavigation = !!(
+    interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
+  );
+
+  const hasInterceptSource = !!interceptSourceUrl;
+  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
+  const effectiveFromMatch = hasInterceptSource
+    ? interceptContextMatch
+    : prevMatch;
+
+  // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
+  const filteredSegmentIds = clientSegmentIds.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+
+  const clientSegmentSet = new Set(clientSegmentIds);
+
+  return {
+    prevUrl,
+    prevParams,
+    prevMatch,
+    interceptContextUrl,
+    interceptContextMatch,
+    clientSegmentIds,
+    clientSegmentSet,
+    filteredSegmentIds,
+    stale,
+    isSameRouteNavigation,
+    effectiveFromUrl,
+    effectiveFromMatch,
+    hasInterceptSource,
+    isHmr,
+  };
+}
+
+/**
+ * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
+ */
+export function createNavigationSnapshot(
+  overrides?: Partial<NavigationSnapshot>,
+): NavigationSnapshot {
+  const defaultUrl = new URL("http://localhost/");
+  return {
+    prevUrl: defaultUrl,
+    prevParams: {},
+    prevMatch: null,
+    interceptContextUrl: defaultUrl,
+    interceptContextMatch: null,
+    clientSegmentIds: [],
+    clientSegmentSet: new Set(),
+    filteredSegmentIds: [],
+    stale: false,
+    isSameRouteNavigation: false,
+    effectiveFromUrl: defaultUrl,
+    effectiveFromMatch: null,
+    hasInterceptSource: false,
+    isHmr: false,
+    ...overrides,
+  };
+}