@rangojs/router 0.18.0 → 0.19.0

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

@@ -3,32 +3,16 @@ declare global {
         readonly default: Cache;
     }
 }
-/**
- * Cloudflare Edge Cache Store
- *
- * Production cache store using Cloudflare's Cache API (L1) with optional
- * KV persistence (L2).
- *
- * L1 (Cache API): Per-colo, fast, ephemeral. Handles SWR atomically.
- * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
- *
- * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
- * Write flow: L1 write + L2 write (both via waitUntil)
- *
- * Features:
- * - Extended TTL for SWR window (max-age = ttl + swr)
- * - Staleness via x-edge-cache-stale-at header
- * - Atomic REVALIDATING status for thundering herd prevention (L1 only)
- * - Non-blocking writes via waitUntil
- * - KV L2 for cross-colo cache persistence
- */
 import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
 export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
 import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions } from "./cf-cache-types.js";
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
-/** @internal Reset the per-isolate shell and marker memos (tests). */
+/**
+ * @internal Reset the per-isolate shell and marker memos and the once-per-
+ * isolate warnings (tests).
+ */
 export declare function resetCFShellMemoForTests(): void;
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
@@ -290,7 +274,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Generation gate for shell writes and the capture scheduler
      * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
-     * Without KV there are no markers: in purge mode the per-request memo is
+     * Without KV there are no markers: in purge mode the per-request mask is
      * the only signal — a capture racing THIS request's updateTag() is still
      * rejected (read-your-own-writes), while cross-request races are bounded
      * by ttl+swr exactly like the data families' purge-mode writes. Without
@@ -553,16 +537,16 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * configured), invalidateTags() evicts L1 entries via a Cloudflare
      * purge-by-tag call, so a hit that SURVIVED is trusted without a per-read
      * marker lookup — that skipped lookup is the entire point of purge mode.
-     * Only the per-request memo is consulted (synchronous, no KV read) so a
-     * request that ran updateTag() still masks its own entries during the purge
-     * propagation window (read-your-own-writes).
+     * Only the request's mask and its memo are consulted (synchronous, no KV
+     * read) so a request that ran updateTag() still misses its own entries
+     * during the purge propagation window (read-your-own-writes).
      *
      * The trust is conditional on the entry actually CARRYING this store's
      * entry Cache-Tag tokens (`headers`): an entry a purge cannot reach — one
      * written before the tokens existed, or whose tag set overflowed the
      * Cache-Tag header limit — keeps the full marker check, or purge mode
      * would serve it stale until TTL with no eviction path. KV-less there are
