vinext 0.0.54 → 0.1.0

package/dist/shims/cache.d.ts

@@ -94,9 +94,29 @@ declare class NoOpCacheHandler implements CacheHandler {
     expire?: number;
   }): Promise<void>;
 }
+type MemoryCacheHandlerOptions = Pick<CacheHandlerContext, "maxMemoryCacheSize"> & {
+  cacheMaxMemorySize?: number;
+};
+/**
+ * In-memory data cache handler. This is the built-in default — vinext installs
+ * it automatically, so consumers should not construct or register it by hand.
+ *
+ * @deprecated Consumers should not instantiate cache handlers directly.
+ * Configure caching declaratively via the `cache` option on the `vinext()`
+ * plugin (see {@link setDataCacheHandler}); the in-memory handler is the
+ * default when nothing is configured, and its size is tuned via the
+ * `cacheMaxMemorySize` plugin option.
+ */
 declare class MemoryCacheHandler implements CacheHandler {
   private store;
   private tagRevalidatedAt;
+  private readonly maxMemoryCacheSize;
+  private currentMemoryCacheSize;
+  constructor(options?: number | MemoryCacheHandlerOptions);
+  private estimateEntrySize;
+  private deleteEntry;
+  private touchEntry;
+  private evictLeastRecentlyUsed;
   get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
   revalidateTag(tags: string | string[], _durations?: {
@@ -104,16 +124,49 @@ declare class MemoryCacheHandler implements CacheHandler {
   }): Promise<void>;
   resetRequestCache(): void;
 }
+declare function configureMemoryCacheHandler(options?: MemoryCacheHandlerOptions): void;
 /**
- * Set a custom CacheHandler. Call this during server startup to
- * plug in Cloudflare KV, Redis, DynamoDB, or any other backend.
+ * Set the **data cache** handler. This backs all data-cache concerns —
+ * `fetch` caching, `"use cache"`, `unstable_cache` — and is also the default
+ * underlying store for page-level ISR (via the default CDN cache adapter).
+ *
+ * The handler must implement the CacheHandler interface (same shape as
+ * Next.js 16's CacheHandler class).
+ *
+ * @deprecated Don't wire up the data cache imperatively. Configure it
+ * declaratively via the `cache.data` option on the `vinext()` plugin in your
+ * `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
  *
- * The handler must implement the CacheHandler interface (same shape
- * as Next.js 16's CacheHandler class).
+ * ```ts
+ * import { vinext } from "vinext";
+ * import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+ *
+ * export default defineConfig({
+ *   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+ * });
+ * ```
+ *
+ * The plugin defers instantiation to the first request and registers the
+ * handler across every runtime/router entry, so you don't have to call this
+ * from a worker entry. This setter remains as the internal registration target
+ * and for backwards compatibility, but is not the recommended consumer API.
+ */
+declare function setDataCacheHandler(handler: CacheHandler): void;
+/**
+ * Get the active data cache handler (for internal use or testing).
+ */
+declare function getDataCacheHandler(): CacheHandler;
+/**
+ * @deprecated Don't wire up the data cache imperatively. Configure it
+ * declaratively via the `cache.data` option on the `vinext()` plugin (e.g.
+ * `kvDataAdapter()` from `@vinext/cloudflare/cache/kv-data-adapter`). See
+ * {@link setDataCacheHandler} for the migration example. Retained as a
+ * backwards-compatible alias — `setCacheHandler` has always configured the
+ * data cache handler.
  */
 declare function setCacheHandler(handler: CacheHandler): void;
 /**
- * Get the active CacheHandler (for internal use or testing).
+ * @deprecated Prefer {@link getDataCacheHandler}.
  */
 declare function getCacheHandler(): CacheHandler;
 /**
@@ -212,9 +265,17 @@ declare function io(): Promise<void>;
 declare function unstable_io(): Promise<void>;
 type UnstableCacheRevalidationMode = "foreground" | "background";
 type ActionRevalidationKind = 0 | 1 | 2;
+type UnstableCacheObservation = Readonly<{
+  kind: "unstable_cache";
+  keyHash: string;
+  revalidate: number | false | null;
+  tagCount: number;
+  tagHash: string | null;
+}>;
 type CacheState = {
   actionRevalidationKind: ActionRevalidationKind;
   requestScopedCacheLife: CacheLifeConfig | null;
+  unstableCacheObservations: Map<string, UnstableCacheObservation>;
   unstableCacheRevalidation: UnstableCacheRevalidationMode;
 };
 /**
@@ -250,6 +311,7 @@ declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
  * @internal
  */
 declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
+declare function _peekUnstableCacheObservations(): UnstableCacheObservation[];
 /**
  * Cache life configuration. Controls stale-while-revalidate behavior.
  */
@@ -307,5 +369,4 @@ type UnstableCacheOptions = {
  */
 declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, getAndClearActionRevalidationKind, getCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
-//# sourceMappingURL=cache.d.ts.map
+export { ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cache.js

@@ -7,6 +7,7 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { readCacheControlNumberField } from "../utils/cache-control-metadata.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
+import { getCdnCacheAdapter } from "./cdn-cache.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -19,12 +20,14 @@ import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
 * existing community adapters (@neshca/cache-handler, @opennextjs/aws, etc.)
 * can be used directly.
 *
-* Configuration (in vite.config.ts or next.config.js):
-*   vinext({ cacheHandler: './my-cache-handler.ts' })
+* Recommended configuration is declarative, via the `cache` option on the
+* `vinext()` plugin in vite.config.ts:
+*   import { kvDataAdapter } from '@vinext/cloudflare/cache/kv-data-adapter';
+*   vinext({ cache: { data: kvDataAdapter({ binding: 'VINEXT_KV_CACHE' }) } })
 *
-* Or set at runtime:
-*   import { setCacheHandler } from 'next/cache';
-*   setCacheHandler(new MyCacheHandler());
+* The imperative `setCacheHandler` / `setDataCacheHandler` setters are
+* deprecated for consumers and retained only as the internal registration
+* target used by the generated cache-adapter module.
 */
 /** @internal Set by cache-runtime.ts on import to avoid circular dependency */
 let _getCacheContextFn = null;
@@ -42,21 +45,86 @@ var NoOpCacheHandler = class {
 	async set(_key, _data, _ctx) {}
 	async revalidateTag(_tags, _durations) {}
 };
+const DEFAULT_MEMORY_CACHE_MAX_SIZE = 50 * 1024 * 1024;
+const MAX_REVALIDATED_TAG_ENTRIES = 1e4;
+function estimateStringMapSize(map) {
+	if (!map) return 0;
+	let size = 0;
+	for (const [key, value] of Object.entries(map)) {
+		size += key.length;
+		if (Array.isArray(value)) for (const item of value) size += item.length;
+		else size += value.length;
+	}
+	return size;
+}
+function estimateIncrementalCacheValueSize(value) {
+	if (value === null) return 25;
+	switch (value.kind) {
+		case "FETCH": return JSON.stringify(value.data ?? "").length;
+		case "PAGES": return value.html.length + JSON.stringify(value.pageData ?? {}).length + estimateStringMapSize(value.headers);
+		case "APP_PAGE": return value.html.length + (value.rscData?.byteLength ?? 0) + (value.postponed?.length ?? 0) + estimateStringMapSize(value.headers);
+		case "APP_ROUTE": return value.body.byteLength + estimateStringMapSize(value.headers);
+		case "REDIRECT": return JSON.stringify(value.props ?? {}).length;
+		case "IMAGE": return value.buffer.byteLength + value.extension.length + value.etag.length;
+		default: return JSON.stringify(value).length;
+	}
+}
+function resolveMemoryCacheMaxSize(options) {
+	if (typeof options === "number") return options;
+	if (typeof options?.cacheMaxMemorySize === "number") return options.cacheMaxMemorySize;
+	if (typeof options?.maxMemoryCacheSize === "number") return options.maxMemoryCacheSize;
+	return DEFAULT_MEMORY_CACHE_MAX_SIZE;
+}
 function readStringArrayField(ctx, field) {
 	const value = ctx?.[field];
 	if (!Array.isArray(value)) return [];
 	return value.filter((item) => typeof item === "string");
 }
+/**
+* In-memory data cache handler. This is the built-in default — vinext installs
+* it automatically, so consumers should not construct or register it by hand.
+*
+* @deprecated Consumers should not instantiate cache handlers directly.
+* Configure caching declaratively via the `cache` option on the `vinext()`
+* plugin (see {@link setDataCacheHandler}); the in-memory handler is the
+* default when nothing is configured, and its size is tuned via the
+* `cacheMaxMemorySize` plugin option.
+*/
 var MemoryCacheHandler = class {
 	store = /* @__PURE__ */ new Map();
 	tagRevalidatedAt = /* @__PURE__ */ new Map();
+	maxMemoryCacheSize;
+	currentMemoryCacheSize = 0;
+	constructor(options) {
+		this.maxMemoryCacheSize = resolveMemoryCacheMaxSize(options);
+	}
+	estimateEntrySize(entry) {
+		return estimateIncrementalCacheValueSize(entry.value) + entry.tags.reduce((sum, tag) => sum + tag.length, 0) + 64;
+	}
+	deleteEntry(key) {
+		const existing = this.store.get(key);
+		if (!existing) return;
+		this.currentMemoryCacheSize -= this.estimateEntrySize(existing);
+		this.store.delete(key);
+	}
+	touchEntry(key, entry) {
+		this.store.delete(key);
+		this.store.set(key, entry);
+	}
+	evictLeastRecentlyUsed() {
+		while (this.maxMemoryCacheSize > 0 && this.currentMemoryCacheSize > this.maxMemoryCacheSize) {
+			const oldestKey = this.store.keys().next().value;
+			if (oldestKey === void 0) return;
+			this.deleteEntry(oldestKey);
+		}
+	}
 	async get(key, _ctx) {
 		const entry = this.store.get(key);
 		if (!entry) return null;
 		for (const tag of entry.tags) {
 			const revalidatedAt = this.tagRevalidatedAt.get(tag);
 			if (revalidatedAt && revalidatedAt >= entry.lastModified) {
-				this.store.delete(key);
+				this.deleteEntry(key);
 				return null;
 			}
 		}
@@ -65,9 +133,10 @@ var MemoryCacheHandler = class {
 			if (revalidatedAt && revalidatedAt >= entry.lastModified) return null;
 		}
 		if (entry.expireAt !== null && Date.now() > entry.expireAt) {
-			this.store.delete(key);
+			this.deleteEntry(key);
 			return null;
 		}
+		this.touchEntry(key, entry);
 		if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) return {
 			lastModified: entry.lastModified,
 			value: entry.value,
@@ -98,19 +167,36 @@ var MemoryCacheHandler = class {
 			revalidate: effectiveRevalidate,
 			expire: effectiveExpire
 		} : void 0;
-		this.store.set(key, {
+		if (this.maxMemoryCacheSize === 0) return;
+		const entry = {
 			value: data,
 			tags,
 			lastModified: now,
 			revalidateAt,
 			expireAt,
 			cacheControl
-		});
+		};
+		const entrySize = this.estimateEntrySize(entry);
+		if (entrySize > this.maxMemoryCacheSize) {
+			this.deleteEntry(key);
+			return;
+		}
+		this.deleteEntry(key);
+		this.store.set(key, entry);
+		this.currentMemoryCacheSize += entrySize;
+		this.evictLeastRecentlyUsed();
 	}
 	async revalidateTag(tags, _durations) {
 		const tagList = Array.isArray(tags) ? tags : [tags];
 		const now = Date.now();
-		for (const tag of tagList) this.tagRevalidatedAt.set(tag, now);
+		for (const tag of tagList) {
+			this.tagRevalidatedAt.set(tag, now);
+			while (this.tagRevalidatedAt.size > MAX_REVALIDATED_TAG_ENTRIES) {
+				const oldest = this.tagRevalidatedAt.keys().next().value;
+				if (oldest === void 0) break;
+				this.tagRevalidatedAt.delete(oldest);
+			}
+		}
 	}
 	resetRequestCache() {}
 };
@@ -119,23 +205,64 @@ const _gHandler = globalThis;
 function _getActiveHandler() {
 	return _gHandler[_HANDLER_KEY] ?? (_gHandler[_HANDLER_KEY] = new MemoryCacheHandler());
 }
+function configureMemoryCacheHandler(options) {
+	const current = _gHandler[_HANDLER_KEY];
+	if (current && !(current instanceof MemoryCacheHandler)) return;
+	_gHandler[_HANDLER_KEY] = new MemoryCacheHandler(options);
+}
 /**
-* Set a custom CacheHandler. Call this during server startup to
-* plug in Cloudflare KV, Redis, DynamoDB, or any other backend.
-*
-* The handler must implement the CacheHandler interface (same shape
-* as Next.js 16's CacheHandler class).
+* Set the **data cache** handler. This backs all data-cache concerns —
+* `fetch` caching, `"use cache"`, `unstable_cache` — and is also the default
+* underlying store for page-level ISR (via the default CDN cache adapter).
+*
+* The handler must implement the CacheHandler interface (same shape as
+* Next.js 16's CacheHandler class).
+*
+* @deprecated Don't wire up the data cache imperatively. Configure it
+* declaratively via the `cache.data` option on the `vinext()` plugin in your
+* `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+*
+* ```ts
+* import { vinext } from "vinext";
+* import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+*
+* export default defineConfig({
+*   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+* });
+* ```
+*
+* The plugin defers instantiation to the first request and registers the
+* handler across every runtime/router entry, so you don't have to call this
+* from a worker entry. This setter remains as the internal registration target
+* and for backwards compatibility, but is not the recommended consumer API.
 */
-function setCacheHandler(handler) {
+function setDataCacheHandler(handler) {
 	_gHandler[_HANDLER_KEY] = handler;
 }
 /**
-* Get the active CacheHandler (for internal use or testing).
+* Get the active data cache handler (for internal use or testing).
 */
-function getCacheHandler() {
+function getDataCacheHandler() {
 	return _getActiveHandler();
 }
 /**
+* @deprecated Don't wire up the data cache imperatively. Configure it
+* declaratively via the `cache.data` option on the `vinext()` plugin (e.g.
+* `kvDataAdapter()` from `@vinext/cloudflare/cache/kv-data-adapter`). See
+* {@link setDataCacheHandler} for the migration example. Retained as a
+* backwards-compatible alias — `setCacheHandler` has always configured the
+* data cache handler.
+*/
+function setCacheHandler(handler) {
+	setDataCacheHandler(handler);
+}
+/**
+* @deprecated Prefer {@link getDataCacheHandler}.
+*/
+function getCacheHandler() {
+	return getDataCacheHandler();
+}
+/**
 * Revalidate cached data associated with a specific cache tag.
 *
 * Works with both `fetch(..., { next: { tags: ['myTag'] } })` and
@@ -155,7 +282,20 @@ async function revalidateTag(tag, profile) {
 		if (resolved) durations = { expire: resolved.expire };
 	} else if (profile && typeof profile === "object") durations = profile;
 	if (!profile || !durations || durations.expire === 0) markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag), durations);
+	await _invalidateEncodedTag(encodeCacheTag(tag), durations);
+}
+/**
+* Invalidate one already-encoded tag across both cache layers.
+*
+* Ordering is intentional and load-bearing: invalidate the data cache store
+* FIRST (covers fetch data, `"use cache"`, and page entries stored there by the
+* default CDN adapter), THEN ask the CDN adapter to purge its edge (a no-op for
+* the default adapter). Purging the edge before the store is invalidated would
+* let the edge re-fetch and re-cache stale data.
+*/
+async function _invalidateEncodedTag(encoded, durations) {
+	await _getActiveHandler().revalidateTag(encoded, durations);
+	await getCdnCacheAdapter().revalidateTag(encoded, durations);
 }
 /**
 * Revalidate cached data associated with a specific path.
@@ -175,8 +315,7 @@ async function revalidateTag(tag, profile) {
 async function revalidatePath(path, type) {
 	markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	const tag = type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`;
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag));
+	await _invalidateEncodedTag(encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`));
 }
 /**
 * No-op shim for API compatibility.
@@ -205,7 +344,7 @@ function refresh() {
 async function updateTag(tag) {
 	if (getHeadersAccessPhase() !== "action") throw new Error("updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag");
 	markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag));
+	await _invalidateEncodedTag(encodeCacheTag(tag));
 }
 /**
 * Opt out of static rendering and indicate a particular component should not be cached.
@@ -286,6 +425,7 @@ const _cacheAls = getOrCreateAls("vinext.cache.als");
 const _cacheFallbackState = _g[_FALLBACK_KEY] ??= {
 	actionRevalidationKind: 0,
 	requestScopedCacheLife: null,
+	unstableCacheObservations: /* @__PURE__ */ new Map(),
 	unstableCacheRevalidation: "foreground"
 };
 const ACTION_DID_NOT_REVALIDATE = 0;
@@ -299,11 +439,13 @@ function _runWithCacheState(fn) {
 	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((uCtx) => {
 		uCtx.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
 		uCtx.requestScopedCacheLife = null;
+		uCtx.unstableCacheObservations = /* @__PURE__ */ new Map();
 		uCtx.unstableCacheRevalidation = "foreground";
 	}, fn);
 	const state = {
 		actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
 		requestScopedCacheLife: null,
+		unstableCacheObservations: /* @__PURE__ */ new Map(),
 		unstableCacheRevalidation: "foreground"
 	};
 	return _cacheAls.run(state, fn);
@@ -317,6 +459,7 @@ function _initRequestScopedCacheState() {
 	const state = _getCacheState();
 	state.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
 	state.requestScopedCacheLife = null;
+	state.unstableCacheObservations = /* @__PURE__ */ new Map();
 }
 function markActionRevalidation(kind) {
 	if (getHeadersAccessPhase() !== "action") return;
@@ -363,6 +506,12 @@ function _consumeRequestScopedCacheLife() {
 	state.requestScopedCacheLife = null;
 	return config;
 }
+function recordUnstableCacheObservation(observation) {
+	_getCacheState().unstableCacheObservations.set(observation.keyHash, observation);
+}
+function _peekUnstableCacheObservations() {
+	return [..._getCacheState().unstableCacheObservations.values()].sort((a, b) => a.keyHash.localeCompare(b.keyHash));
+}
 /**
 * Built-in cache life profiles matching Next.js 16.
 */
@@ -590,6 +739,13 @@ function unstable_cache(fn, keyParts, options) {
 	const revalidateSeconds = options?.revalidate;
 	const cachedFn = async (...args) => {
 		const cacheKey = `unstable_cache:${baseKey}:${JSON.stringify(args)}`;
+		recordUnstableCacheObservation({
+			kind: "unstable_cache",
+			keyHash: fnv1a64(cacheKey),
+			revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : revalidateSeconds === false ? false : null,
+			tagCount: tags.length,
+			tagHash: tags.length > 0 ? fnv1a64(JSON.stringify(tags)) : null
+		});
 		const existing = await _getActiveHandler().get(cacheKey, {
 			kind: "FETCH",
 			tags
@@ -608,6 +764,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, getAndClearActionRevalidationKind, getCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
-
-//# sourceMappingURL=cache.js.map
+export { MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

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

@@ -0,0 +1,125 @@
+import { CacheHandlerValue, IncrementalCacheValue } from "./cache.js";
+
+//#region src/shims/cdn-cache.d.ts
+/** A map of response header name -> value the adapter wants applied. */
+type CdnResponseHeaders = Record<string, string>;
+type CdnCacheableHeaderInput = {
+  /**
+   * The cacheable `Cache-Control` value the framework computed for shared
+   * caches (e.g. `s-maxage=60, stale-while-revalidate`). May be an empty string
+   * when no cacheable policy applies.
+   */
+  cacheControl: string;
+  /**
+   * True when this is a freshly-rendered **streaming** response whose
+   * dynamic-ness is not yet proven (late Server Component request-API usage can
+   * only be detected after the stream drains).
+   *
+   * The default adapter forces `no-store` for the browser in this case — the
+   * page is instead served from the origin store on subsequent requests. Edge
+   * adapters may instead emit edge-only cache headers (e.g. `CDN-Cache-Control`)
+   * so the CDN performs SWR while the browser still sees `no-store`.
+   */
+  pendingDynamicCheck?: boolean;
+  /**
+   * The cache tags associated with this page/route, already canonicalised
+   * (e.g. via `encodeCacheTag`). Edge adapters use these to emit a tag header
+   * (e.g. a `Cache-Tag` header) so tag-based purging can target the response.
+   * The default adapter ignores them.
+   */
+  tags?: readonly string[];
+};
+/**
+ * The serving strategy for page-level ISR. Implement this to delegate
+ * page/route/image caching to a CDN edge instead of the origin store.
+ */
+type CdnCacheAdapter = {
+  /**
+   * Read a page-level artifact. Returning a value lets the origin serve it
+   * (HIT/STALE); returning `null` makes the origin render fresh.
+   *
+   * Default: reads the data cache. Edge adapters typically return `null` so the
+   * edge owns serving.
+   */
+  get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+  /**
+   * Persist a freshly-rendered page-level artifact.
+   *
+   * Default: writes to the data cache. Edge adapters that rely entirely on the
+   * CDN may make this a no-op.
+   */
+  set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+  /**
+   * Build the response cache headers for a given cacheable policy. Returns a map
+   * so an adapter can emit more than one header (e.g. `Cache-Control` +
+   * `CDN-Cache-Control`).
+   */
+  buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  /**
+   * Whether the **origin** runs in-process background regeneration when a stale
+   * entry is served. Edge adapters set this to `false` because the CDN
+   * revalidates by re-requesting the origin.
+   */
+  readonly ownsBackgroundRevalidation: boolean;
+  /**
+   * Propagate a tag/path invalidation to the CDN edge (purge). Called *in
+   * addition to* the data cache's own tag invalidation, so the default
+   * implementation is a no-op (the data cache already invalidated its entries).
+   *
+   * Edge adapters implement this to purge the edge cache — typically firing the
+   * purge through the request execution context (`ctx.waitUntil`).
+   */
+  revalidateTag(tags: string | string[], durations?: {
+    expire?: number;
+  }): Promise<void>;
+};
+/**
+ * Default origin-managed ISR strategy: store page artifacts in the data cache,
+ * serve HIT/STALE from it, run in-process background regeneration, and emit the
+ * framework's standard `Cache-Control` headers.
+ */
+declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+  readonly ownsBackgroundRevalidation = true;
+  get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+  set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+  buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  revalidateTag(_tags: string | string[], _durations?: {
+    expire?: number;
+  }): Promise<void>;
+}
+/**
+ * Set a custom CDN cache adapter to delegate page-level ISR to a CDN edge. An
+ * explicit adapter always wins over the built-in request-context / default
+ * selection.
+ *
+ * @deprecated Don't wire up the CDN cache adapter imperatively. Configure it
+ * declaratively via the `cache.cdn` option on the `vinext()` plugin in your
+ * `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+ *
+ * ```ts
+ * import { vinext } from "vinext";
+ * import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+ *
+ * export default defineConfig({
+ *   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+ * });
+ * ```
+ *
+ * The plugin registers the adapter across every runtime/router entry, so you
+ * don't have to call this from a worker entry. This setter remains as the
+ * internal registration target and for backwards compatibility, but is not the
+ * recommended consumer API.
+ */
+declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
+/**
+ * Get the active CDN cache adapter. See the precedence note above:
+ * explicit (or an already-resolved auto-detected edge adapter) → origin-managed
+ * {@link DefaultCdnCacheAdapter}.
+ *
+ * Auto-detection of the Cloudflare Workers Cache (`ctx.cache`) only runs when
+ * `VINEXT_CDN_CACHE_AUTO_DETECT === "1"`; otherwise the default adapter is used
+ * unless an adapter was set explicitly.
+ */
+declare function getCdnCacheAdapter(): CdnCacheAdapter;
+//#endregion
+export { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders, DefaultCdnCacheAdapter, getCdnCacheAdapter, setCdnCacheAdapter };