vinext 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/server/request-pipeline.d.ts

@@ -1,10 +1,21 @@
-import { NextHeader } from "../config/next-config.js";
-import { BasePathMatchState, RequestContext } from "../config/config-matchers.js";
 import { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS } from "./headers.js";
-import { isOpenRedirectShaped } from "./open-redirect.js";
 import { hasBasePath, stripBasePath } from "../utils/base-path.js";
+import { isOpenRedirectShaped } from "./open-redirect.js";
 
 //#region src/server/request-pipeline.d.ts
+/**
+ * Apply the URL Standard's pathname canonicalization without decoding and
+ * re-encoding ordinary percent escapes.
+ *
+ * In particular, WHATWG URLs remove literal and percent-encoded dot segments
+ * (`/%2e/about` becomes `/about`) while preserving unrelated spellings such
+ * as `/%61bout`, `%2F`, `%5C`, and `%252F` byte-for-byte. Node request adapters
+ * must do this before comparing raw route/config/basePath identity so those
+ * comparisons agree with the `Request` that userland eventually receives.
+ */
+declare function canonicalizeRequestPathname(pathname: string): string;
+/** Canonicalize only the pathname portion while preserving the raw query. */
+declare function canonicalizeRequestUrlPathname(url: string): string;
 /**
  * Shared request pipeline utilities.
  *
@@ -44,18 +55,6 @@ import { hasBasePath, stripBasePath } from "../utils/base-path.js";
  */
 declare function guardProtocolRelativeUrl(rawPathname: string): Response | null;
 type HeaderRecord = Record<string, string | string[]>;
