vinext 1.0.0-beta.1 → 1.0.0-beta.3

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);
@@ -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/revalidation-host.d.ts

@@ -0,0 +1,11 @@
+import { NextI18nConfig } from "../config/next-config.js";
+
+//#region src/server/revalidation-host.d.ts
+/**
+ * Read the logical request hostname carried by a server-pinned revalidation
+ * loopback. The side channel is accepted only as part of the authenticated
+ * revalidation protocol and only for an exact configured i18n domain.
+ */
+declare function readTrustedRevalidationHostname(headers: Headers, i18nConfig: NextI18nConfig | null | undefined, authorizeRevalidation?: (headerValue: string | null) => boolean): string | null;
+//#endregion
+export { readTrustedRevalidationHostname };

package/dist/server/revalidation-host.js

@@ -0,0 +1,19 @@
+import { VINEXT_REVALIDATE_HOST_HEADER } from "../utils/protocol-headers.js";
+import { isOnDemandRevalidateRequest } from "./isr-cache.js";
+import { normalizeDomainHostname } from "../utils/domain-locale.js";
+//#region src/server/revalidation-host.ts
+/**
+* Read the logical request hostname carried by a server-pinned revalidation
+* loopback. The side channel is accepted only as part of the authenticated
+* revalidation protocol and only for an exact configured i18n domain.
+*/
+function readTrustedRevalidationHostname(headers, i18nConfig, authorizeRevalidation = isOnDemandRevalidateRequest) {
+	if (!i18nConfig?.domains?.length || !authorizeRevalidation(headers.get("x-prerender-revalidate"))) return null;
+	const rawHostname = headers.get(VINEXT_REVALIDATE_HOST_HEADER);
+	if (!rawHostname) return null;
+	const hostname = rawHostname.trim().toLowerCase();
+	if (normalizeDomainHostname(hostname) !== hostname) return null;
+	return i18nConfig.domains.find((item) => normalizeDomainHostname(item.domain) === hostname)?.domain.toLowerCase() ?? null;
+}
+//#endregion
+export { readTrustedRevalidationHostname };

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/worker-revalidation-context.d.ts

@@ -0,0 +1,13 @@
+import { ExecutionContextLike } from "../shims/request-context.js";
+
+//#region src/server/worker-revalidation-context.d.ts
+type PlatformExecutionContext = Partial<ExecutionContextLike>;
+/**
+ * Add a request-local, in-process Pages revalidation dispatcher to a Worker
+ * execution context. Re-entering with the derived internal context preserves
+ * the authenticated protocol headers while keeping ordinary inbound requests
+ * on the normal header-scrubbing path.
+ */
+declare function createWorkerRevalidationContext(base: PlatformExecutionContext | undefined, handleInternalRequest: (request: Request, ctx: ExecutionContextLike) => Promise<Response>): ExecutionContextLike;
+//#endregion
+export { createWorkerRevalidationContext };

package/dist/server/worker-revalidation-context.js

@@ -0,0 +1,29 @@
+//#region src/server/worker-revalidation-context.ts
+function deriveExecutionContext(base, dispatchPagesRevalidate, isInternalPagesRevalidation) {
+	return {
+		waitUntil(promise) {
+			if (typeof base?.waitUntil === "function") base.waitUntil(promise);
+			else Promise.resolve(promise).catch(() => {});
+		},
+		...typeof base?.passThroughOnException === "function" ? { passThroughOnException() {
+			base.passThroughOnException?.();
+		} } : {},
+		...base?.cache === void 0 ? {} : { cache: base.cache },
+		...base?.trustedRevalidateOrigin === void 0 ? {} : { trustedRevalidateOrigin: base.trustedRevalidateOrigin },
+		dispatchPagesRevalidate,
+		isInternalPagesRevalidation
+	};
+}
+/**
+* Add a request-local, in-process Pages revalidation dispatcher to a Worker
+* execution context. Re-entering with the derived internal context preserves
+* the authenticated protocol headers while keeping ordinary inbound requests
+* on the normal header-scrubbing path.
+*/
+function createWorkerRevalidationContext(base, handleInternalRequest) {
+	if (typeof base?.dispatchPagesRevalidate === "function") return base;
+	const dispatchPagesRevalidate = (request) => handleInternalRequest(request, deriveExecutionContext(base, dispatchPagesRevalidate, true));
+	return deriveExecutionContext(base, dispatchPagesRevalidate, false);
+}
+//#endregion
+export { createWorkerRevalidationContext };

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-handler.d.ts

@@ -9,7 +9,7 @@ type CacheHandlerValue = {
   value: IncrementalCacheValue | null;
 };
 type CacheControlMetadata = {
-  revalidate: number;
+  revalidate: number | false;
   expire?: number;
 };
 type IncrementalCacheValue = CachedFetchValue | CachedAppPageValue | CachedPagesValue | CachedRouteValue | CachedRedirectValue | CachedImageValue;

package/dist/shims/cache-handler.js

@@ -1,4 +1,4 @@
-import { readCacheControlNumberField } from "../utils/cache-control-metadata.js";
+import { readCacheControlNumberField, readCacheControlRevalidateField } from "../utils/cache-control-metadata.js";
 //#region src/shims/cache-handler.ts
 var NoOpCacheHandler = class {
 	async get(_key, _ctx) {
@@ -88,12 +88,14 @@ var MemoryCacheHandler = class {
 			const revalidatedAt = this.tagRevalidatedAt.get(tag);
 			if (revalidatedAt && revalidatedAt >= entry.lastModified) return null;
 		}
-		if (entry.expireAt !== null && Date.now() > entry.expireAt) {
-			this.deleteEntry(key);
-			return null;
-		}
 		this.touchEntry(key, entry);
 		const now = Date.now();
+		if (entry.expireAt !== null && now > entry.expireAt) return {
+			lastModified: entry.lastModified,
+			value: entry.value,
+			cacheState: "expired",
+			cacheControl: entry.cacheControl
+		};
 		const requestedRevalidate = readPositiveNumberField(ctx, "revalidate");
 		const requestedRevalidateAt = requestedRevalidate === void 0 ? null : entry.lastModified + requestedRevalidate * 1e3;
 		if (entry.revalidateAt !== null && now > entry.revalidateAt || requestedRevalidateAt !== null && now > requestedRevalidateAt) return {
@@ -113,14 +115,15 @@ var MemoryCacheHandler = class {
 		if (data && "tags" in data && Array.isArray(data.tags)) for (const tag of data.tags) tagSet.add(tag);
 		for (const tag of readStringArrayField(ctx, "tags")) tagSet.add(tag);
 		const tags = [...tagSet];
-		let effectiveRevalidate = readCacheControlNumberField(ctx, "revalidate");
+		let effectiveRevalidate = readCacheControlRevalidateField(ctx);
 		const effectiveExpire = readCacheControlNumberField(ctx, "expire");
 		if (data && "revalidate" in data && typeof data.revalidate === "number") effectiveRevalidate = data.revalidate;
+		else if (data && "revalidate" in data && data.revalidate === false) effectiveRevalidate ??= false;
 		if (effectiveRevalidate === 0) return;
 		const now = Date.now();
 		const revalidateAt = typeof effectiveRevalidate === "number" && effectiveRevalidate > 0 ? now + effectiveRevalidate * 1e3 : null;
 		const expireAt = typeof effectiveExpire === "number" && effectiveExpire > 0 ? now + effectiveExpire * 1e3 : null;
-		const cacheControl = typeof effectiveRevalidate === "number" ? effectiveExpire === void 0 ? { revalidate: effectiveRevalidate } : {
+		const cacheControl = typeof effectiveRevalidate === "number" || effectiveRevalidate === false ? effectiveExpire === void 0 ? { revalidate: effectiveRevalidate } : {
 			revalidate: effectiveRevalidate,
 			expire: effectiveExpire
 		} : void 0;

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
@@ -60,6 +71,12 @@ declare function runWithPrivateCache<T>(fn: () => T | Promise<T>): T | Promise<T
  */
 declare function clearPrivateCache(): void;
 type RegisterCachedFunctionOptions = {
+  /**
+   * Whether the original function declaration accepts a second argument.
+   * Function.length cannot represent default or rest parameters, so the
+   * transform records this separately for metadata parent resolution.
+   */
+  acceptsSecondArgument?: boolean;
   /**
    * Internal transform metadata for file-level `"use cache"` default exports
    * in App Router `page.*` files. Page components receive framework-owned
@@ -80,4 +97,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 };