@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/dist/types/testing/internal/context.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Shared internals for the consumer testing primitives.
+ *
+ * Builds a real RequestContext via the same createRequestContext the RSC
+ * handler uses, with test-friendly defaults, so loaders and middleware run
+ * with production-fidelity context (cookies, headers, get/set, use, reverse)
+ * instead of a hand-rolled mock.
+ */
+import { type RequestContext } from "../../server/request-context.js";
+import { seedVariables, type VarsInit, type StateCookieSeed } from "./seed-vars.js";
+import type { ThemeConfig } from "../../theme/types.js";
+import type { SegmentCacheStore } from "../../cache/types.js";
+import type { CacheProfile } from "../../cache/profile-registry.js";
+export type { VarsInit, StateCookieSeed };
+export { seedVariables };
+/** Normalize a Request | string | undefined into a concrete Request. */
+export declare function toRequest(request: Request | string | undefined, init?: RequestInit): Request;
+export interface CreateTestContextOptions<TEnv> {
+    env?: TEnv;
+    request?: Request | string;
+    requestInit?: RequestInit;
+    /** Backing store for ctx.get()/ctx.set(); pre-seeded from `vars`. */
+    variables?: Record<string, unknown>;
+    /** Variables a prior middleware would have set (object or [key, value] list). */
+    vars?: VarsInit;
+    /** Route name -> pattern map enabling ctx.reverse() without global state. */
+    routeMap?: Record<string, string>;
+    routeName?: string;
+    params?: Record<string, string>;
+    /**
+     * Seed `ctx.build` (default false). Set `true` to unit-test middleware or a
+     * handler that branches on the build-time PPR shell-capture pass — e.g.
+     * `if (ctx.build) ctx.dynamic()`. Mirrors the synthetic build request the
+     * shell-capture producer creates; also makes `ctx.waitUntil()` inert, as at
+     * build time.
+     */
+    build?: boolean;
+    /**
+     * Router basename for this request (what the RSC handler stores on the
+     * context). Drives redirect() prefixing. Normalized exactly like
+     * createRouter({ basename }) (leading slash forced, trailing stripped, bare
+     * "/" -> undefined) so passing the same value your router takes yields the
+     * same redirect Location. Defaults to undefined (no basename).
+     */
+    basename?: string;
+    /**
+     * Cache store backing `use cache` functions invoked during the test, the
+     * same shape `createRouter({ cache })` resolves. Without it,
+     * registerCachedFunction bypasses (it checks for a store FIRST), so a cached
+     * function runs uncached and its taint/profile guards never fire. Wire one
+     * (e.g. `new MemorySegmentCacheStore()`) to exercise real cache behavior.
+     */
+    cacheStore?: SegmentCacheStore;
+    /**
+     * Cache profiles in the `createRouter({ cacheProfiles })` shape. Required for
+     * a `use cache: "profileName"` function to resolve its profile (an unknown
+     * profile throws), once a `cacheStore` is wired.
+     */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (resolved
+     * internally). Without it `ctx.theme`/`ctx.setTheme` are inert (undefined),
+     * mirroring an app with no theme configured. Pass one (e.g. `true`, or
+     * `{ 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: 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;
+}
+/**
+ * Create a real RequestContext for unit-testing loaders/middleware.
+ *
+ * The returned `ctx` must be ENTERED before use — wrap your call in
+ * `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`)
+ * so that cookie/header mutations and `getRequestContext()` resolve. For the
+ * common case prefer {@link runInRequestContext}, which builds AND enters the
+ * context in a single call.
+ */
+export declare function createTestRequestContext<TEnv>(opts?: CreateTestContextOptions<TEnv>): TestRequestContext<TEnv>;
+/**
+ * What a run accumulated on the request context, surfaced as PUBLIC values so a
+ * test never has to cast through the `@internal` `ctx.res` / `ctx.cookies()` to
+ * assert what an action produced.
+ */
+export interface RunInRequestContextResult<T> {
+    /**
+     * 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;
+    /**
+     * The effective cookie view after the run: request cookies merged with
+     * 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
+     * `history.state` (empty object when none) — so a post-action flash ("Saved!")
+     * 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;
+}
+export declare function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
+    cookies: Record<string, string>;
+    locationState: Record<string, unknown>;
+};
+export declare function headersToObject(headers: Headers): Record<string, string>;
+export declare function buildRunResponse<TEnv>(ctx: RequestContext<TEnv>, thrown: unknown): Response;
+export declare 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;
+};
+/**
+ * Build a seeded RequestContext (via {@link createTestRequestContext}) and run
+ * `fn` inside it, so code under test that calls `getRequestContext()`,
+ * `cookies()`, or reads/mutates request headers resolves exactly as in
+ * production.
+ *
+ * This is the entry point for the advanced cases the unit wrappers
+ * (`runLoader` / `runMiddleware`) do not model — most notably a server ACTION
+ * that authenticates off the request cookie or sets a session cookie / flash:
+ * an action has no loader context, so `runLoader` is the wrong shape, yet it
+ * still needs a real request context to read the cookie and resolve
+ * `getRequestContext()`.
+ *
+ * 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, thrown } = await runInRequestContext(
+ *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
+ *   {
+ *     env,
+ *     request: new Request("https://app.test/", {
+ *       headers: { Cookie: "sid=abc" },
+ *     }),
+ *   },
+ * );
+ * 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="),
+ * );
+ * ```
+ */
+export declare function runInRequestContext<T, TEnv = unknown>(fn: (ctx: RequestContext<TEnv>) => T | Promise<T>, opts?: CreateTestContextOptions<TEnv>): Promise<RunInRequestContextResult<T>>;

package/dist/types/testing/internal/flight-client-globals.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/testing/internal/seed-vars.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { type ContextVar } from "../../context-var.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 declare function resolveSeededStateCookieName(seed?: StateCookieSeed): string;
+export type VarsInit = Record<string, unknown> | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
+export declare function seedVariables(variables: Record<string, unknown>, vars?: VarsInit): Record<string, unknown>;

package/dist/types/testing/render-handler.d.ts

@@ -0,0 +1,160 @@
+/**
+ * renderHandler — run a REAL route handler and assert what it renders.
+ *
+ * A Rango route handler is a pure function `(ctx) => RSC` (what you pass to
+ * `path("/p/:slug", ProductPage)`), NOT a component. To test one faithfully you
+ * must give it the HandlerContext the router builds at runtime, so `ctx.params`,
+ * `ctx.use(Loader)`, `ctx.use(Meta)` / `ctx.use(Breadcrumbs)` (handles),
+ * `ctx.reverse`, `ctx.get`/`ctx.header`/`cookies()` all work. renderHandler does
+ * exactly that, then serializes the handler's returned RSC and deserializes it
+ * to an inspectable tree (same serialize/deserialize core as renderServerTree).
+ *
+ * Loaders are SEEDED (no real loader execution) the same way `runLoader` seeds
+ * them — pass `loaders: [[ProductLoader, data]]`. Handle pushes
+ * (`ctx.use(Meta)({...})`) are captured on `result.handles`. The handler's
+ * cookie/header/flash effects and a thrown/returned redirect are surfaced too
+ * (like `runInRequestContext`). If the handler returns/throws a `Response`
+ * (a response route / `throw redirect()`), there is no RSC `tree`.
+ *
+ * Must run under the `react-server` export condition (the rsc Vitest project).
+ * Wire `rangoUseClientTransform()` so `"use client"` islands in the handler's RSC
+ * auto-register (or pass `clientComponents`).
+ */
+import type { ReactNode } from "react";
+import { type Handle } from "../handle.js";
+import type { HandlerContext } from "../types/handler-context.js";
+import type { LoaderDefinition } from "../types.js";
+import { type VarsInit, type StateCookieSeed } from "./internal/seed-vars.js";
+export type { StateCookieSeed } from "./internal/seed-vars.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+import type { ThemeConfig } from "../theme/types.js";
+/** A route handler under test: the `(ctx) => RSC | Response` function you pass to `path(...)`. */
+export type TestableHandler<TEnv = any> = (ctx: HandlerContext<any, TEnv>) => ReactNode | Response | Promise<ReactNode | Response>;
+/** Options for {@link renderHandler}. */
+export interface RenderHandlerOptions<TEnv = any> {
+    /** Route params surfaced as `ctx.params`. */
+    params?: Record<string, string>;
+    /** Environment bindings surfaced as `ctx.env`. */
+    env?: TEnv;
+    /** Backing Request (string or Request); defaults to a localhost GET. */
+    request?: Request | string;
+    /** Request headers (e.g. Cookie) the handler reads via `cookies()`. */
+    headers?: HeadersInit;
+    /** Variables a prior middleware set, read via `ctx.get(...)`. Object or tuples. */
+    vars?: VarsInit;
+    /** Matched route name (drives `ctx.routeName` and scoped reverse). */
+    routeName?: string;
+    /** Route name -> pattern map enabling `ctx.reverse()`. */
+    routeMap?: Record<string, string>;
+    /**
+     * Seed `ctx.build` (default false) so a handler that branches on the
+     * build-time pass — including calling `ctx.dynamic()` on a MISS — is
+     * unit-testable. Assert a `ctx.dynamic()` call via `result.dynamic`.
+     */
+    build?: boolean;
+    /**
+     * Seed the data `ctx.use(SomeLoader)` returns — NO real loader runs (same model
+     * as `runLoader`'s `loaders`). Matched by loader reference, so a real
+     * `createLoader()` handle resolves regardless of its build-injected `$$id`.
+     */
+    loaders?: ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>;
+    /**
+     * `"use client"` components in the handler's RSC, so they serialize as real
+     * boundaries when `rangoUseClientTransform()` is not wired. Keyed by name; see
+     * renderServerTree's `clientComponents`.
+     */
+    clientComponents?: Record<string, unknown>;
+    /**
+     * Customize the rango state cookie a handler that calls
+     * `invalidateClientCache()` rotates. The name is ALWAYS seeded (default
+     * `rango-state_router_0`) so the rotation `Set-Cookie` is emitted like
+     * production rather than no-opping; override `prefix`/`routerId` to match your
+     * `createRouter({ stateCookiePrefix, id })`, or `version` (the build
+     * identifier prefixed to the rotated `{version}:{timestamp}` value, default
+     * `"0"`). Assert via `result.response.headers.getSetCookie()` against
+     * `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>;
+    /**
+     * Render as if inside a server action's revalidation render (production sets
+     * this in revalidateAfterAction). A stale `"use cache"` entry whose profile
+     * opts into `foregroundOnAction` then re-executes in the FOREGROUND (fresh
+     * result in this render) instead of being served stale + revalidated in the
+     * background. Without it, a stale entry keeps SWR. Pair with `cacheStore` +
+     * `cacheProfiles` to exercise the `foregroundOnAction` opt-in.
+     */
+    inActionRevalidation?: boolean;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+     * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert,
+     * mirroring an app with no theme configured. Pass one to exercise a handler
+     * that reads `ctx.theme` or writes the theme cookie via `ctx.setTheme(...)`.
+     */
+    theme?: ThemeConfig | true;
+}
+/** Result of {@link renderHandler}. */
+export interface RenderHandlerResult {
+    /**
+     * The deserialized RSC the handler returned, as an inspectable React element
+     * tree — `undefined` when the handler returned or threw a `Response`. Use
+     * `findClientBoundaries` (from testing/flight) to locate client islands.
+     */
+    tree: unknown;
+    /** The raw Flight wire string; `undefined` when the handler produced a `Response`. */
+    flight: string | undefined;
+    /** The value the handler THREW (a `redirect()`/`notFound()` Response), captured not re-thrown. */
+    thrown: unknown;
+    /** The merged Response (status + headers + Set-Cookie); a thrown/returned redirect merged with accumulated effects. */
+    response: Response;
+    /** Effective cookie view after the handler ran, as `{ name: value }`. */
+    cookies: Record<string, string>;
+    /** Response headers as `{ name: value }` (excludes set-cookie; includes a redirect Location). */
+    headers: Record<string, string>;
+    /**
+     * The resolved rango state cookie name this run seeded (default
+     * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert the
+     * `invalidateClientCache()` rotation against it without recomputing:
+     * `response.headers.getSetCookie().some((c) => c.startsWith(stateCookieName + "="))`.
+     */
+    stateCookieName: string;
+    /** Location state the handler set (`ctx.setLocationState`/`redirect({ state })`), as `{ key: value }`. */
+    locationState: Record<string, unknown>;
+    /** What the handler pushed via `ctx.use(Handle)(...)` (e.g. Meta, Breadcrumbs), keyed by handle. */
+    handles: Map<Handle<any, any>, unknown[]>;
+    /**
+     * Whether the handler called `ctx.dynamic()` (the PPR shell opt-out). The
+     * public way to assert the opt-out without reading the `@internal`
+     * `ctx._dynamic`.
+     */
+    dynamic: boolean;
+}
+/**
+ * Run a route handler with a seeded HandlerContext and return its rendered RSC
+ * (deserialized tree) plus the effects it produced. See the module header.
+ *
+ * @example
+ * ```ts
+ * // ProductPage is the real handler: (ctx) => <main>{ctx.params.slug}...</main>
+ * const { tree, handles } = await renderHandler(ProductPage, {
+ *   params: { slug: "wine" },
+ *   loaders: [[ProductLoader, { name: "Wine", price: 9 }]],
+ *   vars: [[Tenant, tenant]],
+ *   routeMap: { product: "/p/:slug" },
+ * });
+ * ```
+ */
+export declare function renderHandler<TEnv = any>(handler: TestableHandler<TEnv>, opts?: RenderHandlerOptions<TEnv>): Promise<RenderHandlerResult>;