vinext 1.4.0 → 1.4.2

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/image-props.d.ts

@@ -71,6 +71,12 @@ export declare function resolveImageSource(v: {
  * Configurable via `images.deviceSizes` in next.config.js.
  */
 export declare const RESPONSIVE_WIDTHS: number[];
+/**
+ * Parse a `quality` prop like Next.js's `getInt` (shared/lib/get-img-props.ts):
+ * finite numbers and digit-only strings pass, anything else becomes NaN, which
+ * the default loader treats as 75.
+ */
+export declare function parseImageQuality(quality: unknown): number | undefined;
 /**
  * Build a `/_next/image` optimization URL.
  *

package/dist/shims/image-props.js

@@ -52,6 +52,14 @@ const __imageSizes = (() => {
 		];
 	}
 })();
+const __imageQualities = (() => {
+	try {
+		const qualities = JSON.parse(process.env.__VINEXT_IMAGE_QUALITIES ?? "null");
+		return Array.isArray(qualities) ? qualities.sort((a, b) => a - b) : null;
+	} catch {
+		return null;
+	}
+})();
 /**
 * Whether dangerouslyAllowSVG is enabled in next.config.js.
 * When false (default), .svg sources auto-skip the optimization endpoint
@@ -195,6 +203,33 @@ function extractLocalDeploymentId(src) {
 }
 const __imageEndpoint = `${process.env.__NEXT_ROUTER_BASEPATH ?? ""}/_next/image${process.env.__VINEXT_TRAILING_SLASH === "true" ? "/" : ""}`;
 /**
+* Parse a `quality` prop like Next.js's `getInt` (shared/lib/get-img-props.ts):
+* finite numbers and digit-only strings pass, anything else becomes NaN, which
+* the default loader treats as 75.
+*/
+function parseImageQuality(quality) {
+	if (quality === void 0) return void 0;
+	if (typeof quality === "number") return Number.isFinite(quality) ? quality : NaN;
+	if (typeof quality === "string" && /^[0-9]+$/.test(quality)) return parseInt(quality, 10);
+	return NaN;
+}
+/**
+* Round a `quality` prop to the closest entry of `images.qualities`, as the
+* Next.js default loader does (shared/lib/find-closest-quality.ts), so the
+* URL is one the optimization endpoint accepts.
+*
+* With no list configured the prop is used as written (75 when absent). This
+* is deliberate: Next.js 16 defaults the list to `[75]` and would round every
+* quality to 75, but vinext keeps the Next.js 14/15 behaviour for an unset
+* list so migrating apps keep the qualities they ask for (see
+* ImageConfig.qualities in server/image-optimization.ts).
+*/
+function findClosestQuality(quality) {
+	const q = quality || 75;
+	if (!__imageQualities?.length) return q;
+	return __imageQualities.reduce((prev, cur) => Math.abs(cur - q) < Math.abs(prev - q) ? cur : prev, __imageQualities[0]);
+}
+/**
 * Build a `/_next/image` optimization URL.
 *
 * In production (Cloudflare Workers), the worker intercepts this path and uses
@@ -202,9 +237,10 @@ const __imageEndpoint = `${process.env.__NEXT_ROUTER_BASEPATH ?? ""}/_next/image
 * server handles it as a passthrough (serves the original file).
 */
 function imageOptimizationUrl(src, width, quality = 75) {
+	const q = findClosestQuality(quality);
 	const source = extractLocalDeploymentId(src);
 	const deploymentQuery = source.src.startsWith("/") && source.deploymentId ? `&dpl=${source.deploymentId}` : "";
-	return `${__imageEndpoint}?url=${encodeURIComponent(source.src)}&w=${width}&q=${quality}${deploymentQuery}`;
+	return `${__imageEndpoint}?url=${encodeURIComponent(source.src)}&w=${width}&q=${q}${deploymentQuery}`;
 }
 /**
 * Generate a srcSet string for responsive images.
@@ -283,7 +319,7 @@ function getImageProps(props) {
 			}
 		}
 	}
-	const imgQuality = typeof _quality === "string" ? Number(_quality) : _quality ?? 75;
+	const imgQuality = parseImageQuality(_quality) ?? 75;
 	const resolvedSrc = blockedInProd ? "" : loader ? loader({
 		src,
 		width: imgWidth ?? 0,
@@ -320,4 +356,4 @@ function getImageProps(props) {
 	return { props: Object.assign(imageProps, { "data-nimg": fill ? "fill" : "1" }) };
 }
 //#endregion
-export { RESPONSIVE_WIDTHS, __dangerouslyAllowSVG, __globallyUnoptimized, __isDev, generateImageAttributes, getFillStyle, getImageProps, imageOptimizationUrl, isRemoteUrl, isSvgUrl, resolveImageSource, sanitizeBlurDataURL, validateRemoteUrl };
+export { RESPONSIVE_WIDTHS, __dangerouslyAllowSVG, __globallyUnoptimized, __isDev, generateImageAttributes, getFillStyle, getImageProps, imageOptimizationUrl, isRemoteUrl, isSvgUrl, parseImageQuality, resolveImageSource, sanitizeBlurDataURL, validateRemoteUrl };

package/dist/shims/image.js

@@ -1,6 +1,6 @@
 "use client";
 import { useMergedRef } from "./use-merged-ref.js";
-import { RESPONSIVE_WIDTHS, __dangerouslyAllowSVG, __globallyUnoptimized, __isDev, generateImageAttributes, getFillStyle, getImageProps, imageOptimizationUrl, isRemoteUrl, isSvgUrl, resolveImageSource, sanitizeBlurDataURL, validateRemoteUrl } from "./image-props.js";
+import { RESPONSIVE_WIDTHS, __dangerouslyAllowSVG, __globallyUnoptimized, __isDev, generateImageAttributes, getFillStyle, getImageProps, imageOptimizationUrl, isRemoteUrl, isSvgUrl, parseImageQuality, resolveImageSource, sanitizeBlurDataURL, validateRemoteUrl } from "./image-props.js";
 import { forwardRef, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 import * as ReactDOM from "react-dom";
@@ -197,7 +197,7 @@ const Image = forwardRef(function Image({ src: srcProp, alt, width, height, fill
 		});
 	}
 	if (loader) {
-		const resolvedQuality = typeof quality === "string" ? Number(quality) : quality ?? 75;
+		const resolvedQuality = parseImageQuality(quality) ?? 75;
 		const resolvedSrc = loader({
 			src,
 			width: imgWidth ?? 0,
@@ -293,7 +293,7 @@ const Image = forwardRef(function Image({ src: srcProp, alt, width, height, fill
 			});
 		}
 	}
-	const imgQuality = typeof quality === "string" ? Number(quality) : quality ?? 75;
+	const imgQuality = parseImageQuality(quality) ?? 75;
 	const skipOptimization = isSvgUrl(src) && !__dangerouslyAllowSVG;
 	const optimizedAttributes = imgWidth && !fill && !skipOptimization ? generateImageAttributes(src, imgWidth, imgQuality, sizes) : void 0;
 	const srcSet = optimizedAttributes ? optimizedAttributes.srcSet : imgWidth && !fill ? RESPONSIVE_WIDTHS.filter((w) => w <= imgWidth * 2).map((w) => `${src} ${w}w`).join(", ") || `${src} ${imgWidth}w` : void 0;