vinext 1.0.1 → 1.2.0

package/dist/shims/cache-adapter-instantiate.js

@@ -0,0 +1,118 @@
+//#region src/shims/cache-adapter-instantiate.ts
+const REQUIREMENTS = {
+	data: {
+		methods: [
+			"get",
+			"set",
+			"revalidateTag"
+		],
+		booleans: [],
+		description: "A data cache adapter implements get, set and revalidateTag."
+	},
+	cdn: {
+		methods: [
+			"get",
+			"set",
+			"revalidateTag",
+			"buildResponseHeaders"
+		],
+		booleans: ["ownsBackgroundRevalidation"],
+		description: "A CDN cache adapter implements get, set, revalidateTag and buildResponseHeaders, and sets ownsBackgroundRevalidation to a boolean."
+	}
+};
+/**
+* Whether `value` has a [[Construct]] internal method. A Proxy is
+* constructible exactly when its target is; its no-op `construct` trap
+* answers without running the export or reading any of its properties.
+*/
+function isConstructor(value) {
+	if (typeof value !== "function") return false;
+	try {
+		new new Proxy(value, { construct: () => ({}) })();
+		return true;
+	} catch {
+		return false;
+	}
+}
+const CLASS_SOURCE = /^class\b/;
+/**
+* Whether an export is class syntax and must be invoked with `new`. The
+* [[Construct]] check excludes methods named `class`, whose source text
+* also starts with that word.
+*/
+function isClassExport(value) {
+	if (!isConstructor(value)) return false;
+	try {
+		return CLASS_SOURCE.test(Function.prototype.toString.call(value));
+	} catch {
+		return false;
+	}
+}
+function describeValue(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "an object";
+	return typeof value === "undefined" ? "undefined" : `a ${typeof value}`;
+}
+const ignore = () => {};
+/**
+* Attach a no-op rejection handler with the intrinsic `Promise.prototype.then`,
+* which throws on a non-Promise before reading anything from it. Returns the
+* derived promise, which a Promise subclass's species constructor chooses.
+*/
+function handleRejection(promise) {
+	return Promise.prototype.then.call(promise, void 0, ignore);
+}
+/**
+* Whether `value` is a Promise, judged by its internal slot or this realm's
+* Promise prototype chain, never by a `then` member: adapter contracts are
+* structural and do not reserve `then`, so an adapter's own `then` method is
+* never read or invoked.
+*
+* A Promise from any realm passes the intrinsic `then`'s brand check, which
+* also attaches a no-op rejection handler, so the discarded result cannot
+* become an unhandled rejection. The derived promise that call returns is
+* handled too, since a subclass's species constructor may return a rejected
+* one.
+*
+* Known limitation: when a Promise subclass's `constructor` or
+* `Symbol.species` lookup throws, that call fails after the brand check, and
+* no handler can be attached (every way of observing a Promise goes through
+* that lookup or its `then`). Such a Promise is still rejected when it comes
+* from this realm, the one adapter modules are evaluated in; one from another
+* realm is judged by its members like any other value.
+*/
+function markHandledIfPromise(value) {
+	let derived;
+	try {
+		derived = handleRejection(value);
+	} catch {
+		try {
+			return value instanceof Promise;
+		} catch {
+			return false;
+		}
+	}
+	try {
+		handleRejection(derived);
+	} catch {}
+	return true;
+}
+function instantiateCacheAdapter(exported, args, slot) {
+	const label = `cache.${slot} adapter`;
+	const requirements = REQUIREMENTS[slot];
+	if (typeof exported !== "function") {
+		const hint = exported !== null && typeof exported === "object" ? " To use an adapter object directly, export a factory that returns it: `export default () => adapter`." : exported === void 0 ? " Check that the module has a default export." : "";
+		throw new TypeError(`${label}: the module's default export must be a factory function or a class that receives { env, options }, got ${describeValue(exported)}.${hint}`);
+	}
+	const adapter = isClassExport(exported) ? new exported(args) : exported(args);
+	const isObjectLike = adapter !== null && typeof adapter === "object" || typeof adapter === "function";
+	if (isObjectLike && markHandledIfPromise(adapter)) throw new TypeError(`${label}: the default export returned a Promise. Adapter factories must return the adapter synchronously; defer async setup to the adapter's methods.`);
+	if (!isObjectLike) throw new TypeError(`${label}: the default export must produce an adapter object, got ${describeValue(adapter)}. ${requirements.description}`);
+	const record = adapter;
+	const problems = [...requirements.methods.filter((method) => typeof record[method] !== "function").map((method) => `method ${method}`), ...requirements.booleans.filter((property) => typeof record[property] !== "boolean").map((property) => `boolean ${property}`)];
+	if (problems.length > 0) throw new TypeError(`${label}: the adapter produced by the default export is missing ${problems.join(", ")}. ${requirements.description}`);
+	return adapter;
+}
+//#endregion
+export { instantiateCacheAdapter, isClassExport, isConstructor };