-type ApplyConfigHeadersOptions = {
-  configHeaders: NextHeader[];
-  pathname: string;
-  requestContext: RequestContext;
-  /**
-   * basePath gating state. When omitted, every rule is treated as a default
-   * (basePath: true) rule for backward compatibility — callers that need to
-   * support `basePath: false` headers must pass this in.
-   */
-  basePathState?: BasePathMatchState; /** Existing framework-generated headers that matching config rules may replace. */
-  overwriteExisting?: ReadonlySet<string>;
-};
 type StaticFileSignalContext = {
   headers: Headers | null;
   status: number | null;
@@ -67,19 +66,6 @@ type ResolvePublicFileRouteOptions = {
   publicFiles: ReadonlySet<string>;
   request: Request;
 };
-/**
- * Apply matched next.config.js headers to a Web Headers object.
- *
- * Next.js evaluates config header match conditions against the original
- * request snapshot. Middleware response headers still win for the same
- * response key, while multi-value headers are additive.
- */
-declare function applyConfigHeadersToResponse(responseHeaders: Headers, options: ApplyConfigHeadersOptions): void;
-/**
- * Apply matched next.config.js headers to the early response header record used
- * by Node and Worker Pages Router pipelines before a concrete response exists.
- */
-declare function applyConfigHeadersToHeaderRecord(headers: HeaderRecord, options: ApplyConfigHeadersOptions): void;
 declare function createStaticFileSignal(pathname: string, context: StaticFileSignalContext): Response;
 /**
  * Resolve the public/ filesystem-route slot in the Next.js routing order.
@@ -184,4 +170,4 @@ declare function cloneRequestWithHeaders(request: Request, headers: Headers): Re
  */
 declare function cloneRequestWithUrl(request: Request, url: string): Request;
 //#endregion
-export { HeaderRecord, INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, applyConfigHeadersToHeaderRecord, applyConfigHeadersToResponse, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, stripBasePath, validateCsrfOrigin, validateServerActionPayload };
+export { HeaderRecord, INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, canonicalizeRequestPathname, canonicalizeRequestUrlPathname, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, stripBasePath, validateCsrfOrigin, validateServerActionPayload };

package/dist/server/request-pipeline.js

@@ -1,10 +1,32 @@
 import { hasBasePath, removeTrailingSlash, stripBasePath } from "../utils/base-path.js";
 import "../utils/protocol-headers.js";
 import { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, VINEXT_STATIC_FILE_HEADER } from "./headers.js";
-import { matchHeaders } from "../config/config-matchers.js";
 import { forbiddenResponse, notFoundResponse } from "./http-error-responses.js";
 import { isOpenRedirectShaped } from "./open-redirect.js";
 //#region src/server/request-pipeline.ts
+const PATHNAME_CANONICALIZATION_BASE = new URL("http://vinext.invalid/");
+/**
+* Apply the URL Standard's pathname canonicalization without decoding and
+* re-encoding ordinary percent escapes.
+*
+* In particular, WHATWG URLs remove literal and percent-encoded dot segments
+* (`/%2e/about` becomes `/about`) while preserving unrelated spellings such
+* as `/%61bout`, `%2F`, `%5C`, and `%252F` byte-for-byte. Node request adapters
+* must do this before comparing raw route/config/basePath identity so those
+* comparisons agree with the `Request` that userland eventually receives.
+*/
+function canonicalizeRequestPathname(pathname) {
+	const url = new URL(PATHNAME_CANONICALIZATION_BASE);
+	url.pathname = pathname;
+	return url.pathname;
+}
+/** Canonicalize only the pathname portion while preserving the raw query. */
+function canonicalizeRequestUrlPathname(url) {
+	const queryIndex = url.indexOf("?");
+	const pathname = queryIndex === -1 ? url : url.slice(0, queryIndex);
+	const search = queryIndex === -1 ? "" : url.slice(queryIndex);
+	return canonicalizeRequestPathname(pathname) + search;
+}
 /**
 * Shared request pipeline utilities.
 *
@@ -50,63 +72,6 @@ const FILE_LIKE_PATHNAME_RE = /\.[^/]+\/?$/;
 function isWellKnownPathname(pathname) {
 	return pathname === "/.well-known" || pathname.startsWith("/.well-known/");
 }
-function findHeaderRecordKey(headers, lowerName) {
-	for (const key of Object.keys(headers)) if (key.toLowerCase() === lowerName) return key;
-}
-function appendHeaderRecord(headers, lowerName, value) {
-	const key = findHeaderRecordKey(headers, lowerName) ?? lowerName;
-	const existing = headers[key];
-	if (existing === void 0) {
-		headers[key] = value;
-		return;
-	}
-	if (Array.isArray(existing)) {
-		existing.push(value);
-		return;
-	}
-	headers[key] = [existing, value];
-}
-function appendVaryHeaderRecord(headers, value) {
-	const key = findHeaderRecordKey(headers, "vary") ?? "vary";
-	const existing = headers[key];
-	if (existing === void 0) {
-		headers[key] = value;
-		return;
-	}
-	if (Array.isArray(existing)) {
-		existing.push(value);
-		return;
-	}
-	headers[key] = existing + ", " + value;
-}
-/**
-* Apply matched next.config.js headers to a Web Headers object.
-*
-* Next.js evaluates config header match conditions against the original
-* request snapshot. Middleware response headers still win for the same
-* response key, while multi-value headers are additive.
-*/
-function applyConfigHeadersToResponse(responseHeaders, options) {
-	const matched = matchHeaders(options.pathname, options.configHeaders, options.requestContext, options.basePathState);
-	for (const header of matched) {
-		const lowerName = header.key.toLowerCase();
-		if (lowerName === "vary" || lowerName === "set-cookie") responseHeaders.append(header.key, header.value);
-		else if (options.overwriteExisting?.has(lowerName) || !responseHeaders.has(lowerName)) responseHeaders.set(header.key, header.value);
-	}
-}
-/**
-* Apply matched next.config.js headers to the early response header record used
-* by Node and Worker Pages Router pipelines before a concrete response exists.
-*/
-function applyConfigHeadersToHeaderRecord(headers, options) {
-	const matched = matchHeaders(options.pathname, options.configHeaders, options.requestContext, options.basePathState);
-	for (const header of matched) {
-		const lowerName = header.key.toLowerCase();
-		if (lowerName === "set-cookie") appendHeaderRecord(headers, lowerName, header.value);
-		else if (lowerName === "vary") appendVaryHeaderRecord(headers, header.value);
-		else if (findHeaderRecordKey(headers, lowerName) === void 0) headers[lowerName] = header.value;
-	}
-}
 function createStaticFileSignal(pathname, context) {
 	const headers = new Headers({ [VINEXT_STATIC_FILE_HEADER]: encodeURIComponent(pathname) });
 	if (context.headers) for (const [key, value] of context.headers) headers.append(key, value);
@@ -341,7 +306,7 @@ function processMiddlewareHeaders(headers) {
 	for (const key of headers.keys()) if (key.startsWith("x-middleware-") && key !== "x-middleware-cache") keysToDelete.push(key);
 	for (const key of keysToDelete) headers.delete(key);
 }
-const STRIPPED_INTERNAL_HEADERS = new Set([...INTERNAL_HEADERS, ...VINEXT_INTERNAL_HEADERS]);
+const STRIPPED_INTERNAL_HEADERS = /* @__PURE__ */ new Set([...INTERNAL_HEADERS, ...VINEXT_INTERNAL_HEADERS]);
 /**
 * Strip internal headers from an inbound request so they cannot be forged by
 * an external attacker to influence routing or impersonate internal state.
@@ -445,4 +410,4 @@ function cloneRequestWithUrl(request, url) {
 	return cloned;
 }
 //#endregion
-export { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, applyConfigHeadersToHeaderRecord, applyConfigHeadersToResponse, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, stripBasePath, validateCsrfOrigin, validateServerActionPayload };
+export { INTERNAL_HEADERS, VINEXT_INTERNAL_HEADERS, canonicalizeRequestPathname, canonicalizeRequestUrlPathname, cloneRequestWithHeaders, cloneRequestWithUrl, createStaticFileSignal, filterInternalHeaders, guardProtocolRelativeUrl, hasBasePath, isOpenRedirectShaped, isOriginAllowed, normalizeTrailingSlash, normalizeTrailingSlashPathname, processMiddlewareHeaders, resolvePublicFileRoute, stripBasePath, validateCsrfOrigin, validateServerActionPayload };

package/dist/server/rsc-stream-hints.js

@@ -1,31 +1,135 @@
 //#region src/server/rsc-stream-hints.ts
-const REACT_FLIGHT_STYLESHEET_PRELOAD_HINT = /(\d*:HL\[.*?),"stylesheet"(\]|,)/g;
-/**
-* React Flight emits HL hints with "stylesheet" for CSS preloads, but the
-* HTML spec requires "style" for <link rel="preload">. Rewrite each complete
-* Flight line so SSR embeds, navigation, and server actions see valid hints.
-*/
+const REACT_FLIGHT_STYLESHEET_PRELOAD_HINT = /^([0-9a-f]*:HL\[.*?),"stylesheet"(\]|,)/;
+const STYLESHEET_TO_STYLE_JSON_PADDING = " ".repeat(5);
+const LENGTH_PREFIXED_ROW_TAGS = /* @__PURE__ */ new Set([
+	"T",
+	"A",
+	"O",
+	"o",
+	"b",
+	"U",
+	"S",
+	"s",
+	"L",
+	"l",
+	"G",
+	"g",
+	"M",
+	"m",
+	"V"
+]);
+const NEWLINE_PREFIXED_ROW_TAGS = /* @__PURE__ */ new Set([
+	"I",
+	"H",
+	"E",
+	"N",
+	"D",
+	"J",
+	"W",
+	"R",
+	"r",
+	"X",
+	"x",
+	"C",
+	"P",
+	"#"
+]);
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/** Rewrite only a complete React Flight stylesheet hint row. */
 function normalizeReactFlightHintLine(line) {
-	return line.replace(REACT_FLIGHT_STYLESHEET_PRELOAD_HINT, "$1,\"style\"$2");
+	const text = decoder.decode(line);
+	const normalized = text.replace(REACT_FLIGHT_STYLESHEET_PRELOAD_HINT, `$1,"style"${STYLESHEET_TO_STYLE_JSON_PADDING}$2`);
+	if (normalized === text) return line;
+	const normalizedBytes = encoder.encode(normalized);
+	return normalizedBytes.byteLength === line.byteLength ? normalizedBytes : line;
+}
+function concatBytes(first, second) {
+	if (first.byteLength === 0) return second;
+	const combined = new Uint8Array(first.byteLength + second.byteLength);
+	combined.set(first);
+	combined.set(second, first.byteLength);
+	return combined;
+}
+function indexOfByte(bytes, byte, from = 0) {
+	for (let index = from; index < bytes.byteLength; index++) if (bytes[index] === byte) return index;
+	return -1;
+}
+function parseHexBytes(bytes, start, end) {
+	if (start === end) return null;
+	let value = 0;
+	for (let index = start; index < end; index++) {
+		const byte = bytes[index];
+		const digit = byte >= 48 && byte <= 57 ? byte - 48 : byte >= 97 && byte <= 102 ? byte - 87 : -1;
+		if (digit === -1) return null;
+		value = value * 16 + digit;
+		if (!Number.isSafeInteger(value)) return null;
+	}
+	return value;
+}
+function isUntaggedJsonRowStart(byte) {
+	return byte === 34 || byte === 45 || byte >= 48 && byte <= 57 || byte === 91 || byte === 102 || byte === 110 || byte === 116 || byte === 123;
 }
 function normalizeReactFlightPreloadHints(stream) {
-	const decoder = new TextDecoder();
-	const encoder = new TextEncoder();
-	let carry = "";
+	let carry = /* @__PURE__ */ new Uint8Array();
+	let rawBytesRemaining = 0;
+	let passThrough = false;
 	return stream.pipeThrough(new TransformStream({
 		transform(chunk, controller) {
-			const text = carry + decoder.decode(chunk, { stream: true });
-			const lastNewline = text.lastIndexOf("\n");
-			if (lastNewline === -1) {
-				carry = text;
+			if (passThrough) {
+				controller.enqueue(chunk);
 				return;
 			}
-			carry = text.slice(lastNewline + 1);
-			controller.enqueue(encoder.encode(normalizeReactFlightHintLine(text.slice(0, lastNewline + 1))));
+			let bytes = concatBytes(carry, chunk);
+			carry = /* @__PURE__ */ new Uint8Array();
+			while (bytes.byteLength > 0) {
+				if (rawBytesRemaining > 0) {
+					const length = Math.min(rawBytesRemaining, bytes.byteLength);
+					controller.enqueue(bytes.slice(0, length));
+					rawBytesRemaining -= length;
+					bytes = bytes.subarray(length);
+					continue;
+				}
+				const colon = indexOfByte(bytes, 58);
+				if (colon === -1 || colon + 1 === bytes.byteLength) {
+					carry = bytes.slice();
+					return;
+				}
+				const tag = String.fromCharCode(bytes[colon + 1]);
+				if (LENGTH_PREFIXED_ROW_TAGS.has(tag)) {
+					const comma = indexOfByte(bytes, 44, colon + 2);
+					if (comma === -1) {
+						carry = bytes.slice();
+						return;
+					}
+					const length = parseHexBytes(bytes, colon + 2, comma);
+					if (length != null) {
+						controller.enqueue(bytes.slice(0, comma + 1));
+						rawBytesRemaining = length;
+						bytes = bytes.subarray(comma + 1);
+						continue;
+					}
+					passThrough = true;
+					controller.enqueue(bytes);
+					return;
+				}
+				const tagByte = bytes[colon + 1];
+				if (!NEWLINE_PREFIXED_ROW_TAGS.has(tag) && !isUntaggedJsonRowStart(tagByte)) {
+					passThrough = true;
+					controller.enqueue(bytes);
+					return;
+				}
+				const newline = indexOfByte(bytes, 10);
+				if (newline === -1) {
+					carry = bytes.slice();
+					return;
+				}
+				controller.enqueue(normalizeReactFlightHintLine(bytes.slice(0, newline + 1)));
+				bytes = bytes.subarray(newline + 1);
+			}
 		},
 		flush(controller) {
-			const text = carry + decoder.decode();
-			if (text) controller.enqueue(encoder.encode(normalizeReactFlightHintLine(text)));
+			if (carry.byteLength > 0) controller.enqueue(rawBytesRemaining > 0 ? carry : normalizeReactFlightHintLine(carry));
 		}
 	}));
 }

package/dist/server/seed-cache.js

@@ -1,10 +1,10 @@
+import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { isrCacheKey, isrSetPrerenderedAppPage } from "./isr-cache.js";
 import { getRenderedAppRoutes, isFallbackShellArtifactPath, readPrerenderManifest } from "./prerender-manifest.js";
 import { buildAppPageCacheTags } from "./app-page-cache.js";
 import { getOutputPath, getRscOutputPath } from "../utils/prerender-output-paths.js";
 import { addPregeneratedConcretePath, clearPregeneratedConcretePaths, normalizePregeneratedPathname } from "./pregenerated-concrete-paths.js";
 import fs from "node:fs";
-import path from "node:path";
 //#region src/server/seed-cache.ts
 /**
 * Seed the memory cache from pre-rendered build output.

package/dist/server/socket-error-backstop.js

@@ -90,7 +90,7 @@ function peerDisconnectCode(err) {
 	const code = err?.code;
 	return code === "ECONNRESET" || code === "EPIPE" || code === "ECONNABORTED" ? code : void 0;
 }
-const STATIC_ASSET_IMPORT_EXTENSIONS = new Set([
+const STATIC_ASSET_IMPORT_EXTENSIONS = /* @__PURE__ */ new Set([
 	".css",
 	".scss",
 	".sass",

package/dist/server/static-file-cache.js

@@ -1,7 +1,6 @@
-import { normalizePathSeparators } from "../utils/path.js";
+import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { ASSET_PREFIX_URL_DIR } from "../utils/asset-prefix.js";
-import path from "node:path";
-import fs from "node:fs/promises";
+import fsp from "node:fs/promises";
 //#region src/server/static-file-cache.ts
 /**
 * Startup metadata cache for static file serving.
@@ -137,7 +136,7 @@ var StaticFileCache = class StaticFileCache {
 			}
 		}
 		for (let i = 0; i < toBuffer.length; i += 64) await Promise.all(toBuffer.slice(i, i + 64).map(async (v) => {
-			v.buffer = await fs.readFile(v.path);
+			v.buffer = await fsp.readFile(v.path);
 		}));
 		return new StaticFileCache(entries);
 	}
@@ -170,7 +169,7 @@ function etagFromFilenameHash(relativePath, ext) {
 		const suffix = basename.slice(lastDash + 1);
 		if (suffix.length >= 6 && suffix.length <= 12 && /^[A-Za-z0-9_-]+$/.test(suffix)) return `W/"${suffix}"`;
 	}
-	const normalizedPath = normalizePathSeparators(relativePath);
+	const normalizedPath = toSlash(relativePath);
 	const managedMediaSegment = `${ASSET_PREFIX_URL_DIR}/media/`;
 	if (normalizedPath.startsWith(managedMediaSegment) || normalizedPath.includes(`/${managedMediaSegment}`)) {
 		const lastDot = basename.lastIndexOf(".");
@@ -204,7 +203,7 @@ const STAT_BATCH_SIZE = 64;
 async function* walkFilesWithStats(dir, base = dir) {
 	let entries;
 	try {
-		entries = await fs.readdir(dir, { withFileTypes: true });
+		entries = await fsp.readdir(dir, { withFileTypes: true });
 	} catch {
 		return;
 	}
@@ -216,9 +215,9 @@ async function* walkFilesWithStats(dir, base = dir) {
 	}
 	for (let i = 0; i < files.length; i += STAT_BATCH_SIZE) {
 		const batch = files.slice(i, i + STAT_BATCH_SIZE);
-		const stats = await Promise.all(batch.map((f) => fs.stat(f)));
+		const stats = await Promise.all(batch.map((f) => fsp.stat(f)));
 		for (let j = 0; j < batch.length; j++) yield {
-			relativePath: normalizePathSeparators(path.relative(base, batch[j])),
+			relativePath: path.relative(base, batch[j]),
 			fullPath: batch[j],
 			stat: {
 				size: stats[j].size,

package/dist/server/worker-utils.js

@@ -14,7 +14,7 @@ import { notFoundStaticAssetResponse } from "./http-error-responses.js";
 * are preserved). Uses getSetCookie() to preserve multiple Set-Cookie values.
 * Keep this in sync with prod-server.ts.
 */
-const NO_BODY_RESPONSE_STATUSES = new Set([
+const NO_BODY_RESPONSE_STATUSES = /* @__PURE__ */ new Set([
 	204,
 	205,
 	304

package/dist/shims/app.d.ts

@@ -36,7 +36,7 @@ declare function appGetInitialProps({
 declare class App<P = any, CP = any, S = any> extends React.Component<P & AppProps<CP>, S> {
   static origGetInitialProps: typeof appGetInitialProps;
   static getInitialProps: typeof appGetInitialProps;
-  render(): React.ReactNode;
+  render(): React.ReactElement;
 }
 //#endregion
 export { AppContext, AppInitialProps, AppProps, App as default };

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

@@ -26,6 +26,8 @@ type UnstableCacheObservation = Readonly<{
 }>;
 type CacheState = {
   actionRevalidationKind: ActionRevalidationKind;
+  pendingRevalidatedTags: Set<string>;
+  pendingRevalidations: Set<Promise<void>>;
   requestScopedCacheLife: CacheLifeConfig | null;
   unstableCacheObservations: Map<string, UnstableCacheObservation>;
   unstableCacheRevalidation: UnstableCacheRevalidationMode;
@@ -37,6 +39,30 @@ 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;
+/** @internal */
+declare function _markPendingRevalidatedTag(tag: string): void;
+/** @internal */
+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
+ * synchronous, matching Next.js, while the request boundary owns the await.
+ *
+ * Returns false outside a request-like phase so standalone calls can retain
+ * their historical background-work behavior without accumulating promises in
+ * the process-global fallback state.
+ *
+ * @internal
+ */
+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
+ * an async continuation while this batch is settling.
+ *
+ * @internal
+ */
+declare function _drainPendingRevalidations(): Promise<void>;
 declare function _setRequestScopedCacheLife(config: CacheLifeConfig): void;
 declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
 declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
@@ -44,4 +70,4 @@ declare function recordUnstableCacheObservation(observation: UnstableCacheObserv
 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, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };

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

@@ -53,6 +53,8 @@ const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
 const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
 const fallbackState = globalState[FALLBACK_KEY] ??= {
 	actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+	pendingRevalidatedTags: /* @__PURE__ */ new Set(),
+	pendingRevalidations: /* @__PURE__ */ new Set(),
 	requestScopedCacheLife: null,
 	unstableCacheObservations: /* @__PURE__ */ new Map(),
 	unstableCacheRevalidation: "foreground"
@@ -70,6 +72,8 @@ function _runWithCacheState(fn) {
 	}, fn);
 	const state = {
 		actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+		pendingRevalidatedTags: /* @__PURE__ */ new Set(),
+		pendingRevalidations: /* @__PURE__ */ new Set(),
 		requestScopedCacheLife: null,
 		unstableCacheObservations: /* @__PURE__ */ new Map(),
 		unstableCacheRevalidation: "foreground"
@@ -93,6 +97,61 @@ function getAndClearActionRevalidationKind() {
 	state.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
 	return kind;
 }
+function hasRequestScopedCacheState() {
+	if (isInsideUnifiedScope() || cacheAls.getStore() !== void 0) return true;
+	const phase = getHeadersAccessPhase();
+	return phase === "action" || phase === "route-handler";
+}
+/** @internal */
+function _markPendingRevalidatedTag(tag) {
+	if (!hasRequestScopedCacheState()) return;
+	getCacheState().pendingRevalidatedTags.add(tag);
+}
+/** @internal */
+function _hasPendingRevalidatedTag(tags) {
+	if (!hasRequestScopedCacheState()) return false;
+	const pendingTags = getCacheState().pendingRevalidatedTags;
+	return tags.some((tag) => pendingTags.has(tag));
+}
+/**
+* Record a cache invalidation that must finish before the current action or
+* route-handler request is finalized. The public revalidation APIs remain
+* synchronous, matching Next.js, while the request boundary owns the await.
+*
+* Returns false outside a request-like phase so standalone calls can retain
+* their historical background-work behavior without accumulating promises in
+* the process-global fallback state.
+*
+* @internal
+*/
+function _queuePendingRevalidation(promise) {
+	if (!hasRequestScopedCacheState()) return false;
+	getCacheState().pendingRevalidations.add(promise);
+	promise.catch(() => {});
+	return true;
+}
+/**
+* Await and clear every cache invalidation queued in the current request.
+* Clearing before awaiting also lets a later drain observe work enqueued by
+* an async continuation while this batch is settling.
+*
+* @internal
+*/
+async function _drainPendingRevalidations() {
+	const state = getCacheState();
+	let didReject = false;
+	let firstRejection;
+	while (state.pendingRevalidations.size > 0) {
+		const pending = [...state.pendingRevalidations];
+		state.pendingRevalidations.clear();
+		const results = await Promise.allSettled(pending);
+		for (const result of results) if (result.status === "rejected" && !didReject) {
+			didReject = true;
+			firstRejection = result.reason;
+		}
+	}
+	if (didReject) throw firstRejection;
+}
 function _setRequestScopedCacheLife(config) {
 	const state = getCacheState();
 	if (state.requestScopedCacheLife === null) {
@@ -123,4 +182,4 @@ function shouldServeStaleUnstableCacheEntry() {
 	return getCacheState().unstableCacheRevalidation === "background";
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };

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

@@ -35,6 +35,17 @@ declare const cacheContextStorage: import("node:async_hooks").AsyncLocalStorage<
  * Get the current cache context. Returns null if not inside a "use cache" function.
  */
 declare function getCacheContext(): CacheContext | null;
+/**
+ * Build the shared-cache key for a "use cache" function from its build-scoped
+ * identity and serialized arguments.
+ *
+ * This is a logical handler key, not a storage key. Backend-specific adapters
+ * are responsible for mapping it to their physical key constraints after
+ * applying any storage prefixes.
+ *
+ * Exported for testing.
+ */
+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
@@ -80,4 +91,4 @@ type RegisterCachedFunctionOptions = {
  */
 declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant?: string, options?: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
 //#endregion
-export { CacheContext, NestedDynamicUseCacheError, PrivateCacheState, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { CacheContext, NestedDynamicUseCacheError, PrivateCacheState, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache-runtime.js

@@ -4,7 +4,7 @@ import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
 import { getDataCacheHandler } from "./cache-handler.js";
 import { trackPprFallbackShellCacheTask } from "./ppr-fallback-shell.js";
 import { markDynamicUsage } from "./headers.js";
-import { _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.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";
 //#region src/shims/cache-runtime.ts
@@ -102,6 +102,16 @@ function getUseCacheBuildIdDefine() {
 function getUseCacheKeySeed() {
 	return getUseCacheDeploymentIdDefine() || getUseCacheBuildIdDefine();
 }
+/**
+* Build the shared-cache key for a "use cache" function from its build-scoped
+* identity and serialized arguments.
+*
+* This is a logical handler key, not a storage key. Backend-specific adapters
+* are responsible for mapping it to their physical key constraints after
+* applying any storage prefixes.
+*
+* Exported for testing.
+*/
 function buildUseCacheKey(id, keySeed, argsKey) {
 	const scopedId = keySeed ? `build:${encodeURIComponent(keySeed)}:${id}` : id;
 	return argsKey === void 0 ? `use-cache:${scopedId}` : `use-cache:${scopedId}:${argsKey}`;
@@ -263,11 +273,16 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 		if (isDev) return executeWithContext(fn, args, cacheVariant);
 		const handler = getDataCacheHandler();
 		const softTags = getCurrentFetchSoftTags();
-		const existing = await handler.get(cacheKey, {
-			kind: "FETCH",
-			softTags
-		});
-		if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale") try {
+		let existing = null;
+		if (!_hasPendingRevalidatedTag(softTags)) try {
+			existing = await handler.get(cacheKey, {
+				kind: "FETCH",
+				softTags
+			});
+		} catch (error) {
+			console.error("[vinext] use cache: handler.get failed; treating as a cache miss:", error);
+		}
+		if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale" && !_hasPendingRevalidatedTag([...existing.value.tags ?? [], ...softTags])) try {
 			propagateCacheTagsToRequest(existing.value.tags);
 			if (rsc && existing.value.data.headers["x-vinext-rsc"] === "1") {
 				const stream = uint8ToStream(base64ToUint8(existing.value.data.body));
@@ -449,4 +464,4 @@ function stableStringify(value, seen) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { NestedDynamicUseCacheError, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };