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

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

@@ -0,0 +1,265 @@
+/**
+ * renderRoute — a React-Testing-Library-style helper for unit-testing CLIENT
+ * components that read @rangojs/router client context (useParams, useReverse,
+ * Outlet, useNavigation, useLoader).
+ *
+ * Peer of React Router's createRoutesStub and Expo Router's renderRouter. It
+ * mounts the router's NavigationProvider plus a synthetic segment tree so that
+ * a component under test sees real router context, without spinning up a
+ * server, a Vite build, or a real Flight round-trip.
+ *
+ * FIDELITY CONTRACT — read before relying on this helper:
+ * This renders the CLIENT tree ONLY. The segment tree is built synthetically
+ * from the `routes` you pass; there is no server render and no Flight
+ * (de)serialization. Consequences:
+ *   - It will NOT catch server/client boundary reference-identity remount bugs
+ *     (a server-serialized component reference differing from the client
+ *     reference). Use renderServerTree / e2e for those.
+ *   - It will NOT catch real Flight serialization errors (non-serializable
+ *     props crossing the RSC boundary), loader execution on the server,
+ *     middleware, or handler ordering. Those are renderServerTree / renderHandler
+ *     / e2e territory.
+ *   - Loader data, location state, handle output, and outlet pending state are
+ *     SEEDED directly into client context (see the `loaders` / `locationState` /
+ *     `handles` / `outletPending` options) — nothing is executed on the server.
+ *     This exercises the context read path, not the run path.
+ *   - navigate() commits synchronously, so it does NOT drive the navigation
+ *     lifecycle: useNavigation().state, useLinkStatus().pending, and
+ *     useAction().state stay "idle". Assert pending/loading/submitting transition
+ *     states with renderServerTree / e2e instead (navigate() warns once if used).
+ * What it DOES cover: client hooks that read NavigationProvider /
+ * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
+ * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
+ * descendant pending state, useLoader/useFetchLoader (seeded data),
+ * useLocationState (seeded), and useHandle (seeded).
+ * Basename-mounted apps: pass the `basename` option so useRouter().basename,
+ * <Link> prefixing, and useMount/useHref resolve against the mount prefix
+ * (without it they resolve at the root "/"). For an include("/shop", ...)
+ * subtree, pass the `mount` option so useMount() returns the mounted prefix
+ * (the segment chain is wrapped in a MountContext exactly as in production).
+ */
+import { type ComponentType } from "react";
+import type { RenderResult } from "@testing-library/react";
+import type { NavigationStore } from "../browser/types.js";
+import type { EventController } from "../browser/event-controller.js";
+import type { LoaderDefinition } from "../types.js";
+import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import type { Handle } from "../handle.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
+/**
+ * Seed shape for `options.handle`, matching the handle wire format:
+ * `{ [handleName]: { [segmentId]: pushedValues[] } }` (each segment accumulates
+ * an array of values pushed for that handle).
+ */
+export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
+export interface RenderRouteSpec {
+    /**
+     * The route pattern this node matches, e.g. "/products/:productId". The LAST
+     * spec in the array is treated as the leaf route; earlier specs are layouts
+     * wrapping it. Only the leaf pattern is matched against the `request` URL to
+     * extract params; layout patterns are informational.
+     */
+    path: string;
+    /** The component rendered for this node (the leaf route or a layout body). */
+    Component: ComponentType;
+    /**
+     * Optional layout component. When set on the LEAF spec it wraps the route in
+     * its own layout segment (useful for a route that owns a layout). Prefer
+     * expressing layouts as their own array entries instead.
+     */
+    layout?: ComponentType;
+    /**
+     * Loader ids ($$id) whose seeded data (from `options.loaderData`) should be
+     * attached to THIS node's segment so useLoader/useFetchLoader resolve it from
+     * context. When omitted, every key in `options.loaderData` is attached to the
+     * leaf route segment.
+     */
+    loaderIds?: string[];
+    /** Optional route name (informational; not used for matching). */
+    name?: string;
+}
+/**
+ * Options for renderRoute.
+ */
+export interface RenderRouteOptions {
+    /**
+     * The initial location to render at: a `Request`, or a URL string (absolute or
+     * path). Only the URL is read (this is a client render — headers/method are
+     * ignored); named `request` for parity with the other primitives. Defaults to
+     * the leaf spec's static prefix or "/".
+     */
+    request?: Request | string;
+    /**
+     * Loader data to seed into client context, keyed by loader id ($$id). A
+     * component calling useLoader(SomeLoader) reads `loaderData[SomeLoader.$$id]`.
+     * Seeded values are placed in the route segment's OutletProvider context, so
+     * the read path is exercised without executing any loader.
+     */
+    loaderData?: Record<string, unknown>;
+    /**
+     * Descendant client-route pending state to seed into each synthetic segment's
+     * production OutletProvider, so `useOutlet().pending` can be tested alongside
+     * `useOutlet().content`. Defaults to false.
+     *
+     * This is a seeded outlet-context value only. It does not model arbitrary
+     * Suspense, navigation, or action pending state.
+     */
+    outletPending?: boolean;
+    /**
+     * Loaders to seed by REFERENCE — the robust way to test a component that calls
+     * `useLoader(loader)`. A real `createLoader()` handle has an empty `$$id` in a
+     * bare test (the id is injected by the Vite plugin at build time), so keying
+     * `loaderData` by `$$id` collides under `""` and `useLoader` resolves nothing.
+     * Passing `[loader, data]` pairs lets renderRoute assign a synthetic stable id
+     * and wire `useLoader` to it. Prefer this over `loaderData` for real handles.
+     *
+     * NOTE: when a real handle has no `$$id`, renderRoute MUTATES it to assign a
+     * synthetic stable id (so repeat renders key consistently). This is a side
+     * effect on your input object; a handle reused across tests keeps that id.
+     *
+     * @example
+     * // useLoader returns an ENVELOPE — destructure `data`, it is not the bare value.
+     * function CartBadge() {
+     *   const { data } = useLoader(CartLoader); // NOT `useLoader(CartLoader).itemCount`
+     *   return <span>{data.itemCount}</span>;
+     * }
+     * renderRoute([{ path: "/cart", Component: CartBadge }], {
+     *   loaders: [[CartLoader, { itemCount: 3, total: 89.97 }]],
+     * });
+     */
+    loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    /**
+     * Explicit params. Merged over (and overriding) params extracted from the
+     * `request` URL. Use this when the URL alone cannot express the params, or to
+     * avoid relying on URL parsing. Supplying params also OPTS OUT of the
+     * request/leaf match check: a `request` whose pathname does not resolve the
+     * leaf is normally rejected under the test runner, but passing params here
+     * tells renderRoute the request is intentionally not the param source.
+     */
+    params?: Record<string, string>;
+    /**
+     * Location-state values to seed by REFERENCE, for components that call
+     * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
+     * handle has an empty injected key in a bare test, so pass `[def, value]`
+     * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+     *
+     * @example
+     * renderRoute([{ path: "/", Component: FlashBanner }], {
+     *   locationState: [[FlashMessage, { text: "Saved" }]],
+     * });
+     */
+    locationState?: ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>;
+    /**
+     * Handles to seed by REFERENCE, for components that read handle output via
+     * `useHandle(SomeHandle)` (e.g. a client `Breadcrumbs` trail). Each entry is
+     * `[handle, pushedValues[]]` — the values a route's handlers would have pushed;
+     * renderRoute attaches them to the leaf route segment under the handle's id.
+     * Built-in handles (Breadcrumbs/Meta) have stable ids and work directly.
+     *
+     * Handle data is accumulated GLOBALLY on the event controller, not scoped per
+     * segment like loaders — so ANY component in the chain reads the seeded values,
+     * a LAYOUT (e.g. a DetailLayout/ActionToolbar reading a handle) just as much as
+     * the leaf route. Most handle usage is server-side (`ctx.use(...)`) and is
+     * better covered by `renderToFlightString`/e2e; this seeds the client read path
+     * only.
+     *
+     * @example
+     * renderRoute([{ path: "/p", Component: BreadcrumbTrail }], {
+     *   handles: [[Breadcrumbs, [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]]],
+     * });
+     */
+    handles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
+    /**
+     * Advanced: raw handle data in wire format
+     * `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles` (which
+     * computes the segment id for you). Merged with `handles`.
+     */
+    handle?: HandleDataSeed;
+    /**
+     * Route name -> pattern map. Informational for parity with the server test
+     * context; client useReverse takes its map directly as an argument, so this
+     * is not consumed by the client hooks.
+     */
+    routeMap?: Record<string, string>;
+    /**
+     * Router basename (the `createRouter({ basename })` value). Wired into
+     * NavigationProvider so `useRouter().basename`, `<Link>` href prefixing, and
+     * `useMount`/`useHref` resolve against the mounted prefix instead of the root.
+     * Normalized exactly like createRouter (leading slash forced, trailing
+     * stripped, bare "/" -> undefined). Defaults to undefined (root mount).
+     */
+    basename?: string;
+    /**
+     * include() mount prefix, to model an `include("/shop", ...)` subtree so a
+     * component (route OR layout in the chain) calling `useMount()` returns the
+     * mounted prefix instead of "/". Wraps the segment chain in a MountContext
+     * exactly as `renderSegments` does in production (a segment whose `mountPath`
+     * is set is wrapped in a MountContextProvider). Normalized like a path prefix
+     * (leading slash forced, trailing stripped, bare "/" -> root). Defaults to "/".
+     * An explicitly-passed `request` must match the leaf `path` directly (paths are
+     * include-RELATIVE; the mount does NOT rewrite the request) — pass the relative
+     * path, not the mount-prefixed one, or renderRoute throws rather than silently
+     * rendering empty params.
+     *
+     * @example
+     * renderRoute([{ path: "/c/wine", Component: ProductPage }], { mount: "/shop" });
+     * // useMount() inside ProductPage returns "/shop"
+     */
+    mount?: string;
+    /**
+     * Theme config in the `createRouter({ theme })` shape (resolved internally) to
+     * wrap the tree in a ThemeProvider. Defaults to no provider. Note: a component
+     * that calls `useTheme()` REQUIRES a provider — it throws "used outside
+     * ThemeProvider" without one — so pass a config (e.g. `true`) to test such a
+     * component.
+     */
+    theme?: ThemeConfig | true;
+    /**
+     * CSP nonce to seed via NonceContext, so a component calling `useNonce()`
+     * (e.g. an analytics/GTM head-script component) sees this value — mirroring
+     * what the SSR renderer provides per request. Defaults to undefined (the
+     * browser default), matching production client behavior.
+     *
+     * @example
+     * const { getByTestId } = await renderRoute(
+     *   [{ path: "/", Component: NonceProbe }],
+     *   { nonce: "test-nonce" },
+     * );
+     * expect(getByTestId("nonce").textContent).toBe("test-nonce");
+     */
+    nonce?: string;
+    /**
+     * Router default prefetch strategy scoped to this rendered tree. This mirrors
+     * `createRouter({ defaultPrefetch })` for Links and eligible plain anchors
+     * inside `basename`. `data-prefetch="false"`/`"none"` opts out; `"true"`
+     * allows an application route with a common static-resource suffix but does
+     * not override a `"none"` default.
+     */
+    defaultPrefetch?: PrefetchStrategy;
+}
+/**
+ * Imperative handle returned alongside the RTL result.
+ */
+export interface TestRouterHandle {
+    /**
+     * Navigate to a new URL. Re-resolves the URL against the supplied `routes`,
+     * updates params + location, and re-renders the segment tree. This is a
+     * client-only navigation: no server fetch occurs, so only the components in
+     * `routes` can be reached.
+     */
+    navigate(url: string): Promise<void>;
+    /** The current committed pathname. */
+    pathname(): string;
+    /** The current committed params. */
+    params(): Record<string, string>;
+    /** The underlying navigation store (advanced use). */
+    store: NavigationStore;
+    /** The underlying event controller (advanced use). */
+    eventController: EventController;
+}
+/** Result of renderRoute: RTL's render result plus the router handle. */
+export type RenderRouteResult = RenderResult & {
+    router: TestRouterHandle;
+};
+export declare function renderRoute(routes: RenderRouteSpec[], options?: RenderRouteOptions): Promise<RenderRouteResult>;

