@rangojs/router 0.16.0 → 0.18.0

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

@@ -12,6 +12,7 @@ import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
+type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
 /**
  * Discriminated outcome of a route cache lookup — see
  * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
@@ -44,11 +45,48 @@ export type CacheRouteLookupOutcome = {
  */
 export declare class CacheScope {
     private readonly defaultKeyPrefix?;
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    readonly boundary?: string | undefined;
     readonly config: PartialCacheOptions | false;
     readonly parent: CacheScope | null;
     /** Explicit store from cache() options, if specified */
     private readonly explicitStore;
-    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined);
+    /**
+     * @internal The `key()` functions that partition this scope's records,
+     * outermost first: every cache() on the parent chain that sets one, this
+     * scope's last (#970). `cache(false)` adds none and does not cut the chain,
+     * so a cache() re-enabled under it stays in the partition. Before, the
+     * innermost config alone decided the key: an inner cache() without `key()`
+     * wrote under the default key and an inner `key()` dropped the outer one,
+     * so a request in one partition HIT another partition's inner records.
+     */
+    readonly keyFns: readonly CacheKeyFn[];
+    /** Whether this scope's own config sets `key()` (the last of keyFns). */
+    private readonly hasOwnKey;
+    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined, 
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    boundary?: string | undefined);
+    /**
+     * @internal Whether a segment belongs to this scope's cache entry. ShortCodes are
+     * hierarchical (server/context.ts getShortCode: parent shortCode + include
+     * scope + type letter + counter), so the boundary's subtree is every id that
+     * extends the boundary shortCode at a non-digit (`C1` must not claim `C10`).
+     * Intercept slot segments ride the target route's entry wherever the
+     * intercept is declared.
+     */
+    covers(id: string, namespace?: string): boolean;
     /**
      * Whether caching is enabled for this scope
      */
