@qzsy/vinext 0.1.7

package/dist/client/vinext-next-data.js

@@ -0,0 +1,50 @@
+import { isUnknownRecord } from "../utils/record.js";
+//#region src/client/vinext-next-data.ts
+function extractVinextNextDataJson(html) {
+	const canonical = /<script\b(?=[^>]*\bid=["']__NEXT_DATA__["'])(?=[^>]*\btype=["']application\/json["'])[^>]*>([\s\S]*?)<\/script>/.exec(html);
+	if (canonical) return canonical[1];
+	const assignment = /<script(?:\s[^>]*)?>\s*window\.__NEXT_DATA__\s*=\s*/.exec(html);
+	if (!assignment || assignment.index === void 0) return null;
+	let start = assignment.index + assignment[0].length;
+	while (html[start] === " " || html[start] === "\n" || html[start] === "	" || html[start] === "\r") start++;
+	if (html[start] !== "{") return null;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let index = start; index < html.length; index++) {
+		const char = html[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") inString = true;
+		else if (char === "{") depth++;
+		else if (char === "}") {
+			depth--;
+			if (depth === 0) return html.slice(start, index + 1);
+		}
+	}
+	return null;
+}
+function parseVinextNextDataJson(json) {
+	const parsed = JSON.parse(json);
+	if (!isBrowserVinextNextData(parsed)) throw new Error("Navigation failed: invalid __NEXT_DATA__ in response");
+	return parsed;
+}
+function isBrowserVinextNextData(value) {
+	if (!isUnknownRecord(value)) return false;
+	const props = value.props;
+	const page = value.page;
+	const query = value.query;
+	const vinext = value.__vinext;
+	return isUnknownRecord(props) && typeof page === "string" && isUnknownRecord(query) && (vinext === void 0 || isUnknownRecord(vinext));
+}
+function applyVinextLocaleGlobals(target, nextData) {
+	if (nextData.locale !== void 0) target.__VINEXT_LOCALE__ = nextData.locale;
+	if (nextData.locales !== void 0) target.__VINEXT_LOCALES__ = [...nextData.locales];
+	if (nextData.defaultLocale !== void 0) target.__VINEXT_DEFAULT_LOCALE__ = nextData.defaultLocale;
+}
+//#endregion
+export { applyVinextLocaleGlobals, extractVinextNextDataJson, parseVinextNextDataJson };

package/dist/client/window-next.d.ts

@@ -0,0 +1,168 @@
+//#region src/client/window-next.d.ts
+/**
+ * Install the `window.next` debug/diagnostic global that Next.js exposes
+ * on the client.
+ *
+ * Next.js publishes a small per-app object on `window.next` from its
+ * client bootstraps and uses it for two distinct purposes:
+ *
+ *   1. An external debugging / test-automation surface. Pages Router tests
+ *      and userland code routinely call `window.next.router.push(...)` and
+ *      `window.next.router.events.on(...)` directly, and the App Router
+ *      bootstrap sets `appDir: true` so consumers can branch on which
+ *      router is active.
+ *      - Pages Router: `packages/next/src/client/next.ts`
+ *      - App Router: `packages/next/src/client/app-bootstrap.ts`
+ *      - App Router public surface:
+ *        `packages/next/src/client/components/app-router-instance.ts`
+ *        (`window.next.router = publicAppRouterInstance` at line 510)
+ *
+ *   2. Internal navigation bookkeeping read by Next.js itself. The App
+ *      Router's <Router> component writes `window.next.__internal_src_page`
+ *      whenever the active source-page changes, and the router instance
+ *      writes `window.next.__pendingUrl` at the start of a programmatic
+ *      navigation so nav-failure-handler.ts can fall back to a hard
+ *      navigation if a render fails.
+ *      - `packages/next/src/client/components/app-router.tsx` (line ~204)
+ *      - `packages/next/src/client/components/app-router-instance.ts`
+ *        (line ~296)
+ *      - `packages/next/src/client/components/nav-failure-handler.ts`
+ *
+ * Without this global, third-party libraries and a large fraction of the
+ * Next.js deploy test suite crash with
+ * `TypeError: Cannot read properties of undefined (reading 'router')`.
+ *
+ * Both routers in vinext share this installer so the field shape stays in
+ * sync and only one source of truth describes the supported keys.
+ */
+/**
+ * The minimum App Router public router surface that Next.js exposes on
+ * `window.next.router`. Mirrors the `publicAppRouterInstance` shape from
+ * `packages/next/src/client/components/app-router-instance.ts`.
+ *
+ * `hmrRefresh` is intentionally omitted — vinext does not implement it.
+ * `experimental_gesturePush` is attached only when
+ * `experimental.gestureTransition` is enabled, matching Next.js.
+ */
+type AppRouterPublicInstance = {
+  push: (href: string, options?: {
+    scroll?: boolean;
+  }) => void;
+  replace: (href: string, options?: {
+    scroll?: boolean;
+  }) => void;
+  back: () => void;
+  forward: () => void;
+  refresh: () => void;
+  prefetch: (href: string, options?: {
+    onInvalidate?: () => void;
+  }) => void;
+  experimental_gesturePush?: (href: string, options?: {
+    scroll?: boolean;
+  }) => void; /** Default placeholder, matches Next.js. */
+  bfcacheId?: string;
+};
+/**
+ * Pages Router singleton surface — matches `NextRouter` from
+ * `packages/next/src/shared/lib/router/router.ts` (line 372).
+ *
+ * Exported because `shims/router.ts` casts its strict `NextRouter` value
+ * to this looser type at the install call site (Pages Router methods take
+ * narrow `UrlObject | string` arguments, which are not contravariantly
+ * assignable to the `unknown[]` surface this global exposes).
+ *
+ * `push` and `replace` return `Promise<boolean>` to match Next.js's
+ * documented contract (`packages/next/src/shared/lib/router/router.ts:1025-1068`
+ * — push/replace delegate to `change()` which returns `Promise<boolean>`,
+ * resolving to `true` on a successful navigation and `false` when blocked
+ * — e.g. hard-navigation fallback). The Next.js deploy test suite reads
+ * the resolved value via `browser.eval('await window.next.router.push(...)')`
+ * to assert success.
+ */
+type PagesRouterPublicInstance = {
+  push: (...args: unknown[]) => Promise<boolean>;
+  replace: (...args: unknown[]) => Promise<boolean>;
+  back: () => void;
+  reload: () => void;
+  prefetch: (...args: unknown[]) => unknown;
+  beforePopState: (cb: (...args: unknown[]) => boolean) => void;
+  events: {
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    off: (event: string, handler: (...args: unknown[]) => void) => void;
+    emit: (event: string, ...args: unknown[]) => void;
+  };
+  /**
+   * Mirrors Next.js's `Router.components`. Read by external tooling (and the
+   * Next.js deploy test suite) to detect routes that have been seen via
+   * prefetch — App Router targets land here as `{ __appRouter: true }`.
+   * See: `packages/next/src/shared/lib/router/router.ts:2525`.
+   */
+  components: Record<string, unknown>;
+};
+declare global {
+  interface Window {
+    next?: WindowNext;
+  }
+}
+/**
+ * The shape of `window.next`. Only includes fields vinext actually
+ * implements. App Router additionally writes `__internal_src_page` and
+ * `__pendingUrl` at runtime; they start undefined.
+ *
+ * Not exported because all use is internal to this module — callers read
+ * the shape off `window.next` directly, which inherits the augmentation
+ * above without a named type import.
+ */
+type WindowNext = {
+  /**
+   * Version string, mirroring Next.js's `process.env.__NEXT_VERSION` set
+   * from `packages/next/src/client/next.ts` (line 5). vinext substitutes
+   * the vinext package version because there is no underlying Next.js
+   * runtime to report.
+   */
+  version: string;
+  /**
+   * `true` when the App Router bootstrap has run on this page. Matches
+   * Next.js `app-bootstrap.ts` (line 15: `appDir: true`). Pages Router
+   * leaves this undefined.
+   */
+  appDir?: boolean;
+  /**
+   * The active router instance. App Router writes the publicAppRouterInstance
+   * here; Pages Router writes its Router singleton. Same property name in
+   * both Next.js and vinext.
+   */
+  router?: AppRouterPublicInstance | PagesRouterPublicInstance;
+  /**
+   * App Router only. The URL of the current in-flight navigation (set when
+   * a navigation begins, cleared on commit). Read by
+   * `nav-failure-handler.ts` to fall back to a hard navigation when a
+   * render fails. Pages Router does not write this.
+   */
+  __pendingUrl?: URL;
+  /**
+   * App Router only. The source page extracted from the current Flight
+   * router state. Read by external tooling and Next.js's own dev hot
+   * reloader. Pages Router does not write this.
+   */
+  __internal_src_page?: string;
+};
+/**
+ * Install `window.next` if it has not already been installed in this
+ * document. Subsequent calls update fields in place so both the Pages
+ * Router and the App Router bootstraps can call this without clobbering
+ * each other (e.g. for hybrid `pages/` + `app/` setups).
+ *
+ * When called a second time, `router` and `appDir` overwrite the previous
+ * values. This mirrors Next.js's load order: in a hybrid app the App
+ * Router's `app-bootstrap.ts` runs after Pages Router's `next.ts` and the
+ * App Router instance wins.
+ *
+ * No module-level cache: we read and write through `window.next` directly
+ * so that a test (or userland code) that deletes `window.next` cleanly
+ * resets state.
+ */
+declare function installWindowNext(fields: Partial<WindowNext>): void;
+declare function setWindowNextInternalSourcePage(sourcePage: string | null): void;
+//#endregion
+export { PagesRouterPublicInstance, installWindowNext, setWindowNextInternalSourcePage };

package/dist/client/window-next.js

@@ -0,0 +1,57 @@
+//#region src/client/window-next.ts
+/**
+* Build-time replacement for the vinext package version, injected by the
+* Vite plugin via `define` (see `index.ts` — `process.env.__NEXT_VERSION`
+* is mirrored from `packages/vinext/package.json#version` so library
+* callers that read `process.env.__NEXT_VERSION` see a real value).
+*
+* In environments where the define did not run (standalone unit tests
+* that import this module without going through the plugin), the
+* `?? "vinext"` fallback prevents a literal `undefined` from landing on
+* `window.next.version`.
+*/
+const VINEXT_VERSION = process.env.__NEXT_VERSION ?? "vinext";
+/**
+* Install `window.next` if it has not already been installed in this
+* document. Subsequent calls update fields in place so both the Pages
+* Router and the App Router bootstraps can call this without clobbering
+* each other (e.g. for hybrid `pages/` + `app/` setups).
+*
+* When called a second time, `router` and `appDir` overwrite the previous
+* values. This mirrors Next.js's load order: in a hybrid app the App
+* Router's `app-bootstrap.ts` runs after Pages Router's `next.ts` and the
+* App Router instance wins.
+*
+* No module-level cache: we read and write through `window.next` directly
+* so that a test (or userland code) that deletes `window.next` cleanly
+* resets state.
+*/
+function installWindowNext(fields) {
+	if (typeof window === "undefined") return;
+	const existing = window.next;
+	if (existing) {
+		if (fields.version !== void 0) existing.version = fields.version;
+		if (fields.appDir !== void 0) existing.appDir = fields.appDir;
+		if (fields.router !== void 0) existing.router = fields.router;
+		if (fields.__pendingUrl !== void 0) existing.__pendingUrl = fields.__pendingUrl;
+		if (fields.__internal_src_page !== void 0) existing.__internal_src_page = fields.__internal_src_page;
+		return;
+	}
+	window.next = {
+		version: fields.version ?? VINEXT_VERSION,
+		...fields
+	};
+}
+function setWindowNextInternalSourcePage(sourcePage) {
+	if (typeof window === "undefined") return;
+	installWindowNext({});
+	if (sourcePage === null) {
+		delete window.next?.__internal_src_page;
+		return;
+	}
+	const next = window.next;
+	if (!next) return;
+	next.__internal_src_page = sourcePage;
+}
+//#endregion
+export { installWindowNext, setWindowNextInternalSourcePage };

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,3 @@
+import { KVCacheHandler } from "./src/cache/kv-data-adapter.runtime.js";
+import { TPROptions, TPRResult, runTPR } from "./tpr.js";
+export { KVCacheHandler, type TPROptions, type TPRResult, runTPR };

package/dist/cloudflare/index.js

@@ -0,0 +1,3 @@
+import { KVCacheHandler } from "./src/cache/kv-data-adapter.runtime.js";
+import { runTPR } from "./tpr.js";
+export { KVCacheHandler, runTPR };

package/dist/cloudflare/src/cache/cdn-adapter.runtime.js

@@ -0,0 +1,102 @@
+import { getRequestExecutionContext } from "../../../shims/request-context.js";
+//#region ../cloudflare/src/cache/cdn-adapter.runtime.ts
+function getWorkersCache() {
+	const cache = getRequestExecutionContext()?.cache;
+	if (cache && typeof cache.purge === "function") return cache;
+	return null;
+}
+/** Non-cacheable responses: nobody (edge or browser) stores them. */
+const NO_STORE = "no-store";
+/**
+* Browser-facing policy for cacheable responses. `public` allows shared caches
+* to participate, but `max-age=0, must-revalidate` forces every reuse to
+* revalidate (against the edge) rather than serving a stored copy — so the user
+* always sees edge-fresh content while still permitting conditional 304s.
+*/
+const BROWSER_REVALIDATE = "public, max-age=0, must-revalidate";
+/**
+* A concrete stale window (1 year) substituted for a value-less
+* `stale-while-revalidate`. The framework emits a bare `stale-while-revalidate`
+* (no `=seconds`) to mean an unbounded stale window — a Vercel CDN extension.
+* Cloudflare follows RFC 5861, which requires `stale-while-revalidate=<seconds>`,
+* and treats the value-less form as a zero-width window (no stale serving →
+* hard expiry at `max-age`, so the next request is a MISS instead of UPDATING).
+* Stamping a large finite value preserves the "serve stale ~indefinitely while
+* revalidating" intent in a form the edge honors.
+*/
+const UNBOUNDED_SWR_SECONDS = 31536e3;
+/**
+* Convert the framework's shared-cache policy into a CDN-scoped one:
+* `s-maxage=…` → `max-age=…` (the edge honors `max-age` inside
+* `CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
+* seconds value (Cloudflare ignores the bare directive), and ensure a leading
+* `public`.
+*/
+function toEdgeCacheControl(cacheControl) {
+	const withMaxAge = cacheControl.replace(/\bs-maxage=/g, "max-age=").replace(/\bstale-while-revalidate\b(?!=)/g, `stale-while-revalidate=${UNBOUNDED_SWR_SECONDS}`);
+	return /\bpublic\b/.test(withMaxAge) ? withMaxAge : `public, ${withMaxAge}`;
+}
+/**
+* Cloudflare's `Cache-Tag` header budget is 16 KB total with each tag capped at
+* 1024 bytes. Keep a conservative ceiling so a page with a large tag set never
+* produces an oversized (silently-dropped) header.
+*/
+const MAX_CACHE_TAG_BYTES = 8 * 1024;
+const MAX_SINGLE_TAG_BYTES = 1024;
+/**
+* Build a `Cache-Tag` header value from canonicalised tags. Tags containing a
+* comma (the header separator) or exceeding the per-tag size are skipped, and
+* the whole value is bounded to stay within Cloudflare's limit.
+*/
+function formatCacheTag(tags) {
+	const parts = [];
+	let total = 0;
+	for (const tag of tags) {
+		if (!tag || tag.includes(",") || tag.length > MAX_SINGLE_TAG_BYTES) continue;
+		const next = total + tag.length + (parts.length > 0 ? 1 : 0);
+		if (next > MAX_CACHE_TAG_BYTES) break;
+		parts.push(tag);
+		total = next;
+	}
+	return parts.length > 0 ? parts.join(",") : null;
+}
+var CloudflareCdnCacheAdapter = class {
+	ownsBackgroundRevalidation = false;
+	/**
+	* The origin keeps no page store — return null so the request renders fresh.
+	* The edge serves cached HIT/STALE responses without reaching the origin.
+	*/
+	async get() {
+		return null;
+	}
+	/** No-op: the platform caches the response via its headers, not an origin store. */
+	async set(_key, _data, _ctx) {}
+	buildResponseHeaders(input) {
+		if (!input.cacheControl) return { "Cache-Control": NO_STORE };
+		if (/\b(?:no-store|no-cache|private)\b/.test(input.cacheControl)) return {
+			"Cache-Control": input.cacheControl,
+			"CDN-Cache-Control": null,
+			"Cloudflare-CDN-Cache-Control": null,
+			"Cache-Tag": null
+		};
+		const headers = {
+			"Cache-Control": BROWSER_REVALIDATE,
+			"CDN-Cache-Control": toEdgeCacheControl(input.cacheControl)
+		};
+		if (input.tags && input.tags.length > 0) {
+			const cacheTag = formatCacheTag(input.tags);
+			if (cacheTag) headers["Cache-Tag"] = cacheTag;
+		}
+		return headers;
+	}
+	/** Purge edge-cached responses by tag via the request context's `cache.purge`. */
+	async revalidateTag(tags, _durations) {
+		const cache = getWorkersCache();
+		if (!cache) return;
+		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string" && t.length > 0);
+		if (tagList.length === 0) return;
+		await cache.purge({ tags: tagList });
+	}
+};
+//#endregion
+export { CloudflareCdnCacheAdapter };

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

@@ -0,0 +1,126 @@
+import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../../../shims/cache-handler.js";
+import { ExecutionContextLike } from "../../../shims/request-context.js";
+
+//#region ../cloudflare/src/cache/kv-data-adapter.runtime.d.ts
+type KVNamespace = {
+  get(key: string, options?: {
+    type?: string;
+  }): Promise<string | null>;
+  get(key: string, options: {
+    type: "arrayBuffer";
+  }): Promise<ArrayBuffer | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
+    expirationTtl?: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    keys: Array<{
+      name: string;
+      metadata?: Record<string, unknown>;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+  }>;
+};
+/** Key prefix for cache entries. */
+/**
+ * Cloudflare KV data cache handler.
+ *
+ * @deprecated Consumers should not instantiate or register this handler by
+ * hand. Configure it declaratively via the `cache.data` option on the
+ * `vinext()` plugin, using the {@link kvDataAdapter} builder:
+ *
+ * ```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" }) } })],
+ * });
+ * ```
+ *
+ * `kvDataAdapter()` is safe to call from `vite.config.ts` — it never touches
+ * the Workers runtime — and the plugin defers instantiation of this handler to
+ * the first request. This class stays exported for the runtime factory and for
+ * backwards compatibility, but is not the recommended consumer API.
+ */
+declare class KVCacheHandler implements CacheHandler {
+  private kv;
+  private prefix;
+  private ctx;
+  private ttlSeconds;
+  /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
+  private _tagCache;
+  /** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */
+  private _tagCacheTtl;
+  constructor(kvNamespace: KVNamespace, options?: {
+    appPrefix?: string;
+    ctx?: ExecutionContextLike;
+    ttlSeconds?: number; /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
+    tagCacheTtlMs?: number;
+  });
+  get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+  /**
+   * Check tag invalidation markers for stored tags or read-time soft tags.
+   * Uses a local in-memory cache to avoid redundant KV reads for recently-seen tags.
+   */
+  private _hasRevalidatedTag;
+  set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+  revalidateTag(tags: string | string[], _durations?: {
+    expire?: number;
+  }): Promise<void>;
+  /**
+   * Invalidate all cache entries whose path tags fall under `pathPrefix`.
+   *
+   * Uses KV list metadata to discover tags without fetching entry values —
+   * entries written by `set()` store their tags in KV metadata, so
+   * `kv.list()` returns them inline with each key. This makes prefix
+   * invalidation O(list_pages) instead of O(entries × get).
+   *
+   * Entries written before metadata was added (no metadata.tags) are
+   * gracefully skipped — they'll be picked up on next `set()` which
+   * writes metadata.
+   *
+   * When present, this method fully replaces the `revalidateTag` call
+   * path in `revalidatePath()` — implementors own all path-based tag
+   * handling.
+   */
+  revalidateByPathPrefix(pathPrefix: string): Promise<void>;
+  /**
+   * Clear the in-memory tag cache for this KVCacheHandler instance.
+   *
+   * Note: KVCacheHandler instances are typically reused across multiple
+   * requests in a Cloudflare Worker. The `_tagCache` is intentionally
+   * cross-request — it reduces redundant KV reads for recently-seen tags
+   * across all requests hitting the same isolate, bounded by `tagCacheTtlMs`
+   * (default 5s). vinext does NOT call this method per request.
+   *
+   * This is an opt-in escape hatch for callers that need stricter isolation
+   * (e.g., tests, or environments with custom lifecycle management).
+   * Callers that require per-request isolation should either construct a
+   * fresh KVCacheHandler per request or invoke this method explicitly.
+   */
+  resetRequestCache(): void;
+  /**
+   * Fire a KV delete in the background.
+   * Prefers the per-request ExecutionContext from ALS (set by
+   * runWithExecutionContext in the worker entry) so that background KV
+   * operations are registered with the correct request's waitUntil().
+   * Falls back to the constructor-provided ctx for callers that set it
+   * explicitly, and to fire-and-forget when neither is available (Node.js dev).
+   */
+  private _deleteInBackground;
+  /**
+   * Execute a KV put and return the promise so callers can await completion.
+   * Also registers with ctx.waitUntil() so the Workers runtime keeps the
+   * isolate alive even if the caller does not await the returned promise.
+   */
+  private _put;
+}
+//#endregion
+export { KVCacheHandler };