@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/testing/internal/context.ts

@@ -28,8 +28,6 @@ import type { CacheProfile } from "../../cache/profile-registry.js";
 
 const DEFAULT_ORIGIN = "http://localhost/";
 
-// VarsInit + seedVariables live in ./seed-vars.js (react-server-safe) so the
-// Flight tier can seed vars too; re-exported here for existing importers.
 export type { VarsInit, StateCookieSeed };
 export { seedVariables };
 
@@ -39,10 +37,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);
+  return typeof request === "string"
+    ? new Request(new URL(request, DEFAULT_ORIGIN), init)
+    : new Request(DEFAULT_ORIGIN, init);
 }
 
 export interface CreateTestContextOptions<TEnv> {
@@ -146,10 +143,6 @@ export function createTestRequestContext<TEnv>(
   const request = toRequest(opts.request, opts.requestInit);
   const url = new URL(request.url);
   const variables = seedVariables(opts.variables ?? {}, opts.vars);
-  // Always seed a resolved name so invalidateClientCache() rotates (and emits
-  // the Set-Cookie) like production instead of no-opping; opts.stateCookie
-  // customizes the name/version. Surfaced on the result so a consumer asserts
-  // the rotation against the same name without recomputing it.
   const stateCookieName = resolveSeededStateCookieName(opts.stateCookie);
   const ctx = createRequestContext<TEnv>({
     env: (opts.env ?? {}) as TEnv,
@@ -174,10 +167,6 @@ export function createTestRequestContext<TEnv>(
       opts.params ?? {},
     ) as RequestContext<TEnv>["reverse"];
   }
-  // ctx.reverse is assigned the routeMap-scoped reverse (string-accepting) above;
-  // expose it through the relaxed type so a test reverses a local route name
-  // without casting. The runtime value matches; RequestContext's reverse is
-  // declared against the narrower global route-name union, hence the cast.
   return {
     ctx: ctx as unknown as TestRequestContextObject<TEnv>,
     request,
@@ -246,13 +235,6 @@ export interface RunInRequestContextResult<T> {
   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()`). Headers are
- * snapshotted separately from the final {@link Response} (via
- * {@link headersToObject}) so a thrown redirect's `Location` is included.
- */
 export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   cookies: Record<string, string>;
   locationState: Record<string, unknown>;
@@ -263,12 +245,6 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   };
 }
 
-/**
- * The response headers as a plain `{ name: value }` object, EXCLUDING
- * `set-cookie` (surfaced parsed on `cookies`). Names are lowercased (HTTP header
- * names are case-insensitive). Read from the final response so a thrown
- * redirect's `Location` and any `ctx.header(...)` both appear.
- */
 export function headersToObject(headers: Headers): Record<string, string> {
   const out: Record<string, string> = {};
   headers.forEach((value, name) => {
@@ -278,14 +254,6 @@ export function headersToObject(headers: Headers): Record<string, string> {
   return out;
 }
 
-/**
- * Build the observable response from what the run accumulated on `ctx.res`. When
- * `fn` threw a `Response` (a `redirect()`/`notFound()`), that Response IS the
- * response — merge the accumulated Set-Cookie/other headers into it (the
- * framework does this when it catches the thrown Response in production), with
- * its status/Location preserved. Otherwise snapshot the stub (status + headers).
- * The `Response`/`Headers` constructors copy, so the result is immutable.
- */
 export function buildRunResponse<TEnv>(
   ctx: RequestContext<TEnv>,
   thrown: unknown,
@@ -305,14 +273,6 @@ export function buildRunResponse<TEnv>(
   return new Response(null, { status: stub.status, headers: stub.headers });
 }
 
-/**
- * Snapshot the shared run-result envelope fields (everything except the primary
- * value) from what a run left on `ctx`: the captured `thrown`, the merged
- * `response`, the effective `cookies`/`headers` views, the `locationState`, and
- * the resolved `stateCookieName`. Shared by `runInRequestContext` and
- * `runLoaderResult` so the snapshot sequence lives once; each spreads it next to
- * its own primary field (`result` / `data`).
- */
 export function buildRunSnapshot<TEnv>(
   ctx: RequestContext<TEnv>,
   thrown: unknown,
@@ -382,8 +342,6 @@ export async function runInRequestContext<T, TEnv = unknown>(
   try {
     result = (await runWithRequestContext(ctx, () => fn(ctx))) as T;
   } catch (error) {
-    // Capture (do NOT re-throw): a redirect/notFound action throws its Response
-    // on the SUCCESS path, and its cookie/flash output must stay observable.
     thrown = error;
   }
   return { result, ...buildRunSnapshot(ctx, thrown, stateCookieName) };

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

@@ -9,14 +9,6 @@
 import { contextSet, type ContextVar } from "../../context-var.js";
 import { resolveStateCookieName } from "../../router/state-cookie-name.js";
 
-/**
- * Seed for the rango state cookie a handler/action/loader rotates when it calls
- * `invalidateClientCache()`. Production always resolves a name at router init
- * (so rotation always fires); the test stub did not, so the call silently
- * no-opped. Supplying this (or accepting the defaults) closes that gap. Lives in
- * the react-server-safe seed module so both the node tier (createTestRequestContext)
- * and the Flight tier (renderHandler) share one shape and one default.
- */
 export interface StateCookieSeed {
   /**
    * Cookie-name prefix, sanitized then composed with `routerId` exactly like
@@ -36,37 +28,19 @@ export interface StateCookieSeed {
   version?: string;
 }
 
-/**
- * Resolve the state cookie name a seed maps to, mirroring `createRouter`'s
- * `resolveStateCookieName` so a test asserts the SAME name production writes.
- * The default routerId `"router_0"` matches a single default router.
- */
 export function resolveSeededStateCookieName(seed?: StateCookieSeed): string {
   return resolveStateCookieName(seed?.prefix, seed?.routerId ?? "router_0");
 }
 
-/**
- * Initializer for seeded context variables (as a prior middleware would have
- * set, or a server component would read during render). 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]>;
 
-/**
- * Preload variables as if set by upstream middleware (or visible to a rendered
- * server tree). 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<

package/src/testing/render-handler.ts

@@ -31,6 +31,7 @@ import {
 import { createHandlerContext } from "../router/handler-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { isHandle, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import type { HandlerContext } from "../types/handler-context.js";
 import type { LoaderDefinition } from "../types.js";
 import {
@@ -41,7 +42,13 @@ import {
 } from "./internal/seed-vars.js";
 
 export type { StateCookieSeed } from "./internal/seed-vars.js";
-import { assertNoLegacyUrlOption, serializeNodeToFlight } from "./flight.js";
+import {
+  assertNoLegacyUrlOption,
+  serializeNodeToFlight,
+  isServerOnlyStubError,
+} from "./flight.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
 import {
   deserializeFlight,
   makeClientManifest,
@@ -94,6 +101,19 @@ export interface RenderHandlerOptions<TEnv = any> {
    * `result.stateCookieName`.
    */
   stateCookie?: StateCookieSeed;
+  /**
+   * Segment cache store backing a `"use cache"` function the handler invokes
+   * (e.g. `new MemorySegmentCacheStore()`). Without it, `registerCachedFunction`
+   * takes the uncached bypass and the cached path is NOT exercised (the runtime
+   * emits a one-time warning under the test runner). Pair with `cacheProfiles`
+   * so the profile the directive names resolves.
+   */
+  cacheStore?: SegmentCacheStore;
+  /**
+   * Cache profiles in the `createRouter({ cacheProfiles })` shape, required for
+   * `"use cache: profileName"` resolution once a `cacheStore` is wired.
+   */
+  cacheProfiles?: Record<string, CacheProfile>;
 }
 
 /** Result of {@link renderHandler}. */
@@ -134,11 +154,6 @@ export interface RenderHandlerResult {
  */
 class RenderHandlerSetupError extends Error {}
 
-// Local copy (not imported from internal/context.ts): that module is the NODE
-// tier and is deliberately NOT react-server-safe (the reason seed-vars.ts was
-// split out), and render-handler ships from the react-server ./testing/flight
-// entry. A 6-line pure projection is cheaper to duplicate than to route a
-// shared util across that boundary.
 function headersToObject(headers: Headers): Record<string, string> {
   const out: Record<string, string> = {};
   headers.forEach((value, name) => {
@@ -147,23 +162,6 @@ function headersToObject(headers: Headers): Record<string, string> {
   return out;
 }
 
-/**
- * Detect the server-only-API stub throw: when a handler/component imports
- * getRequestContext()/cookies()/etc. from the BARE `@rangojs/router` specifier
- * (the out-of-react-server stub in index.ts) instead of the react-server build.
- * In an rsc test this happens when the vitest.rsc.config.ts `resolve.alias` does
- * not map the bare specifier to `index.rsc.ts` (the `rangoTestAliases` preset).
- * The dual-substring match keeps a legitimate handler throw from being
- * reclassified as a setup error.
- */
-function isServerOnlyStubError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    error.message.includes("is only available from") &&
-    error.message.includes("react-server")
-  );
-}
-
 function toRequest(
   request: Request | string | undefined,
   headers?: HeadersInit,
@@ -175,20 +173,6 @@ function toRequest(
   return new Request(DEFAULT_URL, { headers });
 }
 
-/**
- * Build the result `response` from the request-context stub and, when present,
- * the Response the handler returned or threw (`source`). The stub cookies and
- * headers are merged in (Set-Cookie appended to preserve duplicates, other stub
- * headers filled in without clobbering the source), mirroring dispatch.ts's
- * rewrap.
- *
- * The source's BODY is carried over (not dropped): a response route returns a
- * `new Response(JSON.stringify(...))`, so callers reach for
- * `await result.response.text()`/`.json()`. Pre-fix this rewrapped to
- * `new Response(null, ...)` and the body was lost irrecoverably. A body is a
- * single-use stream; `source` is not read again here or by renderHandler, so
- * handing its body to the new Response is safe.
- */
 function buildResponse(reqCtx: RequestContext<any>, source: unknown): Response {
   const stub = reqCtx.res;
   if (source instanceof Response) {
@@ -231,9 +215,6 @@ export async function renderHandler<TEnv = any>(
   if (opts.clientComponents) registerClientComponents(opts.clientComponents);
   const request = toRequest(opts.request, opts.headers);
   const url = new URL(request.url);
-  // Seed a resolved name so a handler calling invalidateClientCache() rotates
-  // (emits the Set-Cookie) like production; opts.stateCookie customizes it. Also
-  // surfaced on the result so a consumer asserts the rotation without recomputing.
   const stateCookieName = resolveSeededStateCookieName(opts.stateCookie);
   const reqCtx = createRequestContext<TEnv>({
     env: (opts.env ?? {}) as TEnv,
@@ -242,6 +223,8 @@ export async function renderHandler<TEnv = any>(
     variables: seedVariables({}, opts.vars),
     stateCookieName,
     version: opts.stateCookie?.version,
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
   });
 
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
@@ -253,7 +236,11 @@ export async function renderHandler<TEnv = any>(
   let didThrow = false;
 
   await runWithRequestContext(reqCtx as RequestContext<TEnv>, async () => {
-    setRequestContextParams(opts.params ?? {}, opts.routeName);
+    // Scope the request-context reverse to opts.routeMap too (not just the
+    // handler context built below), so a nested server component reading
+    // getRequestContext().reverse() resolves against the same map as the
+    // handler's ctx.reverse -- matching renderToFlightString/renderServerTree.
+    setRequestContextParams(opts.params ?? {}, opts.routeName, opts.routeMap);
     const hctx = createHandlerContext<TEnv>(
       opts.params ?? {},
       reqCtx.request,
@@ -264,17 +251,11 @@ export async function renderHandler<TEnv = any>(
       opts.routeMap ?? {},
       opts.routeName,
     );
-    // Seed ctx.use: a handle returns a push fn that RECORDS (so ctx.use(Meta)
-    // doesn't crash and pushes are assertable); a loader returns its seeded data
-    // (no real loader run).
     (hctx as { use: unknown }).use = (item: unknown) => {
       if (isHandle(item)) {
         const handle = item as Handle<any, any>;
-        return (dataOrFn: unknown) => {
-          // Mirror production's push fn (loader-resolution.ts): a FUNCTION arg
-          // (ctx.use(Meta)(() => fetchMeta())) is CALLED and its result is
-          // recorded, not the function itself. An async callback records the
-          // promise it returns, same as production (which does not await it).
+        // withDefer attaches .defer() so the harness mirrors production's push.
+        return withDefer((dataOrFn: unknown) => {
           const value =
             typeof dataOrFn === "function"
               ? (dataOrFn as () => unknown)()
@@ -282,7 +263,7 @@ export async function renderHandler<TEnv = any>(
           const pushed = handlePushes.get(handle) ?? [];
           pushed.push(value);
           handlePushes.set(handle, pushed);
-        };
+        });
       }
       if (loaderSeeds.has(item)) return loaderSeeds.get(item);
       throw new RenderHandlerSetupError(
@@ -294,8 +275,6 @@ export async function renderHandler<TEnv = any>(
 
     try {
       out = await handler(hctx as HandlerContext<any, TEnv>);
-      // Serialize the RSC in THIS context, so nested async server components see
-      // getRequestContext()/cookies()/vars while they render.
       if (out !== undefined && !(out instanceof Response)) {
         flight = await serializeNodeToFlight(
           out as ReactNode,
@@ -304,13 +283,7 @@ export async function renderHandler<TEnv = any>(
         );
       }
     } catch (error) {
-      // A harness misconfiguration (unseeded loader) is the consumer's mistake —
-      // surface it as a rejection, not as a captured handler throw.
       if (error instanceof RenderHandlerSetupError) throw error;
-      // Same for the server-only-API stub throw: the handler read
-      // getRequestContext()/cookies() but the bare `@rangojs/router` resolved to
-      // the throwing stub. Rethrow LOUDLY with the fix, instead of silently
-      // capturing it (which surfaces as an opaque tree:undefined + bare throw).
       if (isServerOnlyStubError(error)) {
         throw new RenderHandlerSetupError(
           `renderHandler: the handler called a server-only API (getRequestContext/cookies/...) ` +
@@ -320,8 +293,6 @@ export async function renderHandler<TEnv = any>(
             `Original: ${(error as Error).message}`,
         );
       }
-      // Otherwise captured, NOT re-thrown: a handler's success path is often
-      // `throw redirect(...)`; its cookies/flash must stay observable.
       didThrow = true;
       thrown = error;
     }
@@ -342,7 +313,6 @@ export async function renderHandler<TEnv = any>(
       }
     )._locationState ?? [],
   );
-  // Deserialize outside the context (the client deserializer needs no ctx).
   const tree =
     flight !== undefined ? await deserializeFlight(flight) : undefined;