vinext 1.4.0 → 1.4.1

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

@@ -1,10 +1,10 @@
+import { CacheLifeConfig } from "../utils/cache-life-profiles.js";
 import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
 //#region src/shims/cache-request-state.d.ts
-export type CacheLifeConfig = {
-  stale?: number;
-  revalidate?: number;
-  expire?: number;
-};
+/**
+ * The built-in profiles merged with next.config `cacheLife`, baked in at
+ * build time like Next.js's `process.env.__NEXT_CACHE_LIFE` define.
+ */
 export declare const cacheLifeProfiles: Record<string, CacheLifeConfig>;
 export type UnstableCacheRevalidationMode = "foreground" | "background";
 export type ActionRevalidationKind = 0 | 1 | 2;
@@ -121,4 +121,4 @@ export declare function _captureRequestScopedCacheLifeAccessors(): {
 export declare function runWithDetachedCacheObservations<T>(fn: () => Promise<T>): Promise<T>;
 export declare function shouldServeStaleUnstableCacheEntry(): boolean;
 //#endregion
-export { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext };
+export { type CacheLifeConfig, _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext };

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

@@ -1,45 +1,15 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
+import { parseCacheLifeProfiles } from "../utils/cache-life-profiles.js";
 import { getCdnCacheAdapter } from "./cdn-cache.js";
 import { getHeadersAccessPhase } from "./internal/headers-state.js";
 import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
 //#region src/shims/cache-request-state.ts
-const cacheLifeProfiles = {
-	default: {
-		revalidate: 900,
-		expire: 4294967294
-	},
-	seconds: {
-		stale: 30,
-		revalidate: 1,
-		expire: 60
-	},
-	minutes: {
-		stale: 300,
-		revalidate: 60,
-		expire: 3600
-	},
-	hours: {
-		stale: 300,
-		revalidate: 3600,
-		expire: 86400
-	},
-	days: {
-		stale: 300,
-		revalidate: 86400,
-		expire: 604800
-	},
-	weeks: {
-		stale: 300,
-		revalidate: 604800,
-		expire: 2592e3
-	},
-	max: {
-		stale: 300,
-		revalidate: 2592e3,
-		expire: 31536e3
-	}
-};
+/**
+* The built-in profiles merged with next.config `cacheLife`, baked in at
+* build time like Next.js's `process.env.__NEXT_CACHE_LIFE` define.
+*/
+const cacheLifeProfiles = parseCacheLifeProfiles(process.env.__VINEXT_CACHE_LIFE_PROFILES);
 const FALLBACK_KEY = Symbol.for("vinext.cache.fallback");
 const globalState = globalThis;
 const cacheAls = getOrCreateAls("vinext.cache.als");

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

@@ -1,4 +1,4 @@
-import { CacheLifeConfig } from "./cache-request-state.js";
+import { CacheLifeConfig } from "../utils/cache-life-profiles.js";
 import { CacheFlightArguments } from "./cache-flight-arguments.js";
 //#region src/shims/cache-runtime.d.ts
 export declare function replayCachedFunction(fn: object, args: CacheFlightArguments): Promise<unknown>;
@@ -16,6 +16,8 @@ export type CacheContext = {
   tags: string[];
   /** Cache life configs collected via cacheLife() — minimum-wins rule applies */
   lifeConfigs: CacheLifeConfig[];
+  /** Resolved lives of nested caches; they only constrain fields cacheLife() left unset */
+  nestedLifeConfigs: CacheLifeConfig[];
   /** Cache variant: "default" | "remote" | "private" */
   variant: string;
   /** Root params observed while producing this public cache entry. */

package/dist/shims/cache-runtime.js

@@ -1,6 +1,7 @@
 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 { isInsideWorkStoreScope } from "./internal/work-store-scope.js";
 import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
 import { shareIsolatePromise } from "../server/isolate-shared-promise.js";
@@ -189,22 +190,46 @@ async function serializeCacheResult(result, rsc) {
 		throw serializationError?.value ?? error;
 	}
 }
+const CACHE_LIFE_FIELDS = [
+	"stale",
+	"revalidate",
+	"expire"
+];
+/** Per field, the smallest value any config sets. */
+function minimumCacheLife(configs) {
+	const result = {};
+	for (const config of configs) for (const field of CACHE_LIFE_FIELDS) {
+		const value = config[field];
+		const current = result[field];
+		if (value !== void 0 && (current === void 0 || value < current)) result[field] = value;
+	}
+	return result;
+}
 /**
-* Resolve collected cacheLife configs into a single effective config.
-* The "minimum-wins" rule: if multiple cacheLife() calls are made,
-* each field takes the smallest value across all calls.
+* Resolve a cache scope's effective life, like Next.js's `collectResult`
+* (use-cache-wrapper.ts). A field set by `cacheLife()` takes the minimum
+* across those calls and wins over nested caches. Any other field takes the
+* minimum of the default profile and the nested caches' lives.
 */
-function resolveCacheLife(configs) {
-	if (configs.length === 0) return { ...cacheLifeProfiles.default };
-	if (configs.length === 1) return { ...configs[0] };
+function resolveCacheLife(ctx) {
+	const explicit = minimumCacheLife(ctx.lifeConfigs);
+	const collected = minimumCacheLife([cacheLifeProfiles.default, ...ctx.nestedLifeConfigs]);
 	const result = {};
-	for (const config of configs) {
-		if (config.stale !== void 0) result.stale = result.stale !== void 0 ? Math.min(result.stale, config.stale) : config.stale;
-		if (config.revalidate !== void 0) result.revalidate = result.revalidate !== void 0 ? Math.min(result.revalidate, config.revalidate) : config.revalidate;
-		if (config.expire !== void 0) result.expire = result.expire !== void 0 ? Math.min(result.expire, config.expire) : config.expire;
+	for (const field of CACHE_LIFE_FIELDS) {
+		const value = explicit[field] ?? collected[field];
+		if (value !== void 0) result[field] = value;
 	}
 	return result;
 }
+/**
+* Hand a finished cache scope's life to what encloses it, like Next.js's
+* `propagateCacheEntryMetadata`: an enclosing cache collects it as a nested
+* life, and only an outermost cache reaches the request.
+*/
+function propagateCacheLife(parentCtx, life) {
+	if (parentCtx) parentCtx.nestedLifeConfigs.push(life);
+	else _setRequestScopedCacheLife(life);
+}
 const _PRIVATE_FALLBACK_KEY = Symbol.for("vinext.cacheRuntime.privateFallback");
 const _g = globalThis;
 const _privateAls = getOrCreateAls("vinext.cacheRuntime.privateAls");
@@ -416,10 +441,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				const timestamp = Date.now();
 				const { result, ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(callFn, callArgs, cacheVariant, (value) => serializeCacheResult(value, rsc));
 				const rootParamNames = ctx.readRootParamNames && ctx.readRootParamNames.size > 0 ? addKnownRootParamNames(id, ctx.readRootParamNames) : knownRootParamsByFunctionId.get(id);
-				if (propagate) {
-					recordRequestScopedCacheLife(effectiveLife);
-					propagateCacheTagsToRequest(ctx.tags);
-				}
+				if (propagate) propagateCacheTagsToRequest(ctx.tags);
 				const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
 				if (collectedResult?.cacheEntry) try {
 					let cacheFunctionInvocation;
@@ -453,32 +475,39 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 							stale: effectiveLife.stale
 						}
 					};
+					let write;
 					if (rootParamNames && rootParamNames.size > 0 && rootParams) {
 						const specificCacheKey = coarseCacheKey + computeRootParamsCacheKeySuffix(rootParams, rootParamNames);
 						const redirectTags = [...ctx.tags, ...[...rootParamNames].map((name) => ROOT_PARAM_TAG_PREFIX + name)];
-						await handler.set(coarseCacheKey, {
-							kind: "FETCH",
-							data: {
-								headers: { [ROOT_PARAM_REDIRECT_HEADER]: "1" },
-								body: "",
-								url: coarseCacheKey
-							},
-							tags: redirectTags,
-							revalidate: revalidateSeconds
-						}, {
-							...cacheContext,
-							tags: redirectTags,
-							...coarseCacheKey === cacheKey ? staleEntry && { staleEntry } : staleRedirect && { staleEntry: staleRedirect }
-						});
+						try {
+							await handler.set(coarseCacheKey, {
+								kind: "FETCH",
+								data: {
+									headers: { [ROOT_PARAM_REDIRECT_HEADER]: "1" },
+									body: "",
+									url: coarseCacheKey
+								},
+								tags: redirectTags,
+								revalidate: revalidateSeconds
+							}, {
+								...cacheContext,
+								tags: redirectTags,
+								...coarseCacheKey === cacheKey ? staleEntry && { staleEntry } : staleRedirect && { staleEntry: staleRedirect }
+							});
+						} catch {}
 						cacheValue.data.url = specificCacheKey;
-						await handler.set(specificCacheKey, cacheValue, {
+						write = handler.set(specificCacheKey, cacheValue, {
 							...cacheContext,
 							...staleEntry && specificCacheKey === cacheKey ? { staleEntry } : {}
 						});
-					} else await handler.set(cacheKey, cacheValue, {
+					} else write = handler.set(cacheKey, cacheValue, {
 						...cacheContext,
 						...staleEntry ? { staleEntry } : {}
 					});
+					const stored = write.then(() => void 0, () => {});
+					if (propagate && isInsideWorkStoreScope()) {
+						if (isInsideUnifiedScope()) getRequestContext().executionContext?.waitUntil(stored);
+					} else await stored;
 				} catch {}
 				return collectedResult ? collectedResult.result : result;
 			};
@@ -539,16 +568,12 @@ function recordRequestScopedCacheControl(cacheControl) {
 		stale: cacheControl.stale
 	};
 	const parentCtx = cacheContextStorage.getStore();
-	parentCtx?.lifeConfigs.push(life);
+	propagateCacheLife(parentCtx, life);
 	if (parentCtx && parentCtx.variant !== "private" && (cacheControl.revalidate === 0 || cacheControl.expire !== void 0 && cacheControl.expire < DYNAMIC_EXPIRE)) {
 		const error = new NestedDynamicUseCacheError();
 		if (typeof Error.captureStackTrace === "function") Error.captureStackTrace(error, recordRequestScopedCacheControl);
 		parentCtx.dynamicNestedCacheError ??= error;
 	}
-	_setRequestScopedCacheLife(life);
-}
-function recordRequestScopedCacheLife(cacheLife) {
-	_setRequestScopedCacheLife(cacheLife);
 }
 /**
 * Bubble a `"use cache"` scope's tags toward where they can drive invalidation.
@@ -575,8 +600,7 @@ function propagateCacheTagsToRequest(tags) {
 	addCollectedRequestTags(tags);
 }
 async function executeWithContext(fn, args, variant, rsc) {
-	const { result, ctx: _ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, (value) => serializeCacheResult(value, rsc));
-	recordRequestScopedCacheLife(effectiveLife);
+	const { result, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, (value) => serializeCacheResult(value, rsc));
 	return {
 		result: collectedResult ? collectedResult.result : result,
 		cacheable: collectedResult?.cacheEntry !== null,
@@ -593,6 +617,7 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 	const ctx = {
 		tags: [],
 		lifeConfigs: [],
+		nestedLifeConfigs: [],
 		variant: variant || "default",
 		readRootParamNames: /* @__PURE__ */ new Set(),
 		hasExplicitRevalidate: false,
@@ -602,21 +627,26 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 	};
 	let collectedResult;
 	const workUnitType = variant === "private" ? "private-cache" : "cache";
-	const result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
-		if (!collectResult) return await fn(...args);
-		let value;
-		const lazyValue = { then: (onFulfilled, onRejected) => (value ??= new Promise((resolve) => resolve(fn(...args)))).then(onFulfilled, onRejected) };
-		collectedResult = await collectResult(lazyValue, ctx);
-		return await lazyValue;
-	}));
+	let result;
+	let effectiveLife;
+	try {
+		result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
+			if (!collectResult) return await fn(...args);
+			let value;
+			const lazyValue = { then: (onFulfilled, onRejected) => (value ??= new Promise((resolve) => resolve(fn(...args)))).then(onFulfilled, onRejected) };
+			collectedResult = await collectResult(lazyValue, ctx);
+			return await lazyValue;
+		}));
+	} finally {
+		effectiveLife = resolveCacheLife(ctx);
+		propagateCacheLife(parentCtx, effectiveLife);
+		if (parentCtx && eagerError && (effectiveLife.revalidate === 0 || effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE)) parentCtx.dynamicNestedCacheError ??= eagerError;
+	}
 	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
-	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);
 	if (parentCtx) {
-		parentCtx.lifeConfigs.push(effectiveLife);
 		for (const tag of ctx.tags) if (!parentCtx.tags.includes(tag)) parentCtx.tags.push(tag);
 		if (parentCtx.variant !== "private") for (const name of ctx.readRootParamNames ?? []) parentCtx.readRootParamNames?.add(name);
 	}
-	if (parentCtx && eagerError && (effectiveLife.revalidate === 0 || effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE)) parentCtx.dynamicNestedCacheError ??= eagerError;
 	if (typeof process !== "undefined" && (process.env.VINEXT_PRERENDER === "1" || process.env.NODE_ENV === "development") && ctx.dynamicNestedCacheError) {
 		if (effectiveLife.revalidate === 0 && !ctx.hasExplicitRevalidate) throw new Error(getNestedCacheZeroRevalidateErrorMessage(), { cause: ctx.dynamicNestedCacheError });
 		if (effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE && !ctx.hasExplicitExpire) throw new Error(getNestedCacheShortExpireErrorMessage(), { cause: ctx.dynamicNestedCacheError });

package/dist/shims/cache.d.ts

@@ -1,7 +1,8 @@
+import { CacheLifeConfig } from "../utils/cache-life-profiles.js";
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.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";
 import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheState, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 //#region src/shims/cache.d.ts
 /**
  * Revalidate cached data associated with a specific cache tag.
@@ -101,12 +102,16 @@ export declare function unstable_io(): Promise<void>;
 /**
  * Set the cache lifetime for a "use cache" function.
  *
- * Accepts either a built-in profile name (e.g., "hours", "days") or a custom
- * configuration object. In Next.js, this only works inside "use cache" functions.
+ * Accepts either a profile name (a built-in like "hours", or one configured
+ * in next.config `cacheLife`) or a custom configuration object; an unknown
+ * profile name throws, like Next.js. In Next.js, this only works inside
+ * "use cache" functions.
  *
  * When called inside a "use cache" function, this sets the cache TTL.
  * The "minimum-wins" rule applies: if called multiple times, the shortest
- * duration for each field wins.
+ * duration for each field wins. Like Next.js, only the fields a call sets are
+ * explicit: the others resolve from the default profile and any nested caches
+ * (see `resolveCacheLife` in cache-runtime.ts).
  *
  * When called outside a "use cache" context, this is a validated no-op.
  */
@@ -143,4 +148,4 @@ type UnstableCacheOptions = {
  */
 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, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, registerDataCacheHandler, registerLazyDataCacheHandler, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, type CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, registerDataCacheHandler, registerLazyDataCacheHandler, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache.js

@@ -230,29 +230,34 @@ let _unstableIoWarned = false;
 /**
 * Set the cache lifetime for a "use cache" function.
 *
-* Accepts either a built-in profile name (e.g., "hours", "days") or a custom
-* configuration object. In Next.js, this only works inside "use cache" functions.
+* Accepts either a profile name (a built-in like "hours", or one configured
+* in next.config `cacheLife`) or a custom configuration object; an unknown
+* profile name throws, like Next.js. In Next.js, this only works inside
+* "use cache" functions.
 *
 * When called inside a "use cache" function, this sets the cache TTL.
 * The "minimum-wins" rule applies: if called multiple times, the shortest
-* duration for each field wins.
+* duration for each field wins. Like Next.js, only the fields a call sets are
+* explicit: the others resolve from the default profile and any nested caches
+* (see `resolveCacheLife` in cache-runtime.ts).
 *
 * When called outside a "use cache" context, this is a validated no-op.
 */
 function cacheLife(profile) {
 	let resolvedConfig;
 	if (typeof profile === "string") {
-		if (!cacheLifeProfiles[profile]) {
-			console.warn(`[vinext] cacheLife: unknown profile "${profile}". Available profiles: ${Object.keys(cacheLifeProfiles).join(", ")}`);
-			return;
+		const configuredProfile = Object.hasOwn(cacheLifeProfiles, profile) ? cacheLifeProfiles[profile] : void 0;
+		if (configuredProfile === void 0) {
+			if (Object.hasOwn(cacheLifeProfiles, profile.trim())) throw new Error(`Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\nDid you mean "${profile.trim()}" without the spaces?`);
+			throw new Error(`Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\nmodule.exports = {
+  cacheLife: {
+    "${profile}": ...\n  }
+}`);
 		}
-		resolvedConfig = { ...cacheLifeProfiles[profile] };
+		resolvedConfig = { ...configuredProfile };
 	} else if (typeof profile === "object" && profile !== null) {
 		if (profile.expire !== void 0 && profile.revalidate !== void 0 && profile.expire < profile.revalidate) console.warn("[vinext] cacheLife: expire must be >= revalidate");
-		resolvedConfig = {
-			...cacheLifeProfiles.default,
-			...profile
-		};
+		resolvedConfig = { ...profile };
 	} else return;
 	try {
 		const ctx = getRegisteredCacheContext();
@@ -260,11 +265,13 @@ function cacheLife(profile) {
 			ctx.lifeConfigs.push(resolvedConfig);
 			if (resolvedConfig.revalidate !== void 0) ctx.hasExplicitRevalidate = true;
 			if (resolvedConfig.expire !== void 0) ctx.hasExplicitExpire = true;
-			_setRequestScopedCacheLife(resolvedConfig);
 			return;
 		}
 	} catch {}
-	_setRequestScopedCacheLife(resolvedConfig);
+	_setRequestScopedCacheLife(typeof profile === "string" ? resolvedConfig : {
+		...cacheLifeProfiles.default,
+		...profile
+	});
 }
 /**
 * Tag a "use cache" function's cached result for on-demand revalidation.
@@ -327,7 +334,7 @@ function unstable_cacheTag(...tags) {
 	}
 	return cacheTag(...tags);
 }
-const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v2";
+const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v3";
 /**
 * AsyncLocalStorage to track whether we're inside an unstable_cache() callback.
 * Stored on globalThis via Symbol so headers.ts can detect the scope without
@@ -396,7 +403,7 @@ function scheduleUnstableCacheBackgroundRevalidation(cacheKey, refresh) {
 	pending.set(cacheKey, trackedRevalidation);
 	waitUntilUnstableCacheRevalidation(trackedRevalidation);
 }
-async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry) {
+async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry, deferWrite) {
 	const argsUnchanged = serializeArgsOrNull(args) === keyedArgs;
 	const result = await _unstableCacheAls.run(true, () => _unstableCacheCallbackAls.run({ useCacheContext: _useCacheContextAls.getStore() }, () => fn(...args)));
 	if (!argsUnchanged) return result;
@@ -410,12 +417,18 @@ async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, r
 		tags,
 		revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : false
 	};
-	await getDataCacheHandler().set(cacheKey, cacheValue, {
-		fetchCache: true,
-		tags,
-		revalidate: revalidateSeconds,
-		...staleEntry ? { staleEntry } : {}
+	const write = new Promise((resolve) => {
+		resolve(getDataCacheHandler().set(cacheKey, cacheValue, {
+			fetchCache: true,
+			tags,
+			revalidate: revalidateSeconds,
+			...staleEntry ? { staleEntry } : {}
+		}));
+	}).catch((err) => {
+		console.error("[vinext] unstable_cache write error:", err);
 	});
+	if (deferWrite) getRequestExecutionContext()?.waitUntil(write);
+	else await write;
 	return result;
 }
 function serializeArgsOrNull(args) {
@@ -458,7 +471,7 @@ function unstable_cache(fn, keyParts, options) {
 				if (cached.ok) {
 					if (existing.cacheState === "stale") {
 						if (shouldServeStaleUnstableCacheEntry()) {
-							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry));
+							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry, false));
 							return cached.value;
 						}
 					} else return cached.value;
@@ -466,7 +479,7 @@ function unstable_cache(fn, keyParts, options) {
 			}
 		}
 		if (isDraftMode) return await _unstableCacheAls.run(true, () => fn(...args));
-		return await refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry);
+		return await refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry, !staleEntry && isInsideWorkStoreScope());
 	};
 	return cachedFn;
 }

package/dist/shims/client-hook-error.d.ts

@@ -9,4 +9,6 @@
  */
 export declare function buildClientHookErrorMessage(hookName: string): string;
 export declare function throwClientHookError(hookName: string): never;
+/** Rewrites that TypeError into the actionable message, like Next.js's formatServerError. */
+export declare function rewriteClientHookError(error: Error): void;
 //#endregion

package/dist/shims/client-hook-error.js

@@ -13,5 +13,20 @@ function buildClientHookErrorMessage(hookName) {
 function throwClientHookError(hookName) {
 	throw new Error(buildClientHookErrorMessage(hookName));
 }
+const clientHookPattern = /\b(useState|useEffect|useReducer|useRef|useContext|useLayoutEffect|useInsertionEffect|useSyncExternalStore|useTransition|useImperativeHandle|useDeferredValue|useActionState|useOptimistic|useEffectEvent)\b.*is not a function/;
+/** Rewrites that TypeError into the actionable message, like Next.js's formatServerError. */
+function rewriteClientHookError(error) {
+	const match = error.message.match(clientHookPattern);
+	if (!match) return;
+	const message = buildClientHookErrorMessage(match[1]);
+	try {
+		if (error.stack) {
+			const lines = error.stack.split("\n");
+			lines[0] = message;
+			error.stack = lines.join("\n");
+		}
+		error.message = message;
+	} catch {}
+}
 //#endregion
-export { buildClientHookErrorMessage, throwClientHookError };
+export { buildClientHookErrorMessage, rewriteClientHookError, throwClientHookError };

package/dist/shims/fetch-cache.js

@@ -804,7 +804,9 @@ function createPatchedFetch() {
 				cached = null;
 			}
 			if (cached?.value && cached.value.kind === "FETCH" && cached.cacheState !== "stale") {
-				await lowerFetchCacheRevalidateIfNeeded(handler, cacheKey, cached.value, tags, revalidateSeconds);
+				await lowerFetchCacheRevalidateIfNeeded(handler, cacheKey, cached.value, tags, revalidateSeconds).catch((err) => {
+					console.error("[vinext] fetch cache write error:", err);
+				});
 				const cachedData = cached.value.data;
 				return recordFetchOutcome(buildCachedFetchResponse(cachedData, input), "hit", cacheReason);
 			}
@@ -812,7 +814,9 @@ function createPatchedFetch() {
 				staleEntry = cached;
 				if (shouldRefreshStaleFetchInForeground()) {
 					const freshResponse = await dedupeFetch(input, fetchInit);
-					await writeFetchCacheResponse(handler, cacheKey, freshResponse, tags, revalidateSeconds, { staleEntry: cached });
+					await writeFetchCacheResponse(handler, cacheKey, freshResponse, tags, revalidateSeconds, { staleEntry: cached }).catch((err) => {
+						console.error("[vinext] fetch cache write error:", err);
+					});
 					return recordFetchOutcome(freshResponse, "miss", cacheReason);
 				}
 				const staleData = cached.value.data;

package/dist/shims/headers.d.ts

@@ -168,7 +168,8 @@ export declare function getActiveDraftModeState(): boolean | null;
 /**
  * Read the active request's draft-mode state without recording request API usage.
  * Internal cache implementations use this to bypass persistent reads and writes,
- * matching Next.js's request-level `workStore.isDraftMode` guard.
+ * matching Next.js's request-level `workStore.isDraftMode` guard. Once the
+ * headers context is cleared, the request keeps the state it had then.
  */
 export declare function isDraftModeEnabled(): boolean;
 type DraftModeResult = {

package/dist/shims/headers.js

@@ -1,4 +1,4 @@
-import { ensureRenderDynamicLatch, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
+import { ensureRenderDynamicLatch, getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { MIDDLEWARE_SET_COOKIE_HEADER } from "../utils/protocol-headers.js";
 import { buildRequestHeadersFromMiddlewareResponse } from "../utils/middleware-request-headers.js";
 import { parseEdgeRequestCookieHeader } from "../utils/parse-cookie.js";
@@ -292,6 +292,7 @@ function setHeadersContext(ctx) {
 		state.draftModeCookieHeader = null;
 		state.phase = "render";
 	} else {
+		if (state.headersContext && isInsideUnifiedScope()) getRequestContext().draftModeAtHeadersClear = getActiveDraftModeState() === true;
 		state.headersContext = null;
 		state.phase = "render";
 	}
@@ -638,10 +639,11 @@ function getActiveDraftModeState() {
 /**
 * Read the active request's draft-mode state without recording request API usage.
 * Internal cache implementations use this to bypass persistent reads and writes,
-* matching Next.js's request-level `workStore.isDraftMode` guard.
+* matching Next.js's request-level `workStore.isDraftMode` guard. Once the
+* headers context is cleared, the request keeps the state it had then.
 */
 function isDraftModeEnabled() {
-	return getActiveDraftModeState() ?? false;
+	return getActiveDraftModeState() ?? (isInsideUnifiedScope() && getRequestContext().draftModeAtHeadersClear === true);
 }
 function createDraftModeScopeError(expression) {
 	return /* @__PURE__ */ new Error(`${expression} can only be called from a Server Component, Route Handler, or Server Action.`);

package/dist/shims/internal/cache-context-accessor.d.ts

@@ -1,4 +1,4 @@
-import { CacheLifeConfig } from "../cache-request-state.js";
+import { CacheLifeConfig } from "../../utils/cache-life-profiles.js";
 //#region src/shims/internal/cache-context-accessor.d.ts
 type CacheContextLike = {
   tags: string[];

package/dist/shims/link.js

@@ -149,7 +149,7 @@ function getLinkPrefetchRouterMode() {
 /**
 * Prefetch a URL for faster navigation.
 *
-* For App Router (RSC): fetches the .rsc payload in the background and
+* For App Router (RSC): fetches the RSC payload in the background and
 * stores it in an in-memory cache for instant use during navigation.
 * For Pages Router: warms the page chunk, prefetches data only for SSG pages,
 * and falls back to a document prefetch hint when no page loader matches.
@@ -381,7 +381,7 @@ function prefetchUrl(href, mode, priority = "low", pagesRouteHref, locale, owner
 async function promotePrefetchEntriesForNavigation(href) {
 	if (typeof window === "undefined") return;
 	if (!hasLinkAppNavigationRuntime()) return;
-	const [{ getMountedSlotsHeader, getPrefetchCache, getPrefetchInterceptionContext, promotePrefetchCacheEntryForNavigation }, { parseRscRequestPath, stripRscCacheBustingSearchParam, stripRscSuffix }] = await Promise.all([loadNavigationModule(), loadAppRscCacheBustingModule()]);
+	const [{ getMountedSlotsHeader, getPrefetchCache, getPrefetchInterceptionContext, promotePrefetchCacheEntryForNavigation }, { parseRscRequestPath, stripRscCacheBustingSearchParam }] = await Promise.all([loadNavigationModule(), loadAppRscCacheBustingModule()]);
 	let target;
 	const fullHref = toCanonicalBrowserNavigationHref(href, window.location.href, __basePath, __trailingSlash);
 	try {
@@ -405,7 +405,7 @@ async function promotePrefetchEntriesForNavigation(href) {
 			continue;
 		}
 		stripRscCacheBustingSearchParam(cached);
-		if (stripRscSuffix(cached.pathname) === target.pathname && cached.search === target.search) promotePrefetchCacheEntryForNavigation(cacheKey, entry);
+		if (cached.pathname === target.pathname && cached.search === target.search) promotePrefetchCacheEntryForNavigation(cacheKey, entry);
 	}
 }
 /**
@@ -627,16 +627,11 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 		})
 	});
 	const [pending, setPending] = useState(false);
-	const mountedRef = useRef(true);
 	const pendingPagesIntentPrefetchRef = useRef(null);
-	const setPendingRef = useRef((next) => {
-		if (mountedRef.current) setPending(next);
-	});
+	const setPendingRef = useRef(setPending);
 	useEffect(() => {
-		mountedRef.current = true;
 		const setter = setPendingRef.current;
 		return () => {
-			mountedRef.current = false;
 			pendingPagesIntentPrefetchRef.current?.();
 			pendingPagesIntentPrefetchRef.current = null;
 			if (setter) clearLinkForCurrentNavigation(setter);
@@ -802,7 +797,7 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 			setPending(true);
 			React.startTransition(() => {
 				navigateClientSide(navigateHref, replace ? "replace" : "push", scroll, false).finally(() => {
-					if (mountedRef.current) setPending(false);
+					setPending(false);
 					if (setter) clearLinkForCurrentNavigation(setter);
 				});
 			});

package/dist/shims/navigation.js

@@ -11,7 +11,7 @@ import { resolveDirectHybridClientRouteOwner } from "./internal/hybrid-client-ro
 import { isHashOnlyBrowserUrlChange, toCanonicalBrowserNavigationHref, toSameOriginAppPath, withBasePath } from "./url-utils.js";
 import { disableSmoothScrollDuringRouteTransition } from "./disable-smooth-scroll.js";
 import { retryScrollTo, scrollToHashTarget } from "./hash-scroll.js";
-import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, createRscRequestHeaders, createRscRequestUrl, formatRscRequestPath, parseRscRequestPath, stripRscCacheBustingSearchParam, stripRscSuffix } from "../server/app-rsc-cache-busting.js";
+import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, createRscRequestHeaders, createRscRequestUrl, formatRscRequestPath, parseRscRequestPath, stripRscCacheBustingSearchParam } from "../server/app-rsc-cache-busting.js";
 import { clearAppNavigationFailureTarget, stageAppNavigationFailureTarget } from "../client/app-nav-failure-handler.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
 import { getNavigationRuntime, hasAppNavigationRuntime, loadNavigationRuntimeRouteManifest } from "../client/navigation-runtime.js";
@@ -245,8 +245,7 @@ function normalizeRscCacheLookupUrl(rscUrl) {
 }
 function normalizeRscCacheLookupPathname(rscUrl) {
 	try {
-		const url = parseRscRequestPath(rscUrl);
-		return stripRscSuffix(url.pathname);
+		return parseRscRequestPath(rscUrl).pathname;
 	} catch {
 		return null;
 	}