@rangojs/router 0.20.0 → 0.22.0

package/src/testing/action-form.ts

@@ -0,0 +1,66 @@
+/**
+ * createActionForm: the FormData a browser posts when a form is submitted
+ * before hydration (no JavaScript), for a server action.
+ *
+ * React's server render writes hidden fields on the form so the POST names its
+ * action and carries the bound state; decodeAction / decodeFormState read them
+ * back. A test cannot render those fields (react-dom/server does not load under
+ * the react-server condition), so this builds the same wire format and
+ * registers the action where the plugin-rsc stub's decodeAction resolves it,
+ * tagged as a server reference like a built "use server" export so the bound
+ * action keeps its `$$id` (onError's actionId, the action phase label).
+ * Post the result with `serveShellRequest(router, url, { form })`.
+ */
+
+import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+import { registerServerModule } from "./internal/server-modules.js";
+
+/** Options for {@link createActionForm}. */
+export interface CreateActionFormOptions {
+  /**
+   * The action's reference id, `<module id>#<export name>`, as the build gives
+   * a "use server" export. Any unique string of that shape in a test.
+   */
+  id: string;
+  /**
+   * A `useActionState` form (default): the action runs as `(prevState, formData)`
+   * and the POST carries the state key. false: a plain `<form action={fn}>`
+   * ($ACTION_ID_), the action runs as `(formData)`.
+   */
+  useActionState?: boolean;
+  /** The form's own fields, as the person filled them. */
+  fields?: Record<string, string>;
+}
+
+/**
+ * Build a no-JS form POST body for `action` and register it so a handler
+ * decodes it back to `action`.
+ */
+export function createActionForm(
+  action: (...args: any[]) => unknown,
+  options: CreateActionFormOptions,
+): FormData {
+  const { id, useActionState = true, fields = {} } = options;
+  const [moduleId, name] = id.split("#");
+  if (!moduleId || !name) {
+    throw new Error(
+      `createActionForm: id must be "<module id>#<export name>", received ${JSON.stringify(id)}`,
+    );
+  }
+  registerServerModule(moduleId, {
+    [name]: RSDServer.registerServerReference(action, moduleId, name),
+  });
+
+  const form = new FormData();
+  if (useActionState) {
+    form.set("$ACTION_REF_1", "");
+    form.set("$ACTION_1:0", JSON.stringify({ id, bound: "$@1" }));
+    // The state the hook held when the form was submitted: its initial null.
+    form.set("$ACTION_1:1", "[null]");
+    form.set("$ACTION_KEY", "k0");
+  } else {
+    form.set(`$ACTION_ID_${id}`, "");
+  }
+  for (const [field, value] of Object.entries(fields)) form.set(field, value);
+  return form;
+}

package/src/testing/build-versions.ts

