@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

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

package/src/router/pattern-matching.ts

@@ -7,6 +7,7 @@
 import type { RouteEntry, TrailingSlashMode } from "../types";
 import type { EntryData } from "../server/context";
 import { debugLog, isRouterDebugEnabled } from "./logging.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 /**
  * Parsed segment info
@@ -16,6 +17,7 @@ export interface ParsedSegment {
   value: string; // static text, param name, or "*"
   optional: boolean;
   constraint?: string[]; // enum values like ["en", "gb"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
 }
 
 /**
@@ -38,11 +40,22 @@ export function parsePattern(pattern: string): ParsedSegment[] {
   // - :param(a|b)
   // - :param(a|b)?
   // - *
-  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
+  const segmentRegex =
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
   let match;
   while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
 
     if (wildcard) {
       segments.push({ type: "wildcard", value: "*", optional: false });
@@ -52,6 +65,7 @@ export function parsePattern(pattern: string): ParsedSegment[] {
         value: paramName,
         optional: optional === "?",
         constraint: constraint ? constraint.split("|") : undefined,
+        suffix: suffix || undefined,
       });
     } else if (staticText) {
       segments.push({ type: "static", value: staticText, optional: false });
@@ -61,6 +75,55 @@ export function parsePattern(pattern: string): ParsedSegment[] {
   return segments;
 }
 
+/**
+ * Compiled pattern result containing regex, param metadata, and trailing slash info.
+ */
+export interface CompiledPattern {
+  regex: RegExp;
+  paramNames: string[];
+  optionalParams: Set<string>;
+  hasTrailingSlash: boolean;
+  /**
+   * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
+   * Validated against the **decoded** param value after regex extraction so
+   * a URL like `/en%20GB` still matches `:lang(en GB)` — matching the trie
+   * path's behavior (trie-matching.ts:validateAndBuild).
+   */
+  constraints?: Record<string, string[]>;
+}
+
+// Module-level cache for compiled patterns. Route patterns are a finite set
+// defined at build time, so this map is bounded by the number of routes.
+const compiledPatternCache = new Map<string, CompiledPattern>();
+
+/**
+ * Get a compiled pattern from cache or compile and cache it.
+ * Avoids O(routes) regex compilations per request in the fallback path.
+ */
+export function getCompiledPattern(pattern: string): CompiledPattern {
+  let compiled = compiledPatternCache.get(pattern);
+  if (compiled) return compiled;
+  compiled = compilePattern(pattern);
+  compiledPatternCache.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * Return the current size of the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function getPatternCacheSize(): number {
+  return compiledPatternCache.size;
+}
+
+/**
+ * Clear the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function clearPatternCache(): void {
+  compiledPatternCache.clear();
+}
+
 /**
  * Compile a route pattern to regex
  *
@@ -78,12 +141,7 @@ export function parsePattern(pattern: string): ParsedSegment[] {
  * compilePattern("/:locale(en|gb)/blog")  // matches /en/blog or /gb/blog
  * compilePattern("/:locale(en|gb)?/blog") // matches /blog, /en/blog, or /gb/blog
  */
-export function compilePattern(pattern: string): {
-  regex: RegExp;
-  paramNames: string[];
-  optionalParams: Set<string>;
-  hasTrailingSlash: boolean;
-} {
+export function compilePattern(pattern: string): CompiledPattern {
   // Detect if pattern has trailing slash (but not just "/")
   const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
   // Remove trailing slash for parsing (we'll add it back to regex if needed)
@@ -92,6 +150,7 @@ export function compilePattern(pattern: string): {
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
   const optionalParams = new Set<string>();
+  let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
 
@@ -101,16 +160,22 @@ export function compilePattern(pattern: string): {
       regexPattern += "/(.*)";
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
-      const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
-        : "([^/]+)";
+      const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
+      // Constrained params capture anything here; the allowed values are
+      // checked post-decode in findMatch so URL-encoded constraint values
+      // (e.g. `:lang(en GB)` via `/en%20GB`) still match.
+      const valuePattern = segment.suffix ? "([^/]+?)" : "([^/]+)";
+
+      if (segment.constraint) {
+        (constraints ??= {})[segment.value] = segment.constraint;
+      }
 
       if (segment.optional) {
         optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
-        regexPattern += `(?:/${valuePattern})?`;
+        regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
-        regexPattern += `/${valuePattern}`;
+        regexPattern += `/${valuePattern}${suffixPattern}`;
       }
     } else {
       // Static segment
@@ -123,6 +188,20 @@ export function compilePattern(pattern: string): {
     regexPattern = "/";
   }
 
+  // Patterns of only optional segments (e.g. `/:locale?`, `/:a?/:b?`) need
+  // an explicit `/` alternative so a bare `/` matches the absent form. The
+  // optional template `(?:/X)?` matches `/X` or empty string, but pathnames
+  // are never empty. Arises from `include("/:locale?", routes)` + inner
+  // `path("/")`. Skip when an explicit trailing slash already anchors the
+  // match.
+  const hasOnlyOptionalSegments =
+    !hasTrailingSlash &&
+    segments.length > 0 &&
+    segments.every((segment) => segment.type === "param" && segment.optional);
+  if (hasOnlyOptionalSegments) {
+    regexPattern = `(?:/|${regexPattern})`;
+  }
+
   // Add trailing slash to regex if pattern has one
   if (hasTrailingSlash) {
     regexPattern += "/";
@@ -133,9 +212,35 @@ export function compilePattern(pattern: string): {
     paramNames,
     optionalParams,
     hasTrailingSlash,
+    ...(constraints ? { constraints } : {}),
   };
 }
 
+/**
+ * Validate decoded params against a compiled pattern's constraints.
+ * Returns false if any constrained param has a non-empty value not in the
+ * allowed list. Absent optionals (key missing or `undefined`) are allowed;
+ * `""` is also tolerated as "absent" so user-provided params or fixtures
+ * that pass empty strings explicitly behave the same way.
+ */
+function satisfiesConstraints(
+  params: Record<string, string>,
+  constraints: Record<string, string[]> | undefined,
+): boolean {
+  if (!constraints) return true;
+  for (const name in constraints) {
+    const value = params[name];
+    if (
+      value !== undefined &&
+      value !== "" &&
+      !constraints[name].includes(value)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * Escape special regex characters in a string
  */
@@ -143,6 +248,27 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Build the named-params record from a regex match. Optional segments that
+ * didn't capture leave the corresponding group `undefined`; we skip those
+ * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
+ * keeps the runtime aligned with the `ExtractParams` type and matches the
+ * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ */
+function buildParamsFromMatch(
+  match: RegExpExecArray,
+  paramNames: string[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, index) => {
+    const captured = match[index + 1];
+    if (captured !== undefined) {
+      params[name] = safeDecodeURIComponent(captured);
+    }
+  });
+  return params;
+}
+
 /**
  * Extract the static prefix from a route pattern.
  * Returns everything before the first param/wildcard.
@@ -191,11 +317,28 @@ export function extractStaticPrefix(pattern: string): string {
   return pattern.slice(0, lastSlash);
 }
 
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export function joinPrefix(base: string | undefined, prefix: string): string {
+  if (!base) return prefix;
+  return base.endsWith("/") && prefix.startsWith("/")
+    ? base + prefix.slice(1)
+    : base + prefix;
+}
+
 /**
  * Match a pathname against registered routes
  *
- * Note: Optional params that are absent in the path will have empty string value.
- * Use the pattern definition to determine if a param is optional.
+ * Note: Optional params that are absent in the path are omitted from the
+ * returned `params` (read as `undefined`), matching the trie matcher and
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition or
+ * `optionalParams` to determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -215,8 +358,6 @@ export interface RouteMatchResult<TEnv = any> {
   params: Record<string, string>;
   optionalParams: Set<string>;
   redirectTo?: string;
-  /** Ancestry shortCodes for layout pruning (from trie match) */
-  ancestry?: string[];
   /** Route has pre-rendered data available (from trie) */
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params (from trie) */
@@ -240,7 +381,7 @@ export interface LazyEvaluationNeeded<TEnv = any> {
  * Type guard to check if result is a lazy evaluation needed response
  */
 export function isLazyEvaluationNeeded<TEnv>(
-  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null
+  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null,
 ): result is LazyEvaluationNeeded<TEnv> {
   return result !== null && "lazyEntry" in result;
 }
@@ -261,12 +402,16 @@ export function enableMatchDebug(enabled: boolean): void {
 }
 
 export function getMatchDebugStats(): MatchDebugStats {
-  return { entriesChecked: debugStats.entriesChecked, entriesSkipped: debugStats.entriesSkipped, routesChecked: debugStats.routesChecked };
+  return {
+    entriesChecked: debugStats.entriesChecked,
+    entriesSkipped: debugStats.entriesSkipped,
+    routesChecked: debugStats.routesChecked,
+  };
 }
 
 export function findMatch<TEnv>(
   pathname: string,
-  routesEntries: RouteEntry<TEnv>[]
+  routesEntries: RouteEntry<TEnv>[],
 ): RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null {
   const effectiveDebug = debugEnabled || isRouterDebugEnabled();
 
@@ -282,7 +427,8 @@ export function findMatch<TEnv>(
     }
   }
 
-  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
+  const pathnameHasTrailingSlash =
+    pathname.length > 1 && pathname.endsWith("/");
   // Try alternate pathname for redirect matching
   const alternatePathname = pathnameHasTrailingSlash
     ? pathname.slice(0, -1)
@@ -334,22 +480,36 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } = compilePattern(fullPattern);
+      const {
+        regex,
+        paramNames,
+        optionalParams,
+        hasTrailingSlash,
+        constraints,
+      } = getCompiledPattern(fullPattern);
 
       // Get trailing slash mode for this route (per-route config or pattern-based)
-      const trailingSlashMode: TrailingSlashMode | undefined = entry.trailingSlash?.[routeKey];
-
+      const trailingSlashMode: TrailingSlashMode | undefined =
+        entry.trailingSlash?.[routeKey];
 
       // Prerender flag from entry metadata (set by urls() for prerender handlers)
-      const prFlag = entry.prerenderRouteKeys?.has(routeKey) ? { pr: true as const } : {};
+      const prFlag = entry.prerenderRouteKeys?.has(routeKey)
+        ? { pr: true as const }
+        : {};
+      const ptFlag = entry.passthroughRouteKeys?.has(routeKey)
+        ? { pt: true as const }
+        : {};
 
       // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = match[index + 1] ?? "";
-        });
+        const params = buildParamsFromMatch(match, paramNames);
+
+        // Validate constraints against decoded values; a failure falls
+        // through to the next route so other patterns can still match.
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
 
         if (effectiveDebug) {
           debugLog("findMatch", "matched route", {
@@ -360,46 +520,121 @@ export function findMatch<TEnv>(
         }
 
         // Check if trailing slash mode requires redirect even on exact match
-        if (trailingSlashMode === "always" && !pathnameHasTrailingSlash && pathname !== "/") {
+        if (
+          trailingSlashMode === "always" &&
+          !pathnameHasTrailingSlash &&
+          pathname !== "/"
+        ) {
           // Mode says always have trailing slash, but pathname doesn't have it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname + "/", ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: pathname + "/",
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
           // Mode says never have trailing slash, but pathname has it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname.slice(0, -1), ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: pathname.slice(0, -1),
+            ...prFlag,
+            ...ptFlag,
+          };
         }
 
-        return { entry, routeKey, params, optionalParams, ...prFlag };
+        return {
+          entry,
+          routeKey,
+          params,
+          optionalParams,
+          ...prFlag,
+          ...ptFlag,
+        };
       }
 
       // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = altMatch[index + 1] ?? "";
-        });
+        const params = buildParamsFromMatch(altMatch, paramNames);
+
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
 
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never") {
           // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname, ...prFlag };
+            return {
+              entry,
+              routeKey,
+              params,
+              optionalParams,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "always") {
           // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname, ...prFlag };
+            return {
+              entry,
+              routeKey,
+              params,
+              optionalParams,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else {
           // No explicit mode - use pattern-based detection
           // Redirect to canonical form (what the pattern defines)
-          const canonicalPath = hasTrailingSlash ? alternatePathname : pathname.slice(0, -1);
-          return { entry, routeKey, params, optionalParams, redirectTo: canonicalPath, ...prFlag };
+          const canonicalPath = hasTrailingSlash
+            ? alternatePathname
+            : pathname.slice(0, -1);
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: canonicalPath,
+            ...prFlag,
+            ...ptFlag,
+          };
         }
       }
     }