-     * no markers, so it gets the per-request memo check like any hit (#973).
+     * no markers, so it gets the per-request mask check like any hit (#973).
      *
      * Without tagPurge this is the full marker cascade. KV-tier reads and
      * shells always use isGloballyInvalidated directly: purge cannot reach KV,
@@ -575,9 +559,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Read a tag's latest invalidation timestamp (or null if never invalidated)
      * through the cascade: per-request memo -> per-colo L1 cache (only when
-     * tagCacheTtl > 0) -> KV (the global truth). The memo is always consulted
-     * first so it stays authoritative within a request (read-your-own-writes),
-     * and every KV/L1 result is written back into the memo. A Cache API miss
+     * tagCacheTtl > 0) -> KV (the global truth). Every KV/L1 result is written
+     * back into the memo, so the request reads one value per tag. A Cache API miss
      * always falls through to KV; absence is represented by a cached sentinel,
      * never by a miss.
      *
@@ -588,9 +571,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private readTagMarker;
     /**
-     * A PPR shell read's marker for `tag`: this request's own value if it has
-     * one (its invalidateTags() writes, or a store read), else through the
-     * per-isolate marker memo (isolate-tag-memo.ts, stale-while-revalidate
+     * A PPR shell read's marker for `tag`: this request's own store read if it
+     * has one, else through the per-isolate marker memo (isolate-tag-memo.ts,
+     * stale-while-revalidate
      * under `markerFreshMs` / `markerMaxStaleMs`; a request carrying the
      * fresh-reads cookie reads L1/KV). The value is kept in the request's
      * shell-read record, never in the per-request memo the data families read,
@@ -679,14 +662,45 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private putTagMarkerL1;
     /**
-     * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
-     * SAME KV markers used by runtime envelopes also evict immutable build shells
-     * and captures whose write races updateTag(). Thin public wrapper over the
-     * shell generation check (marker >= since, fail open); KV-less it degrades
-     * to the per-request memo in purge mode and to false otherwise — see
+     * SegmentCacheStore.isTagsInvalidatedSince: the SAME KV markers used by
+     * runtime envelopes also evict immutable build shells, and gate the writes
+     * of cache executions that started before an invalidation (#977,
+     * tag-invalidation.ts predatesInvalidation). Marker >= since. A marker read
+     * that fails or times out answers false (fail open), or true for the write
+     * gate (`failClosed`). With KV each marker is read past the per-request
+     * memo (isInvalidatedSincePastMemo); KV-less it degrades to the per-request
+     * mask in purge mode and to false otherwise — see
      * isShellGenerationInvalidated.
      */
-    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    isTagsInvalidatedSince(tags: string[], sinceMs: number, options?: {
+        failClosed?: boolean;
+    }): Promise<boolean>;
+    /**
+     * isTagsInvalidatedSince with KV, never answered from a marker value this
+     * request read before the asking gate. A write gate asks after an
+     * execution that can run for seconds, and the per-request memo can hold
+     * the marker the request read before it (a stale hit reads its entry's
+     * markers, then its refresh runs): answered from it, another isolate's
+     * invalidation in between let the refresh write.
+     *
+     * - This request's own invalidations answer from its mask, checked again
+     *   once the reads are back: a read in flight when the request invalidated
+     *   one of the tags resolved to the marker before it.
+     * - Each tag is read through gateMarkerRead (request-tag-mask.ts): gates
+     *   asking while a read is in flight share it; a settled read is not
+     *   reused.
+     * - The read returns its own value from L1 (tagCacheTtl) or KV, not one an
+     *   older read of the tag memoized while it was in flight, and fills the
+     *   memo only when it holds nothing, so a build shell's check still serves
+     *   the request's later reads. A timed-out read fills nothing.
+     * - It publishes to L1 unless the request masked the tag
+     *   (fetchTagMarker), and never without a request context (a detached
+     *   waitUntil task), where a mask cannot be told apart.
+     * - A read that fails or times out answers `failClosed`: the write gate
+     *   counts it as an invalidation, other callers as none.
+     * @internal
+     */
+    private isInvalidatedSincePastMemo;
     /**
      * Invalidate every entry tagged with any of `tags`. Receives the whole batch
      * from one updateTag()/revalidateTag() call so the eager-purge hook fires
@@ -716,14 +730,11 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     invalidateTags(tags: string[]): Promise<void>;
     /**
      * The request-local half of invalidateTags(), run before its first await
-     * (#973): this request's marker memo takes the new marker, so every later
+     * (#973): the request masks the tags (request-tag-mask.ts), so every later
      * read in the request (data families, purge-mode L1 hits, shell reads)
-     * treats the tags as invalidated at `invalidatedAt` without waiting for the
-     * KV put or the purge that revalidateTag() leaves to waitUntil. Written
-     * before the durable write is confirmed: if that write fails, this request
-     * pays extra misses, never a stale read, and later requests read the
-     * durable state. Skipped where no read consults the memo (neither KV nor
-     * tagPurge).
+     * treats them as invalidated at `invalidatedAt` without waiting for the KV
+     * put or the purge that revalidateTag() leaves to waitUntil. Skipped where
+     * no read consults the mask (neither KV nor tagPurge).
      */
     private maskTagsForRequest;
     /** invalidateTags' marker writes, tag purge, and hooks. */

package/dist/types/cache/cf/cf-shell-frame.d.ts

@@ -24,7 +24,7 @@ export interface ShellFrameHead {
     /** ShellCacheEntry.reactVersion */
     rv: string;
     /** ShellCacheEntry.buildVersion */
-    bv?: string;
+    bv: string;
     /** Capture-generation start time (ms epoch), used by tag marker checks. */
     c: number;
     /** When the entry becomes stale (ms epoch). */

package/dist/types/cache/cf/cf-tag-marker-memo.d.ts

@@ -12,22 +12,7 @@ export declare const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
  * never "no marker" - absence is only ever represented by this cached sentinel.
  */
 export declare const TAG_MARKER_ABSENT = "none";
-/**
- * Request context -> store instance -> T, both levels weakly held. Also
- * VercelCacheStore's request tag mask (#973).
- */
-export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
-/** The value for (ctx, store), created on first use. */
-export declare function perRequestStoreValue<T>(map: PerRequestStoreMap<T>, ctx: object, store: object, create: () => T): T;
 export declare function getTagMarkerMemo(ctx: object, store: object): Map<string, number | null>;
-/**
- * Mask `tags` at `at` for the rest of the request: in the request's mask and
- * in every memo the request's contexts hold for `store` (a memo created later
- * starts from the mask).
- */
-export declare function maskRequestTags(ctx: object, store: object, tags: readonly string[], at: number): void;
-/** Whether this request masked `tag` through `store` (maskRequestTags). */
-export declare function isRequestMasked(ctx: object, store: object, tag: string): boolean;
 /**
  * A request's PPR shell-read marker reads (issue #941), kept apart from the
  * per-request memo above, HIT or MISS. A shell read may answer a marker from

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

@@ -13,6 +13,16 @@
  * 4. If miss → run handler, cache if response has cache headers
  */
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+import { type RequestContext } from "../server/request-context.js";
+/**
+ * Whether this cache will store the response the current render produces, as
+ * far as the render can tell: the middleware runs it (a MISS or a stale
+ * refresh) and the response stub already opts in. payloadInitialTheme
+ * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
+ * Cache-Control written after next() is not on the stub yet; for that render
+ * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
+ */
+export declare function documentCacheStoresRender(reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">): boolean;
 export interface DocumentCacheOptions<TEnv = any> {
     /**
      * Skip caching for specific paths (e.g., API routes)

package/dist/types/cache/handle-snapshot.d.ts

@@ -44,6 +44,28 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
 export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore): Record<string, SegmentHandleData>;
 /** The owners of captureHandles' values; undefined when none is owned. */
 export declare function captureHandleOwners(segments: ResolvedSegment[], handleStore: HandleStore): HandleOwners | undefined;
+/** How restoreHandles delivers a record's loader-owned values. */
+export interface OwnedPushDelivery {
+    /**
+     * Asked once per owner delivered through pushReplayed
+     * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
+     */
+    claim?: (loaderId: string) => boolean;
+    /**
+     * A PPR shell's record (capture, document HIT tail, navigation replay): the
+     * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
+     * the store (HandleStore.markLiveLane). A hole's values are replayed
+     * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
+     * place (HandleStore.redeliverReplays), and its run ending without a push
+     * drops them (HandleStore.settleLoaderRun).
+     */
+    liveLane?: ReadonlySet<string>;
+    /**
+     * A document HIT tail: every owner outside `liveLane` goes through
+     * pushRestored and stands, unclaimed.
+     */
+    restore?: boolean;
+}
 /**
  * Restore handle data from a cached snapshot into the handle store.
  * Used when serving cached segments to replay their handle data: a route
@@ -51,15 +73,25 @@ export declare function captureHandleOwners(segments: ResolvedSegment[], handleS
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
  * recorded order, an owned value through pushReplayed: if the owning loader
- * runs on the HIT (a live loader, or a promise-carrying `ssr: false` one;
- * a promise-free one is served from the shell and does not), its live pushes
- * replace the recorded ones in place instead of appending a second copy. `claim`
- * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
- * loader's own cache() HIT does not replay its pushes a second time
- * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A
- * record without owners restores as a plain replay.
+ * runs (a client navigation replaying a ppr route's cache() record runs its
+ * `ssr: false` loaders), its live pushes replace the recorded ones in place
+ * instead of appending a second copy. `owned.claim` is asked once per
+ * owner, so the loader's own cache() HIT does not replay its pushes a second
+ * time (loader-cache.ts replayLoaderHandles). A record without owners
+ * restores as a plain replay.
+ *
+ * `owned.restore`: a document HIT tail restoring the shell's doc record
+ * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
+ * through pushRestored and stand: a run of that loader on the HIT (a
+ * promise-carrying `ssr: false` loader, one whose record asks for a run)
+ * reads the store, and its settled pushes are dropped, not swapped in.
+ * Nothing is claimed, so the loader's own cache() HIT still replays the
+ * pushes the record could not keep (the thenable ones pushRestored lets
+ * through). A loader the route also runs on the live lane is a hole: its
+ * values keep pushReplayed, unclaimed, and its live run replaces them
+ * (#936), even inside a restored loader's body (`owned.liveLane`).
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, claim?: (loaderId: string) => boolean): void;
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For

package/dist/types/cache/invalidation-order.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a cache execution ("use cache", a loader's own cache(), a route
+ * cache() render, a request's document) started: its position in this
+ * isolate's order, and the store clock for invalidations this isolate did
+ * not see.
+ */
+export interface ExecutionStart {
+    readonly seq: number;
+    readonly at: number;
+}
+/** Record an execution's start, before it reads its data. */
+export declare function executionStart(): ExecutionStart;
+/**
+ * Whether this isolate invalidated any of `tags` after `since` (the `seq` of
+ * an ExecutionStart), in any request: the execution's value may predate the
+ * invalidation, so it is neither joined nor written (#973, #977).
+ */
+export declare function invalidatedSince(tags: readonly string[] | undefined, since: number): boolean;
+/**
+ * Record an invalidation of `tags` in this isolate's order
+ * (updateTag()/revalidateTag(), before any store sees it).
+ */
+export declare function markInvalidated(tags: readonly string[]): void;

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

@@ -0,0 +1,54 @@
+/**
+ * The per-request tag mask behind read-your-own-writes (#973).
+ *
+ * updateTag() and revalidateTag() call a store's invalidateTags() inside the
+ * request, and a built-in store masks the tags here before its first await:
+ * every later read in that request, through any context derived from it,
+ * treats an entry carrying one of the tags, written at or before the mask, as
+ * invalidated, without waiting for the durable write (the KV marker put, the
+ * tag purge, expireTag()) that revalidateTag() leaves to waitUntil. The mask
+ * only ever turns this request's hits into misses: if the durable write then
+ * fails, the request paid extra misses, never a stale read, and other
+ * requests read the durable state. CFCacheStore and VercelCacheStore share it.
+ */
+/** Request context -> store instance -> T, both levels weakly held. */
+export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
+/** The value for (ctx, store), created on first use. */
+export declare function perRequestStoreValue<T>(map: PerRequestStoreMap<T>, ctx: object, store: object, create: () => T): T;
+/**
+ * The request a context belongs to: RequestContext._requestRoot, which
+ * createRequestContext defines and a derived context (Object.create: a shell
+ * capture, a PPR HIT tail) inherits. A bare test context is its own root.
+ */
+export declare function requestRoot<T extends object>(ctx: T & {
+    _requestRoot?: T;
+}): T;
+/** Mask `tags` at `at` through `store` for the rest of `ctx`'s request. */
+export declare function maskRequestTags(ctx: object, store: object, tags: readonly string[], at: number): void;
+/**
+ * Whether `ctx`'s request masked one of `tags` through `store` at or after
+ * `taggedAt`. `>=`, as the stores' marker checks: an entry written in the
+ * invalidation's millisecond may hold a value computed before it, so it
+ * misses (a false miss, never a stale read).
+ */
+export declare function maskedForRequest(ctx: object | undefined, store: object, tags: readonly string[] | undefined, taggedAt: number): boolean;
+/**
+ * A marker read for a write gate (isTagsInvalidatedSince, from
+ * tag-invalidation.ts predatesInvalidation), shared by the gates of a
+ * request that ask while it is in flight. A page's writes (its "use cache"
+ * misses, its route record, its document) finish together and often carry
+ * the same tags, and each read its own marker before: one KV or
+ * runtime-cache read per tag per write.
+ *
+ * A read answers only for invalidations before it was issued. So a gate
+ * shares one still in flight, issued at or after its execution started
+ * (`sinceMs` is the millisecond after that start), and the read is dropped
+ * once it settles: a gate asking later reads again, and a shared read
+ * leaves open at most one marker round-trip. Reusing a settled read let a
+ * gate asking long after it miss another isolate's invalidation in
+ * between (a capture's putShell answered by a "use cache" write's read
+ * from the start of the capture), and kept a timed-out read's fail-open
+ * answer for the rest of the request. Without a request context `read()`
+ * runs unshared.
+ */
+export declare function gateMarkerRead<T>(ctx: object | undefined, store: object, tag: string, sinceMs: number, read: () => Promise<T>): Promise<T>;