@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/testing/internal/context.ts

@@ -12,10 +12,16 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { drainOnResponseCallbacks } from "../../rsc/helpers.js";
 import { resolveLocationStateEntries } from "../../browser/react/location-state-shared.js";
 import { createReverseFunction } from "../../router/handler-context.js";
 import { normalizeBasename } from "../../router/basename.js";
-import { contextSet, type ContextVar } from "../../context-var.js";
+import {
+  seedVariables,
+  resolveSeededStateCookieName,
+  type VarsInit,
+  type StateCookieSeed,
+} from "./seed-vars.js";
 import type { ThemeConfig } from "../../theme/types.js";
 import { resolveThemeConfig } from "../../theme/constants.js";
 import type { SegmentCacheStore } from "../../cache/types.js";
@@ -23,15 +29,8 @@ import type { CacheProfile } from "../../cache/profile-registry.js";
 
 const DEFAULT_ORIGIN = "http://localhost/";
 
-/**
- * Initializer for seeded context variables (as a prior middleware would have
- * set). Either a plain object keyed by var name (the common, best-inferring
- * form: `{ user: u }`) or a list of `[key, value]` tuples where the key may be a
- * `createVar()` handle or a string (`[[userVar, u], ["flag", true]]`).
- */
-export type VarsInit =
-  | Record<string, unknown>
-  | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
+export type { VarsInit, StateCookieSeed };
+export { seedVariables };
 
 /** Normalize a Request | string | undefined into a concrete Request. */
 export function toRequest(
@@ -39,32 +38,9 @@ export function toRequest(
   init?: RequestInit,
 ): Request {
   if (request instanceof Request) return request;
-  if (typeof request === "string") {
-    return new Request(new URL(request, DEFAULT_ORIGIN), init);
-  }
-  return new Request(DEFAULT_ORIGIN, init);
-}
-
-/**
- * Preload variables as if set by upstream middleware. Accepts entries keyed by
- * either a ContextVar (from createVar) or a string, matching ctx.set().
- */
-export function seedVariables(
-  variables: Record<string, unknown>,
-  vars?: VarsInit,
-): Record<string, unknown> {
-  if (!vars) return variables;
-  // Array/iterable form -> use the tuples as-is; plain object -> its entries.
-  const entries: Iterable<readonly [ContextVar<unknown> | string, unknown]> =
-    Symbol.iterator in (vars as object)
-      ? (vars as ReadonlyArray<
-          readonly [ContextVar<unknown> | string, unknown]
-        >)
-      : Object.entries(vars as Record<string, unknown>);
-  for (const [key, value] of entries) {
-    contextSet(variables, key as ContextVar<unknown>, value);
-  }
-  return variables;
+  return typeof request === "string"
+    ? new Request(new URL(request, DEFAULT_ORIGIN), init)
+    : new Request(DEFAULT_ORIGIN, init);
 }
 
 export interface CreateTestContextOptions<TEnv> {
@@ -108,13 +84,49 @@ export interface CreateTestContextOptions<TEnv> {
    * `{ themes: [...] }`) to exercise a handler that reads them.
    */
   theme?: ThemeConfig | true;
+  /**
+   * Customize the rango state cookie that `invalidateClientCache()` rotates.
+   * The name is ALWAYS seeded (default `rango-state_router_0`) so a call to
+   * `invalidateClientCache()` rotates and emits the `Set-Cookie` exactly as in
+   * production, rather than silently no-opping. Override `prefix`/`routerId` to
+   * match your `createRouter({ stateCookiePrefix, id })` so the test asserts the
+   * same name, or `version` (the build identifier prefixed to the rotated
+   * `{version}:{timestamp}` value, default `"0"`). Assert
+   * `response.headers.getSetCookie()` against the resolved `stateCookieName`
+   * (returned by `runInRequestContext`).
+   */
+  stateCookie?: StateCookieSeed;
 }
 
+/**
+ * The seeded RequestContext with its `reverse` RELAXED to accept any route NAME
+ * from the `routeMap` you passed, rather than the global `Rango.GeneratedRouteMap`
+ * union — so reversing a test-only route name is not a type error (it works at
+ * runtime; the names come from your `routeMap`). Mirrors runLoader's
+ * `TestLoaderContext.reverse`. Everything else is the real `RequestContext`.
+ */
+export type TestRequestContextObject<TEnv> = Omit<
+  RequestContext<TEnv>,
+  "reverse"
+> & {
+  reverse: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string;
+};
+
 export interface TestRequestContext<TEnv> {
-  ctx: RequestContext<TEnv>;
+  ctx: TestRequestContextObject<TEnv>;
   request: Request;
   url: URL;
   variables: Record<string, unknown>;
+  /**
+   * The resolved rango state cookie name seeded into the context (default
+   * `rango-state_router_0`, or composed from `opts.stateCookie`). The name a
+   * call to `invalidateClientCache()` rotates.
+   */
+  stateCookieName: string;
 }
 
 /**
@@ -132,6 +144,7 @@ export function createTestRequestContext<TEnv>(
   const request = toRequest(opts.request, opts.requestInit);
   const url = new URL(request.url);
   const variables = seedVariables(opts.variables ?? {}, opts.vars);
+  const stateCookieName = resolveSeededStateCookieName(opts.stateCookie);
   const ctx = createRequestContext<TEnv>({
     env: (opts.env ?? {}) as TEnv,
     request,
@@ -141,6 +154,8 @@ export function createTestRequestContext<TEnv>(
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
     cacheStore: opts.cacheStore,
     cacheProfiles: opts.cacheProfiles,
+    stateCookieName,
+    version: opts.stateCookie?.version,
   });
   if (opts.basename !== undefined)
     ctx._basename = normalizeBasename(opts.basename);
@@ -153,7 +168,13 @@ export function createTestRequestContext<TEnv>(
       opts.params ?? {},
     ) as RequestContext<TEnv>["reverse"];
   }
-  return { ctx, request, url, variables };
+  return {
+    ctx: ctx as unknown as TestRequestContextObject<TEnv>,
+    request,
+    url,
+    variables,
+    stateCookieName,
+  };
 }
 
 /**
@@ -162,14 +183,28 @@ export function createTestRequestContext<TEnv>(
  * assert what an action produced.
  */
 export interface RunInRequestContextResult<T> {
-  /** The value `fn` returned (awaited if it returned a promise). */
-  result: T;
   /**
-   * A Response carrying the status, headers, and Set-Cookie cookies the run set
-   * on the request context (via `cookies().set()`, `ctx.header()`, etc.).
-   * Assert Set-Cookie with `response.headers.getSetCookie()`. This is the
-   * accumulated side-channel, NOT a Response `fn` itself returned (that is
-   * `result`).
+   * The value `fn` returned (awaited), or `undefined` if `fn` threw — in which
+   * case the thrown value is on {@link thrown}. The snapshot below is captured
+   * either way.
+   */
+  result: T | undefined;
+  /**
+   * The value `fn` threw, or `undefined` if it returned normally. Commonly a
+   * `Response` from `throw redirect(...)` / `throw notFound()` — the dominant
+   * cookie+flash case is an action that sets them then throws a redirect — so
+   * this (and the snapshot below) is observable WITHOUT wrapping the action in
+   * your own try/catch. NOTE: the value is captured, NOT re-thrown; assert on it
+   * for a throwing action.
+   */
+  thrown: unknown;
+  /**
+   * A Response carrying the status, headers, and Set-Cookie the run set (via
+   * `cookies().set()`, `ctx.header()`, etc.). Assert Set-Cookie with
+   * `response.headers.getSetCookie()`. When `fn` threw a `Response` (a redirect),
+   * THIS is that Response with the accumulated Set-Cookie/headers merged in
+   * (mirroring how the framework merges them in production), so a redirect's
+   * Location AND the cookies it set are both observable here.
    */
   response: Response;
   /**
@@ -177,6 +212,14 @@ export interface RunInRequestContextResult<T> {
    * anything the run set or deleted (last-write-wins), as `{ name: value }`.
    */
   cookies: Record<string, string>;
+  /**
+   * The response headers the run set (via `ctx.header(...)`, plus a thrown
+   * redirect's `Location`), as a plain `{ name: value }` object — the same view
+   * as `response.headers`, but assertable like `cookies`/`locationState`.
+   * EXCLUDES `set-cookie` (use `cookies`, or `response.headers.getSetCookie()`).
+   * Header names are lowercased (HTTP headers are case-insensitive).
+   */
+  headers: Record<string, string>;
   /**
    * Location state the run set via `ctx.setLocationState()` / `redirect({ state })`,
    * resolved to the flat `{ key: value }` shape the client reads off
@@ -184,13 +227,15 @@ export interface RunInRequestContextResult<T> {
    * is assertable at the unit layer.
    */
   locationState: Record<string, unknown>;
+  /**
+   * The resolved rango state cookie name seeded into the run (default
+   * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert an
+   * action's `invalidateClientCache()` rotation against it without recomputing:
+   * `response.headers.getSetCookie().some((c) => c.startsWith(stateCookieName + "="))`.
+   */
+  stateCookieName: string;
 }
 
-/**
- * Snapshot the observable effects a run left on `ctx` (cookies + location
- * state). Reads the fields directly off the ctx object, so it works both inside
- * and outside the AsyncLocalStorage scope (no `getRequestContext()`).
- */
 export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   cookies: Record<string, string>;
   locationState: Record<string, unknown>;
@@ -201,6 +246,74 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   };
 }
 