package/dist/shims/cache-callable-runtime.d.ts

@@ -4,48 +4,12 @@ import { RegisterCachedFunctionOptions } from "./cache-runtime.js";
 declare const CACHE_CAPTURE_TYPE = "use-cache-captures";
 type CacheCaptureEnvelope = {
   type: typeof CACHE_CAPTURE_TYPE;
-  encrypted: string | PromiseLike<string>;
+  encrypted: Promise<string>;
 };
-/**
- * Flight serializes a promise as its resolved value and drops its own fields.
- * Next.js params are promises that also expose their resolved fields, and the
- * cache key is built from those fields, so the payload carries each such
- * promise's fields next to the arguments and decoding assigns them back.
- */
-type EncodedCacheArguments = {
-  args: unknown[];
-  thenableObjects: EncodedThenableObject[];
-};
-/**
- * Flight writes each object once, so `promise` decodes to the same promise as
- * every other reference to it, including ones inside resolved values, and the
- * fields share references with the arguments. The fields build the cache key;
- * the resolved value can differ: the params proxy hides params named like
- * promise or React fields (`value`, `status`) from its own keys but still
- * resolves to them.
- */
-type EncodedThenableObject = {
-  fields: Record<string, unknown>;
-  promise: PromiseLike<unknown>;
-};
-export declare function encryptCacheCaptures(captures: unknown[]): CacheCaptureEnvelope;
-/**
- * What to do when a read would run a getter: `reject` throws
- * `UnreplayableCacheArgumentsError`, `skip` leaves the getter unread.
- */
-type GetterHandling = "reject" | "skip";
-/**
- * Collect the own fields of every promise-augmented object in the arguments,
- * including ones inside resolved promise values. The arguments are passed to
- * Flight as they are, so Flight keeps their shared references and cycles.
- * With `getters: "reject"`, throws `UnreplayableCacheArgumentsError` when the
- * arguments hold a getter; with `"skip"`, promise fields behind a getter are
- * not recorded.
- */
-export declare function encodeCacheArguments(args: unknown[], getters?: GetterHandling): Promise<EncodedCacheArguments>;
-/** Restore the promise fields that `encodeCacheArguments` captured before Flight encoding. */
-export declare function decodeCacheArguments(value: unknown): unknown[];
-export declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant: string, options: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
-/** Load and invoke one transformed cache function through its server-reference identity. */
+export declare function encryptCacheCaptures(referenceId: string, captures: unknown[]): CacheCaptureEnvelope;
+export declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant: string, { captureCount, ...options }: RegisterCachedFunctionOptions & {
+  captureCount?: number;
+}): (...args: TArgs) => Promise<TResult>;
+/** Replay the persisted payload without re-reading or re-encoding caller objects. */
 export declare function invokeCacheFunction(invocation: VinextCacheFunctionInvocation, loadServerAction: (id: string) => Promise<unknown>): Promise<void>;
 //#endregion

package/dist/shims/cache-callable-runtime.js

@@ -1,190 +1,81 @@
-import { isThenableObject, isUseCacheFunction, registerCachedFunction as registerCachedFunction$1 } from "./cache-runtime.js";
+import { restoreFlightReply, snapshotFlightReply } from "./cache-flight-arguments.js";
+import { isUseCacheFunction, memoizeInCacheScope, registerCachedFunction as registerCachedFunction$1, replayCachedFunction } from "./cache-runtime.js";
 import { decryptActionBoundArgs, encryptActionBoundArgs } from "@vitejs/plugin-rsc/utils/encryption-runtime";
+import { createFromReadableStream, renderToReadableStream } from "@vitejs/plugin-rsc/react/rsc";
 //#region src/shims/cache-callable-runtime.ts
 const CACHE_CAPTURE_TYPE = "use-cache-captures";
