@qzsy/vinext 0.1.7

package/dist/shims/cache-handler.js

@@ -0,0 +1,176 @@
+import { readCacheControlNumberField } from "../utils/cache-control-metadata.js";
+//#region src/shims/cache-handler.ts
+var NoOpCacheHandler = class {
+	async get(_key, _ctx) {
+		return null;
+	}
+	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");
+}
+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.deleteEntry(key);
+				return null;
+			}
+		}
+		for (const tag of readStringArrayField(ctx, "softTags")) {
+			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);
+		if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) return {
+			lastModified: entry.lastModified,
+			value: entry.value,
+			cacheState: "stale",
+			cacheControl: entry.cacheControl
+		};
+		return {
+			lastModified: entry.lastModified,
+			value: entry.value,
+			cacheControl: entry.cacheControl
+		};
+	}
+	async set(key, data, ctx) {
+		const tagSet = /* @__PURE__ */ new Set();
+		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");
+		const effectiveExpire = readCacheControlNumberField(ctx, "expire");
+		if (data && "revalidate" in data && typeof data.revalidate === "number") effectiveRevalidate = data.revalidate;
+		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 } : {
+			revalidate: effectiveRevalidate,
+			expire: effectiveExpire
+		} : void 0;
+		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) {
+		const tagList = Array.isArray(tags) ? tags : [tags];
+		const now = Date.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() {}
+};
+const HANDLER_KEY = Symbol.for("vinext.cacheHandler");
+const globalHandlers = globalThis;
+function getActiveHandler() {
+	return globalHandlers[HANDLER_KEY] ?? (globalHandlers[HANDLER_KEY] = new MemoryCacheHandler());
+}
+function configureMemoryCacheHandler(options) {
+	const current = globalHandlers[HANDLER_KEY];
+	if (current && !(current instanceof MemoryCacheHandler)) return;
+	globalHandlers[HANDLER_KEY] = new MemoryCacheHandler(options);
+}
+function setDataCacheHandler(handler) {
+	globalHandlers[HANDLER_KEY] = handler;
+}
+function getDataCacheHandler() {
+	return getActiveHandler();
+}
+function setCacheHandler(handler) {
+	setDataCacheHandler(handler);
+}
+function getCacheHandler() {
+	return getDataCacheHandler();
+}
+//#endregion
+export { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler };

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

@@ -0,0 +1,47 @@
+//#region src/shims/cache-request-state.d.ts
+type CacheLifeConfig = {
+  stale?: number;
+  revalidate?: number;
+  expire?: number;
+};
+declare const cacheLifeProfiles: Record<string, CacheLifeConfig>;
+type CacheContextLike = {
+  tags: string[];
+  lifeConfigs: CacheLifeConfig[];
+  variant: string;
+  hasExplicitRevalidate: boolean;
+  hasExplicitExpire: boolean;
+  dynamicNestedCacheError: Error | undefined;
+};
+declare function _registerCacheContextAccessor(fn: () => CacheContextLike | null): void;
+declare function getRegisteredCacheContext(): CacheContextLike | null;
+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;
+};
+declare const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
+declare const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
+declare function _runWithCacheState<T>(fn: () => Promise<T>): Promise<T>;
+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;
+declare function _setRequestScopedCacheLife(config: CacheLifeConfig): void;
+declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
+declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
+declare function recordUnstableCacheObservation(observation: UnstableCacheObservation): void;
+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 };

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

@@ -0,0 +1,126 @@
+import { getOrCreateAls } from "./internal/als-registry.js";
+import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
+import { getHeadersAccessPhase } from "./headers.js";
+//#region src/shims/cache-request-state.ts
+const cacheLifeProfiles = {
+	default: {
+		revalidate: 900,
+		expire: 4294967294
+	},
+	seconds: {
+		stale: 30,
+		revalidate: 1,
+		expire: 60
+	},
+	minutes: {
+		stale: 300,
+		revalidate: 60,
+		expire: 3600
+	},
+	hours: {
+		stale: 300,
+		revalidate: 3600,
+		expire: 86400
+	},
+	days: {
+		stale: 300,
+		revalidate: 86400,
+		expire: 604800
+	},
+	weeks: {
+		stale: 300,
+		revalidate: 604800,
+		expire: 2592e3
+	},
+	max: {
+		stale: 300,
+		revalidate: 2592e3,
+		expire: 31536e3
+	}
+};
+let getCacheContext = null;
+function _registerCacheContextAccessor(fn) {
+	getCacheContext = fn;
+}
+function getRegisteredCacheContext() {
+	return getCacheContext?.() ?? null;
+}
+const FALLBACK_KEY = Symbol.for("vinext.cache.fallback");
+const globalState = globalThis;
+const cacheAls = getOrCreateAls("vinext.cache.als");
+const ACTION_DID_NOT_REVALIDATE = 0;
+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,
+	requestScopedCacheLife: null,
+	unstableCacheObservations: /* @__PURE__ */ new Map(),
+	unstableCacheRevalidation: "foreground"
+};
+function getCacheState() {
+	if (isInsideUnifiedScope()) return getRequestContext();
+	return cacheAls.getStore() ?? fallbackState;
+}
+function _runWithCacheState(fn) {
+	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((context) => {
+		context.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
+		context.requestScopedCacheLife = null;
+		context.unstableCacheObservations = /* @__PURE__ */ new Map();
+		context.unstableCacheRevalidation = "foreground";
+	}, fn);
+	const state = {
+		actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+		requestScopedCacheLife: null,
+		unstableCacheObservations: /* @__PURE__ */ new Map(),
+		unstableCacheRevalidation: "foreground"
+	};
+	return cacheAls.run(state, fn);
+}
+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;
+	const state = getCacheState();
+	state.actionRevalidationKind = state.actionRevalidationKind === 1 ? 1 : kind;
+}
+function getAndClearActionRevalidationKind() {
+	const state = getCacheState();
+	const kind = state.actionRevalidationKind;
+	state.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
+	return kind;
+}
+function _setRequestScopedCacheLife(config) {
+	const state = getCacheState();
+	if (state.requestScopedCacheLife === null) {
+		state.requestScopedCacheLife = { ...config };
+		return;
+	}
+	if (config.stale !== void 0) state.requestScopedCacheLife.stale = state.requestScopedCacheLife.stale !== void 0 ? Math.min(state.requestScopedCacheLife.stale, config.stale) : config.stale;
+	if (config.revalidate !== void 0) state.requestScopedCacheLife.revalidate = state.requestScopedCacheLife.revalidate !== void 0 ? Math.min(state.requestScopedCacheLife.revalidate, config.revalidate) : config.revalidate;
+	if (config.expire !== void 0) state.requestScopedCacheLife.expire = state.requestScopedCacheLife.expire !== void 0 ? Math.min(state.requestScopedCacheLife.expire, config.expire) : config.expire;
+}
+function _peekRequestScopedCacheLife() {
+	const config = getCacheState().requestScopedCacheLife;
+	return config === null ? null : { ...config };
+}
+function _consumeRequestScopedCacheLife() {
+	const state = getCacheState();
+	const config = state.requestScopedCacheLife;
+	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));
+}
+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 };

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