+export function headersToObject(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, name) => {
+    if (name.toLowerCase() === "set-cookie") return;
+    out[name] = value;
+  });
+  return out;
+}
+
+export function buildRunResponse<TEnv>(
+  ctx: RequestContext<TEnv>,
+  thrown: unknown,
+): Response {
+  const stub = ctx.res;
+  let response: Response;
+  if (thrown instanceof Response) {
+    const headers = new Headers(thrown.headers);
+    for (const cookie of stub.headers.getSetCookie()) {
+      headers.append("set-cookie", cookie);
+    }
+    stub.headers.forEach((value, name) => {
+      if (name.toLowerCase() === "set-cookie") return;
+      if (!headers.has(name)) headers.set(name, value);
+    });
+    response = new Response(null, { status: thrown.status, headers });
+  } else {
+    response = new Response(null, {
+      status: stub.status,
+      headers: stub.headers,
+    });
+  }
+  // Mirror production response finalization: every response-finalization path
+  // drains ctx.onResponse() callbacks (createResponseWithMergedHeaders /
+  // finalizeResponse). buildRunResponse runs AFTER runWithRequestContext has
+  // exited, so _getRequestContext() (and finalizeResponse) would no-op — drain
+  // ctx._onResponseCallbacks explicitly. Reuses the SAME production drain
+  // (swap-before-iterate + external-redirect brand preservation) so a callback's
+  // header mutations / returned replacement Response are reflected on the result
+  // the harness surfaces. rsc/helpers is plugin-rsc-free on its eager graph
+  // (dispatch.ts in this same testing barrel already statically imports from it).
+  // drainOnResponseCallbacks is typed against the default-env RequestContext (it
+  // touches only the env-agnostic _onResponseCallbacks); the harness ctx is
+  // RequestContext<TEnv> — assignable in the router's own tsc but not when a
+  // consumer pins a concrete Env, so cast to the param type.
+  return drainOnResponseCallbacks(
+    ctx as Parameters<typeof drainOnResponseCallbacks>[0],
+    response,
+  );
+}
+
+export function buildRunSnapshot<TEnv>(
+  ctx: RequestContext<TEnv>,
+  thrown: unknown,
+  stateCookieName: string,
+): {
+  thrown: unknown;
+  response: Response;
+  cookies: Record<string, string>;
+  headers: Record<string, string>;
+  locationState: Record<string, unknown>;
+  stateCookieName: string;
+} {
+  const { cookies, locationState } = snapshotRunEffects(ctx);
+  const response = buildRunResponse(ctx, thrown);
+  const headers = headersToObject(response.headers);
+  return { thrown, response, cookies, headers, locationState, stateCookieName };
+}
+
 /**
  * Build a seeded RequestContext (via {@link createTestRequestContext}) and run
  * `fn` inside it, so code under test that calls `getRequestContext()`,
@@ -214,16 +327,19 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
  * still needs a real request context to read the cookie and resolve
  * `getRequestContext()`.
  *
- * Returns `{ result, response, cookies, locationState }` so the action's OUTPUT
- * (Set-Cookie, headers, flash) is assertable without casting through the
- * `@internal` `ctx.res` / `ctx.cookies()`. `fn` may be async — the context
- * stays active across its awaits (AsyncLocalStorage), and the snapshot is taken
- * after it settles.
+ * Returns `{ result, thrown, response, cookies, headers, locationState }` so the
+ * action's OUTPUT (Set-Cookie, response headers, flash) is assertable without
+ * casting through the `@internal` `ctx.res` / `ctx.cookies()`. `fn` may be async — the context stays
+ * active across its awaits (AsyncLocalStorage), and the snapshot is captured
+ * whether `fn` returns OR throws. The throw path matters: the most common
+ * cookie+flash case is an auth action that sets a cookie + flash then
+ * `throw redirect(...)` on success — the thrown redirect is on `thrown` (NOT
+ * re-thrown) and its Location plus the cookies are on `response`/`cookies`.
  *
  * @example
  * ```ts
- * const { result, cookies, response } = await runInRequestContext(
- *   () => loginAction(input),
+ * const { result, cookies, response, thrown } = await runInRequestContext(
+ *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
  *   {
  *     env,
  *     request: new Request("https://app.test/", {
@@ -232,6 +348,8 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
  *   },
  * );
  * expect(cookies.session).toBe("new-token");
+ * expect(headers.location).toBe("/app"); // response headers as a plain object
+ * expect((thrown as Response).headers.get("Location")).toBe("/app");
  * expect(response.headers.getSetCookie()).toContainEqual(
  *   expect.stringContaining("session="),
  * );
@@ -241,15 +359,13 @@ export async function runInRequestContext<T, TEnv = unknown>(
   fn: (ctx: RequestContext<TEnv>) => T | Promise<T>,
   opts: CreateTestContextOptions<TEnv> = {},
 ): Promise<RunInRequestContextResult<T>> {
-  const { ctx } = createTestRequestContext<TEnv>(opts);
-  const result = (await runWithRequestContext(ctx, () => fn(ctx))) as T;
-  const { cookies, locationState } = snapshotRunEffects(ctx);
-  // Snapshot the accumulated response from the stub directly (status + headers,
-  // incl. Set-Cookie). The Response constructor copies the Headers, so this is
-  // an immutable snapshot independent of later ctx mutations.
-  const response = new Response(null, {
-    status: ctx.res.status,
-    headers: ctx.res.headers,
-  });
-  return { result, response, cookies, locationState };
+  const { ctx, stateCookieName } = createTestRequestContext<TEnv>(opts);
+  let result: T | undefined;
+  let thrown: unknown;
+  try {
+    result = (await runWithRequestContext(ctx, () => fn(ctx))) as T;
+  } catch (error) {
+    thrown = error;
+  }
+  return { result, ...buildRunSnapshot(ctx, thrown, stateCookieName) };
 }

package/src/testing/internal/flight-client-globals.ts

@@ -0,0 +1,30 @@
+/**
+ * Side-effect module: define the webpack-style globals the vendored
+ * react-server-dom CLIENT deserializer reads at module-eval time.
+ *
+ * In a real app the plugin-rsc Vite plugin rewrites `__webpack_require__` ->
+ * `__vite_rsc_require__` and `__webpack_require__.u` -> `({}).u`
+ * (@vitejs/plugin-rsc `core/plugin.js`). That transform does NOT run in a bare
+ * Vitest process, so the vendored client's free `__webpack_require__` /
+ * `__webpack_chunk_load__` references would be undefined. We provide minimal
+ * shims: `__webpack_require__` routes to the loader installed via
+ * `setRequireModule`, and `__webpack_chunk_load__` is a no-op (renderServerTree
+ * serializes with empty `chunks`, so no chunk fetch ever happens).
+ *
+ * MUST be imported (for side effect) BEFORE `@vitejs/plugin-rsc/react/browser`,
+ * which is why flight-tree.ts lists it first.
+ */
+const g = globalThis as unknown as {
+  __webpack_require__?: ((id: string) => unknown) & { u?: unknown };
+  __webpack_chunk_load__?: (chunkId: string) => Promise<unknown>;
+  __vite_rsc_client_require__?: (id: string) => unknown;
+};
+
+if (!g.__webpack_require__) {
+  g.__webpack_require__ = (id: string) => g.__vite_rsc_client_require__!(id);
+}
+if (!g.__webpack_chunk_load__) {
+  g.__webpack_chunk_load__ = async () => {};
+}
+
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * Variable seeding shared by the node/DOM testing tier (internal/context.ts)
+ * AND the react-server Flight tier (flight.ts). Depends only on the
+ * dependency-free `context-var` module and the env-agnostic state-cookie-name
+ * composition (no window/document), so it is safe to import under the
+ * `react-server` condition (unlike internal/context.ts, which pulls
+ * client/browser modules).
+ */
+import { contextSet, type ContextVar } from "../../context-var.js";
+import { resolveStateCookieName } from "../../router/state-cookie-name.js";
+
+export interface StateCookieSeed {
+  /**
+   * Cookie-name prefix, sanitized then composed with `routerId` exactly like
+   * `createRouter({ stateCookiePrefix })`. Defaults to `"rango-state"`.
+   */
+  prefix?: string;
+  /**
+   * Router id; the resolved name is `{sanitizedPrefix}_{sanitizedRouterId}`.
+   * Defaults to `"router_0"` (the name a single default router resolves to), so
+   * the default name is `rango-state_router_0`.
+   */
+  routerId?: string;
+  /**
+   * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
+   * Defaults to `"0"` (resolved inside createRequestContext).
+   */
+  version?: string;
+}
+
+export function resolveSeededStateCookieName(seed?: StateCookieSeed): string {
+  return resolveStateCookieName(seed?.prefix, seed?.routerId ?? "router_0");
+}
+
+export type VarsInit =
+  | Record<string, unknown>
+  | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
+
+export function seedVariables(
+  variables: Record<string, unknown>,
+  vars?: VarsInit,
+): Record<string, unknown> {
+  if (!vars) return variables;
+  const entries: Iterable<readonly [ContextVar<unknown> | string, unknown]> =
+    Symbol.iterator in (vars as object)
+      ? (vars as ReadonlyArray<
+          readonly [ContextVar<unknown> | string, unknown]
+        >)
+      : Object.entries(vars as Record<string, unknown>);
+  for (const [key, value] of entries) {
+    contextSet(variables, key as ContextVar<unknown>, value);
+  }
+  return variables;
+}