@@ -0,0 +1,64 @@
+/**
+ * Testing primitive for the per-router cache versions.
+ *
+ * A production build gives every `createRouter()` a data version and a
+ * document version (docs/design/per-app-cache-version.md) and ships them as a
+ * table in the `@rangojs/router:version` module. A test has no build, so the
+ * module is a stub and every router serves unversioned. `setBuildVersions`
+ * installs a table in its place; the request handler, `dispatch` and the cache
+ * stores then resolve versions through the same code path the built app uses.
+ * Calling it again is a deploy: the next request is served by a handler that
+ * resolved the new versions.
+ */
+import { installRouterVersionsTable } from "../server/build-version-table.js";
+import {
+  DEFAULT_ROUTER_VERSIONS_KEY,
+  type RouterVersions,
+  type RouterVersionsTable,
+} from "../router-versions.js";
+
+export type { RouterVersions };
+
+/**
+ * The versions a simulated build ships.
+ *
+ * - `data` and `document`: the versions of every router the test does not list
+ *   under `routers` (the build's whole-build pair).
+ * - `routers`: versions per router id (`router.id`), as a host-router build
+ *   computes them.
+ */
+export interface BuildVersions extends RouterVersions {
+  routers?: Record<string, RouterVersions>;
+}
+
+/**
+ * Install the cache versions of a simulated build, or remove them with no
+ * argument (routers serve unversioned again, the default in tests).
+ *
+ * A router that sets `createRouter({ version })` keeps that value for both
+ * versions, exactly as in production.
+ *
+ * @example A deploy that changes the client only keeps cached data
+ * ```ts
+ * setBuildVersions({ data: "d1", document: "h1" });
+ * await serveShellRequest(router, "/product/1", { cacheStore });
+ * setBuildVersions({ data: "d1", document: "h2" });
+ * const { shellStatus } = await serveShellRequest(router, "/product/1", {
+ *   cacheStore,
+ * });
+ * // shellStatus is "MISS": the stored HTML was keyed by document version h1.
+ * ```
+ */
+export function setBuildVersions(versions?: BuildVersions): void {
+  if (!versions) {
+    installRouterVersionsTable(undefined);
+    return;
+  }
+  const table: Record<string, readonly [string, string]> = {
+    [DEFAULT_ROUTER_VERSIONS_KEY]: [versions.data, versions.document],
+  };
+  for (const [routerId, pair] of Object.entries(versions.routers ?? {})) {
+    table[routerId] = [pair.data, pair.document];
+  }
+  installRouterVersionsTable(table satisfies RouterVersionsTable);
+}

package/src/testing/dispatch.ts