-function encryptCacheCaptures(captures) {
-	return {
-		type: CACHE_CAPTURE_TYPE,
-		encrypted: encryptCaptures(captures)
-	};
-}
-async function decryptCacheCaptures(value) {
-	if (!isCacheCaptureEnvelope(value)) return;
-	return decryptCacheArguments(value.encrypted);
-}
-async function encryptCaptures(captures) {
-	return encryptActionBoundArgs(await encodeCacheArguments(captures, "skip"));
-}
-async function encryptCacheArguments(args) {
-	return encryptActionBoundArgs(await encodeCacheArguments(args));
-}
-async function decryptCacheArguments(encrypted) {
-	return decodeCacheArguments(await decryptActionBoundArgs(Promise.resolve(encrypted)));
-}
-function isThenable(value) {
-	return "then" in value && typeof value.then === "function";
-}
-function isPlainRecord(value) {
-	const prototype = Object.getPrototypeOf(value);
-	return (prototype === Object.prototype || prototype === null) && !("$$typeof" in value);
-}
-/**
-* The arguments hold a getter. Flight reads it again while serializing, and a
-* getter can return a different value, such as a new promise, on every read,
-* so the recorded promise fields may not match what Flight serializes.
-*/
-var UnreplayableCacheArgumentsError = class extends Error {
-	constructor() {
-		super("Cache function arguments with getters cannot be replayed");
-	}
-};
-/**
-* The own entries of `value` that Flight serializes: every index below an
-* array's `length`, including holes and non-enumerable indices, as
-* `JSON.stringify` reads them, and the enumerable own keys of anything else.
-* A getter, own or inherited through an array hole, is never run.
-*/
-function ownEntries(value, getters) {
-	const keys = Array.isArray(value) ? Array.from({ length: value.length }, (_, index) => String(index)) : Object.keys(value);
-	const entries = [];
-	for (const key of keys) {
-		if (readsGetter(value, key)) {
-			if (getters === "reject") throw new UnreplayableCacheArgumentsError();
-			continue;
-		}
-		entries.push([key, Reflect.get(value, key)]);
-	}
-	return entries;
-}
-/**
-* Whether reading `key` from `value` runs a getter. An array hole reads
-* through the prototype chain, which can hold an indexed data property or
-* accessor. A setter-only accessor reads as `undefined` without running code.
-*/
-function readsGetter(value, key) {
-	for (let target = value; target !== null; target = Reflect.getPrototypeOf(target)) {
-		const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
-		if (descriptor) return typeof descriptor.get === "function";
-	}
-	return false;
-}
-/** Members of the values Flight serializes recursively, which can hold params. */
-function flightMembers(value, getters) {
-	if (value instanceof Map) return [...value].flat();
-	if (value instanceof Set) return [...value];
-	if (isThenableObject(value) || Array.isArray(value) || isPlainRecord(value)) return ownEntries(value, getters).map(([, member]) => member);
-	return [];
+async function encryptArguments(value) {
+	return encryptActionBoundArgs(JSON.stringify(value));
+}
+async function decryptArguments(encrypted) {
+	const serialized = await decryptActionBoundArgs(Promise.resolve(encrypted));
+	if (typeof serialized !== "string") throw new Error("Invalid cache function arguments");
+	const value = JSON.parse(serialized);
+	if (value?.version !== 1) throw new Error("Invalid cache function arguments");
+	return value;
 }
-/**
-* Collect the own fields of every promise-augmented object in the arguments,
-* including ones inside resolved promise values. The arguments are passed to
-* Flight as they are, so Flight keeps their shared references and cycles.
-* With `getters: "reject"`, throws `UnreplayableCacheArgumentsError` when the
-* arguments hold a getter; with `"skip"`, promise fields behind a getter are
-* not recorded.
-*/
-async function encodeCacheArguments(args, getters = "reject") {
-	const settled = /* @__PURE__ */ new Map();
-	for (;;) {
-		const thenableObjects = [];
-		const unsettled = [];
-		const visited = /* @__PURE__ */ new Set();
-		const pending = [args];
-		while (pending.length > 0) {
-			const value = pending.pop();
-			if (typeof value !== "object" || value === null || visited.has(value)) continue;
-			visited.add(value);
-			const children = flightMembers(value, getters);
-			if (isThenableObject(value)) {
-				const fields = Object.fromEntries(ownEntries(value, getters));
-				thenableObjects.push({
-					fields,
-					promise: value
-				});
+function encryptCacheCaptures(referenceId, captures) {
+	return memoizedCaptureEnvelope(referenceId, ...captures);
+}
+const memoizedCaptureEnvelope = memoizeInCacheScope((referenceId, ...captures) => ({
+	type: CACHE_CAPTURE_TYPE,
+	encrypted: encryptCaptures(referenceId, captures)
+}));
+async function encryptCaptures(referenceId, captures) {
+	const files = new FormData();
+	let nextFileId = 0;
+	const temporaryReferences = new class extends WeakMap {
+		get(value) {
+			let id = super.get(value);
+			if (id === void 0 && value instanceof File) {
+				id = String(nextFileId++);
+				super.set(value, id);
+				files.append(id, value);
 			}
-			if (isThenable(value)) {
-				const result = settled.get(value);
-				if (!result) unsettled.push(value);
-				else if (result.status === "fulfilled") children.push(result.value);
-			}
-			for (const child of children) pending.push(child);
+			return id;
 		}
-		if (unsettled.length === 0) return {
-			args,
-			thenableObjects
-		};
-		const results = await Promise.allSettled(unsettled);
-		unsettled.forEach((thenable, index) => settled.set(thenable, results[index]));
-	}
-}
-/** Restore the promise fields that `encodeCacheArguments` captured before Flight encoding. */
-function decodeCacheArguments(value) {
-	if (typeof value !== "object" || value === null || !("args" in value) || !Array.isArray(value.args) || !("thenableObjects" in value) || !Array.isArray(value.thenableObjects)) throw new Error("Invalid cache function arguments");
-	adoptFlightThenables(value);
-	for (const thenableObject of value.thenableObjects) {
-		if (!isEncodedThenableObject(thenableObject)) throw new Error("Invalid cache function arguments");
-		Object.assign(thenableObject.promise, thenableObject.fields);
-	}
-	return value.args;
-}
-function isEncodedThenableObject(value) {
-	if (typeof value !== "object" || value === null || !isPlainRecord(value)) return false;
-	const { fields, promise } = value;
-	return typeof fields === "object" && fields !== null && isPlainRecord(fields) && promise instanceof Promise;
-}
-/**
-* Flight decodes promises as React chunks whose own fields are React's
-* internal state. Adopt them into native promises, which have no own fields,
-* so key serialization sees a promise exactly as the original call did.
-* Flight shares one chunk between references to the same promise, so each
-* chunk is adopted once, including references inside resolved values.
-*/
-function adoptFlightThenables(value, adopted = /* @__PURE__ */ new WeakMap()) {
-	if (typeof value !== "object" || value === null) return value;
-	if (adopted.has(value)) return adopted.get(value);
-	if (isThenable(value)) {
-		const promise = Promise.resolve(value).then((resolved) => adoptFlightThenables(resolved, adopted));
-		promise.catch(() => {});
-		adopted.set(value, promise);
-		return promise;
-	}
-	if (value instanceof Map) {
-		adopted.set(value, value);
-		const entries = [...value];
-		value.clear();
-		for (const [key, item] of entries) value.set(adoptFlightThenables(key, adopted), adoptFlightThenables(item, adopted));
-		return value;
-	}
-	if (value instanceof Set) {
-		adopted.set(value, value);
-		const items = [...value];
-		value.clear();
-		for (const item of items) value.add(adoptFlightThenables(item, adopted));
-		return value;
-	}
-	if (!Array.isArray(value) && !isPlainRecord(value)) return value;
-	adopted.set(value, value);
-	for (const key of Object.keys(value)) Reflect.set(value, key, adoptFlightThenables(Reflect.get(value, key), adopted));
-	return value;
-}
-function isCacheCaptureEnvelope(value) {
-	if (typeof value !== "object" || value === null) return false;
-	if (!("type" in value) || value.type !== CACHE_CAPTURE_TYPE || !("encrypted" in value)) return false;
+	}();
+	const stream = renderToReadableStream(captures, { temporaryReferences });
+	const bytes = await new Response(stream).arrayBuffer();
+	return encryptActionBoundArgs(JSON.stringify({
+		version: 1,
+		referenceId,
+		result: Buffer.from(bytes).toString("base64"),
+		files: await snapshotFlightReply(files)
+	}));
+}
+async function decryptCacheCaptures(value, referenceId, captureCount) {
+	if (typeof value !== "object" || value === null || !("type" in value) || value.type !== CACHE_CAPTURE_TYPE || !("encrypted" in value)) throw new Error("Invalid cache capture arguments");
 	const encrypted = value.encrypted;
-	return typeof encrypted === "string" || typeof encrypted === "object" && encrypted !== null && isThenable(encrypted);
-}
-function registerCachedFunction(fn, id, variant, options) {
+	if (typeof encrypted !== "string" && !(typeof encrypted === "object" && encrypted !== null && "then" in encrypted && typeof encrypted.then === "function")) throw new Error("Invalid cache capture arguments");
+	const serialized = await decryptActionBoundArgs(Promise.resolve(encrypted));
+	if (typeof serialized !== "string") throw new Error("Invalid cache capture arguments");
+	const payload = JSON.parse(serialized);
+	if (payload.version !== 1 || payload.referenceId !== referenceId) throw new Error("Invalid cache capture arguments");
+	const files = restoreFlightReply(payload.files);
+	if (typeof files === "string") throw new Error("Invalid cache capture files");
+	const captures = await createFromReadableStream(new Response(Buffer.from(payload.result, "base64")).body, { temporaryReferences: new Map([...files].map(([id, file]) => [`$${id}`, file])) }, { preserveServerReferences: true });
+	if (!Array.isArray(captures) || captures.length !== captureCount) throw new Error("Invalid cache capture arguments");
+	return captures;
+}
+function registerCachedFunction(fn, id, variant, { captureCount, ...options }) {
+	let decryptCaptures;
+	if (captureCount !== void 0) {
+		const referenceId = options.serverReferenceId;
+		if (referenceId === void 0) throw new Error(`Cache function ${id} has captures but no server reference`);
+		decryptCaptures = (value) => decryptCacheCaptures(value, referenceId, captureCount);
+	}
 	return registerCachedFunction$1(fn, id, variant, {
 		...options,
-		decryptCaptures: decryptCacheCaptures,
-		encodeInvocationArgs: encryptCacheArguments
+		...decryptCaptures ? { decryptCaptures } : {},
+		encodeInvocation: encryptArguments
 	});
 }
-/** Load and invoke one transformed cache function through its server-reference identity. */
+/** Replay the persisted payload without re-reading or re-encoding caller objects. */
 async function invokeCacheFunction(invocation, loadServerAction) {
 	const fn = await loadServerAction(invocation.referenceId);
 	if (!isUseCacheFunction(fn)) throw new Error(`Server reference ${invocation.referenceId} is not a cache function`);
-	await fn(...await decryptCacheArguments(invocation.encryptedArgs));
+	await replayCachedFunction(fn, await decryptArguments(invocation.encryptedArgs));
 }
 //#endregion
-export { decodeCacheArguments, encodeCacheArguments, encryptCacheCaptures, invokeCacheFunction, registerCachedFunction };
+export { encryptCacheCaptures, invokeCacheFunction, registerCachedFunction };

package/dist/shims/cache-flight-arguments.d.ts

@@ -0,0 +1,22 @@
+//#region src/shims/cache-flight-arguments.d.ts
+/** The persisted argument transport. React owns the object graph and wire protocol. */
+export type CacheFlightArguments = {
+  version: 1;
+  reply: string | ([string, string] | [string, string, string, number, string])[];
+  pagePropsIndex?: number;
+  layoutPropsIndex?: number;
+};
+/** Snapshot only the multipart transport, never traverse user arguments. */
+export declare function snapshotFlightReply(reply: string | FormData, pagePropsIndex?: number): Promise<CacheFlightArguments>;
+export declare function restoreFlightReply(args: CacheFlightArguments): string | FormData;
+/**
+ * Like Next.js (use-cache-wrapper.ts, `encodeFormData`), a binary entry is keyed
+ * by its bytes alone. Its name, type, and timestamp are replayed but not keyed:
+ * native FormData gives each Blob wrapper a wall-clock timestamp.
+ *
+ * Hashed synchronously, as Next.js derives its key without leaving the task: a
+ * cache hit must resolve before React flushes the shell, and an async digest
+ * waits for a later event-loop turn.
+ */
+export declare function flightArgumentsKey(args: CacheFlightArguments): string;
+//#endregion

package/dist/shims/cache-flight-arguments.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+//#region src/shims/cache-flight-arguments.ts
+const blobType = Object.getOwnPropertyDescriptor(Blob.prototype, "type").get;
+const fileName = Object.getOwnPropertyDescriptor(File.prototype, "name").get;
+const fileTime = Object.getOwnPropertyDescriptor(File.prototype, "lastModified").get;
+/** Snapshot only the multipart transport, never traverse user arguments. */
+async function snapshotFlightReply(reply, pagePropsIndex) {
+	if (typeof reply === "string") return {
+		version: 1,
+		reply,
+		pagePropsIndex
+	};
+	const entries = [];
+	for (const [name, value] of reply) entries.push(typeof value === "string" ? [name, value] : [
+		name,
+		Buffer.from(await Blob.prototype.arrayBuffer.call(value)).toString("base64"),
+		fileName.call(value),
+		fileTime.call(value),
+		blobType.call(value)
+	]);
+	return {
+		version: 1,
+		reply: entries,
+		pagePropsIndex
+	};
+}
+function restoreFlightReply(args) {
+	if (typeof args.reply === "string") return args.reply;
+	const reply = new FormData();
+	for (const entry of args.reply) {
+		const [name, data] = entry;
+		reply.append(name, entry.length === 2 ? data : new File([Buffer.from(data, "base64")], entry[2], {
+			lastModified: entry[3],
+			type: entry[4]
+		}));
+	}
+	return reply;
+}
+/**
+* Like Next.js (use-cache-wrapper.ts, `encodeFormData`), a binary entry is keyed
+* by its bytes alone. Its name, type, and timestamp are replayed but not keyed:
+* native FormData gives each Blob wrapper a wall-clock timestamp.
+*
+* Hashed synchronously, as Next.js derives its key without leaving the task: a
+* cache hit must resolve before React flushes the shell, and an async digest
+* waits for a later event-loop turn.
+*/
+function flightArgumentsKey(args) {
+	const reply = typeof args.reply === "string" ? args.reply : args.reply.map((entry) => entry.length === 2 ? entry : [entry[0], { bytes: entry[1] }]);
+	return createHash("sha256").update(JSON.stringify({
+		...args,
+		reply
+	})).digest("base64url");
+}
+//#endregion
+export { flightArgumentsKey, restoreFlightReply, snapshotFlightReply };

package/dist/shims/cache-handler.js

@@ -8,7 +8,6 @@ var NoOpCacheHandler = class {
 	async revalidateTag(_tags, _durations) {}
 };
 const DEFAULT_MEMORY_CACHE_MAX_SIZE = 52428800;
-const MAX_REVALIDATED_TAG_ENTRIES = 1e4;
 function estimateStringMapSize(map) {
 	if (!map) return 0;
 	let size = 0;
@@ -151,14 +150,7 @@ var MemoryCacheHandler = class {
 	async revalidateTag(tags) {
 		const tagList = Array.isArray(tags) ? tags : [tags];
 		const now = Date.now();
-		for (const tag of tagList) {
-			this.tagRevalidatedAt.set(tag, now);
-			while (this.tagRevalidatedAt.size > MAX_REVALIDATED_TAG_ENTRIES) {
-				const oldest = this.tagRevalidatedAt.keys().next().value;
-				if (oldest === void 0) break;
-				this.tagRevalidatedAt.delete(oldest);
-			}
-		}
+		for (const tag of tagList) this.tagRevalidatedAt.set(tag, now);
 	}
 	resetRequestCache() {}
 };

package/dist/shims/cache-request-state.d.ts

@@ -15,8 +15,17 @@ export type UnstableCacheObservation = Readonly<{
   tagCount: number;
   tagHash: string | null;
 }>;
+/**
+ * Collects the cacheLife claims made anywhere below the scope that installed
+ * it, including nested scopes that reset `requestScopedCacheLife`. Shallow
+ * scope clones share it by reference.
+ */
+export type CacheLifeSink = {
+  cacheLife: CacheLifeConfig | null;
+};
 export type CacheState = {
   actionRevalidationKind: ActionRevalidationKind;
+  cacheLifeSink: CacheLifeSink | null;
   pendingRevalidatedTags: Set<string>;
   pendingRevalidations: Set<Promise<void>>;
   requestScopedCacheLife: CacheLifeConfig | null;
@@ -70,6 +79,12 @@ export declare function _captureRequestScopedCacheLifeAccessors(): {
 };
 export declare function recordUnstableCacheObservation(observation: UnstableCacheObservation): void;
 export declare function _peekUnstableCacheObservations(): UnstableCacheObservation[];
+/**
+ * Run `fn` with the request's cache settings, including its revalidation mode,
+ * but its own record of cache lives and unstable_cache observations, so work
+ * done on the request's behalf after the fact leaves the request untouched.
+ */
+export declare function runWithDetachedCacheObservations<T>(fn: () => Promise<T>): Promise<T>;
 export declare function shouldServeStaleUnstableCacheEntry(): boolean;
 //#endregion
 export { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext };

package/dist/shims/cache-request-state.js

@@ -47,6 +47,7 @@ const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
 const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
 const fallbackState = globalState[FALLBACK_KEY] ??= {
 	actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+	cacheLifeSink: null,
 	pendingRevalidatedTags: /* @__PURE__ */ new Set(),
 	pendingRevalidations: /* @__PURE__ */ new Set(),
 	requestScopedCacheLife: null,
@@ -60,12 +61,14 @@ function getCacheState() {
 function _runWithCacheState(fn) {
 	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((context) => {
 		context.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
+		context.cacheLifeSink = null;
 		context.requestScopedCacheLife = null;
 		context.unstableCacheObservations = /* @__PURE__ */ new Map();
 		context.unstableCacheRevalidation = "foreground";
 	}, fn);
 	const state = {
 		actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+		cacheLifeSink: null,
 		pendingRevalidatedTags: /* @__PURE__ */ new Set(),
 		pendingRevalidations: /* @__PURE__ */ new Set(),
 		requestScopedCacheLife: null,
@@ -146,15 +149,17 @@ async function _drainPendingRevalidations() {
 	}
 	if (didReject) throw firstRejection;
 }
+function mergeCacheLife(current, config) {
+	if (current === null) return { ...config };
+	if (config.stale !== void 0) current.stale = current.stale !== void 0 ? Math.min(current.stale, config.stale) : config.stale;
+	if (config.revalidate !== void 0) current.revalidate = current.revalidate !== void 0 ? Math.min(current.revalidate, config.revalidate) : config.revalidate;
+	if (config.expire !== void 0) current.expire = current.expire !== void 0 ? Math.min(current.expire, config.expire) : config.expire;
+	return current;
+}
 function _setRequestScopedCacheLife(config) {
 	const state = getCacheState();
-	if (state.requestScopedCacheLife === null) {
-		state.requestScopedCacheLife = { ...config };
-		return;
-	}
-	if (config.stale !== void 0) state.requestScopedCacheLife.stale = state.requestScopedCacheLife.stale !== void 0 ? Math.min(state.requestScopedCacheLife.stale, config.stale) : config.stale;
-	if (config.revalidate !== void 0) state.requestScopedCacheLife.revalidate = state.requestScopedCacheLife.revalidate !== void 0 ? Math.min(state.requestScopedCacheLife.revalidate, config.revalidate) : config.revalidate;
-	if (config.expire !== void 0) state.requestScopedCacheLife.expire = state.requestScopedCacheLife.expire !== void 0 ? Math.min(state.requestScopedCacheLife.expire, config.expire) : config.expire;
+	state.requestScopedCacheLife = mergeCacheLife(state.requestScopedCacheLife, config);
+	if (state.cacheLifeSink) state.cacheLifeSink.cacheLife = mergeCacheLife(state.cacheLifeSink.cacheLife, config);
 }
 function _peekRequestScopedCacheLife() {
 	const config = getCacheState().requestScopedCacheLife;
@@ -193,8 +198,26 @@ function recordUnstableCacheObservation(observation) {
 function _peekUnstableCacheObservations() {
 	return [...getCacheState().unstableCacheObservations.values()].sort((a, b) => a.keyHash.localeCompare(b.keyHash));
 }
+/**
+* Run `fn` with the request's cache settings, including its revalidation mode,
+* but its own record of cache lives and unstable_cache observations, so work
+* done on the request's behalf after the fact leaves the request untouched.
+*/
+function runWithDetachedCacheObservations(fn) {
+	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((context) => {
+		context.cacheLifeSink = null;
+		context.requestScopedCacheLife = null;
+		context.unstableCacheObservations = /* @__PURE__ */ new Map();
+	}, fn);
+	return cacheAls.run({
+		...getCacheState(),
+		cacheLifeSink: null,
+		requestScopedCacheLife: null,
+		unstableCacheObservations: /* @__PURE__ */ new Map()
+	}, fn);
+}
 function shouldServeStaleUnstableCacheEntry() {
 	return getCacheState().unstableCacheRevalidation === "background";
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry };