@vinext/cloudflare 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/images/images-optimizer.d.ts

@@ -1,7 +1,8 @@
 //#region src/images/images-optimizer.d.ts
 /** Options accepted by {@link imagesOptimizer}, forwarded to the runtime factory. */
-type ImagesOptimizerOptions = {
-  /** Cloudflare Images binding name on the Worker `env`. @default "IMAGES" */binding?: string;
+export type ImagesOptimizerOptions = {
+  /** Cloudflare Images binding name on the Worker `env`. @default "IMAGES" */
+  binding?: string;
 };
 /**
  * Config-time builder: returns a serializable descriptor whose `adapter` is the
@@ -20,9 +21,8 @@ type ImagesOptimizerOptions = {
  *   plugins: [vinext({ images: { optimizer: imagesOptimizer() } })],
  * });
  */
-declare function imagesOptimizer(options?: ImagesOptimizerOptions): {
+export declare function imagesOptimizer(options?: ImagesOptimizerOptions): {
   adapter: string;
   options: ImagesOptimizerOptions | undefined;
 };
-//#endregion
-export { ImagesOptimizerOptions, imagesOptimizer };
+//#endregion

package/dist/images/images-optimizer.runtime.d.ts

@@ -1,14 +1,10 @@
 import { ImageOptimizer } from "vinext/server/image-optimization";
-
 //#region src/images/images-optimizer.runtime.d.ts
 /** Options accepted by the optimizer factory (mirrors `ImagesOptimizerOptions`). */
 type ImagesOptimizerOptions = {
   binding?: string;
 };
-declare const createCloudflareImageOptimizer: ({
-  env,
-  options
-}: {
+declare const createCloudflareImageOptimizer: ({ env, options }: {
   env?: Record<string, unknown>;
   options?: ImagesOptimizerOptions;
 }) => ImageOptimizer;

package/dist/prerender-kv-populate.d.ts

@@ -7,13 +7,13 @@
  * KVCacheEntry shape written by KVCacheHandler.set(), and returns Wrangler KV
  * bulk import records for deploy-time upload.
  */
-type KVBulkPair = {
+export type KVBulkPair = {
   key: string;
   value: string;
   expiration_ttl?: number;
   metadata?: Record<string, unknown>;
 };
-declare function buildPrerenderKVPairs(serverDir: string, options?: {
+export declare function buildPrerenderKVPairs(serverDir: string, options?: {
   appPrefix?: string;
   now?: number;
   ttlSeconds?: number;
@@ -21,5 +21,4 @@ declare function buildPrerenderKVPairs(serverDir: string, options?: {
   routeCount: number;
   pairs: KVBulkPair[];
 };
-//#endregion
-export { KVBulkPair, buildPrerenderKVPairs };
+//#endregion

package/dist/prerender-kv-populate.js

@@ -1,11 +1,11 @@
-import { ENTRY_PREFIX } from "./cache/kv-data-adapter.runtime.js";
-import path from "node:path";
+import { createKvKeySpace } from "./cache/kv-key.js";
 import fs from "node:fs";
-import { getRenderedAppRoutes, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
+import path from "node:path";
+import { getRenderedAppRoutes, getRenderedMetadataRoutes, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
 import { appIsrCacheKey } from "vinext/internal/server/isr-cache";
-import { buildAppPageCacheTags } from "vinext/internal/server/app-page-cache";
+import { buildAppPageCacheTags, buildAppRouteCacheTags } from "vinext/internal/server/app-page-cache";
 import { normalizePregeneratedPathname } from "vinext/internal/server/pregenerated-concrete-paths";
-import { getOutputPath, getRscOutputPath } from "vinext/internal/utils/prerender-output-paths";
+import { getAppRouteOutputPath, getOutputPath, getRscOutputPath } from "vinext/internal/utils/prerender-output-paths";
 //#region src/prerender-kv-populate.ts
 /**
 * Deploy-time KV population for App Router prerendered artifacts.
@@ -16,7 +16,7 @@ import { getOutputPath, getRscOutputPath } from "vinext/internal/utils/prerender
 * bulk import records for deploy-time upload.
 */
 /** Default KV expiration TTL used by KVCacheHandler for revalidating entries. */
-const DEFAULT_KV_TTL_SECONDS = 720 * 3600;
+const DEFAULT_KV_TTL_SECONDS = 2592e3;
 function resolveContainedFile(rootDir, relativePath) {
 	const resolvedRoot = path.resolve(rootDir);
 	const resolvedFile = path.resolve(resolvedRoot, relativePath);
@@ -28,13 +28,11 @@ function formatUnknownError(error) {
 	if (error instanceof Error && error.message) return error.message;
 	return String(error);
 }
-function buildKVKey(appPrefix, cacheKey) {
-	return `${appPrefix ? `${appPrefix}:` : ""}${ENTRY_PREFIX}${cacheKey}`;
-}
-function buildCacheEntry(value, tags, now, revalidateSeconds, expireSeconds) {
-	const cacheControl = revalidateSeconds === void 0 ? void 0 : expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
+function buildCacheEntry(value, tags, now, revalidateSeconds, expireSeconds, staleSeconds) {
+	const cacheControl = revalidateSeconds === void 0 ? void 0 : {
 		revalidate: revalidateSeconds,
-		expire: expireSeconds
+		...expireSeconds === void 0 ? {} : { expire: expireSeconds },
+		...staleSeconds === void 0 ? {} : { stale: staleSeconds }
 	};
 	return JSON.stringify({
 		value,
@@ -50,7 +48,8 @@ function buildMetadata(tags) {
 	return JSON.stringify(metadata).length <= 1024 ? metadata : void 0;
 }
 function buildPrerenderKVPairs(serverDir, options) {
-	const manifest = readPrerenderManifest(path.join(serverDir, "vinext-prerender.json"));
+	const manifestPath = path.join(serverDir, "vinext-prerender.json");
+	const manifest = readPrerenderManifest(manifestPath);
 	if (!manifest?.buildId || !Array.isArray(manifest.routes)) return {
 		routeCount: 0,
 		pairs: []
@@ -64,6 +63,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 	const now = options?.now ?? Date.now();
 	const ttlSeconds = options?.ttlSeconds ?? DEFAULT_KV_TTL_SECONDS;
 	const trailingSlash = manifest.trailingSlash ?? false;
+	const keySpace = createKvKeySpace(options?.appPrefix);
 	let routeCount = 0;
 	for (const route of getRenderedAppRoutes(manifest.routes)) {
 		const artifactPathname = route.path ?? route.route;
@@ -81,36 +81,69 @@ function buildPrerenderKVPairs(serverDir, options) {
 		if (typeof route.revalidate === "number" && route.revalidate <= 0) continue;
 		const revalidateSeconds = typeof route.revalidate === "number" ? route.revalidate : void 0;
 		const expireSeconds = typeof route.expire === "number" ? route.expire : void 0;
+		const staleSeconds = typeof route.stale === "number" && route.stale >= 0 ? route.stale : void 0;
 		const expirationTtl = revalidateSeconds === void 0 ? void 0 : ttlSeconds;
-		const tags = buildAppPageCacheTags(cachePathname, []);
+		const tags = buildAppPageCacheTags(cachePathname, route.tags ?? []);
 		const metadata = buildMetadata(tags);
 		const htmlKey = appIsrCacheKey(cachePathname, "html", manifest.buildId);
 		const rscKey = appIsrCacheKey(cachePathname, "rsc", manifest.buildId);
 		pairs.push({
-			key: buildKVKey(options?.appPrefix, htmlKey),
+			key: keySpace.entryKey(htmlKey),
 			value: buildCacheEntry({
 				kind: "APP_PAGE",
 				html: fs.readFileSync(htmlPath, "utf-8"),
 				headers: route.headers
-			}, tags, now, revalidateSeconds, expireSeconds),
+			}, tags, now, revalidateSeconds, expireSeconds, staleSeconds),
 			...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
 			...metadata ? { metadata } : {}
 		});
 		if (fs.existsSync(rscPath)) {
 			const rscData = fs.readFileSync(rscPath).toString("base64");
 			pairs.push({
-				key: buildKVKey(options?.appPrefix, rscKey),
+				key: keySpace.entryKey(rscKey),
 				value: buildCacheEntry({
 					kind: "APP_PAGE",
 					html: "",
 					rscData
-				}, tags, now, revalidateSeconds, expireSeconds),
+				}, tags, now, revalidateSeconds, expireSeconds, staleSeconds),
 				...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
 				...metadata ? { metadata } : {}
 			});
 		}
 		routeCount++;
 	}
+	for (const route of getRenderedMetadataRoutes(manifest.routes)) {
+		const pathname = route.path ?? route.route;
+		let artifactPath;
+		try {
+			artifactPath = resolveContainedFile(prerenderDir, getAppRouteOutputPath(pathname));
+		} catch (error) {
+			console.warn(`[vinext] Skipping metadata prerender KV seed for ${pathname}: ${formatUnknownError(error)}`);
+			continue;
+		}
+		if (!fs.existsSync(artifactPath)) continue;
+		const cachePathname = normalizePregeneratedPathname(pathname);
+		if (typeof route.revalidate === "number" && route.revalidate <= 0) continue;
+		const revalidateSeconds = typeof route.revalidate === "number" ? route.revalidate : void 0;
+		const expireSeconds = typeof route.expire === "number" ? route.expire : void 0;
+		const staleSeconds = typeof route.stale === "number" && route.stale >= 0 ? route.stale : void 0;
+		const expirationTtl = revalidateSeconds === void 0 ? void 0 : ttlSeconds;
+		const tags = buildAppRouteCacheTags(cachePathname, route.tags ?? [], route.routeSegments ?? []);
+		const metadata = buildMetadata(tags);
+		const routeKey = appIsrCacheKey(cachePathname, "route", manifest.buildId);
+		pairs.push({
+			key: keySpace.entryKey(routeKey),
+			value: buildCacheEntry({
+				kind: "APP_ROUTE",
+				body: fs.readFileSync(artifactPath).toString("base64"),
+				headers: route.headers ?? {},
+				status: route.responseStatus ?? 200
+			}, tags, now, revalidateSeconds, expireSeconds, staleSeconds),
+			...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
+			...metadata ? { metadata } : {}
+		});
+		routeCount++;
+	}
 	return {
 		routeCount,
 		pairs

package/dist/tpr.d.ts

@@ -1,61 +1,32 @@
+import { parseWranglerConfig } from "./wrangler-config.js";
 //#region src/tpr.d.ts
-/**
- * TPR: Traffic-aware Pre-Rendering
- *
- * Uses Cloudflare zone analytics to determine which pages actually get
- * traffic, and pre-renders only those during deploy. The pre-rendered
- * HTML is uploaded to KV in the same format ISR uses at runtime — no
- * runtime changes needed.
- *
- * Flow:
- *   1. Parse wrangler config to find custom domain and KV namespace
- *   2. Resolve the Cloudflare zone for the custom domain
- *   3. Query zone analytics (GraphQL) for top pages by request count
- *   4. Walk ranked list until coverage threshold is met
- *   5. Start the built production server locally
- *   6. Fetch each hot route to produce HTML
- *   7. Upload pre-rendered HTML to KV (same KVCacheEntry format ISR reads)
- *
- * TPR is an experimental feature enabled via --experimental-tpr. It
- * gracefully skips when no custom domain, no API token, no traffic data,
- * or no KV namespace is configured.
- */
-type TPROptions = {
-  /** Project root directory. */root: string; /** Wrangler config path, relative to root unless absolute. */
-  config?: string; /** Traffic coverage percentage (0–100). Default: 90. */
-  coverage: number; /** Hard cap on number of pages to pre-render. Default: 1000. */
-  limit: number; /** Analytics lookback window in hours. Default: 24. */
+export type TPROptions = {
+  /** Project root directory. */
+  root: string;
+  /** Wrangler config path, relative to root unless absolute. */
+  config?: string;
+  /** Wrangler environment whose custom domain should be analyzed. */
+  env?: string;
+  /** Explicit domain used to resolve the analytics zone, overriding Wrangler routes. */
+  hostname?: string;
+  /** Analytics lookback window in hours. Default: 24. */
   window: number;
 };
-type TPRResult = {
-  /** Total unique page paths found in analytics. */totalPaths: number; /** Number of pages successfully pre-rendered and uploaded. */
-  prerenderedCount: number; /** Actual traffic coverage achieved (percentage). */
-  coverageAchieved: number; /** Wall-clock duration of the TPR step in milliseconds. */
-  durationMs: number; /** If TPR was skipped, the reason. */
+export type TPRRouteResult = {
+  routes: TrafficEntry[];
+  /** If TPR was skipped, the reason. */
   skipped?: string;
 };
-type PrerenderResult = {
-  html: string;
-  status: number;
-  headers: Record<string, string>;
+export type TrafficEntry = {
+  path: string;
+  requests: number;
 };
-type WranglerConfig = {
-  accountId?: string;
-  kvNamespaceId?: string;
-  customDomain?: string;
-  name?: string;
-  legacyEnv?: boolean;
-  env?: Record<string, WranglerEnvironmentConfig>;
+export type SelectedRoutes = {
+  routes: TrafficEntry[];
+  totalRequests: number;
+  coveredRequests: number;
+  coveragePercent: number;
 };
-type WranglerEnvironmentConfig = {
-  customDomain?: string;
-  name?: string;
-};
-/**
- * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
- * account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
- */
-declare function parseWranglerConfig(root: string, configPath?: string): WranglerConfig | null;
 /**
  * Generate zone lookup candidates from shortest (2-part) to longest.
  * Tries the most common case first (e.g., "example.com") and progressively
@@ -65,27 +36,18 @@ declare function parseWranglerConfig(root: string, configPath?: string): Wrangle
  * "shop.example.co.uk"  → ["co.uk", "example.co.uk", "shop.example.co.uk"]
  * "example.com"         → ["example.com"]
  */
-declare function domainCandidates(domain: string): string[];
-declare function resolveVinextProdServerPath(root: string): string;
+export declare function domainCandidates(domain: string): string[];
+/** Filter out non-page requests (static assets, API routes, internal routes). */
+export declare function filterTrafficPaths(entries: TrafficEntry[]): TrafficEntry[];
 /**
- * Build KV bulk API pairs from pre-rendered entries.
- *
- * Key format matches the runtime KVCacheHandler exactly:
- *   ENTRY_PREFIX + isrCacheKey("app", pathname, buildId) + ":html"
- *   → "cache:app:<buildId>:<pathname>:html"
+ * Walk the ranked traffic list, accumulating request counts until the
+ * coverage target is met or the hard cap is reached.
  */
-declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId: string | undefined, defaultRevalidateSeconds: number): Array<{
-  key: string;
-  value: string;
-  expiration_ttl: number;
-}>;
+export declare function selectRoutes(traffic: TrafficEntry[], coverageTarget: number, limit: number): SelectedRoutes;
 /**
- * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
- *
- * Designed to be called between the build step and wrangler deploy in the
- * `vinext-cloudflare deploy` pipeline. Gracefully skips (never errors) when
- * the prerequisites aren't met.
+ * Resolve ranked traffic paths. The standard CDN pre-warming flow owns route
+ * matching, coverage selection, rendering, and cache admission.
  */
-declare function runTPR(options: TPROptions): Promise<TPRResult>;
+export declare function resolveTPRRoutes(options: TPROptions): Promise<TPRRouteResult>;
 //#endregion
-export { TPROptions, TPRResult, WranglerEnvironmentConfig, buildTprKVPairs, domainCandidates, parseWranglerConfig, resolveVinextProdServerPath, runTPR };
+export { parseWranglerConfig };