@vinext/cloudflare 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/cache/cdn-adapter.runtime.d.ts

@@ -1,6 +1,5 @@
 import { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders } from "vinext/shims/cdn-cache";
 import { CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
-
 //#region src/cache/cdn-adapter.runtime.d.ts
 declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   readonly ownsBackgroundRevalidation = false;

package/dist/cache/kv-data-adapter.d.ts

@@ -2,9 +2,13 @@
 declare const DEFAULT_KV_DATA_CACHE_BINDING = "VINEXT_KV_CACHE";
 /** Options accepted by {@link kvDataAdapter}, forwarded to the runtime factory. */
 type KvDataAdapterOptions = {
-  /** KV namespace binding name on the Worker `env`. @default "VINEXT_KV_CACHE" */binding?: string; /** Namespace prefix for cache keys (isolates multiple apps in one namespace). */
-  appPrefix?: string; /** Default KV `expirationTtl` in seconds. @default 2592000 (30 days) */
-  ttlSeconds?: number; /** TTL in milliseconds for the in-memory tag-invalidation cache. @default 5000 */
+  /** KV namespace binding name on the Worker `env`. @default "VINEXT_KV_CACHE" */
+  binding?: string;
+  /** Namespace prefix for cache keys (isolates multiple apps in one namespace). */
+  appPrefix?: string;
+  /** Default KV `expirationTtl` in seconds. @default 2592000 (30 days) */
+  ttlSeconds?: number;
+  /** TTL in milliseconds for the in-memory tag-invalidation cache. @default 5000 */
   tagCacheTtlMs?: number;
 };
 /**

package/dist/cache/kv-data-adapter.runtime.d.ts

@@ -2,7 +2,6 @@ import { KvDataAdapterOptions } from "./kv-data-adapter.js";
 import { ENTRY_PREFIX } from "./kv-key.js";
 import { ExecutionContextLike } from "vinext/shims/request-context";
 import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
-
 //#region src/cache/kv-data-adapter.runtime.d.ts
 type KVNamespace = {
   get(key: string, options?: {
@@ -62,7 +61,8 @@ declare class KVCacheHandler implements CacheHandler {
   constructor(kvNamespace: KVNamespace, options?: {
     appPrefix?: string;
     ctx?: ExecutionContextLike;
-    ttlSeconds?: number; /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
+    ttlSeconds?: number;
+    /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
     tagCacheTtlMs?: number;
   });
   private _entryKey;
@@ -125,10 +125,7 @@ declare class KVCacheHandler implements CacheHandler {
    */
   private _put;
 }
