vinext 1.0.0-beta.9 → 1.0.0

package/dist/shims/cache-handler.js

@@ -7,7 +7,7 @@ var NoOpCacheHandler = class {
 	async set(_key, _data, _ctx) {}
 	async revalidateTag(_tags, _durations) {}
 };
-const DEFAULT_MEMORY_CACHE_MAX_SIZE = 50 * 1024 * 1024;
+const DEFAULT_MEMORY_CACHE_MAX_SIZE = 52428800;
 const MAX_REVALIDATED_TAG_ENTRIES = 1e4;
 function estimateStringMapSize(map) {
 	if (!map) return 0;
@@ -163,7 +163,45 @@ var MemoryCacheHandler = class {
 	resetRequestCache() {}
 };
 const HANDLER_KEY = Symbol.for("vinext.cacheHandler");
+const CONFIGURED_HANDLER_KEY = Symbol.for("vinext.configuredCacheHandler");
+const EXPLICIT_HANDLER_KEY = Symbol.for("vinext.explicitCacheHandler");
+const LAZY_HANDLER_KEY = Symbol.for("vinext.lazyCacheHandler");
 const globalHandlers = globalThis;
+var LazyDataCacheHandler = class {
+	load;
+	resolved;
+	loadedHandler;
+	constructor(load) {
+		this.load = load;
+	}
+	resolve() {
+		return this.resolved ??= this.load().then(() => {
+			const registered = globalHandlers[HANDLER_KEY];
+			if (registered && registered !== this) {
+				this.loadedHandler = registered;
+				return registered;
+			}
+			const fallback = new MemoryCacheHandler();
+			globalHandlers[HANDLER_KEY] = fallback;
+			globalHandlers[CONFIGURED_HANDLER_KEY] = fallback;
+			delete globalHandlers[LAZY_HANDLER_KEY];
+			this.loadedHandler = fallback;
+			return fallback;
+		});
+	}
+	async get(key, ctx) {
+		return (await this.resolve()).get(key, ctx);
+	}
+	async set(key, data, ctx) {
+		await (await this.resolve()).set(key, data, ctx);
+	}
+	async revalidateTag(tags, durations) {
+		await (await this.resolve()).revalidateTag(tags, durations);
+	}
+	resetRequestCache() {
+		this.loadedHandler?.resetRequestCache?.();
+	}
+};
 function getActiveHandler() {
 	return globalHandlers[HANDLER_KEY] ?? (globalHandlers[HANDLER_KEY] = new MemoryCacheHandler());
 }
@@ -174,6 +212,27 @@ function configureMemoryCacheHandler(options) {
 }
 function setDataCacheHandler(handler) {
 	globalHandlers[HANDLER_KEY] = handler;
+	globalHandlers[EXPLICIT_HANDLER_KEY] = handler;
+	delete globalHandlers[LAZY_HANDLER_KEY];
+}
+/**
+* Lazily keep the first declaratively configured handler shared across
+* duplicated stage modules. Imperative setters remain able to replace it.
+*/
+function registerDataCacheHandler(factory) {
+	if (globalHandlers[EXPLICIT_HANDLER_KEY] !== void 0 || globalHandlers[CONFIGURED_HANDLER_KEY] !== void 0) return;
+	const handler = factory();
+	if (globalHandlers[EXPLICIT_HANDLER_KEY] !== void 0 || globalHandlers[CONFIGURED_HANDLER_KEY] !== void 0) return;
+	globalHandlers[HANDLER_KEY] = handler;
+	globalHandlers[CONFIGURED_HANDLER_KEY] = handler;
+	delete globalHandlers[LAZY_HANDLER_KEY];
+}
+/** Register a lightweight proxy that imports the configured handler on first use. */
+function registerLazyDataCacheHandler(load) {
+	if (globalHandlers[EXPLICIT_HANDLER_KEY] !== void 0 || globalHandlers[CONFIGURED_HANDLER_KEY] !== void 0 || globalHandlers[LAZY_HANDLER_KEY] !== void 0) return;
+	const handler = new LazyDataCacheHandler(load);
+	globalHandlers[HANDLER_KEY] = handler;
+	globalHandlers[LAZY_HANDLER_KEY] = handler;
 }
 function getDataCacheHandler() {
 	return getActiveHandler();
@@ -185,4 +244,4 @@ function getCacheHandler() {
 	return getDataCacheHandler();
 }
 //#endregion
-export { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler };
+export { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler };

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

@@ -1,10 +1,10 @@
 //#region src/shims/cache-request-state.d.ts
-type CacheLifeConfig = {
+export type CacheLifeConfig = {
   stale?: number;
   revalidate?: number;
   expire?: number;
 };
-declare const cacheLifeProfiles: Record<string, CacheLifeConfig>;
+export declare const cacheLifeProfiles: Record<string, CacheLifeConfig>;
 type CacheContextLike = {
   tags: string[];
   lifeConfigs: CacheLifeConfig[];
@@ -14,20 +14,20 @@ type CacheContextLike = {
   hasExplicitExpire: boolean;
   dynamicNestedCacheError: Error | undefined;
 };
-declare function _registerCacheContextAccessor(fn: () => CacheContextLike | null): void;
-declare function getRegisteredCacheContext(): CacheContextLike | null;
+export declare function _registerCacheContextAccessor(fn: () => CacheContextLike | null): void;
+export declare function getRegisteredCacheContext(): CacheContextLike | null;
 /** Record a root-param dependency on the active public `"use cache"` scope. */
-declare function _recordUseCacheRootParamRead(name: string): void;
-type UnstableCacheRevalidationMode = "foreground" | "background";
-type ActionRevalidationKind = 0 | 1 | 2;
-type UnstableCacheObservation = Readonly<{
+export declare function _recordUseCacheRootParamRead(name: string): void;
+export type UnstableCacheRevalidationMode = "foreground" | "background";
+export type ActionRevalidationKind = 0 | 1 | 2;
+export type UnstableCacheObservation = Readonly<{
   kind: "unstable_cache";
   keyHash: string;
   revalidate: number | false | null;
   tagCount: number;
   tagHash: string | null;
 }>;
-type CacheState = {
+export type CacheState = {
   actionRevalidationKind: ActionRevalidationKind;
   pendingRevalidatedTags: Set<string>;
   pendingRevalidations: Set<Promise<void>>;
@@ -35,17 +35,17 @@ type CacheState = {
   unstableCacheObservations: Map<string, UnstableCacheObservation>;
   unstableCacheRevalidation: UnstableCacheRevalidationMode;
 };
-declare const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
-declare const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
-declare function _runWithCacheState<T>(fn: () => Promise<T>): Promise<T>;
-declare function _runWithCacheState<T>(fn: () => T | Promise<T>): T | Promise<T>;
-declare function _initRequestScopedCacheState(): void;
-declare function markActionRevalidation(kind: ActionRevalidationKind): void;
-declare function getAndClearActionRevalidationKind(): ActionRevalidationKind;
+export declare const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
+export declare const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
+export declare function _runWithCacheState<T>(fn: () => Promise<T>): Promise<T>;
+export declare function _runWithCacheState<T>(fn: () => T | Promise<T>): T | Promise<T>;
+export declare function _initRequestScopedCacheState(): void;
+export declare function markActionRevalidation(kind: ActionRevalidationKind): void;
+export declare function getAndClearActionRevalidationKind(): ActionRevalidationKind;
 /** @internal */
-declare function _markPendingRevalidatedTag(tag: string): void;
+export declare function _markPendingRevalidatedTag(tag: string): void;
 /** @internal */
-declare function _hasPendingRevalidatedTag(tags: readonly string[]): boolean;
+export declare function _hasPendingRevalidatedTag(tags: readonly string[]): boolean;
 /**
  * Record a cache invalidation that must finish before the current action or
  * route-handler request is finalized. The public revalidation APIs remain
@@ -57,7 +57,7 @@ declare function _hasPendingRevalidatedTag(tags: readonly string[]): boolean;
  *
  * @internal
  */
-declare function _queuePendingRevalidation(promise: Promise<void>): boolean;
+export declare function _queuePendingRevalidation(promise: Promise<void>): boolean;
 /**
  * Await and clear every cache invalidation queued in the current request.
  * Clearing before awaiting also lets a later drain observe work enqueued by
@@ -65,10 +65,10 @@ declare function _queuePendingRevalidation(promise: Promise<void>): boolean;
  *
  * @internal
  */
-declare function _drainPendingRevalidations(): Promise<void>;
-declare function _setRequestScopedCacheLife(config: CacheLifeConfig): void;
-declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
-declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
+export declare function _drainPendingRevalidations(): Promise<void>;
+export declare function _setRequestScopedCacheLife(config: CacheLifeConfig): void;
+export declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
+export declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
 /**
  * Capture access to the current request's cache-life slot for work that may
  * finish after the AsyncLocalStorage request scope has returned. RSC response
@@ -76,12 +76,11 @@ declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
  * store from a stream-finalization callback can otherwise read a detached
  * context and lose cacheLife claims made while rendering the body.
  */
-declare function _captureRequestScopedCacheLifeAccessors(): {
+export declare function _captureRequestScopedCacheLifeAccessors(): {
   consume: () => CacheLifeConfig | null;
   peek: () => CacheLifeConfig | null;
 };
-declare function recordUnstableCacheObservation(observation: UnstableCacheObservation): void;
-declare function _peekUnstableCacheObservations(): UnstableCacheObservation[];
-declare function shouldServeStaleUnstableCacheEntry(): boolean;
-//#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export declare function recordUnstableCacheObservation(observation: UnstableCacheObservation): void;
+export declare function _peekUnstableCacheObservations(): UnstableCacheObservation[];
+export declare function shouldServeStaleUnstableCacheEntry(): boolean;
+//#endregion

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

@@ -7,10 +7,10 @@ import { markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key
  * life up to the outer cache. Constructed eagerly while the caller is still on
  * the synchronous stack.
  */
-declare class NestedDynamicUseCacheError extends Error {
+export declare class NestedDynamicUseCacheError extends Error {
   constructor();
 }
-type CacheContext = {
+export type CacheContext = {
   /** Tags collected via cacheTag() during execution */
   tags: string[];
   /** Cache life configs collected via cacheLife() — minimum-wins rule applies */
@@ -36,11 +36,11 @@ type CacheContext = {
    */
   invalidDynamicUsageError?: unknown;
 };
-declare const cacheContextStorage: import("node:async_hooks").AsyncLocalStorage<CacheContext>;
+export declare const cacheContextStorage: import("node:async_hooks").AsyncLocalStorage<CacheContext>;
 /**
  * Get the current cache context. Returns null if not inside a "use cache" function.
  */
-declare function getCacheContext(): CacheContext | null;
+export declare function getCacheContext(): CacheContext | null;
 /**
  * Build the shared-cache key for a "use cache" function from its build-scoped
  * identity and serialized arguments.
@@ -51,7 +51,7 @@ declare function getCacheContext(): CacheContext | null;
  *
  * Exported for testing.
  */
-declare function buildUseCacheKey(id: string, keySeed: string | undefined, argsKey?: string): string;
+export declare function buildUseCacheKey(id: string, keySeed: string | undefined, argsKey?: string): string;
 /**
  * Convert an encodeReply result (string | FormData) to a cache key string.
  * For FormData (binary args), produces a deterministic SHA-256 hash over
@@ -60,8 +60,8 @@ declare function buildUseCacheKey(id: string, keySeed: string | undefined, argsK
  *
  * Exported for testing.
  */
-declare function replyToCacheKey(reply: string | FormData): Promise<string>;
-type PrivateCacheState = {
+export declare function replyToCacheKey(reply: string | FormData): Promise<string>;
+export type PrivateCacheState = {
   _privateCache: Map<string, unknown> | null;
 };
 /**
@@ -69,31 +69,25 @@ type PrivateCacheState = {
  * Ensures per-request isolation for "use cache: private" entries
  * on concurrent runtimes.
  */
-declare function runWithPrivateCache<T>(fn: () => Promise<T>): Promise<T>;
-declare function runWithPrivateCache<T>(fn: () => T | Promise<T>): T | Promise<T>;
+export declare function runWithPrivateCache<T>(fn: () => Promise<T>): Promise<T>;
+export declare function runWithPrivateCache<T>(fn: () => T | Promise<T>): T | Promise<T>;
 /**
  * Clear the private per-request cache. Should be called at the start of each request.
  * Only needed when not using runWithPrivateCache() (legacy path).
  */
-declare function clearPrivateCache(): void;
-type RegisterCachedFunctionOptions = {
+export declare function clearPrivateCache(): void;
+export type RegisterCachedFunctionOptions = {
   /**
    * Whether the original function declaration accepts a second argument.
    * Function.length cannot represent default or rest parameters, so the
    * transform records this separately for metadata parent resolution.
    */
   acceptsSecondArgument?: boolean;
-  /**
-   * Internal transform metadata for file-level `"use cache"` default exports
-   * in App Router `page.*` files. Page components receive framework-owned
-   * `{ params, searchParams }` props. React may copy that props object before
-   * invocation, so this invariant must live at the cached function boundary
-   * rather than on the intermediate createElement config object.
-   */
-  appPageDefaultExport?: boolean;
   /** Number of declared arguments supplied by the directive transform. */
   argumentCount?: number;
   decryptCaptures?: (value: unknown) => Promise<unknown[] | undefined>;
+  encodeInvocationArgs?: (args: unknown[]) => Promise<string>;
+  serverReferenceId?: string;
 };
 /**
  * Register a function as a cached function. This is called by the Vite
@@ -104,6 +98,14 @@ type RegisterCachedFunctionOptions = {
  * @param variant - Cache variant: "" (default/shared), "remote", "private"
  * @returns A wrapper function that checks cache before calling the original
  */
-declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant?: string, options?: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
+export declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant?: string, options?: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
+/** Whether a loaded server reference is a transformed `"use cache"` function. */
+export declare function isUseCacheFunction(value: unknown): value is (...args: unknown[]) => Promise<unknown>;
+/**
+ * A thenable (not an array) with own enumerable properties — the
+ * `Object.assign(Promise.resolve(obj), obj)` pattern Next.js params use. The
+ * cache key is built from its fields instead of the promise.
+ */
+export declare function isThenableObject(value: object): value is PromiseLike<unknown>;
 //#endregion
-export { CacheContext, NestedDynamicUseCacheError, PrivateCacheState, RegisterCachedFunctionOptions, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { markAppPagePropsForUseCache };

package/dist/shims/cache-runtime.js

@@ -1,16 +1,17 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
+import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
+import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
 import { getDataCacheHandler } from "./cache-handler.js";
 import { suppressHangingPromiseAbortRejections } from "./internal/make-hanging-promise.js";
 import { createPprFallbackShellSuspensePromise, trackPprFallbackShellCacheTask } from "./ppr-fallback-shell.js";
-import { isDraftModeEnabled, markDynamicUsage } from "./headers.js";
+import { isDraftModeEnabled, markDynamicUsage, throwIfInsideCacheScope } from "./headers.js";
 import { _hasPendingRevalidatedTag, _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { isMarkedAppPagePropsObject, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
-import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
+import { makeThenableParams } from "./thenable-params.js";
+import { APP_PAGE_USE_CACHE_MARKER, hasUseCachePageMarker, isMarkedAppPagePropsObject, isUseCacheFunctionReference, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
 import { getCurrentRootParams } from "./root-params.js";
-import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache-runtime.ts
 /**
 * "use cache" runtime
@@ -309,7 +310,8 @@ function propagateRootParamNamesToParent(names) {
 */
 function registerCachedFunction(fn, id, variant, options = {}) {
 	const cacheVariant = variant ?? "";
-	const omitAppPageSearchParamsFromFirstArg = options.appPageDefaultExport === true;
+	const omitAppPageSearchParams = cacheVariant !== "private";
+	const cacheFunctionId = options.serverReferenceId ? JSON.stringify([id, options.serverReferenceId]) : id;
 	const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
 	const cachedFn = (...args) => {
 		if (cacheVariant === "private") {
@@ -346,18 +348,29 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			const keySeed = getUseCacheKeySeed();
 			const captures = options.decryptCaptures ? await options.decryptCaptures(args[0]) : void 0;
 			const hasCaptureEnvelope = captures !== void 0;
-			const admittedArgs = options.argumentCount === void 0 ? args : hasCaptureEnvelope ? [args[0], ...args.slice(1, 1 + options.argumentCount)] : args.slice(0, options.argumentCount);
+			const pagePropsArgIndex = args.findIndex(hasUseCachePageMarker);
+			const isPageInvocation = pagePropsArgIndex !== -1;
+			const invocationArgs = isPageInvocation ? replaceArgument(args, pagePropsArgIndex, withoutUseCachePageMarker(args[pagePropsArgIndex])) : args;
+			const admittedArgs = options.argumentCount === void 0 ? invocationArgs : hasCaptureEnvelope ? [invocationArgs[0], ...invocationArgs.slice(1, 1 + options.argumentCount)] : invocationArgs.slice(0, options.argumentCount);
 			const executionArgs = hasCaptureEnvelope ? [captures, ...admittedArgs.slice(1)] : admittedArgs;
-			const callArgs = executionArgs;
+			const pagePropsIndex = omitAppPageSearchParams && isPageInvocation ? pagePropsArgIndex : void 0;
+			const callArgs = pagePropsIndex === void 0 ? executionArgs : withErroringPageSearchParams(executionArgs, pagePropsIndex);
 			let cacheKey;
 			try {
-				const processedArgs = executionArgs.length > 0 ? unwrapThenableObjectArray(executionArgs, { omitAppPageSearchParamsFromFirstArg }) : [];
+				const processedArgs = executionArgs.length > 0 ? unwrapThenableObjectArray(executionArgs, {
+					pagePropsIndex,
+					omitMarkedAppPageSearchParams: omitAppPageSearchParams
+				}) : [];
 				if (rsc && executionArgs.length > 0) {
 					const tempRefs = rsc.createClientTemporaryReferenceSet();
-					cacheKey = buildUseCacheKey(id, keySeed, await replyToCacheKey(await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs })));
-				} else cacheKey = buildUseCacheKey(id, keySeed, processedArgs.length > 0 ? stableStringify(processedArgs) : void 0);
+					const encoded = await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs });
+					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, await replyToCacheKey(encoded));
+				} else {
+					const argsKey = processedArgs.length > 0 ? stableStringify(processedArgs) : void 0;
+					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, argsKey);
+				}
 			} catch {
-				return fn(...callArgs);
+				return (await executeWithContext(fn, callArgs, cacheVariant)).result;
 			}
 			if (cacheVariant === "private") {
 				const privateCache = _getPrivateState()._privateCache;
@@ -415,6 +428,15 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			propagateCacheTagsToRequest(ctx.tags);
 			const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
 			if (collectedResult?.cacheEntry) try {
+				let cacheFunctionInvocation;
+				if (options.serverReferenceId && options.encodeInvocationArgs) try {
+					cacheFunctionInvocation = {
+						encryptedArgs: await options.encodeInvocationArgs(pagePropsIndex === void 0 ? admittedArgs : toReplayablePageArgs(admittedArgs, pagePropsIndex)),
+						referenceId: options.serverReferenceId,
+						rootParams: Object.fromEntries(Object.entries(rootParams ?? {}).filter((entry) => entry[1] !== void 0)),
+						softTags
+					};
+				} catch {}
 				const serialized = collectedResult.cacheEntry;
 				const cacheValue = {
 					kind: "FETCH",
@@ -429,6 +451,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				const cacheContext = {
 					fetchCache: true,
 					tags: ctx.tags,
+					...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
 					cacheControl: {
 						revalidate: revalidateSeconds,
 						expire: effectiveLife.expire,
@@ -470,6 +493,10 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
 /** @internal Symbol carrying transform-derived cached function argument metadata. */
 const USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL = Symbol.for("vinext.useCacheAcceptsSecondArgument");
+/** Whether a loaded server reference is a transformed `"use cache"` function. */
+function isUseCacheFunction(value) {
+	return isUseCacheFunctionReference(value);
+}
 function throwPrivateUseCacheInsidePublicUseCacheError() {
 	const error = /* @__PURE__ */ new Error("\"use cache: private\" must not be used within \"use cache\". It can only be nested inside of another \"use cache: private\".");
 	const ctx = getRequestContext();
@@ -551,11 +578,12 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 		invalidDynamicUsageError: void 0
 	};
 	let collectedResult;
-	const result = await cacheContextStorage.run(ctx, async () => {
+	const workUnitType = variant === "private" ? "private-cache" : "cache";
+	const result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
 		const value = await fn(...args);
 		if (collectResult) collectedResult = await collectResult(value, ctx);
 		return value;
-	});
+	}));
 	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
 	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);
 	if (parentCtx) {
@@ -575,27 +603,79 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 		collectedResult
 	};
 }
-function unwrapThenableObjects(value, options = {}) {
+function unwrapThenableObjects(value, options) {
 	if (value === null || value === void 0 || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item));
-	if (typeof value.then === "function") {
-		const keys = Object.keys(value);
-		if (keys.length > 0) {
-			const plain = {};
-			for (const key of keys) plain[key] = unwrapThenableObjects(value[key]);
-			return plain;
-		}
-		return value;
+	const childOptions = { omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams };
+	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item, childOptions));
+	if (isThenableObject(value)) {
+		const plain = {};
+		for (const key of Object.keys(value)) plain[key] = unwrapThenableObjects(value[key], childOptions);
+		return plain;
 	}
+	if (typeof value.then === "function") return value;
 	const result = {};
 	for (const key of Object.keys(value)) {
-		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || isMarkedAppPagePropsObject(value))) continue;
-		result[key] = unwrapThenableObjects(value[key]);
+		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || options.omitMarkedAppPageSearchParams && isMarkedAppPagePropsObject(value))) continue;
+		result[key] = unwrapThenableObjects(value[key], childOptions);
 	}
 	return result;
 }
+/**
+* A thenable (not an array) with own enumerable properties — the
+* `Object.assign(Promise.resolve(obj), obj)` pattern Next.js params use. The
+* cache key is built from its fields instead of the promise.
+*/
+function isThenableObject(value) {
+	return !Array.isArray(value) && "then" in value && typeof value.then === "function" && Object.keys(value).length > 0;
+}
+function isPagePropsObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function replaceArgument(args, index, value) {
+	const result = [...args];
+	result[index] = value;
+	return result;
+}
+/** Remove the `$$isPage` invocation marker before props reach the key or user code. */
+function withoutUseCachePageMarker(props) {
+	const { [APP_PAGE_USE_CACHE_MARKER]: _marker, ...pageProps } = props;
+	return isMarkedAppPagePropsObject(props) ? markAppPagePropsForUseCache(pageProps) : pageProps;
+}
+/**
+* Response Store replay args for a public page cache: drop `searchParams` from
+* the page props at `index` (after a capture envelope, if any), as Next.js does
+* for the serialized arguments (use-cache-wrapper.ts, `isPageSegmentFunction`),
+* and keep the `$$isPage` marker so a replay regains page semantics, including
+* the erroring searchParams fallback.
+*/
+function toReplayablePageArgs(args, index) {
+	const props = args[index];
+	if (!isPagePropsObject(props)) return [...args];
+	const { searchParams: _searchParams, ...pageProps } = props;
+	return replaceArgument(args, index, {
+		...pageProps,
+		[APP_PAGE_USE_CACHE_MARKER]: true
+	});
+}
+/**
+* Give page props at `index` without `searchParams` (a Response Store replay of
+* args encoded by `toReplayablePageArgs`) a value that throws on
+* access inside the cache scope, like Next.js's
+* `makeErroringSearchParamsForUseCache`, instead of `undefined`.
+*/
+function withErroringPageSearchParams(args, index) {
+	const props = args[index];
+	if (!isPagePropsObject(props) || "searchParams" in props) return args;
+	return replaceArgument(args, index, {
+		...props,
+		searchParams: makeThenableParams({}, { observeParamAccess: () => throwIfInsideCacheScope("searchParams") })
+	});
+}
 function unwrapThenableObjectArray(values, options) {
-	return values.map((value, index) => unwrapThenableObjects(value, { omitAppPageSearchParamsAtRoot: index === 0 && options.omitAppPageSearchParamsFromFirstArg }));
+	return values.map((value, index) => unwrapThenableObjects(value, {
+		omitAppPageSearchParamsAtRoot: index === options.pagePropsIndex,
+		omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams
+	}));
 }
 function stableStringify(value, seen) {
 	if (value === void 0) return "undefined";
@@ -622,4 +702,4 @@ function stableStringify(value, seen) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, isThenableObject, isUseCacheFunction, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache.d.ts

@@ -1,6 +1,6 @@
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
 import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
-import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 //#region src/shims/cache.d.ts
 /**
  * Revalidate cached data associated with a specific cache tag.
@@ -15,7 +15,7 @@ import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerVa
  * @param tag - Cache tag to revalidate
  * @param profile - cacheLife profile name (e.g. 'max', 'hours') or inline { expire: number }
  */
-declare function revalidateTag(tag: string, profile?: string | {
+export declare function revalidateTag(tag: string, profile?: string | {
   expire?: number;
 }): undefined;
 /**
@@ -33,7 +33,7 @@ declare function revalidateTag(tag: string, profile?: string | {
  * The `type` parameter is App Router only — Pages Router does not generate
  * layout/page hierarchy tags, so only no-type invalidation applies there.
  */
-declare function revalidatePath(path: string, type?: "page" | "layout"): undefined;
+export declare function revalidatePath(path: string, type?: "page" | "layout"): undefined;
 /**
  * No-op shim for API compatibility.
  *
@@ -42,7 +42,7 @@ declare function revalidatePath(path: string, type?: "page" | "layout"): undefin
  * vinext reports the dynamic-only invalidation through the Server Action
  * response header that the client router already understands.
  */
-declare function refresh(): void;
+export declare function refresh(): void;
 /**
  * Expire a cache tag immediately (Next.js 16).
  *
@@ -56,7 +56,7 @@ declare function refresh(): void;
  *
  * @see https://nextjs.org/docs/app/api-reference/functions/updateTag
  */
-declare function updateTag(tag: string): undefined;
+export declare function updateTag(tag: string): undefined;
 /**
  * Opt out of static rendering and indicate a particular component should not be cached.
  *
@@ -65,7 +65,7 @@ declare function updateTag(tag: string): undefined;
  * have the same static/dynamic rendering split — all server rendering is on-demand.
  * It's provided for API compatibility so apps importing it don't break.
  */
-declare function unstable_noStore(): void;
+export declare function unstable_noStore(): void;
 /**
  * Marks an IO boundary in server components by returning a resolved promise
  * during requests and a hanging promise during prerendering.
@@ -89,13 +89,13 @@ declare function unstable_noStore(): void;
  * When no work unit store is present (e.g. client-side, standalone script),
  * resolves immediately — matching the browser/client implementation.
  */
-declare function io(): Promise<void>;
+export declare function io(): Promise<void>;
 /**
  * @deprecated Use `io` instead. Kept as a transitional alias since vinext
  * shipped the unstable name longer than upstream Next.js (see #805). Will be
  * removed in a future minor.
  */
-declare function unstable_io(): Promise<void>;
+export declare function unstable_io(): Promise<void>;
 /**
  * Set the cache lifetime for a "use cache" function.
  *
@@ -108,7 +108,7 @@ declare function unstable_io(): Promise<void>;
  *
  * When called outside a "use cache" context, this is a validated no-op.
  */
-declare function cacheLife(profile: string | CacheLifeConfig): void;
+export declare function cacheLife(profile: string | CacheLifeConfig): void;
 /**
  * Tag a "use cache" function's cached result for on-demand revalidation.
  *
@@ -120,15 +120,15 @@ declare function cacheLife(profile: string | CacheLifeConfig): void;
  *
  * When called outside a "use cache" context, this is a no-op.
  */
-declare function cacheTag(...tags: string[]): void;
-declare function unstable_cacheLife(profile: string | CacheLifeConfig): void;
-declare function unstable_cacheTag(...tags: string[]): void;
+export declare function cacheTag(...tags: string[]): void;
+export declare function unstable_cacheLife(profile: string | CacheLifeConfig): void;
+export declare function unstable_cacheTag(...tags: string[]): void;
 /**
  * Check if the current execution context is inside an unstable_cache() callback.
  * Used by headers(), cookies(), and connection() to throw errors when
  * dynamic request APIs are called inside a cache scope.
  */
-declare function isInsideUnstableCacheScope(): boolean;
+export declare function isInsideUnstableCacheScope(): boolean;
 type UnstableCacheOptions = {
   revalidate?: number | false;
   tags?: string[];
@@ -139,6 +139,6 @@ type UnstableCacheOptions = {
  * Returns a new function that caches results. The cache key is derived
  * from keyParts + serialized arguments.
  */
-declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
+export declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, recordUnstableCacheObservation, registerDataCacheHandler, registerLazyDataCacheHandler, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };