@rangojs/router 0.18.0 → 0.19.0

package/src/testing/serve-shell-request.ts

@@ -261,24 +261,27 @@ function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
 /**
  * Reset the per-isolate PPR state requests leave behind, so the next test
  * starts as a fresh worker would: the capture's stampede guard, its backoff
- * (a refused capture backs its URL off for later tests too), the capture's
- * and the serve path's once-per-key warnings, the build-shell manifest memo,
- * and CFCacheStore's isolate memos (shells, tag markers, tag hints), which
- * every CFCacheStore in the process shares by namespace and URL. Call it in
- * `beforeEach`, never while a request is in flight. VercelCacheStore's memos
- * live on the `cache` handle it is given: a new handle starts empty.
+ * (a refused capture backs its URL off for later tests too), the shell path's
+ * once-per-key warnings, the build-shell manifest memo, the "use cache"
+ * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * tag markers, tag hints) and warnings, which every CFCacheStore in the
+ * process shares by namespace and URL. Call it in `beforeEach`, never while
+ * a request is in flight. VercelCacheStore's memos live on the `cache`
+ * handle it is given: a new handle starts empty.
  */
 export async function resetShellTestState(): Promise<void> {
-  const [capture, serve, buildShells, cf] = await Promise.all([
+  const [capture, serve, buildShells, cf, cacheRuntime] = await Promise.all([
     import("../rsc/shell-capture.js"),
     import("../rsc/shell-serve.js"),
     import("../rsc/shell-build-manifest.js"),
     import("../cache/cf/cf-cache-store.js"),
+    import("../cache/cache-runtime.js"),
   ]);
   capture.resetShellCaptureStateForTests();
   serve.resetShellServeStateForTests();
   buildShells.resetBuildShellManifestForTests();
   cf.resetCFShellMemoForTests();
+  cacheRuntime.resetCacheRuntimeForTests();
 }
 
 /** Settle background tasks, including ones scheduled while settling. */

package/src/testing/shell-status.ts

@@ -32,48 +32,28 @@
  * (Playwright — same pure helpers, no Vite virtuals).
  */
 
+import { composeCacheKeys } from "../cache/cache-key-utils.js";
 import {
-  composeCacheKeys,
-  sortedSearchString,
-} from "../cache/cache-key-utils.js";
-import { partitionShellKey } from "../rsc/shell-capture-constants.js";
+  PPR_REPLAY_BYPASS_REASONS,
+  PPR_REPLAY_STATUS_HEADER,
+  SHELL_STATUS_HEADER,
+  buildShellKey,
+  partitionShellKey,
+  type PprReplayBypassReason,
+} from "../rsc/shell-capture-constants.js";
 import {
   compileSearchParamsFilter,
   type CacheSearchParams,
 } from "../cache/search-params-filter.js";
 
-/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
-export const SHELL_STATUS_HEADER: string = "x-rango-shell";
-
-/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
-export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
+// The production header names and bypass reasons, from the React-free leaf
+// the serve path reads them from.
+export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER };
+export type { PprReplayBypassReason };
 
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
 
-const PPR_REPLAY_BYPASS_REASONS = [
-  "method",
-  "dynamic",
-  "nonce",
-  "store-unavailable",
-  "passive-read-unsupported",
-  "no-navigation-context",
-  "prerender-store",
-  "intercept",
-  "cache-disabled",
-  "read-error",
-  "no-entry",
-  "invalid-version",
-  "corrupt-entry",
-  "no-segment-snapshot",
-  "snapshot-miss",
-  "explicit-cache-hit",
-  "stale-build-entry",
-] as const;
-
-/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
-export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
-
 /** Parsed `x-rango-ppr-replay` value. */
 export type PprReplayStatus =
   | { outcome: "HIT"; freshness: "fresh" | "stale" }
@@ -83,44 +63,68 @@ export type PprReplayStatus =
 export type ShellStatusTarget = Response | { headers: Headers };
 
 /**
- * Shell store key for a document URL — same formula as production
- * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
- * `:shell`), then the production `partitionShellKey` itself (the leaf
- * `rsc/shell-capture-constants.ts`). The base is kept here so the testing
- * barrel never imports the shell-serve module (it pulls React). A parity test
- * pins the two implementations.
+ * What partitions a ppr route's shell, for {@link shellCacheKey}: the
+ * request's results of the functions that partition the route's cache()
+ * record.
+ */
+export interface ShellCachePartition {
+  /** The route's cache() `key()` results, outermost first. */
+  keys?: readonly string[];
+  /**
+   * Store `keyGenerator` results, one per store, outermost first: an
+   * enclosing cache() on another store's, then the store's of the route's
+   * own cache() when it sets no `key()` (with no route cache(), the app
+   * store's). When every one returns the default key they partition
+   * nothing: leave them out. Otherwise each keeps its position, and one
+   * that returns the default key is `""`.
+   */
+  generated?: readonly string[];
+}
+
+/**
+ * Shell store key for a document URL: the production `buildShellKey` (host +
+ * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
+ * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
+ * imports the shell-serve module (it pulls React).
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
  * config as `searchParams` when the app under test sets one — the production
  * key applies it, so the expected key must too. When the route's record is
- * partitioned by the request — its `cache({ key })`, or the store's
- * `keyGenerator` — its shell is too: pass the key that function returns for
- * the request as `partition` (appended URI-encoded; a result equal to the
- * default key partitions nothing, so pass none). Under nested keyed
- * `cache()` scopes, pass their `key()` results as an array, outermost first:
- * they compose as the production record key composes them
- * (`composeCacheKeys`).
+ * partitioned by the request, its shell is too: pass what partitions it as
+ * `partition`, composed as production composes it (`composeCacheKeys`,
+ * which namespaces each `key()` result):
+ * - its `cache({ key })` result, as a string;
+ * - nested keyed `cache()` scopes' `key()` results, as an array, outermost
+ *   first;
+ * - store `keyGenerator` results, with or without `key()` results, as
+ *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
 export function shellCacheKey(
   url: URL | string,
   searchParams?: CacheSearchParams,
-  partition?: string | readonly string[],
+  partition?: string | readonly string[] | ShellCachePartition,
 ): string {
   const resolved =
     typeof url === "string" ? new URL(url, "http://localhost") : url;
-  const sorted = sortedSearchString(
-    resolved.searchParams,
-    compileSearchParamsFilter(searchParams),
-  );
-  const searchSuffix = sorted ? `?${sorted}` : "";
-  const key = `${resolved.host}${resolved.pathname}${searchSuffix}:shell`;
+  const key = buildShellKey(resolved, compileSearchParamsFilter(searchParams));
   if (partition === undefined) return key;
-  if (typeof partition === "string") return partitionShellKey(key, partition);
-  // No key() results: no partition, as when `partition` is omitted.
-  return partition.length === 0
+  const { keys = [], generated = [] }: ShellCachePartition =
+    typeof partition === "string"
+      ? { keys: [partition] }
+      : isPartitionList(partition)
+        ? { keys: partition }
+        : partition;
+  // Nothing partitions: the key as when `partition` is omitted.
+  return keys.length === 0 && generated.length === 0
     ? key
-    : partitionShellKey(key, composeCacheKeys(partition));
+    : partitionShellKey(key, composeCacheKeys(keys, generated));
+}
+
+function isPartitionList(
+  partition: readonly string[] | ShellCachePartition,
+): partition is readonly string[] {
+  return Array.isArray(partition);
 }
 
 function getHeaders(target: ShellStatusTarget): Headers {

package/src/transition-when-ref.ts

@@ -0,0 +1,220 @@
+/**
+ * transition({ when }) references: what a route definition may carry as a
+ * `when`, how definitions are validated, and how the browser turns the carried
+ * value back into a callable predicate.
+ *
+ * `when` is a BROWSER predicate. The server never calls it; it only carries it
+ * to the browser inside the segment's transition config, as one of:
+ *
+ * - a React client reference: a function exported from a `"use client"`
+ *   module and imported into a server `urls()` file, or an inline literal the
+ *   build hoisted into one (vite/plugins/transition-when-hoist.ts). Flight
+ *   serializes it as a module reference and the browser resolves it to the
+ *   real function;
+ * - a clientUrls() when reference, synthesized by the projection materializer
+ *   (client-urls/server-projection.ts): the group's definition client
+ *   reference plus the route id. The browser resolves it to the `when` the
+ *   route declared in its `"use client"` module.
+ *
+ * A plain function (a server function) cannot cross Flight, and a
+ * non-function is never callable. Both are LOUD errors: route discovery
+ * (generateManifestFull `validateTransitionWhen`) fails dev startup, the
+ * build and HMR re-discovery, and attachTransitionWhen (rsc/) throws the same
+ * error at render time for a route discovery did not see.
+ *
+ * Telling a client reference apart from a server function needs the
+ * react-server module graph, where a `"use client"` import IS a client
+ * reference. Outside it (a node/DOM unit-test project that aliases the router
+ * entry) the import is the plain function, so strict validation is enabled
+ * only by the Vite plugin: discovery passes the option, and the generated
+ * routes-manifest module calls enableTransitionWhenValidation() in the app's
+ * RSC realm (vite/discovery/virtual-module-codegen.ts).
+ */
+
+import { isAutoGeneratedRouteName } from "./route-name.js";
+import type { TransitionWhenFn } from "./types/segments.js";
+
+const CLIENT_REFERENCE = Symbol.for("react.client.reference");
+
+/** String key, so the marker survives Flight (symbol keys are not serialized). */
+const CLIENT_URLS_WHEN_KEY = "__rangoClientUrlsWhen";
+
+interface ClientUrlsWhenRef {
+  readonly __rangoClientUrlsWhen: 1;
+  /** The clientUrls() definition: a client reference on the server, the definition object in the browser. */
+  readonly definition: unknown;
+  readonly routeId: string;
+}
+
+export function isClientReference(value: unknown): boolean {
+  if (typeof value !== "function" && (typeof value !== "object" || !value)) {
+    return false;
+  }
+  return (value as { $$typeof?: unknown }).$$typeof === CLIENT_REFERENCE;
+}
+
+function isClientUrlsWhenRef(value: unknown): value is ClientUrlsWhenRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[CLIENT_URLS_WHEN_KEY] === 1
+  );
+}
+
+export function createClientUrlsWhenRef(
+  definition: unknown,
+  routeId: string,
+): TransitionWhenFn {
+  const ref: ClientUrlsWhenRef = {
+    __rangoClientUrlsWhen: 1,
+    definition,
+    routeId,
+  };
+  return ref as unknown as TransitionWhenFn;
+}
+
+let strictValidation = false;
+
+/**
+ * Turn on server-function rejection for this realm. Called by the Vite
+ * plugin's generated routes-manifest module, never by tests: see the module
+ * comment for why it cannot be on by default.
+ */
+export function enableTransitionWhenValidation(): void {
+  strictValidation = true;
+}
+
+export function isTransitionWhenValidationEnabled(): boolean {
+  return strictValidation;
+}
+
+/** @internal Reset for unit tests. */
+export function resetTransitionWhenValidation(): void {
+  strictValidation = false;
+}
+
+/** Thrown for an invalid transition({ when }); recognized by the dev HMR overlay. */
+export class TransitionWhenError extends Error {
+  override readonly name: string = "TransitionWhenError";
+}
+
+/**
+ * The TransitionWhenError in an error's cause chain, matched by name: discovery
+ * throws it from the module runner's copy of this module (another class
+ * object), and include resolution wraps it (build/generate-manifest.ts).
+ */
+export function findTransitionWhenError(error: unknown): Error | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (
+    typeof current === "object" &&
+    current !== null &&
+    !seen.has(current)
+  ) {
+    seen.add(current);
+    if ((current as Error).name === "TransitionWhenError") {
+      return current as Error;
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+/** Where an invalid `when` was declared, for the error message. */
+export interface TransitionWhenSite {
+  /** The route the entry belongs to (the matched or enumerated route). */
+  readonly routeName?: string;
+  readonly pattern?: string;
+  /** The declaring entry's type when it is not the route itself. */
+  readonly entryType?: string;
+}
+
+function describeSite(site: TransitionWhenSite): string {
+  const named =
+    site.routeName && !isAutoGeneratedRouteName(site.routeName)
+      ? `route "${site.routeName}"${site.pattern ? ` (${site.pattern})` : ""}`
+      : site.pattern
+        ? `route ${site.pattern}`
+        : "a route";
+  if (!site.entryType || site.entryType === "route") return named;
+  return `a ${site.entryType} of ${named}`;
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+/**
+ * The problem with a `when` value, or null when it is valid. Non-functions
+ * are always invalid; a plain function is invalid only under strict
+ * validation (see the module comment).
+ */
+export function transitionWhenProblem(
+  when: unknown,
+  strict: boolean,
+): "not-a-function" | "server-function" | null {
+  if (when === undefined || isClientUrlsWhenRef(when)) return null;
+  if (typeof when !== "function") return "not-a-function";
+  if (strict && !isClientReference(when)) return "server-function";
+  return null;
+}
+
+export function createTransitionWhenError(
+  when: unknown,
+  problem: "not-a-function" | "server-function",
+  site: TransitionWhenSite,
+): TransitionWhenError {
+  const where = `transition({ when }) on ${describeSite(site)}`;
+  const head =
+    problem === "not-a-function"
+      ? `${where} must be a function, got ${describeValue(when)}.`
+      : `${where} is not a client function.`;
+  return new TransitionWhenError(
+    `[rango] ${head} ` +
+      "`when` runs in the browser: write it inline in the transition() call " +
+      "(transition({ when: (ctx) => ... }), where transition is the urls() helper " +
+      'or imported from "@rangojs/router"; the build hoists that literal into a ' +
+      'client module) or export it from a "use client" module and import it ' +
+      "into your urls() file. It receives { kind, from, to, isAction, action }: " +
+      "URLs, params, route names, history state and action data; get(), env " +
+      'and handler state do not exist there. See skills/view-transitions "Conditional transitions".',
+  );
+}
+
+/**
+ * Definition-time shape check (the DSL's transition()). Runs in every
+ * environment, so it rejects only what is invalid everywhere: a non-function.
+ */
+export function assertTransitionWhenShape(when: unknown): void {
+  if (transitionWhenProblem(when, false) === "not-a-function") {
+    throw new TypeError(
+      createTransitionWhenError(when, "not-a-function", {}).message,
+    );
+  }
+}
+
+/**
+ * Browser: turn a transition config's `when` into the predicate to call.
+ * Undefined when there is none (or a clientUrls route no longer declares it).
+ */
+export function resolveTransitionWhen(
+  when: unknown,
+): TransitionWhenFn | undefined {
+  if (typeof when === "function") return when as TransitionWhenFn;
+  if (!isClientUrlsWhenRef(when)) return undefined;
+  const definition = when.definition as
+    | {
+        routes?: ReadonlyArray<{
+          id: string;
+          transition?: { when?: unknown };
+        }>;
+      }
+    | undefined;
+  const record = definition?.routes?.find(
+    (candidate) => candidate.id === when.routeId,
+  );
+  const fn = record?.transition?.when;
+  return typeof fn === "function" ? (fn as TransitionWhenFn) : undefined;
+}

package/src/types/cache-types.ts

@@ -72,7 +72,13 @@ export interface CacheOptions<TEnv = unknown> {
   /**
    * Override the cache store for this boundary.
    * When specified, this boundary and its children use this store
-   * instead of the app-level store from handler config.
+   * instead of the app-level store from handler config. The records of a
+   * boundary with a store here are partitioned by the `keyGenerator` of each
+   * enclosing cache() without a `key` whose store differs, the app-level
+   * store included: under `cache(() => [...])` on an app store with a
+   * `keyGenerator`, `cache({ store })` records are split by its result too.
+   * Likewise, without a `key` of its own, this store's `keyGenerator`
+   * partitions a nested cache() on another store.
    *
    * Useful for:
    * - Different backends per route section (memory vs KV vs Redis)
@@ -108,6 +114,8 @@ export interface CacheOptions<TEnv = unknown> {
   /**
    * Conditional cache read function.
    * Return false to skip cache for this request (always fetch fresh).
+   * It gates every cache() nested under this one too: a nested boundary
+   * caches only when every enclosing condition allows it.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
    * Runs after global and route middleware on RSC routes; on response routes,
@@ -130,7 +138,10 @@ export interface CacheOptions<TEnv = unknown> {
 
   /**
    * Custom cache key function - FULL OVERRIDE.
-   * Bypasses default key generation AND store's keyGenerator.
+   * Bypasses default key generation AND store's keyGenerator. The result is
+   * stored namespaced (`key:` plus its URI encoding), so no value it returns
+   * names another route's record; a nested cache() keys its records within
+   * this partition.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
    * Runs after global and route middleware on RSC routes; on response routes,
@@ -154,7 +165,8 @@ export interface CacheOptions<TEnv = unknown> {
 
   /**
    * Tags for cache invalidation.
-   * Can be a static array or a function that returns tags.
+   * Can be a static array or a function that returns tags. They tag the
+   * records of every cache() nested under this one too.
    *
    * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
    * `VercelCacheStore` index by tag.

package/src/types/index.ts

@@ -51,6 +51,9 @@ export type {
   TransitionConfig,
   TransitionWhenFn,
   TransitionWhenContext,
+  TransitionWhenKind,
+  RouteLocation,
+  ServerRouteLocation,
   ResolvedSegment,
   SegmentMetadata,
   SlotState,