@rangojs/router 0.18.0 → 0.19.0

package/src/build/generate-manifest.ts

@@ -11,12 +11,20 @@
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems } from "../route-types.js";
 import { extractStaticPrefix } from "../router/pattern-matching.js";
-import { RangoContext, runWithPrefixes } from "../server/context.js";
+import {
+  getParallelSlotEntries,
+  RangoContext,
+  runWithPrefixes,
+} from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
 import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+import {
+  createTransitionWhenError,
+  transitionWhenProblem,
+} from "../transition-when-ref.js";
 import {
   isIncludeProvider,
   resolveIncludeModule,
@@ -59,6 +67,57 @@ export interface GeneratedManifest {
   routeSearchSchemas?: Record<string, Record<string, string>>;
 }
 
+/**
+ * Fail discovery on an invalid transition({ when }) anywhere in the entry
+ * chains of the evaluated routes: the route itself, its ancestors, their
+ * orphan layouts, parallel slots and intercepts. Strict: a plain function is
+ * rejected, because discovery evaluates the tree in the react-server graph
+ * where a "use client" import is a client reference (transition-when-ref.ts).
+ * The error names the first route found through the entry.
+ */
+function validateTransitionWhens(
+  manifest: Map<string, EntryData>,
+  patterns: Map<string, string>,
+): void {
+  const seen = new Set<object>();
+  for (const [routeName, routeEntry] of manifest) {
+    const route = {
+      routeName,
+      pattern:
+        patterns.get(routeName) ??
+        (routeEntry.type === "route" ? routeEntry.pattern : undefined),
+    };
+    const check = (when: unknown, entryType: string): void => {
+      const problem = transitionWhenProblem(when, true);
+      if (problem) {
+        throw createTransitionWhenError(when, problem, {
+          ...route,
+          entryType,
+        });
+      }
+    };
+    const visit = (entry: EntryData): void => {
+      if (seen.has(entry)) return;
+      seen.add(entry);
+      check(entry.transition?.when, entry.type);
+      for (const orphan of entry.layout) visit(orphan);
+      for (const { entry: slot } of getParallelSlotEntries(entry.parallel)) {
+        visit(slot);
+      }
+      for (const intercept of entry.intercept) {
+        check(intercept.transition?.when, "intercept");
+      }
+    };
+    for (
+      let entry: EntryData | null | undefined = routeEntry;
+      entry;
+      entry = entry.parent ?? entry.orphanOwner
+    ) {
+      visit(entry);
+    }
+  }
+}
+
 /**
  * Build prefix tree node by running the patterns with proper context.
  * Uses a visited set to detect circular includes and prevent infinite recursion.
@@ -116,6 +175,7 @@ async function buildPrefixTreeNode(
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
   routerId?: string,
+  validateTransitionWhen?: boolean,
 ): Promise<PrefixTreeNode> {
   // Resolve an async include provider (`() => import("./routes")`) so its routes
   // are walked into the build-time manifest/types/href. Runtime matching still
@@ -174,6 +234,8 @@ async function buildPrefixTreeNode(
       },
     );
 
+    if (validateTransitionWhen) validateTransitionWhens(manifest, patternsMap);
+
     // Collect route names defined in this include (routes have prefixes applied)
     const routes = [...patternsMap.keys()];
     Object.assign(routeManifest, Object.fromEntries(patternsMap));
@@ -230,6 +292,7 @@ async function buildPrefixTreeNode(
         responseTypeRoutes,
         routeSearchSchemas,
         routerId,
+        validateTransitionWhen,
       ),
     );
 
@@ -313,6 +376,14 @@ export async function generateManifestFull<TEnv>(
      * EntryData map built below is local; this is the only seam that surfaces it.
      */
     collectClientFallbackRef?: (refKey: string) => void;
+    /**
+     * Fail on an invalid transition({ when }): a non-function, or a plain
+     * (server) function where a client reference is required. Only the Vite
+     * plugin's discovery passes it: it evaluates the tree in the react-server
+     * graph, the one place a "use client" import is told apart from a server
+     * function (transition-when-ref.ts).
+     */
+    validateTransitionWhen?: boolean;
   },
 ): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
@@ -351,6 +422,10 @@ export async function generateManifestFull<TEnv>(
     },
   );
 
+  if (options?.validateTransitionWhen) {
+    validateTransitionWhens(manifest, patternsMap);
+  }
+
   // Surface the "use client" components registered as error/notFound fallbacks
   // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
   // The boundary may be a handler function and/or wrap the client boundary in
@@ -413,6 +488,7 @@ export async function generateManifestFull<TEnv>(
       responseTypeRoutes,
       routeSearchSchemas,
       options?.routerId,
+      options?.validateTransitionWhen,
     ),
   );
 

package/src/cache/background-task.ts

@@ -1,8 +1,10 @@
 /**
  * Background Task Runner
  *
- * Unified helper for scheduling async work via waitUntil.
- * When waitUntil is unavailable, falls back to blocking or skipping.
+ * Unified helper for scheduling async work via waitUntil, and the two bounded
+ * waits the PPR shell capture puts on background work (raceDeadline,
+ * settleGrowing). When waitUntil is unavailable, falls back to blocking or
+ * skipping.
  */
 
 interface WaitUntilHost {
@@ -32,3 +34,54 @@ export function runBackground(
     return task();
   }
 }
+
+/**
+ * Race `work` against an absolute deadline (epoch ms), keeping its value. The
+ * losing work is not cancelled (a router match has no abort signal) and its
+ * late rejection is swallowed. The timer is unref'd, so a pending deadline
+ * never keeps a Node dev process alive.
+ */
+export async function raceDeadline<T>(
+  work: Promise<T>,
+  deadline: number,
+): Promise<{ done: true; value: T } | { done: false }> {
+  work.catch(() => {});
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<{ done: false }>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ done: false }),
+      Math.max(0, deadline - Date.now()),
+    );
+    (timer as { unref?: () => void }).unref?.();
+  });
+  try {
+    return await Promise.race([
+      work.then((value) => ({ done: true as const, value })),
+      expired,
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Wait until every promise in `list` has settled, including ones appended
+ * while waiting (a settled write can schedule a nested one: cacheRoute
+ * schedules its store.set in a second waitUntil), or until `deadline` (epoch
+ * ms). Resolves true when the list drained, false at the deadline. Never
+ * mutates `list`: a later call waits for what is still pending.
+ */
+export async function settleGrowing(
+  list: readonly Promise<unknown>[],
+  deadline: number,
+): Promise<boolean> {
+  let seen = 0;
+  while (list.length > seen) {
+    if (Date.now() >= deadline) return false;
+    const batch = list.slice(seen);
+    seen = list.length;
+    const settled = await raceDeadline(Promise.allSettled(batch), deadline);
+    if (!settled.done) return false;
+  }
+  return true;
+}

package/src/cache/cache-exec-scope.ts

@@ -38,6 +38,53 @@ export interface CacheExecScope {
 
 const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();
 
+// Global key: the value must survive HMR re-evaluation of this module, like
+// the other request-scoped ALS instances (server/context.ts RangoContext).
+const IDENTITY_EXEMPT_KEY = Symbol.for("rangojs-router:identity-exempt");
+const identityExemptStorage: AsyncLocalStorage<boolean> = ((globalThis as any)[
+  IDENTITY_EXEMPT_KEY
+] ??= new AsyncLocalStorage<boolean>());
+
+/**
+ * Run a callback whose identity reads never reach a shared entry, so
+ * guardIdentityRead (server/context.ts) lets them through and records
+ * nothing (#976):
+ *
+ * - a cache's own decisions and metadata: a `key()`, a store `keyGenerator`
+ *   (cache-policy.ts resolveCacheKey), a `condition()` (cache-scope.ts
+ *   conditionAllows, loader-cache.ts) and a `tags()` function
+ *   (cache-policy.ts resolveTagsOption). The value picks the entry, whether
+ *   one is used, or how it is invalidated; it is never rendered. Reading the
+ *   request there is the documented way to partition an entry;
+ * - the router's `onError` (router/error-handling.ts invokeOnError): it
+ *   observes, and a render error can reach it inside a capture or a cached
+ *   scope.
+ *
+ * Scar: a ppr capture resolves its doc record key, and the record's tags,
+ * again under the capture context; once `ctx.request.headers` was guarded, a
+ * keyGenerator or tags() reading it refused every capture of the route.
+ *
+ * The exemption is async-local, so it would follow everything the callback
+ * starts. A "use cache" body (runWithCacheExecScope), a loader body
+ * (server/context.ts runInsideLoaderBodyScope) and a segment funnel
+ * (getContext().runWithStore) end it on entry (endIdentityExempt). Scar: a
+ * key() that awaited a "use cache" function reading cookies() stored the
+ * first visitor's cookie and served it to the next.
+ */
+export function runIdentityExempt<T>(fn: () => T): T {
+  return identityExemptStorage.run(true, fn);
+}
+
+/** True inside runIdentityExempt, and not in a scope started from it. */
+export function isInsideIdentityExempt(): boolean {
+  return identityExemptStorage.getStore() === true;
+}
+
+/** Run `fn` with the identity exemption ended (see runIdentityExempt). */
+export function endIdentityExempt<T>(fn: () => T): T {
+  return isInsideIdentityExempt() ? identityExemptStorage.run(false, fn) : fn();
+}
+
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
@@ -48,7 +95,7 @@ export function runWithCacheExecScope<T>(
   fn: () => T,
   scope: CacheExecScope = createCacheExecScope(),
 ): T {
-  return cacheExecStorage.run(scope, fn);
+  return endIdentityExempt(() => cacheExecStorage.run(scope, fn));
 }
 
 /** A scope nested in the calling chain's current one, if any. */

package/src/cache/cache-key-utils.ts

@@ -97,21 +97,61 @@ export function cacheKeyBase(
 }
 
 /**
- * The record key, or shell partition, of nested keyed cache() scopes (#970)
- * from its parts, outermost first: the chain's `key()` results and, for an
- * inner scope without its own `key()`, that scope's default key
- * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
- * scope keeps its key byte for byte. Two or more are joined by `|`, each
- * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
- * encoded part holds no `|`, so every tuple maps to its own key, of any
- * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
- * key holds no `:` either, so a single raw result with one (a prefixed
- * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
- * can. Shared with the testing helper `shellCacheKey`, which composes a
- * nested partition the same way.
+ * The prefix of a `key()` result's part in a record key (#975), and of a
+ * loader's own `key()` result after its `loader:<id>:` namespace (#1009,
+ * loader-cache.ts loaderKeyFromResult).
  */
-export function composeCacheKeys(parts: readonly string[]): string {
-  return parts.length === 1
-    ? parts[0]
-    : parts.map((part) => encodeURIComponent(part)).join("|");
+export const KEY_PART_PREFIX = "key:";
+
+/**
+ * A cache() record key, or ppr shell partition, from its parts
+ * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
+ * results of the scope's cache() chain, outermost first, then its default
+ * parts: the keyGenerator results of enclosing scopes on another store
+ * (#974) and, for a record key under a scope without its own `key()`, its
+ * default key (or its store's keyGenerator result, #970).
+ *
+ * Key scheme invariant (#975). A `key()` result is often request input,
+ * and a record key has no route or scope discriminator (the store reads
+ * `store.get(key)`), so a result that equals another record's key writes
+ * one route's content under the other's entry. Before #975 a single
+ * `key()` result was stored raw: the header value `doc:localhost/pricing`
+ * named /pricing's default-keyed record, and `gold|doc%3Alocalhost%2Fpricing`
+ * named gold's nested /pricing record (#970). So every part is encoded:
+ *
+ * - a `key()` part is `key:` plus `encodeURIComponent(result)`: it starts
+ *   with `key:` and holds no `|` and no other `:`;
+ * - a default part is `encodeURIComponent(value)`: it holds no `:` or `|`;
+ *   an enclosing store's keyGenerator result equal to the default key is an
+ *   empty part, so each store keeps its position (CacheScope
+ *   positionalParts);
+ * - one `key()` part is the key; two or more parts are joined by `|`,
+ *   `key()` parts first;
+ * - a lone default part stays raw: with no `key()` on the chain the record
+ *   key is the default key or the store's keyGenerator result, unchanged.
+ *
+ * Why nothing collides: the router's default keys (`doc:`, `partial:`,
+ * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
+ * A namespaced `key()` result starts with `key:` and holds no `|`. A
+ * composed key holds a `|` and either starts with `key:` or holds no `:`.
+ * Among composed keys, splitting on `|` recovers each part, a part's kind
+ * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
+ * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
+ * result is the store's own namespace, as before.
+ *
+ * Shared with the testing helper `shellCacheKey`, so a test builds the
+ * production partition.
+ */
+export function composeCacheKeys(
+  keyResults: readonly string[],
+  defaultParts: readonly string[] = [],
+): string {
+  if (keyResults.length === 0 && defaultParts.length === 1) {
+    return defaultParts[0];
+  }
+  const parts = keyResults.map(
+    (result) => KEY_PART_PREFIX + encodeURIComponent(result),
+  );
+  for (const part of defaultParts) parts.push(encodeURIComponent(part));
+  return parts.join("|");
 }

package/src/cache/cache-policy.ts

@@ -8,6 +8,7 @@
 
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { runIdentityExempt } from "./cache-exec-scope.js";
 import type { RequestContext } from "../server/request-context.js";
 import { normalizeTags } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
@@ -127,16 +128,18 @@ export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
   defaultKey: string,
-  _label: string,
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
+  // A key reads the request to partition the entry (runIdentityExempt): the
+  // identity guards let it through, a ppr capture included.
   if (keyFn && requestCtx) {
-    return await keyFn(requestCtx);
+    return await runIdentityExempt(() => keyFn(requestCtx));
   }
 
   if (store?.keyGenerator && requestCtx) {
-    return await store.keyGenerator(requestCtx, defaultKey);
+    const keyGenerator = store.keyGenerator;
+    return await runIdentityExempt(() => keyGenerator(requestCtx, defaultKey));
   }
 
   return defaultKey;
@@ -157,7 +160,9 @@ export function resolveTagsOption<TEnv>(
       return undefined;
     }
     try {
-      return normalizeTagList(tags(ctx));
+      // Tags label the entry, never render: identity reads pass
+      // (runIdentityExempt), a ppr capture's record write included.
+      return normalizeTagList(runIdentityExempt(() => tags(ctx)));
     } catch (error) {
       reportCacheError(
         error,