package/dist/types/testing/run-loader.d.ts

@@ -0,0 +1,195 @@
+/**
+ * runLoader — unit-test a loader function in isolation.
+ *
+ * Pass the RAW async loader body `(ctx) => ...`, or a registered `createLoader()`
+ * handle (its fn is recovered from the fetchable registry by `$$id`). The raw
+ * body needs no build step; the handle works because `createLoader` assigns a
+ * runtime-fallback `$$id` and registers its fn even without the Vite plugin (when
+ * imported through the server build — the consumer's `@rangojs/router` under the
+ * `rangoTestConfig()` preset). Either way the function is invoked directly with a
+ * constructed LoaderContext.
+ *
+ * The LoaderContext mirrors the canonical shape the router builds at runtime
+ * (see createUseFunction in server/request-context.ts). The loader runs inside
+ * runWithRequestContext so getRequestContext(), cookie reads, and header
+ * mutations resolve exactly as in production.
+ *
+ * Limitations (v1):
+ * - `ctx.rendered()` is not available — it requires the DSL render barrier,
+ *   which only exists inside a full match. Calling it throws.
+ * - `ctx.reverse()` throws unless `routeMap` is provided (it does NOT fall back
+ *   to the global route map — that would leak whichever routes another test
+ *   registered).
+ * - `ctx.use(handle)` follows the production rule: reading a handle before
+ *   `await ctx.rendered()` throws (pass `rendered` to mock the barrier).
+ * - `use cache` functions only cache (and only fire their taint/profile guards)
+ *   when a `cacheStore` is provided — without one, registerCachedFunction
+ *   bypasses (it checks for a store first). Pass `cacheStore`/`cacheProfiles`
+ *   to exercise cached loaders; otherwise such a call runs uncached, like an
+ *   app with no cache configured.
+ * - `formData` is exposed verbatim; no multipart parsing is performed.
+ * - Scoped dot-local reverse (`.sibling`) uses only the supplied `routeMap`;
+ *   the production root-scoping signal (derived from the global registry) is
+ *   not modeled, so a dotted name resolves against `routeMap` as given.
+ */
+import type { LoaderContext, LoaderDefinition } from "../types.js";
+import type { ContextVar } from "../context-var.js";
+import { type Handle } from "../handle.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
+/**
+ * The loader context surfaced to a `runLoader` body. It mirrors the runtime
+ * LoaderContext but RELAXES the two members that are otherwise bound to the
+ * app's global route/var augmentation, because in a unit test they are driven by
+ * the `routeMap` / `vars` options instead:
+ * - `reverse` accepts any route name (the names come from `routeMap`, not the
+ *   registered route map), and
+ * - `get` accepts any string key or ContextVar (keys come from `vars`).
+ */
+export type TestLoaderContext<TEnv = any> = Omit<LoaderContext<any, TEnv>, "reverse" | "get"> & {
+    reverse: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
+        <T = unknown>(key: string): T | undefined;
+    };
+};
+/**
+ * A resolver for `ctx.use(OtherLoader)` composition. Receives the dependency
+ * loader definition and returns its data (or a promise of it). When omitted,
+ * `ctx.use` delegates to the real request-context use(), which executes the
+ * dependency's own `fn` if present.
+ */
+export type UseResolver = <T>(loader: LoaderDefinition<T, any>) => Promise<T> | T;
+/**
+ * Options for runLoader.
+ */
+export interface RunLoaderOptions<TEnv = any> {
+    /** Route params surfaced as `ctx.params` and `ctx.routeParams`. */
+    params?: Record<string, string>;
+    /** Search params; merged into the request URL so `ctx.searchParams` reflects them. */
+    search?: Record<string, string>;
+    /**
+     * The TYPED `ctx.search` object a route's search schema would produce. Distinct
+     * from `search` (which sets the raw `ctx.searchParams`): a loader on a typed
+     * search route reads `ctx.search`, which is otherwise `{}` in a test.
+     */
+    searchData?: Record<string, unknown>;
+    /** Router basename surfaced on the context (drives redirect() prefixing). */
+    basename?: string;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+     * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
+     * or cache contexts created from this loader observe it. Loaders themselves do
+     * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
+     */
+    theme?: ThemeConfig | true;
+    /** Environment bindings surfaced as `ctx.env`. */
+    env?: TEnv;
+    /** Override the backing Request (string or Request). Defaults to a localhost GET. */
+    request?: Request | string;
+    /** Variables a prior middleware would have set (object or [key, value] list). */
+    vars?: VarsInit;
+    /** Route name -> pattern map enabling `ctx.reverse()`. */
+    routeMap?: Record<string, string>;
+    /** Matched route name for scoped `.name` reverse resolution. */
+    routeName?: string;
+    /** HTTP method surfaced as `ctx.method`. Defaults to "GET". */
+    method?: string;
+    /** Request body surfaced as `ctx.body`. */
+    body?: unknown;
+    /** Form data surfaced as `ctx.formData`. */
+    formData?: FormData;
+    /**
+     * Seed the data `ctx.use(OtherLoader)` returns, by loader REFERENCE — the same
+     * tuple form `renderHandler` / `renderRoute` use (`[[OtherLoader, data]]`).
+     * Matched by reference, so a real `createLoader()` handle resolves regardless
+     * of its build-injected `$$id`. For dynamic resolution (compute per dependency)
+     * use `use` instead; `loaders` is checked first.
+     */
+    loaders?: ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>;
+    /** Resolver for `ctx.use(OtherLoader)` composition (dynamic; `loaders` wins if both match). */
+    use?: UseResolver;
+    /**
+     * Cache store backing `use cache` functions the loader invokes. Without it,
+     * a cached function bypasses (registerCachedFunction checks for a store
+     * first) and runs uncached — its taint/profile guards never fire. Pass one
+     * (e.g. `new MemorySegmentCacheStore()`) to test a cached loader.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Customize the rango state cookie a loader that calls
+     * `invalidateClientCache()` rotates (the name is always seeded — default
+     * `rango-state_router_0` — so it rotates like production). Assert via the
+     * `Set-Cookie` on the request context's response.
+     */
+    stateCookie?: StateCookieSeed;
+    /**
+     * Mock the `ctx.rendered()` render barrier so a loader that does
+     * `await ctx.rendered()` (to read handle data pushed during render) can be
+     * unit-tested. By default `ctx.rendered()` throws, because the real barrier
+     * only exists during a full route match. Pass `true` to resolve it
+     * immediately, or a function to control its timing/side effects.
+     *
+     * This tests the loader's POST-barrier compute logic against the seeded
+     * `handles` below — it does NOT exercise the real push -> accumulate -> barrier
+     * wiring (that stays e2e). Pair with `handles` to feed `ctx.use(SomeHandle)`.
+     */
+    rendered?: boolean | (() => void | Promise<void>);
+    /**
+     * Seed the values `ctx.use(SomeHandle)` returns — the ACCUMULATED handle data a
+     * loader reads after `await ctx.rendered()`. Matched by handle reference, so a
+     * real handle works regardless of its (build-injected) `$$id`.
+     *
+     * @example
+     * await runLoader(livePricesBody, {
+     *   rendered: true,
+     *   handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+     * });
+     */
+    handles?: ReadonlyArray<readonly [Handle<any, any>, unknown]>;
+}
+/** A raw loader body, or a registered `createLoader()` handle (its fn is recovered). */
+export type RunnableLoader<T> = ((ctx: TestLoaderContext) => Promise<T> | T) | LoaderDefinition<T, any>;
+export declare function runLoader<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<T>;
+export interface RunLoaderResult<T> {
+    /**
+     * The loader's resolved data (the value bare `runLoader` returns), or
+     * `undefined` if it threw (see {@link thrown}). Named `result` for parity with
+     * `runInRequestContext`'s envelope.
+     */
+    result: T | undefined;
+    /**
+     * What the loader threw (commonly a `Response` from `throw redirect(...)` on a
+     * success path) — captured, NOT re-thrown; assert on it. `undefined` if the
+     * loader returned normally.
+     */
+    thrown: unknown;
+    /**
+     * The merged `Response` (status + headers + Set-Cookie). On a thrown redirect,
+     * that redirect's `Location` merged with the accumulated cookies/headers — so a
+     * loader that sets a session cookie then `throw redirect("/")` exposes BOTH.
+     */
+    response: Response;
+    /** Effective cookie view: request cookies + the loader's mutations, last-write-wins. */
+    cookies: Record<string, string>;
+    /** Response headers as `{ name: value }`, EXCLUDING set-cookie (use `cookies`). Lowercased. */
+    headers: Record<string, string>;
+    /** Location state the loader set (`ctx.setLocationState()` / `redirect({ state })`). */
+    locationState: Record<string, unknown>;
+    /** The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). */
+    stateCookieName: string;
+    /**
+     * Handle writes the loader made via `ctx.use(SomeHandle)({...})`, in push
+     * order. A `.defer()` resolver's value is recorded when the resolver runs.
+     */
+    handlePushes: Array<{
+        handle: Handle<any, any>;
+        value: unknown;
+    }>;
+}
+export declare function runLoaderResult<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<RunLoaderResult<T>>;