@@ -0,0 +1,83 @@
+import { CacheLifeConfig } from "./cache-request-state.js";
+import { markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
+
+//#region src/shims/cache-runtime.d.ts
+/**
+ * Used purely as `cause` for the nested-dynamic cache error: its captured stack
+ * points at the inner "use cache" invocation that propagated a dynamic cache
+ * life up to the outer cache. Constructed eagerly while the caller is still on
+ * the synchronous stack.
+ */
+declare class NestedDynamicUseCacheError extends Error {
+  constructor();
+}
+type CacheContext = {
+  /** Tags collected via cacheTag() during execution */tags: string[]; /** Cache life configs collected via cacheLife() — minimum-wins rule applies */
+  lifeConfigs: CacheLifeConfig[]; /** Cache variant: "default" | "remote" | "private" */
+  variant: string; /** Whether cacheLife() was called with an explicit revalidate value */
+  hasExplicitRevalidate: boolean; /** Whether cacheLife() was called with an explicit expire value */
+  hasExplicitExpire: boolean;
+  /**
+   * The first nested public "use cache" invocation with a dynamic cache life
+   * (revalidate === 0 or expire < DYNAMIC_EXPIRE) that propagated up to this
+   * cache. Used as `cause` for the nested-dynamic cache error.
+   */
+  dynamicNestedCacheError: Error | undefined;
+  /**
+   * Dynamic request API error recorded inside this cache scope. This persists
+   * even if user code catches the original throw, so the wrapper can avoid
+   * storing request-specific output under a shared cache key.
+   */
+  invalidDynamicUsageError?: unknown;
+};
+declare const cacheContextStorage: import("node:async_hooks").AsyncLocalStorage<CacheContext>;
+/**
+ * Get the current cache context. Returns null if not inside a "use cache" function.
+ */
+declare function getCacheContext(): CacheContext | null;
+/**
+ * Convert an encodeReply result (string | FormData) to a cache key string.
+ * For FormData (binary args), produces a deterministic SHA-256 hash over
+ * the sorted entries. We can't hash `new Response(formData).arrayBuffer()`
+ * because multipart boundaries are non-deterministic across serializations.
+ *
+ * Exported for testing.
+ */
+declare function replyToCacheKey(reply: string | FormData): Promise<string>;
+type PrivateCacheState = {
+  _privateCache: Map<string, unknown> | null;
+};
+/**
+ * Run a function within a private cache ALS scope.
+ * Ensures per-request isolation for "use cache: private" entries
+ * on concurrent runtimes.
+ */
+declare function runWithPrivateCache<T>(fn: () => Promise<T>): Promise<T>;
+declare function runWithPrivateCache<T>(fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Clear the private per-request cache. Should be called at the start of each request.
+ * Only needed when not using runWithPrivateCache() (legacy path).
+ */
+declare function clearPrivateCache(): void;
+type RegisterCachedFunctionOptions = {
+  /**
+   * Internal transform metadata for file-level `"use cache"` default exports
+   * in App Router `page.*` files. Page components receive framework-owned
+   * `{ params, searchParams }` props. React may copy that props object before
+   * invocation, so this invariant must live at the cached function boundary
+   * rather than on the intermediate createElement config object.
+   */
+  appPageDefaultExport?: boolean;
+};
+/**
+ * Register a function as a cached function. This is called by the Vite
+ * transform for each "use cache" function.
+ *
+ * @param fn - The original async function
+ * @param id - A stable identifier for the function (module path + export name)
+ * @param variant - Cache variant: "" (default/shared), "remote", "private"
+ * @returns A wrapper function that checks cache before calling the original
+ */
+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 };