-declare const createKvDataCacheAdapter: ({
-  env,
-  options
-}: {
+declare const createKvDataCacheAdapter: ({ env, options }: {
   env?: Record<string, unknown>;
   options?: KvDataAdapterOptions;
 }) => CacheHandler;

package/dist/cache/kv-data-adapter.runtime.js

@@ -213,14 +213,16 @@ var KVCacheHandler = class {
 		let effectiveExpire;
 		effectiveRevalidate = readCacheControlNumberField(ctx, "revalidate");
 		effectiveExpire = readCacheControlNumberField(ctx, "expire");
+		const effectiveStale = readCacheControlNumberField(ctx, "stale");
 		if (data && "revalidate" in data && typeof data.revalidate === "number") effectiveRevalidate = data.revalidate;
 		if (effectiveRevalidate === 0) return Promise.resolve();
 		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" ? {
 			revalidate: effectiveRevalidate,
-			expire: effectiveExpire
+			...effectiveExpire === void 0 ? {} : { expire: effectiveExpire },
+			...effectiveStale === void 0 ? {} : { stale: effectiveStale }
 		} : void 0;
 		const entry = {
 			value: data ? serializeForJSON(data) : null,
@@ -350,6 +352,7 @@ function validateCacheEntry(raw) {
 		if (!isUnknownRecord(obj.cacheControl)) return null;
 		if (typeof obj.cacheControl.revalidate !== "number") return null;
 		if (obj.cacheControl.expire !== void 0 && typeof obj.cacheControl.expire !== "number") return null;
+		if (obj.cacheControl.stale !== void 0 && typeof obj.cacheControl.stale !== "number") return null;
 	}
 	if (obj.value !== null) {
 		if (!obj.value || typeof obj.value !== "object") return null;

package/dist/cache/kv-key.d.ts

@@ -2,7 +2,8 @@
 /** Key prefix for cache entries. */
 declare const ENTRY_PREFIX = "cache:";
 type KvKeySpace = {
-  /** Prefix shared by every cache entry, including entries with hashed logical keys. */entryPrefix: string;
+  /** Prefix shared by every cache entry, including entries with hashed logical keys. */
+  entryPrefix: string;
   entryKey(logicalKey: string): string;
   tagKey(tag: string): string;
 };

package/dist/cdn-warm.d.ts

@@ -1,5 +1,4 @@
 import { PrerenderManifest, PrerenderedPathSelectionOptions } from "vinext/internal/server/prerender-manifest";
-
 //#region src/cdn-warm.d.ts
 type CdnWarmOptions = {
   targetUrl: string;

package/dist/cli.d.ts

@@ -1 +1 @@
-export { };
+export {}

package/dist/deploy-config.d.ts

@@ -1,5 +1,4 @@
 import { VinextCacheConfig } from "vinext/internal/cache-adapters";
-
 //#region src/deploy-config.d.ts
 /**
  * Check whether an existing vite.config file already imports and uses the

package/dist/deploy.d.ts

@@ -2,27 +2,45 @@ import { parseWranglerConfig } from "./tpr.js";
 import { WranglerDeploymentStatus, WranglerVersionTraffic } from "./version-deploy.js";
 import { KVBulkPair } from "./prerender-kv-populate.js";
 import { spawn } from "node:child_process";
-
 //#region src/deploy.d.ts
 type DeployOptions = {
-  /** Project root directory */root: string; /** Deploy to preview environment (default: production) */
-  preview?: boolean; /** Wrangler environment name from wrangler.jsonc env.<name> */
-  env?: string; /** Custom project name for the Worker */
-  name?: string; /** Wrangler config path, relative to root unless absolute */
-  config?: string; /** Skip the build step (assume already built) */
-  skipBuild?: boolean; /** Dry run — validate setup but don't build or deploy */
-  dryRun?: boolean; /** Pre-render all discovered routes into the dist output after building */
-  prerenderAll?: boolean; /** Maximum number of routes to prerender in parallel */
-  prerenderConcurrency?: number; /** Warm Cloudflare's CDN cache by requesting build-discovered paths for the uploaded version */
-  warmCdnCache?: boolean; /** Maximum number of CDN warmup requests to issue in parallel */
-  warmCdnConcurrency?: number; /** Per-request CDN warmup timeout in milliseconds */
-  warmCdnTimeout?: number; /** Number of CDN warmup retries for transient failures */
-  warmCdnRetries?: number; /** Fail deployment if any CDN warmup request fails */
-  warmCdnStrict?: boolean; /** Include PPR fallback-shell placeholder paths during CDN warmup */
-  warmCdnIncludeFallbacks?: boolean; /** Enable experimental TPR (Traffic-aware Pre-Rendering) */
-  experimentalTPR?: boolean; /** TPR: traffic coverage percentage target (0–100, default: 90) */
-  tprCoverage?: number; /** TPR: hard cap on number of pages to pre-render (default: 1000) */
-  tprLimit?: number; /** TPR: analytics lookback window in hours (default: 24) */
+  /** Project root directory */
+  root: string;
+  /** Deploy to preview environment (default: production) */
+  preview?: boolean;
+  /** Wrangler environment name from wrangler.jsonc env.<name> */
+  env?: string;
+  /** Custom project name for the Worker */
+  name?: string;
+  /** Wrangler config path, relative to root unless absolute */
+  config?: string;
+  /** Skip the build step (assume already built) */
+  skipBuild?: boolean;
+  /** Dry run — validate setup but don't build or deploy */
+  dryRun?: boolean;
+  /** Pre-render all discovered routes into the dist output after building */
+  prerenderAll?: boolean;
+  /** Maximum number of routes to prerender in parallel */
+  prerenderConcurrency?: number;
+  /** Warm Cloudflare's CDN cache by requesting build-discovered paths for the uploaded version */
+  warmCdnCache?: boolean;
+  /** Maximum number of CDN warmup requests to issue in parallel */
+  warmCdnConcurrency?: number;
+  /** Per-request CDN warmup timeout in milliseconds */
+  warmCdnTimeout?: number;
+  /** Number of CDN warmup retries for transient failures */
+  warmCdnRetries?: number;
+  /** Fail deployment if any CDN warmup request fails */
+  warmCdnStrict?: boolean;
+  /** Include PPR fallback-shell placeholder paths during CDN warmup */
+  warmCdnIncludeFallbacks?: boolean;
+  /** Enable experimental TPR (Traffic-aware Pre-Rendering) */
+  experimentalTPR?: boolean;
+  /** TPR: traffic coverage percentage target (0–100, default: 90) */
+  tprCoverage?: number;
+  /** TPR: hard cap on number of pages to pre-render (default: 1000) */
+  tprLimit?: number;
+  /** TPR: analytics lookback window in hours (default: 24) */
   tprWindow?: number;
 };
 declare function parseDeployArgs(args: string[]): {

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;
+  /** Cloudflare Images binding name on the Worker `env`. @default "IMAGES" */
+  binding?: string;
 };
 /**
  * Config-time builder: returns a serializable descriptor whose `adapter` is the

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.js

@@ -28,10 +28,11 @@ function formatUnknownError(error) {
 	if (error instanceof Error && error.message) return error.message;
 	return String(error);
 }
-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,
@@ -79,8 +80,9 @@ 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);
@@ -90,7 +92,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 				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 } : {}
 		});
@@ -102,7 +104,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 					kind: "APP_PAGE",
 					html: "",
 					rscData
-				}, tags, now, revalidateSeconds, expireSeconds),
+				}, tags, now, revalidateSeconds, expireSeconds, staleSeconds),
 				...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
 				...metadata ? { metadata } : {}
 			});

package/dist/tpr.d.ts

@@ -21,17 +21,27 @@
  * 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. */
+  /** 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. */
   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. */
+  /** 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. */
   skipped?: string;
 };
 type PrerenderResult = {

package/dist/version-deploy.d.ts

@@ -1,7 +1,6 @@
 import { parseWorkersDevUrl } from "./workers-dev-url.js";
 import { DeployOptions } from "./deploy.js";
 import { execFileSync } from "node:child_process";
-
 //#region src/version-deploy.d.ts
 type WranglerVersionUploadResult = {
   versionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinext/cloudflare",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "Cloudflare adapters for vinext (KV data cache and Images-backed image optimization).",
   "license": "MIT",
   "repository": {
@@ -52,12 +52,12 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
-    "vite-plus": "0.2.2",
-    "vinext": "1.0.0-beta.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.6",
+    "vite-plus": "0.2.6",
+    "vinext": "1.0.0-beta.5"
   },
   "peerDependencies": {
-    "vinext": "^1.0.0-beta.3"
+    "vinext": "^1.0.0-beta.5"
   },
   "engines": {
     "node": ">=22"