package/dist/types/testing/run-middleware.d.ts

@@ -0,0 +1,132 @@
+/**
+ * runMiddleware — unit-test one or more middleware functions in isolation.
+ *
+ * Executes the middleware chain via the SAME executeLoaderMiddleware the router
+ * uses, so ordering, `next()`, short-circuit (return OR throw Response),
+ * double-next guards, and header/cookie merging behave identically to
+ * production. The chain runs inside runWithRequestContext, so cookie/header
+ * mutations and getRequestContext() resolve.
+ *
+ * The returned `ctx` is the underlying RequestContext (not the per-middleware
+ * MiddlewareContext), exposing `ctx.cookies()`, `ctx.get()`, and
+ * `ctx.res.headers` for assertions on what the chain produced.
+ *
+ * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
+ * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ */
+import { type RequestContext } from "../server/request-context.js";
+import type { MiddlewareFn } from "../router/middleware-types.js";
+import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+/**
+ * Options for runMiddleware.
+ */
+export interface RunMiddlewareOptions<TEnv = any> {
+    /**
+     * The request the chain runs under: a `Request`, or a URL string (absolute or
+     * path). Optional for parity with `runLoader`/`runInRequestContext` — when
+     * omitted it defaults to `http://localhost/`. Pass it for path-, header-, or
+     * cookie-driven middleware.
+     */
+    request?: Request | string;
+    /** Environment bindings surfaced as `ctx.env`. */
+    env?: TEnv;
+    /** Route params surfaced as `ctx.params`. */
+    params?: Record<string, string>;
+    /**
+     * Seed `ctx.build` (default false) so a middleware that branches on the
+     * build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`) is
+     * unit-testable. With `build: true`, `ctx.waitUntil()` is inert, matching the
+     * build producer. Assert a `ctx.dynamic()` call via `result.dynamic`.
+     */
+    build?: boolean;
+    /** Variables a prior middleware would have set (object or [key, value] list). */
+    vars?: VarsInit;
+    /** Route name -> pattern map enabling `ctx.reverse()`. */
+    routeMap?: Record<string, string>;
+    /**
+     * Matched route name surfaced as `ctx.routeName`. Does NOT scope `.name`
+     * reverse: the chain receives a map-only `reverse` (built from `routeMap`
+     * alone), matching production app/response middleware — see the reverse
+     * construction below.
+     */
+    routeName?: string;
+    /** Router basename surfaced on the context (drives redirect() prefixing). */
+    basename?: string;
+    /** Theme config in the `createRouter({ theme })` shape (enables ctx.theme). */
+    theme?: ThemeConfig | true;
+    /**
+     * Terminal handler invoked when the chain calls `next()` all the way through.
+     * Defaults to a 200 empty Response. Use this to model the downstream
+     * route/handler response.
+     */
+    next?: () => Promise<Response>;
+    /**
+     * Cache store backing any `use cache` function a middleware invokes. Without
+     * it, registerCachedFunction bypasses (it checks for a store first), so the
+     * cached function runs uncached and its taint/profile guards never fire.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Customize the rango state cookie a middleware that calls
+     * `invalidateClientCache()` rotates (the name is always seeded — default
+     * `rango-state_router_0` — so it rotates like production). Assert via the
+     * `Set-Cookie` on `result.response` / `result.cookies`.
+     */
+    stateCookie?: StateCookieSeed;
+}
+/**
+ * Result of runMiddleware.
+ */
+export interface RunMiddlewareResult<TEnv = any> {
+    /** The final Response (downstream response, or a middleware short-circuit). */
+    response: Response;
+    /**
+     * The underlying RequestContext. Read `ctx.cookies()`, `ctx.get(...)`, and
+     * `ctx.res.headers` to assert on the chain's effects. (This is always the
+     * RequestContext the chain ran under — not a per-middleware MiddlewareContext —
+     * so `ctx.cookies()` and the other RequestContext accessors are available.)
+     */
+    ctx: RequestContext<TEnv>;
+    /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
+    nextCalled: number;
+    /**
+     * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
+     * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
+     */
+    dynamic: boolean;
+    /**
+     * The effective cookie view after the chain ran: request cookies merged with
+     * anything the chain set or deleted (last-write-wins), as `{ name: value }`.
+     * The public way to assert a cookie a middleware set, without casting through
+     * the `@internal` `ctx.cookies()`. Set-Cookie headers are also on `response`.
+     */
+    cookies: Record<string, string>;
+    /**
+     * The final response's headers as a plain `{ name: value }` object (the same
+     * view as `response.headers`), EXCLUDING `set-cookie` (use `cookies`). The
+     * public way to assert a header a middleware set (e.g. a security header)
+     * without reading `ctx.res.headers`. Header names are lowercased.
+     */
+    headers: Record<string, string>;
+    /**
+     * Location state the chain set via `ctx.setLocationState()` / `redirect({ state })`,
+     * resolved to the flat `{ key: value }` shape the client reads off
+     * `history.state` (empty object when none) — parity with `runInRequestContext`
+     * and `renderHandler`.
+     */
+    locationState: Record<string, unknown>;
+    /**
+     * The resolved rango state cookie name seeded for the run (default
+     * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert a
+     * middleware's `invalidateClientCache()` rotation against it without
+     * recomputing — parity with `runInRequestContext` / `runLoaderResult` /
+     * `renderHandler`.
+     */
+    stateCookieName: string;
+}
+export declare function runMiddleware<TEnv = any>(mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[], opts: RunMiddlewareOptions<TEnv>): Promise<RunMiddlewareResult<TEnv>>;

package/dist/types/testing/run-transition-when.d.ts

@@ -0,0 +1,78 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+import { type RequestContext } from "../server/request-context.js";
+import { type VarsInit } from "./internal/context.js";
+import type { TransitionConfig, TransitionWhenContext } from "../types/segments.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+    /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+    request?: Request | string;
+    /** Route params for the target (`nextParams`). */
+    params?: Record<string, string>;
+    /** Target route name (`toRouteName`). */
+    toRouteName?: string;
+    /** Environment bindings surfaced as `env` (and `ctx.env`). */
+    env?: TEnv;
+    /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
+    vars?: VarsInit;
+    /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+    currentUrl?: string | URL;
+    /** Source route params (`currentParams`). */
+    currentParams?: Record<string, string>;
+    /** Source route name (`fromRouteName`). */
+    fromRouteName?: string;
+    /** Id of the action that triggered a revalidation (`actionId`). */
+    actionId?: string;
+    /** Url the action was submitted from (`actionUrl`). */
+    actionUrl?: string | URL;
+    /** The action's return value (`actionResult`). */
+    actionResult?: unknown;
+    /** FormData from a form action (`formData`). */
+    formData?: FormData;
+    /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+    onError?: OnErrorCallback;
+    /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+    ppr?: boolean;
+}
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+    /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+    kept: boolean;
+    /** Convenience inverse of `kept`. */
+    dropped: boolean;
+    /**
+     * The production-assembled predicate context. Undefined when the config has
+     * no `when` predicate.
+     */
+    whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+    /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+    ctx: RequestContext<TEnv>;
+}
+export declare function runTransitionWhen<TEnv = any>(config: TransitionConfig, opts?: RunTransitionWhenOptions<TEnv>): RunTransitionWhenResult<TEnv>;