@@ -81,6 +119,57 @@ export declare class CacheScope {
      * @internal
      */
     private resolveKey;
+    /**
+     * A shell captured from a route record this request read or wrote must not
+     * outlive it (noteRouteRecordWindow). The implicit doc scope's own record
+     * is the shell's, so it notes nothing.
+     */
+    private noteRecordWindow;
+    /**
+     * @internal This scope's record key for `defaultKey`, resolved once per
+     * request: a ppr route's shell partition (resolvePartition) and the record
+     * lookup share the `key()` runs, and a rejection is shared too.
+     *
+     * With `key()` functions on the chain (keyFns) the parts are their results,
+     * outermost first, composed by composeCacheKeys (a single part raw), so a
+     * nested cache() keys its records within the enclosing partition (#970).
+     * A scope whose own config sets no `key()` appends its own default key
+     * (resolveDefaultKey). Reusing the outer `key()` result alone would give
+     * every route under the inner cache() one record: a `key()` replaces the
+     * whole default key, so an outer key that names no route (`tier:gold`)
+     * would make `/a` HIT `/b`'s record. A scope with its own `key()` adds no
+     * default key: a `key()` is a full override, and no keyGenerator runs.
+     * Without `key()` on the chain it is resolveDefaultKey alone. With one but
+     * no request context it rejects (keyWithoutContextError).
+     *
+     * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
+     * by function: it runs once per request whatever the default key
+     * (document, partial or `doc` shell prefix) and however many scopes share
+     * it (sibling routes under one keyed cache()). A shell capture, whose
+     * context is `Object.create` of the request's (shell-capture.ts), reads the
+     * foreground's results through the prototype chain and never runs `key()`
+     * itself: a `key()` calling `cookies()` would trip the capture guard there,
+     * and a capture must store the partition its request resolved.
+     */
+    resolveKeyFrom(defaultKey: string): Promise<string>;
+    /**
+     * @internal The request partition of a ppr route's shell under this scope
+     * (resolveShellPartition): the chain's `key()` results, composed like the
+     * record key but without the default key, which the URL-based shell key
+     * already carries. A scope without its own `key()` whose store has a
+     * keyGenerator adds that result when it differs from the `doc` default
+     * key, as an unkeyed scope's partition always did: the record is split by
+     * it, so the shell must be too. Undefined (synchronously, with no work)
+     * when nothing can partition; null when nothing does.
+     */
+    resolvePartition(pathname: string, params: Record<string, string> | undefined): Promise<string | null> | undefined;
+    /** The chain's `key()` results, each once per request (memoizedKey). */
+    private resolveKeyResults;
+    /**
+     * This scope's store keyGenerator result for `defaultKey` (once per request
+     * and default key), else `defaultKey` (resolveCacheKey).
+     */
+    private resolveDefaultKey;
     /**
      * @internal Whether a cache read/write is allowed for the current request:
      * the scope is enabled AND its `condition` (if any) returns true. "read"
@@ -127,8 +216,10 @@ export declare class CacheScope {
      * @param pathname - URL pathname for cache key generation
      * @param params - Route params for cache key generation
      * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     * @param claimLoaderPushes - The handler context's _claimLoaderPushes, for
+     *   restoreHandles' loader-owned values
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<{
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, claimLoaderPushes?: (loaderId: string) => boolean): Promise<{
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | null>;
@@ -150,7 +241,7 @@ export declare class CacheScope {
      * A corrupt entry that was evicted reads as `miss`: the store was consulted
      * and holds nothing servable, which is the post-eviction truth.
      */
-    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<CacheRouteLookupOutcome>;
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean, claimLoaderPushes?: (loaderId: string) => boolean): Promise<CacheRouteLookupOutcome>;
     /**
      * Record this scope's segment-DSL cache({ tags }) into the request tag union
      * synchronously, under the same gate cacheRoute() uses for a write.
@@ -179,11 +270,28 @@ export declare class CacheScope {
     cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
 }
 /**
- * Create a cache scope from entry's cache config
+ * @internal The request partition of a ppr route's shell: with a route
+ * cache() scope, its CacheScope.resolvePartition (the chain's `key()`
+ * results, composed, plus a keyGenerator's contribution for a scope without
+ * its own `key()` (#970)); with none, the app store's keyGenerator result
+ * given the document default key. Undefined (synchronously, with no work)
+ * when neither applies: the shell key stays host + path + filtered search.
+ * Resolves to null when the partition is the default key itself (a
+ * keyGenerator that returns it unchanged): that partitions nothing, so the
+ * shell stays unpartitioned and keeps its build shell. The shell's key, its
+ * read and capture, and partial replay all use it, so a visitor is only
+ * served its own partition. A rejected promise is a failed key resolution:
+ * the caller serves no shell.
+ */
+export declare function resolveShellPartition(routeScope: CacheScope | null | undefined, appStore: SegmentCacheStore | null | undefined, pathname: string, params: Record<string, string> | undefined): Promise<string | null> | undefined;
+/**
+ * Create a cache scope from entry's cache config. `shortCode` is the cache()
+ * entry's: a scope nested in an enabled parent keeps the parent's boundary
+ * (one entry covers both), any other opens its own at this entry.
  */
 export declare function createCacheScope(config: {
     options: PartialCacheOptions | false;
-} | undefined, parent?: CacheScope | null): CacheScope | null;
+} | undefined, parent?: CacheScope | null, shortCode?: string): CacheScope | null;
 type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"]>;
 /**
  * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key
@@ -192,24 +300,29 @@ type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"
  * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
  * the explicit-scope composition sites (capture doc record in the cache-store
  * middleware, seeded replay fallback in withCacheLookup) so both ends of the
- * shell contract resolve the SAME canonical document key.
+ * shell contract resolve the SAME canonical document key. A document HIT
+ * tail's marker carries the entry's own key (`fixedDocKey`), which wins over
+ * key resolution.
  */
 export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMarker): CacheScope;
 /**
- * Shell fast path: when the route tree derived NO cache scope and the current
- * request context carries the `_shellImplicitCache` marker (a shell capture,
- * an eligible HIT tail, or a normal partial navigation replay), substitute an
- * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
- * matched route as a cache() boundary — the shell entry IS a cache() of the
- * handler layer, with loaders as the live carve-outs
- * (resolveFreshLoadersAndYield).
+ * The doc record scope: when the current request context carries the
+ * `_shellImplicitCache` marker (a shell capture, a document HIT tail, or a
+ * normal partial navigation replay), substitute an implicit doc-level scope
+ * so withCacheLookup/withCacheStore treat the WHOLE matched route as a
+ * cache() boundary — the shell entry IS a cache() of the handler layer, with
+ * loaders as the live carve-outs (resolveFreshLoadersAndYield).
  *
- * An existing scope — including an explicit cache(false) opt-out — always
- * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
- * are never overridden, and cache(false) keeps the tail on the full handler
- * re-run path. On the navigation-replay serve path the marker still composes
- * with an explicit scope downstream (withCacheLookup's seeded fallback after
- * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ * A document HIT tail (`docTail`) always gets the implicit scope: it replays
+ * the shell's own record and never consults a route-derived scope, whose
+ * opt-outs the serve gate evaluated before the commit (shellServePlan). Every
+ * other marker leaves an existing scope — including an explicit cache(false)
+ * — in place: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden. On the navigation-replay serve path the marker still
+ * composes with an explicit scope downstream (withCacheLookup's seeded
+ * fallback after an explicit-tier miss) — see `onExplicitHit` on
+ * `_shellImplicitCache`; during a capture, recordShellCaptureDocRecord
+ * (cache-store.ts) writes the record for such a scope.
  */
 export declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;
 export {};

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