@@ -106,6 +106,7 @@ import {
   runWithRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { resolveRouterVersions } from "../server/build-version-table.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type {
   MiddlewareEntry,
@@ -166,6 +167,8 @@ import { applyStreamIdleTimeout } from "../rsc/stream-idle.js";
 interface DispatchableRouter<TEnv> {
   id?: string;
   routerId?: string;
+  /** createRouter({ version }), the consumer-set version. */
+  version?: string;
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
   onError?: OnErrorCallback<TEnv>;
@@ -411,6 +414,9 @@ export async function dispatch<TEnv = any>(
     cacheStore,
     searchParamsFilter,
     cacheProfiles: router.cacheProfiles,
+    // The store keys with the router's versions, resolved as the production
+    // handler resolves them (rsc/handler.ts).
+    versions: resolveRouterVersions(routerId, router.version),
   });
   // Wire background error reporting so cache degradation (reportCacheError ->
   // _reportBackgroundError) reaches the router's onError, mirroring the production

package/src/testing/dom.entry.ts

@@ -18,5 +18,6 @@ export type {
   RenderRouteOptions,
   TestRouterHandle,
   RenderRouteResult,
+  RenderRouteHydrateResult,
   HandleDataSeed,
 } from "./render-route.js";

package/src/testing/flight-runtime.d.ts

@@ -22,6 +22,33 @@ declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
   /** Server-side temporary-reference set (a WeakMap). */
   export function createTemporaryReferenceSet(): unknown;
 
+  /** Resolve a no-JS form POST to its action, bound to the form data; null for a plain form. */
+  export function decodeAction(
+    body: FormData,
+    serverManifest: unknown,
+  ): Promise<unknown> | null;
+
+  /** Decode an action's encoded arguments; rejects for a raw form body. */
+  export function decodeReply(
+    body: string | FormData,
+    serverManifest: unknown,
+    options?: object,
+  ): Promise<unknown>;
+
+  /** The useActionState form state of a no-JS POST, or null. */
+  export function decodeFormState(
+    actionResult: unknown,
+    body: FormData,
+    serverManifest: unknown,
+  ): Promise<unknown>;
+
+  /** Tag a function as a server reference; `$$id` becomes `${id}#${exportName}`. */
+  export function registerServerReference<T>(
+    reference: T,
+    id: string,
+    exportName: string,
+  ): T;
+
   /**
    * Tag a value as a client reference. Mutates `impl` in place (defining
    * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports

package/src/testing/flight.entry.ts

@@ -56,6 +56,9 @@ export type {
   StateCookieSeed,
 } from "./render-handler.js";
 
+export { createActionForm } from "./action-form.js";
+export type { CreateActionFormOptions } from "./action-form.js";
+
 export {
   serveShellRequest,
   resetShellTestState,
@@ -63,4 +66,5 @@ export {
 export type {
   ServeShellRequestOptions,
   ServeShellRequestResult,
+  ShellRequestHandles,
 } from "./serve-shell-request.js";

package/src/testing/index.ts

@@ -61,6 +61,25 @@ export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 
+// On-demand prerender: an in-memory WritablePrerenderStore fake for unit-testing
+// code that calls router.prerender(). Dep-free (a plain Map), so it stays on this
+// React/RSC-free barrel. See @rangojs/router/prerender for the store contracts.
+export { createMemoryPrerenderStore } from "../prerender/memory-prerender-store.js";
+export type {
+  MemoryPrerenderStore,
+  MemoryPrerenderStoreOptions,
+} from "../prerender/memory-prerender-store.js";
+export type {
+  WritablePrerenderStore,
+  PrerenderStoredEntry,
+  PrerenderKey,
+} from "../prerender/writable-store.js";
+export type {
+  PrerenderConfig,
+  PrerenderResult,
+  PrerenderWarmCaches,
+} from "../prerender/on-demand.js";
+
 export {
   assertCacheStatus,
   assertCacheDecision,
@@ -98,6 +117,9 @@ export type {
   ShellStatusTarget,
 } from "./shell-status.js";
 
+export { setBuildVersions } from "./build-versions.js";
+export type { BuildVersions, RouterVersions } from "./build-versions.js";
+
 export { collectHandle } from "./collect-handle.js";
 
 export { withLocationStateKey } from "./location-state-key.js";

package/src/testing/internal/context.ts

@@ -19,6 +19,7 @@ import { normalizeBasename } from "../../router/basename.js";
 import {
   seedVariables,
   resolveSeededStateCookieName,
+  seededVersions,
   type VarsInit,
   type StateCookieSeed,
 } from "./seed-vars.js";
@@ -164,7 +165,7 @@ export function createTestRequestContext<TEnv>(
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
     stateCookieName,
-    version: opts.stateCookie?.version,
+    versions: seededVersions(opts.stateCookie),
   });
   if (opts.basename !== undefined)
     ctx._basename = normalizeBasename(opts.basename);

package/src/testing/internal/seed-vars.ts

@@ -8,6 +8,7 @@
  */
 import { contextSet, type ContextVar } from "../../context-var.js";
 import { resolveStateCookieName } from "../../router/state-cookie-name.js";
+import { uniformVersions, type RouterVersions } from "../../router-versions.js";
 
 export interface StateCookieSeed {
   /**
@@ -22,8 +23,10 @@ export interface StateCookieSeed {
    */
   routerId?: string;
   /**
-   * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
-   * Defaults to `"0"` (resolved inside createRequestContext).
+   * The app's version, as `createRouter({ version })` would set it: the
+   * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
+   * store keys with. Defaults to `"0"` for the prefix (resolved inside
+   * createRequestContext) and to the build versions for the store.
    */
   version?: string;
 }
@@ -32,6 +35,15 @@ export function resolveSeededStateCookieName(seed?: StateCookieSeed): string {
   return resolveStateCookieName(seed?.prefix, seed?.routerId ?? "router_0");
 }
 
+/** The request context's `versions` for a seeded `stateCookie.version`. */
+export function seededVersions(
+  seed?: StateCookieSeed,
+): RouterVersions | undefined {
+  return seed?.version === undefined
+    ? undefined
+    : uniformVersions(seed.version);
+}
+
 export type VarsInit =
   | Record<string, unknown>
   | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;

package/src/testing/internal/server-modules.ts

@@ -0,0 +1,32 @@
+/**
+ * Server reference modules a test registered, by the module id the action's
+ * `$$id` (`<module id>#<export name>`) names. The plugin-rsc stub's module
+ * loader reads this when decodeAction resolves a no-JS form POST to its action.
+ */
+const SERVER_MODULES: Map<string, Record<string, unknown>> = new Map();
+
+/**
+ * Register `exports` as the server module `id`, merging into an earlier call.
+ * The module object is kept and mutated: the stub's require is memoized per
+ * id, so a later export must appear on the object it first returned.
+ */
+export function registerServerModule(
+  id: string,
+  exports: Record<string, unknown>,
+): void {
+  const existing = SERVER_MODULES.get(id);
+  if (existing) Object.assign(existing, exports);
+  else SERVER_MODULES.set(id, { ...exports });
+}
+
+/** The module a decoded server reference resolves to. */
+export function loadServerModule(id: string): Record<string, unknown> {
+  const found = SERVER_MODULES.get(id);
+  if (!found) {
+    throw new Error(
+      `plugin-rsc stub: server reference module "${id}" is not loadable in a test. ` +
+        "Build the form with createActionForm() so its action is registered.",
+    );
+  }
+  return found;
+}

package/src/testing/location-state-key.ts

@@ -1,12 +1,11 @@
 import {
+  isLocationStateKey,
+  LOCATION_STATE_KEY_PREFIX,
+  LOCATION_STATE_KEY_SUFFIX_SEPARATOR,
   peekLocationStateKey,
   type LocationStateDefinition,
 } from "../browser/react/location-state-shared.js";
 
-// Typed history.state slots must carry this prefix: buildHistoryState spreads
-// only `__rsc_ls_*` keys onto history.state (history-state.ts).
-const KEY_PREFIX = "__rsc_ls_";
-
 let syntheticKeyCounter = 0;
 
 /**
@@ -16,11 +15,15 @@ let syntheticKeyCounter = 0;
  * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
  *
  * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
- *   (a name that already starts with `__rsc_ls_` is used as-is).
+ *   (a name that already starts with `__rsc_ls_` is used as-is). A definition
+ *   with `clearOnReload` appends its suffix, so read the stored key back from
+ *   `GridState.__rsc_ls_key` (`__rsc_ls_GridState~r`).
  * - Without a name, a key already set (by the plugin or an earlier call) is
  *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
  *   which then stays on it.
  *
+ * A name may not contain "~": that separator is reserved for the suffix.
+ *
  * Returns the definition.
  *
  * @example
@@ -35,11 +38,18 @@ export function withLocationStateKey<
   TDefinition extends LocationStateDefinition<any, any>,
 >(definition: TDefinition, name?: string): TDefinition {
   if (name !== undefined) {
-    definition.__rsc_ls_key = name.startsWith(KEY_PREFIX)
+    if (name.includes(LOCATION_STATE_KEY_SUFFIX_SEPARATOR)) {
+      throw new Error(
+        `withLocationStateKey: "${name}" contains "${LOCATION_STATE_KEY_SUFFIX_SEPARATOR}", ` +
+          "which is reserved for the key suffix of the `clearOnReload` option. " +
+          "Pass the name without a suffix; the definition appends its own.",
+      );
+    }
+    definition.__rsc_ls_key = isLocationStateKey(name)
       ? name
-      : KEY_PREFIX + name;
+      : LOCATION_STATE_KEY_PREFIX + name;
   } else if (!peekLocationStateKey(definition)) {
-    definition.__rsc_ls_key = `${KEY_PREFIX}test_${syntheticKeyCounter++}`;
+    definition.__rsc_ls_key = `${LOCATION_STATE_KEY_PREFIX}test_${syntheticKeyCounter++}`;
   }
   return definition;
 }

package/src/testing/render-handler.ts

@@ -37,6 +37,7 @@ import type { LoaderDefinition } from "../types.js";
 import {
   seedVariables,
   resolveSeededStateCookieName,
+  seededVersions,
   type VarsInit,
   type StateCookieSeed,
 } from "./internal/seed-vars.js";
@@ -253,7 +254,7 @@ export async function renderHandler<TEnv = any>(
     variables: seedVariables({}, opts.vars),
     build: opts.build,
     stateCookieName,
-    version: opts.stateCookie?.version,
+    versions: seededVersions(opts.stateCookie),
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
     themeConfig: