@rangojs/router 0.17.0 → 0.19.0

package/dist/types/browser/types.d.ts

@@ -41,6 +41,12 @@ export interface RscMetadata {
     resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
+    /**
+     * The matched route's name (include name prefix applied), when the route is
+     * named. The browser keeps it per history entry for transition({ when })'s
+     * `from.routeName` / `to.routeName` (browser/transition-when.ts).
+     */
+    routeName?: string;
     /**
      * State of named slots for this route match
      * Key is slot name (e.g., "@modal"), value is slot state
@@ -246,6 +252,17 @@ export interface SegmentState {
     currentUrl: string;
     currentSegmentIds: string[];
 }
+/**
+ * What the router remembers about one history entry for transition({ when })
+ * (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface HistoryEntryMemory {
+    readonly routeName: string | undefined;
+    /** The entry's `history.state` as last recorded. */
+    readonly state: unknown;
+}
 /**
  * Navigation update emitted when UI should re-render
  *
@@ -265,11 +282,51 @@ export interface NavigationUpdate {
     };
 }
 /**
- * State value for navigate/Link
- * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Plain state format (object or getter function)
+ * Plain object accepted as {@link PlainHistoryState}. The `any` string index
+ * admits interface-typed values (an `unknown` index would reject interfaces,
+ * which carry no implicit index signature). The `never` members reject:
+ * - a single typed entry (`GridState(value)` without the array) — its
+ *   `__rsc_ls_*` fields would be spread onto history.state and
+ *   `useLocationState(GridState)` would read `undefined`;
+ * - functions, including a location-state definition passed uncalled
+ *   (`Symbol.hasInstance` comes from `Function.prototype`), which throw
+ *   `DataCloneError`;
+ * - arrays and other iterables (`Symbol.iterator`), so an array must match the
+ *   typed-entry or plain-array member instead;
+ * - built-ins tagged with `Symbol.toStringTag` (`Promise`, `WeakMap`,
+ *   `WeakSet`), which throw `DataCloneError`. The cloneable tagged ones
+ *   (`Map`, `Set`, `ArrayBuffer`, typed arrays) have their own members.
+ *
+ * Members are not checked: a function, symbol, or React element inside a
+ * plain object still compiles, as does a top-level `ReactElement` or DOM node
+ * (an object with none of the keys above).
+ */
+export interface PlainHistoryObject {
+    readonly [key: string]: any;
+    readonly __rsc_ls_key?: never;
+    readonly __rsc_ls_value?: never;
+    readonly __rsc_ls_lazy?: never;
+    readonly [Symbol.iterator]?: never;
+    readonly [Symbol.hasInstance]?: never;
+    readonly [Symbol.toStringTag]?: never;
+}
+/**
+ * Plain (untyped) navigation state, stored under `history.state.state` and
+ * read with `useLocationState<T>()`. A structured-clone-safe value: primitives,
+ * arrays, `Map`/`Set`, `ArrayBuffer`, typed arrays, and plain objects. Excludes
+ * functions, symbols, `Promise`/`WeakMap`/`WeakSet`, and objects carrying
+ * `__rsc_ls_*` keys (a typed entry passed without its array). Arrays, `Map`,
+ * and `Set` are checked element by element; plain object members are not
+ * checked (see {@link PlainHistoryObject}).
  */
-export type HistoryState = import("./react/location-state-shared.js").LocationStateEntry[] | unknown;
+export type PlainHistoryState = string | number | boolean | bigint | null | undefined | readonly PlainHistoryState[] | ReadonlyMap<PlainHistoryState, PlainHistoryState> | ReadonlySet<PlainHistoryState> | ArrayBuffer | ArrayBufferView | PlainHistoryObject;
+/**
+ * State value for `router.push()` / `router.replace()` / `<Link state>`.
+ * - `readonly LocationStateEntry[]`: typed entries from `createLocationState()`
+ *   definitions, e.g. `[GridState({ count: 3 })]` (recommended)
+ * - {@link PlainHistoryState}: plain structured-clone-safe state
+ */
+export type HistoryState = readonly import("./react/location-state-shared.js").LocationStateEntry[] | PlainHistoryState;
 /**
  * Options for navigation operations
  */
@@ -295,6 +352,22 @@ export interface NavigateOptions {
      * ```
      */
     revalidate?: boolean;
+    /**
+     * Set to `false` to present this navigation without a transition: the
+     * commit is urgent and every `<ViewTransition>` class resolves to `"none"`,
+     * the same result as a `transition({ when })` predicate returning `false`.
+     * No `when` predicate is called. Back/forward, action and revalidation
+     * commits are unaffected (they are not started by this call).
+     *
+     * @default true (the route's transition config applies)
+     *
+     * @example
+     * ```tsx
+     * router.push("/photos/2", { transition: false });
+     * <Link to="/photos/2" transition={false}>Next</Link>
+     * ```
+     */
+    transition?: boolean;
     /**
      * State to pass to history.pushState/replaceState
      * Accessible via useLocationState() hook.
@@ -316,14 +389,21 @@ export interface NavigateOptions {
      * // Plain static state
      * navigate("/product", { state: { from: "list" } });
      *
-     * // Plain just-in-time state
-     * navigate("/product", { state: () => ({ from: window.location.pathname }) });
+     * // Compile errors (and a dev-mode runtime error for untyped callers):
+     * navigate("/product", { state: ProductState(p) }); // entry without the array
+     * navigate("/product", { state: [ProductState] }); // definition not called
      * ```
      */
     state?: HistoryState;
 }
-/** @internal Extended options used only within the navigation bridge */
-export interface NavigateOptionsInternal extends NavigateOptions {
+/**
+ * @internal Extended options used only within the navigation bridge. `state`
+ * is widened to `unknown`: the redirect lanes pass state already resolved to
+ * a flat `history.state` record, and in dev Link passes an uncalled
+ * definition through to resolveNavigationState's check.
+ */
+export interface NavigateOptionsInternal extends Omit<NavigateOptions, "state"> {
+    state?: unknown;
     /** Skip segment cache (used by redirect-with-state to force re-render) */
     _skipCache?: boolean;
 }
@@ -402,6 +482,21 @@ export interface NavigationStore {
     setSegmentIds(ids: string[]): void;
     getHistoryKey(): string;
     setHistoryKey(key: string): void;
+    /**
+     * Per-history-entry memory for transition({ when }) sources: record the
+     * entry on screen (keyed by its `history.state.key`) with its current
+     * `history.state` and, when given, its route name (kept from the last
+     * record otherwise; every push/replace creates a new key, so a stale name
+     * never carries to another entry). Called after every commit, restore and
+     * state merge.
+     */
+    rememberDisplayedEntry(routeName?: string): void;
+    /**
+     * The memory of the entry on screen, or of `entryKey`. At popstate
+     * history.state already belongs to the destination, so back/forward reads
+     * the entry being LEFT from here. In-memory only: empty after a reload.
+     */
+    getHistoryEntryMemory(entryKey?: string): HistoryEntryMemory | undefined;
     /** Monotonic token of the most recently committed navigation. */
     getNavInstance(): number;
     cacheSegmentsForHistory(historyKey: string, segments: ResolvedSegment[], handleData?: HandleData): void;
@@ -517,7 +612,7 @@ export interface ServerActionBridgeConfig {
  * Navigation bridge for handling client-side navigation
  */
 export interface NavigationBridge {
-    navigate(url: string, options?: NavigateOptions): Promise<void>;
+    navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
     refresh(): Promise<void>;
     handlePopstate(): Promise<void>;
     registerLinkInterception(): () => void;

package/dist/types/build/generate-manifest.d.ts

@@ -93,6 +93,14 @@ export declare function generateManifestFull<TEnv>(urlpatterns: UrlPatterns<TEnv
      * EntryData map built below is local; this is the only seam that surfaces it.
      */
     collectClientFallbackRef?: (refKey: string) => void;
+    /**
+     * Fail on an invalid transition({ when }): a non-function, or a plain
+     * (server) function where a client reference is required. Only the Vite
+     * plugin's discovery passes it: it evaluates the tree in the react-server
+     * graph, the one place a "use client" import is told apart from a server
+     * function (transition-when-ref.ts).
+     */
+    validateTransitionWhen?: boolean;
 }): Promise<FullManifest>;
 /**
  * Generate TypeScript code for the manifest

package/dist/types/cache/background-task.d.ts

@@ -1,8 +1,10 @@
 /**
  * Background Task Runner
  *
- * Unified helper for scheduling async work via waitUntil.
- * When waitUntil is unavailable, falls back to blocking or skipping.
+ * Unified helper for scheduling async work via waitUntil, and the two bounded
+ * waits the PPR shell capture puts on background work (raceDeadline,
+ * settleGrowing). When waitUntil is unavailable, falls back to blocking or
+ * skipping.
  */
 interface WaitUntilHost {
     waitUntil?: (fn: () => Promise<void>) => void;
@@ -18,4 +20,24 @@ interface WaitUntilHost {
  * @returns A promise when blocking fallback is used, void otherwise.
  */
 export declare function runBackground(host: WaitUntilHost | null | undefined, task: () => Promise<void>, blockWhenNoWaitUntil?: boolean): Promise<void> | void;
+/**
+ * Race `work` against an absolute deadline (epoch ms), keeping its value. The
+ * losing work is not cancelled (a router match has no abort signal) and its
+ * late rejection is swallowed. The timer is unref'd, so a pending deadline
+ * never keeps a Node dev process alive.
+ */
+export declare function raceDeadline<T>(work: Promise<T>, deadline: number): Promise<{
+    done: true;
+    value: T;
+} | {
+    done: false;
+}>;
+/**
+ * Wait until every promise in `list` has settled, including ones appended
+ * while waiting (a settled write can schedule a nested one: cacheRoute
+ * schedules its store.set in a second waitUntil), or until `deadline` (epoch
+ * ms). Resolves true when the list drained, false at the deadline. Never
+ * mutates `list`: a later call waits for what is still pending.
+ */
+export declare function settleGrowing(list: readonly Promise<unknown>[], deadline: number): Promise<boolean>;
 export {};

package/dist/types/cache/cache-exec-scope.d.ts

@@ -31,6 +31,37 @@
 export interface CacheExecScope {
     readonly parent?: CacheExecScope;
 }
+/**
+ * Run a callback whose identity reads never reach a shared entry, so
+ * guardIdentityRead (server/context.ts) lets them through and records
+ * nothing (#976):
+ *
+ * - a cache's own decisions and metadata: a `key()`, a store `keyGenerator`
+ *   (cache-policy.ts resolveCacheKey), a `condition()` (cache-scope.ts
+ *   conditionAllows, loader-cache.ts) and a `tags()` function
+ *   (cache-policy.ts resolveTagsOption). The value picks the entry, whether
+ *   one is used, or how it is invalidated; it is never rendered. Reading the
+ *   request there is the documented way to partition an entry;
+ * - the router's `onError` (router/error-handling.ts invokeOnError): it
+ *   observes, and a render error can reach it inside a capture or a cached
+ *   scope.
+ *
+ * Scar: a ppr capture resolves its doc record key, and the record's tags,
+ * again under the capture context; once `ctx.request.headers` was guarded, a
+ * keyGenerator or tags() reading it refused every capture of the route.
+ *
+ * The exemption is async-local, so it would follow everything the callback
+ * starts. A "use cache" body (runWithCacheExecScope), a loader body
+ * (server/context.ts runInsideLoaderBodyScope) and a segment funnel
+ * (getContext().runWithStore) end it on entry (endIdentityExempt). Scar: a
+ * key() that awaited a "use cache" function reading cookies() stored the
+ * first visitor's cookie and served it to the next.
+ */
+export declare function runIdentityExempt<T>(fn: () => T): T;
+/** True inside runIdentityExempt, and not in a scope started from it. */
+export declare function isInsideIdentityExempt(): boolean;
+/** Run `fn` with the identity exemption ended (see runIdentityExempt). */
+export declare function endIdentityExempt<T>(fn: () => T): T;
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.

package/dist/types/cache/cache-key-utils.d.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 import type { SearchParamsFilter } from "./search-params-filter.js";
 /**
@@ -41,3 +41,49 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
  */
 export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * The prefix of a `key()` result's part in a record key (#975), and of a
+ * loader's own `key()` result after its `loader:<id>:` namespace (#1009,
+ * loader-cache.ts loaderKeyFromResult).
+ */
+export declare const KEY_PART_PREFIX = "key:";
+/**
+ * A cache() record key, or ppr shell partition, from its parts
+ * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
+ * results of the scope's cache() chain, outermost first, then its default
+ * parts: the keyGenerator results of enclosing scopes on another store
+ * (#974) and, for a record key under a scope without its own `key()`, its
+ * default key (or its store's keyGenerator result, #970).
+ *
+ * Key scheme invariant (#975). A `key()` result is often request input,
+ * and a record key has no route or scope discriminator (the store reads
+ * `store.get(key)`), so a result that equals another record's key writes
+ * one route's content under the other's entry. Before #975 a single
+ * `key()` result was stored raw: the header value `doc:localhost/pricing`
+ * named /pricing's default-keyed record, and `gold|doc%3Alocalhost%2Fpricing`
+ * named gold's nested /pricing record (#970). So every part is encoded:
+ *
+ * - a `key()` part is `key:` plus `encodeURIComponent(result)`: it starts
+ *   with `key:` and holds no `|` and no other `:`;
+ * - a default part is `encodeURIComponent(value)`: it holds no `:` or `|`;
+ *   an enclosing store's keyGenerator result equal to the default key is an
+ *   empty part, so each store keeps its position (CacheScope
+ *   positionalParts);
+ * - one `key()` part is the key; two or more parts are joined by `|`,
+ *   `key()` parts first;
+ * - a lone default part stays raw: with no `key()` on the chain the record
+ *   key is the default key or the store's keyGenerator result, unchanged.
+ *
+ * Why nothing collides: the router's default keys (`doc:`, `partial:`,
+ * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
+ * A namespaced `key()` result starts with `key:` and holds no `|`. A
+ * composed key holds a `|` and either starts with `key:` or holds no `:`.
+ * Among composed keys, splitting on `|` recovers each part, a part's kind
+ * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
+ * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
+ * result is the store's own namespace, as before.
+ *
+ * Shared with the testing helper `shellCacheKey`, so a test builds the
+ * production partition.
+ */
+export declare function composeCacheKeys(keyResults: readonly string[], defaultParts?: readonly string[]): string;

package/dist/types/cache/cache-policy.d.ts

@@ -42,6 +42,23 @@ export declare function resolveTtl(explicit: number | undefined, defaults: Cache
  * non-finite/negative (degrade rather than feed bad math into expiry).
  */
 export declare function resolveSwrWindow(explicit: number | undefined, defaults: CacheDefaults | undefined): number;
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export declare const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1000;
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export declare function staleShellRecaptureDue(entry: {
+    readonly createdAt?: number;
+}, now: number): boolean;
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *
@@ -54,6 +71,6 @@ export declare function computeExpiration(ttlSeconds: number, swrSeconds?: numbe
     staleAt: number;
     expiresAt: number;
 };
-export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string, _label: string): Promise<string>;
+export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string): Promise<string>;
 export declare function resolveTagsOption<TEnv>(tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined, ctx: RequestContext<TEnv> | undefined, label: string): string[] | undefined;
 export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;

package/dist/types/cache/cache-runtime.d.ts

@@ -40,6 +40,13 @@ export { isCachedFunction };
  * identical arg sets.
  */
 export declare function replyToCacheKey(encoded: string | FormData): Promise<string>;
+/**
+ * @internal Reset this module's per-isolate state: the in-flight leaders a
+ * follower would join for up to IN_FLIGHT_LEADER_MAX_WAIT_MS, and the
+ * once-per-function warnings. Tests only (testing/serve-shell-request.ts
+ * resetShellTestState), never while a request is in flight.
+ */
+export declare function resetCacheRuntimeForTests(): void;
 /**
  * Register a function as a cached function.
  * Called by the Vite transform for each "use cache" function.