@rangojs/router 0.0.0-experimental.83 → 0.0.0-experimental.8332dbe4

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
@@ -82,6 +83,13 @@ export interface CompiledPattern {
   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
@@ -142,6 +150,7 @@ export function compilePattern(pattern: string): CompiledPattern {
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
   const optionalParams = new Set<string>();
+  let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
 
@@ -152,11 +161,14 @@ export function compilePattern(pattern: string): CompiledPattern {
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
       const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
-      const valuePattern = segment.constraint
-        ? `(${segment.constraint.map(escapeRegex).join("|")})`
-        : 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);
@@ -176,6 +188,20 @@ export function compilePattern(pattern: string): CompiledPattern {
     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 += "/";
@@ -186,9 +212,35 @@ export function compilePattern(pattern: string): CompiledPattern {
     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
  */
@@ -196,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.
@@ -247,8 +320,10 @@ export function extractStaticPrefix(pattern: string): string {
 /**
  * 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()
@@ -392,8 +467,13 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } =
-        getCompiledPattern(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 =
@@ -410,10 +490,13 @@ export function findMatch<TEnv>(
       // 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", {
@@ -465,10 +548,11 @@ export function findMatch<TEnv>(
       // 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") {

package/src/router/revalidation.ts

@@ -59,6 +59,14 @@ interface EvaluateRevalidationOptions<TEnv> {
   stale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
+  /**
+   * Override the segment-type-derived default. When set, the value is used as
+   * the seed `defaultShouldRevalidate` passed to user revalidate fns and the
+   * reason flows into the trace. Callers use this when client-knowledge
+   * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
+   * instead of the params/method-based heuristic.
+   */
+  defaultOverride?: { value: boolean; reason: string };
 }
 
 /**
@@ -81,6 +89,7 @@ export async function evaluateRevalidation<TEnv>(
     actionContext,
     stale,
     traceSource,
+    defaultOverride,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
@@ -110,7 +119,12 @@ export async function evaluateRevalidation<TEnv>(
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
-  if (request.method === "POST") {
+  if (defaultOverride) {
+    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
+    // Skip the type-derived heuristic — caller knows better in this context.
+    defaultShouldRevalidate = defaultOverride.value;
+    defaultReason = defaultOverride.reason;
+  } else if (request.method === "POST") {
     // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
       // Route segment always revalidates on actions

package/src/router/segment-resolution/fresh.ts

@@ -515,6 +515,14 @@ export async function resolveParallelEntry<TEnv>(
       if (handler === undefined) {
         continue;
       }
+      // Pin `_currentSegmentId` to the slot's own id so handle pushes from
+      // inside the slot handler get their own bucket in the HandleStore.
+      // Parent-keying would collapse them into the parent layout's bucket;
+      // the partial-update merge then replaces the parent's bucket on a
+      // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
+      // filterSegmentOrder() retains slot ids so the client preserves them.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        `${parentShortCode}.${slot}`;
       const doneParallelHandler = track(
         `handler:${parallelEntry.id}.${slot}`,
         2,

package/src/router/segment-resolution/revalidation.ts

@@ -89,6 +89,27 @@ function observeStreamedHandler(
   });
 }
 
+/**
+ * Trace a parallel slot that's being force-rendered on a full refetch (client
+ * has no cached state). User revalidate fns are bypassed in this case — see
+ * the call sites for the load-bearing rationale.
+ */
+function traceFullRefetchedParallelSlot(
+  parallelId: string,
+  belongsToRoute: boolean,
+): void {
+  if (!isTraceActive()) return;
+  pushRevalidationTraceEntry({
+    segmentId: parallelId,
+    segmentType: "parallel",
+    belongsToRoute,
+    source: "parallel",
+    defaultShouldRevalidate: true,
+    finalShouldRevalidate: true,
+    reason: "full-refetch",
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Revalidation telemetry helper
 // ---------------------------------------------------------------------------
@@ -448,44 +469,30 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 
     const isFullRefetch = clientSegmentIds.size === 0;
     const isNewParent = !clientSegmentIds.has(entry.shortCode);
-    if (
-      isFullRefetch ||
-      clientSegmentIds.has(parallelId) ||
-      belongsToRoute ||
-      isNewParent
-    ) {
-      matchedIds.push(parallelId);
-    }
+    // Always announce the slot in matchedIds — it's unconditionally appended
+    // to `segments` below, and a segment present in segments but missing from
+    // matched lets the client prune it (then it's missing from clientSegmentIds
+    // on the next request, perpetuating the staleness).
+    matchedIds.push(parallelId);
 
-    const shouldResolve = await (async () => {
-      if (isFullRefetch) {
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "full-refetch",
-          });
-        }
-        return true;
-      }
+    let shouldResolve: boolean;
+    if (isFullRefetch) {
+      // Client has nothing cached — slot MUST render. User revalidate fns are
+      // bypassed here because returning false would leave the segment blank
+      // with no client-side fallback.
+      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
+      shouldResolve = true;
+    } else {
+      // For non-empty client sets, consult user revalidate fns. When the slot
+      // is unknown to the client, override the type-derived default so the
+      // soft chain seeds with the right "new segment" / "parent-chain" value.
+      let defaultOverride: { value: boolean; reason: string } | undefined;
       if (!clientSegmentIds.has(parallelId)) {
-        const result = belongsToRoute || isNewParent;
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: result,
-            finalShouldRevalidate: result,
-            reason: result ? "new-segment" : "skip-parent-chain",
-          });
-        }
-        return result;
+        const value = belongsToRoute || isNewParent;
+        defaultOverride = {
+          value,
+          reason: value ? "new-segment" : "skip-parent-chain",
+        };
       }
 
       const dummySegment: ResolvedSegment = {
@@ -503,7 +510,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -519,8 +526,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -529,8 +537,11 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     );
 
     let component: ReactNode | undefined;
+    let handlerRan = false;
     if (shouldResolve) {
       component = await tryStaticSlot(parallelEntry, slot, parallelId);
+      // tryStaticSlot returning a value means the static cache supplied the
+      // component — handler did NOT run. handlerRan stays false.
     }
     if (component === undefined) {
       const hasLoadingFallback =
@@ -541,29 +552,37 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         // Handler evicted (production static slot) but static lookup missed.
         // Nothing to render — use null so the client keeps its cached version.
         component = null;
-      } else if (hasLoadingFallback) {
-        const result =
-          typeof handler === "function" ? handler(context) : handler;
-        if (result instanceof Promise) {
-          const tracked = deps.trackHandler(result, {
-            segmentId: parallelId,
-            segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
-            routeKey,
-            params,
-          );
-          component = tracked as ReactNode;
+      } else {
+        // Slot-keyed pushes — slot owns its own bucket, parent layout owns
+        // its own. On slot-only revalidations the partial merge updates only
+        // the slot's bucket; the parent's bucket stays intact.
+        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+          parallelId;
+        handlerRan = true;
+        if (hasLoadingFallback) {
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
-          component = result as ReactNode;
+          component =
+            typeof handler === "function" ? await handler(context) : handler;
         }
-      } else {
-        component =
-          typeof handler === "function" ? await handler(context) : handler;
       }
     }
 
@@ -577,6 +596,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: parallelEntry.transition,
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath
@@ -631,6 +651,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
 ): Promise<{ segment: ResolvedSegment; matchedId: string }> {
   const matchedId = entry.shortCode;
 
+  let handlerRan = false;
   const component = await revalidate(
     async () => {
       const hasSegment = clientSegmentIds.has(entry.shortCode);
@@ -707,6 +728,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      handlerRan = true;
       const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
@@ -788,6 +810,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       ? { layoutName: entry.id }
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    _handlerRan: handlerRan,
   };
 
   return { segment, matchedId };
@@ -868,7 +891,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         true,
         deps,
         actionContext,
@@ -953,7 +975,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         false,
         deps,
         actionContext,
@@ -980,7 +1001,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   prevUrl: URL,
   nextUrl: URL,
   routeKey: string,
-  loaderPromises: Map<string, Promise<any>>,
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
@@ -1166,21 +1186,20 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     const parallelId = `${orphan.shortCode}.${slot}`;
     matchedIds.push(parallelId);
 
-    const shouldResolve = await (async () => {
-      if (!clientSegmentIds.has(parallelId)) {
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "new-segment",
-          });
-        }
-        return true;
-      }
+    const isFullRefetch = clientSegmentIds.size === 0;
+    let shouldResolve: boolean;
+    if (isFullRefetch) {
+      // Same load-bearing rationale as the main parallel path: full refetch
+      // means the client has nothing to fall back to, so the slot must render.
+      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
+      shouldResolve = true;
+    } else {
+      // When slot is unknown to the client, seed the soft chain with `true`
+      // (orphan parallels always belong to the route — we want them rendered
+      // unless the user explicitly opts out via revalidate()).
+      const defaultOverride = clientSegmentIds.has(parallelId)
+        ? undefined
+        : { value: true, reason: "new-segment" };
 
       const dummySegment: ResolvedSegment = {
         id: parallelId,
@@ -1197,7 +1216,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1213,8 +1232,9 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -1223,6 +1243,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     let component: ReactNode | undefined;
+    let handlerRan = false;
     if (shouldResolve) {
       component = await tryStaticSlot(parallelEntry, slot, parallelId);
     }
@@ -1234,29 +1255,35 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       } else if (handler === undefined) {
         // Handler evicted (production static slot) but static lookup missed.
         component = null;
-      } else if (hasLoadingFallback) {
-        const result =
-          typeof handler === "function" ? handler(context) : handler;
-        if (result instanceof Promise) {
-          const tracked = deps.trackHandler(result, {
-            segmentId: parallelId,
-            segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
-            routeKey,
-            params,
-          );
-          component = tracked as ReactNode;
+      } else {
+        // Slot-keyed pushes — see resolveParallelSegmentsWithRevalidation.
+        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+          parallelId;
+        handlerRan = true;
+        if (hasLoadingFallback) {
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
-          component = result as ReactNode;
+          component =
+            typeof handler === "function" ? await handler(context) : handler;
         }
-      } else {
-        component =
-          typeof handler === "function" ? await handler(context) : handler;
       }
     }
 
@@ -1270,6 +1297,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       transition: parallelEntry.transition,
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath

package/src/router/substitute-pattern-params.ts

@@ -0,0 +1,56 @@
+import { encodePathSegment } from "./url-params.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`. Two-pass: optional params (`:name?`) first so absent values
+ * collapse cleanly, then required params (throws on missing). Constraint
+ * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was
+ * actually omitted.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export function substitutePatternParams(
+  pattern: string,
+  params: Record<string, string | undefined>,
+  routeName: string,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      // The matcher omits absent optional params (so `value` is `undefined`
+      // here), but caller-supplied params or `getParams()` shapes may still
+      // pass `""` explicitly. Treat both as the absent form.
+      if (value === undefined || value === "") {
+        hadOmittedOptional = true;
+        return "";
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}