@@ -10,6 +10,54 @@
  * profile/DSL tags before storing.
  */
 import { type RequestContext } from "../server/request-context.js";
+import { type LoaderIdentityRead } from "../server/context.js";
+/**
+ * Arm the record tag owners for `ctx`: its match resolved a cache scope, so
+ * it can write a route cache() record (match-api.ts). A capture's or
+ * background re-render's derived context inherits the flag.
+ */
+export declare function armRecordTagOwners(ctx?: RequestContext | undefined): void;
+/** Whether `ctx` records tag owners (see armRecordTagOwners). */
+export declare function recordTagOwnersArmed(ctx?: RequestContext | undefined): boolean;
+/**
+ * Call `fn(arg)` inside segment `segmentId`'s tag scope: tags recorded while
+ * it or its async continuations run (outside a loader body) are owned by that
+ * segment. Unarmed, it is a plain call.
+ */
+export declare function runInSegmentTagScope<R, A = undefined>(segmentId: string, fn: (arg: A) => R, arg?: A): R;
+/**
+ * Record that the current owner reads loader `loaderId`'s value (ctx.use),
+ * so the loader's tags follow the reader onto a record. The DSL funnel
+ * starting a loader (resolveLoaderData, inside the DSL loader scope but no
+ * loader body) is not a reader.
+ */
+export declare function linkLoaderTags(loaderId: string, ctx?: RequestContext | undefined): void;
+/**
+ * Record `tags` as loader `loaderId`'s own, read outside its body (its
+ * cache() config tags, or a loader-cache HIT's stored tags):
+ * recordRequestTags with an explicit owner.
+ */
+export declare function recordLoaderTags(loaderId: string, tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * The tags segment `segmentId`'s content recorded in `ctx`: its own, plus
+ * those of every loader it consumed, transitively.
+ */
+export declare function getSegmentTags(ctx: RequestContext, segmentId: string): ReadonlySet<string>;
+/**
+ * Record `tags` onto each of `segmentIds` (a route cache() HIT replaying
+ * those segments): a record written from the replay, such as a shell
+ * capture's doc record (match-middleware/cache-store.ts), then carries them
+ * as a fresh render's record would. Unarmed, a no-op.
+ */
+export declare function recordSegmentTags(segmentIds: readonly string[], tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * The owner of the loaders a shell capture bakes (loader-cache.ts bake
+ * lane): their data is shell material that no handler reads, so their tags
+ * reach the shell through this owner (shell-capture.ts), not a record.
+ */
+export declare const SHELL_BAKE_TAG_OWNER: string;
+/** Link loader `loaderId`'s tags to `ownerId` (see SHELL_BAKE_TAG_OWNER). */
+export declare function linkLoaderTagsTo(ownerId: string, loaderId: string, ctx?: RequestContext | undefined): void;
 export declare function normalizeTag(tag: string): string | null;
 export declare function normalizeTags(tags: Iterable<string>): string[];
 /**
@@ -32,14 +80,15 @@ export declare function normalizeTags(tags: Iterable<string>): string[];
  *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
  *    execution-PRESERVING (everything still runs underneath; only document bytes
  *    are shortcut), so its tags ride this existing instrument rather than a
- *    first-class ppr key/tag API. The shell-expiry invariant holds by
- *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
- *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
- *    never execute during capture, so nothing under a hole can tag the shell).
+ *    first-class ppr key/tag API. Whatever renders into the shell records here,
+ *    at capture or on the route's cache() record the capture replays. A masked
+ *    live-lane loader never executes at capture, so its own tags reach a shell
+ *    only through a handler that reads it (ctx.use).
  *
- * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
- * level, not the segment (only the "use cache" runtime enters the tag scope) — a
- * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * Inside a route cache() boundary the render-callable form also tags that
+ * route's cache() record, which re-records it on every HIT (#957). A loader's
+ * tags reach the record only when a handler consumes its value (ctx.use);
+ * see runInSegmentTagScope / linkLoaderTags. An empty/whitespace-only tag is
  * dropped in both forms (the render-callable form silently, via normalizeTags in
  * recordRequestTags; the scope form with a dev warning).
  *
@@ -63,6 +112,42 @@ export declare function normalizeTags(tags: Iterable<string>): string[];
  */
 export declare function cacheTag(...tags: string[]): void;
 export declare function recordRequestTags(tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * Arm the per-execution loader tag sets for `ctx`: its match resolved a
+ * loader bound with its own cache() (match-api.ts, bindsLoaderCache), or such
+ * a binding started (loader-cache.ts). A loader-cache MISS captures its own
+ * execution and encodes either way.
+ */
+export declare function armLoaderTagSets(ctx?: RequestContext | undefined): void;
+/** Whether `ctx` records per-execution loader tag sets (armLoaderTagSets). */
+export declare function loaderTagSetsArmed(ctx: RequestContext | undefined): boolean;
+/**
+ * Call `fn`, adding every tag recorded in its async chain
+ * (recordRequestTags, recordLoaderTags) to `into`, until a loader body
+ * started inside it takes over with its own set.
+ */
+export declare function captureRecordedTags<T>(into: Set<string>, fn: () => T): T;
+/** `into` also answers for every tag `from` records. */
+export declare function linkRecordedTags(into: Set<string>, from: Set<string>): void;
+/** Mark a loader's value promise as carrying `tags` (see readValueTags). */
+export declare function tagLoaderValue(value: object, tags: Set<string>): void;
+/** A loader value's tags also answer for `tags` (tagLoaderValue). */
+export declare function linkValueTags(value: object, tags: Set<string>): void;
+/** The current execution reads a loader's value: it takes on its tags. */
+export declare function readValueTags(value: object): void;
+/**
+ * A loader-cache HIT restores the read its entry's MISS recorded onto the
+ * value's set, so an unkeyed reader of the value refuses it as it would on
+ * the MISS (loader-cache.ts identity mark).
+ */
+export declare function markIdentityRead(set: Set<string>, read: LoaderIdentityRead): void;
+/**
+ * The identity read `root`'s execution recorded, or one a set it links to
+ * recorded, nearest first (breadth-first, so the execution's own read wins).
+ */
+export declare function recordedIdentityRead(root: Set<string>): LoaderIdentityRead | undefined;
+/** `root`'s tags plus those of every set it links to, transitively. */
+export declare function flattenRecordedTags(root: Set<string>): Set<string>;
 /**
  * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
  * accumulate into the returned Set.

package/dist/types/cache/cf/cf-base64.d.ts

@@ -1,4 +1,10 @@
 /** Encode ArrayBuffer to base64 string. */
 export declare function bufferToBase64(buffer: ArrayBuffer): string;
+/** Encode bytes (a view's own region only) to a base64 string. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decode a base64 string to bytes. Throws on a character outside the alphabet. */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/** The byte length `base64` decodes to (padded or not), without decoding. */
+export declare function base64ByteLength(base64: string): number;
 /** Decode base64 string to ArrayBuffer. */
 export declare function base64ToBuffer(base64: string): ArrayBuffer;

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -110,3 +110,14 @@ export declare const EDGE_READ_TIMEOUT_MS = 20;
  * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
  */
 export declare const KV_READ_TIMEOUT_MS = 170;
+/**
+ * Floor (ms) on the budget for reading a PPR shell's snapshot, the rest of a
+ * frame whose head and prelude were already read. A document HIT has sent
+ * its prelude by then and cannot render the rest without the snapshot's doc
+ * record, so a timed-out read degrades the HIT (the entry is replaced, the
+ * page reloads once into a MISS; rsc-rendering.ts degradeUnreplayableShell).
+ * That costs far more than waiting, so a slow body read gets at least this
+ * long; `kvReadTimeoutMs` above it wins, and `kvReadTimeoutMs <= 0` still
+ * disables the bound.
+ */
+export declare const SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS = 1000;