vinext 1.0.0-beta.8 → 1.0.0

package/dist/cache/cache-adapters-virtual.d.ts

@@ -1,3 +1,4 @@
+import { VinextMultiStageOutput } from "../server/multi-stage.js";
 //#region src/cache/cache-adapters-virtual.d.ts
 /**
  * A serializable pointer to a cache adapter module — the shape of each `cache`
@@ -6,7 +7,71 @@
  * by hand. `options` must be JSON-serializable: it is inlined into the generated
  * registration module and forwarded to the adapter factory at runtime.
  */
-type CacheAdapterDescriptor<O extends Record<string, unknown> = Record<string, unknown>> = {
+export type CdnCacheAdapterCapabilities = {
+  /**
+   * Page responses include the current application build identity in the
+   * framework-owned `X-Vinext-Build-Id` response header, including responses
+   * that are ultimately marked non-cacheable.
+   *
+   * Deploy adapters use this guarantee to distinguish the newly uploaded
+   * Worker from an older version while staged traffic is propagating.
+   */
+  buildIdentity?: "response-header";
+  /**
+   * The shared cache selects response variants using every request header
+   * named by `Vary`, comparing the header values verbatim.
+   *
+   * Deploy warmup can address the canonical full-route and loading-shell RSC
+   * variants when this guarantee is present.
+   */
+  responseVary?: "verbatim";
+  /** Warm by observing framework `X-Vinext-Cache` admission instead of an edge-cache header. */
+  warmup?: "data-cache" | "response-store";
+  /**
+   * Rewrites and other request routing run before the shared response stage,
+   * and the resolved response-stage invocation participates in cache identity.
+   *
+   * Warm planners may therefore request rewrite source paths: conditional and
+   * default route resolutions cannot reuse one another's cached response.
+   */
+  requestRouting?: "uncached-stage";
+  /**
+   * Cacheable App Page responses require a build-bound probe manifest before
+   * the adapter may emit public shared-cache policy. The adapter's deployment
+   * integration is responsible for carrying that manifest into the runtime
+   * that serves the corresponding application build.
+   */
+  routeCacheability?: "probe-manifest";
+  /**
+   * Whether a provider-specific response header controls the adapter's shared
+   * cache. Prerender discovery calls this to avoid collapsing a dynamic route
+   * pattern when next.config assigns different cache policy to its concrete
+   * pathnames.
+   */
+  isResponsePolicyHeader?: (name: string) => boolean;
+};
+export type CacheAdapterBuildOutput = {
+  /** Omitted for finalizer-only outputs; staged outputs use `multi-stage`. */
+  type?: undefined;
+  /** Whether this adapter owns output for the resolved build platform. */
+  matchesBuild?: (build: {
+    plugins: readonly {
+      name?: string;
+    }[];
+  }) => boolean;
+  /** Finalize an emitted directory after other platform output hooks. */
+  finalizeBuildOutput?: (output: {
+    root: string;
+    outDir: string;
+    isPrimaryServerOutput: boolean;
+  }) => Promise<void> | void;
+  /** Package locally prerendered artifacts after the prerender phase completes. */
+  finalizePrerenderOutput?: (output: {
+    root: string;
+    clientOutDir: string;
+  }) => Promise<void> | void;
+};
+export type CacheAdapterDescriptor<O extends Record<string, unknown> = Record<string, unknown>> = {
   /**
    * Module specifier (or absolute path, e.g. from `require.resolve(...)`) whose
    * default export is a cache adapter factory.
@@ -14,30 +79,51 @@ type CacheAdapterDescriptor<O extends Record<string, unknown> = Record<string, u
   adapter: string;
   /** JSON-serializable options forwarded to the factory at runtime. */
   options?: O;
+  /** Optional adapter-owned platform finalization or generic staged output. */
+  output?: CacheAdapterBuildOutput | VinextMultiStageOutput;
+  /** Build-time cache semantics used by shared request protocol code. */
+  capabilities?: CdnCacheAdapterCapabilities;
 };
+export declare function hasVerbatimResponseVary(cache?: VinextCacheConfig | null): boolean;
+export declare function supportsCanonicalRscWarmup(cache?: VinextCacheConfig | null): boolean;
+export declare function cacheWarmupStatusSource(cache?: VinextCacheConfig | null): "cloudflare" | "data-cache" | "vinext";
+/** Whether a configured adapter consumes locally prerendered build artifacts. */
+export declare function hasCacheAdapterPrerenderOutput(cache?: VinextCacheConfig | null): boolean;
+/** Let configured adapters package locally prerendered build artifacts. */
+export declare function finalizeCacheAdapterPrerenderOutput(cache: VinextCacheConfig | null | undefined, root: string, output?: {
+  clientOutDir?: string;
+}): Promise<void>;
+export declare function hasUncachedRequestRouting(cache?: VinextCacheConfig | null): boolean;
+export declare function hasBuildIdentityResponseHeader(cache?: VinextCacheConfig | null): boolean;
+export declare function requiresRouteCacheabilityProbeManifest(cache?: VinextCacheConfig | null): boolean;
+/** Whether a response header controls core or the configured CDN adapter. */
+export declare function isConfiguredCdnResponsePolicyHeader(cache?: VinextCacheConfig | null, name?: string): boolean;
 /**
  * The `cache` option of the vinext() plugin: declaratively register cache
  * handlers instead of calling `setDataCacheHandler()` / `setCdnCacheAdapter()`
  * from a worker entry.
  */
-type VinextCacheConfig = {
+export type VinextCacheConfig = {
   /** Page-level ISR serving strategy (CDN cache adapter). */
   cdn?: CacheAdapterDescriptor;
   /** Data cache (fetch / `"use cache"` / `unstable_cache`) handler. */
   data?: CacheAdapterDescriptor;
 };
 /** Public virtual module id imported by the server entries. */
-declare const VIRTUAL_CACHE_ADAPTERS = "virtual:vinext-cache-adapters";
-declare const VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY = "__vinextCacheConfig";
+export declare const VIRTUAL_CACHE_ADAPTERS = "virtual:vinext-cache-adapters";
+/** Request-stage module that cannot retain the data-cache adapter graph. */
+export declare const VIRTUAL_CDN_CACHE_ADAPTER = "virtual:vinext-cdn-cache-adapter";
+export declare const VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY = "__vinextCacheConfig";
 type ViteConfigLoader = {
   loadConfigFromFile: typeof import("vite").loadConfigFromFile;
 };
-declare function findVinextCacheConfigInPlugins(plugins: import("vite").PluginOption[] | undefined): Promise<VinextCacheConfig | null>;
-declare function loadVinextCacheConfigFromViteConfig(vite: ViteConfigLoader, root: string): Promise<VinextCacheConfig | null>;
+export declare function findVinextCacheConfigInPlugins(plugins: import("vite").PluginOption[] | undefined): Promise<VinextCacheConfig | null>;
+export declare function loadVinextCacheConfigFromViteConfig(vite: ViteConfigLoader, root: string): Promise<VinextCacheConfig | null>;
 /**
  * Generate the source of the `virtual:vinext-cache-adapters` module for the
  * given config. Always exports `registerConfiguredCacheAdapters(env)`.
  */
-declare function generateCacheAdaptersModule(cache?: VinextCacheConfig): string;
-//#endregion
-export { VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY, VIRTUAL_CACHE_ADAPTERS, VinextCacheConfig, findVinextCacheConfigInPlugins, generateCacheAdaptersModule, loadVinextCacheConfigFromViteConfig };
+export declare function generateCacheAdaptersModule(cache?: VinextCacheConfig): string;
+/** Generate request-stage registration without importing a configured data adapter. */
+export declare function generateCdnCacheAdapterModule(cache?: VinextCacheConfig): string;
+//#endregion

package/dist/cache/cache-adapters-virtual.js

@@ -1,3 +1,4 @@
+import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { flattenPluginOptions } from "../utils/plugin-options.js";
 //#region src/cache/cache-adapters-virtual.ts
 /**
@@ -16,8 +17,50 @@ import { flattenPluginOptions } from "../utils/plugin-options.js";
 * never touches the Workers runtime — instantiation is deferred to the first
 * request.
 */
+function hasVerbatimResponseVary(cache) {
+	return cache?.cdn?.capabilities?.responseVary === "verbatim";
+}
+function supportsCanonicalRscWarmup(cache) {
+	return hasVerbatimResponseVary(cache);
+}
+function cacheWarmupStatusSource(cache) {
+	if (cache?.cdn?.capabilities?.warmup === "response-store") return "vinext";
+	if (cache?.cdn?.capabilities?.warmup === "data-cache") return "data-cache";
+	if (!cache?.cdn?.adapter && cache?.data?.capabilities?.warmup === "data-cache") return "data-cache";
+	return "cloudflare";
+}
+function prerenderOutputFinalizers(cache) {
+	return [cache?.data?.output, cache?.cdn?.output].map((output) => output && "finalizePrerenderOutput" in output ? output.finalizePrerenderOutput : void 0).filter((finalize) => Boolean(finalize));
+}
+/** Whether a configured adapter consumes locally prerendered build artifacts. */
+function hasCacheAdapterPrerenderOutput(cache) {
+	return prerenderOutputFinalizers(cache).length > 0;
+}
+/** Let configured adapters package locally prerendered build artifacts. */
+async function finalizeCacheAdapterPrerenderOutput(cache, root, output = {}) {
+	for (const finalize of new Set(prerenderOutputFinalizers(cache))) await finalize({
+		root,
+		clientOutDir: path.resolve(root, output.clientOutDir ?? "dist/client")
+	});
+}
+function hasUncachedRequestRouting(cache) {
+	return cache?.cdn?.capabilities?.requestRouting === "uncached-stage";
+}
+function hasBuildIdentityResponseHeader(cache) {
+	return cache?.cdn?.capabilities?.buildIdentity === "response-header" || !cache?.cdn?.adapter && cache?.data?.capabilities?.buildIdentity === "response-header";
+}
+function requiresRouteCacheabilityProbeManifest(cache) {
+	return cache?.cdn?.capabilities?.routeCacheability === "probe-manifest";
+}
+/** Whether a response header controls core or the configured CDN adapter. */
+function isConfiguredCdnResponsePolicyHeader(cache, name) {
+	if (!name) return false;
+	return name.trim().toLowerCase() === "cache-control" || cache?.cdn?.capabilities?.isResponsePolicyHeader?.(name) === true;
+}
 /** Public virtual module id imported by the server entries. */
 const VIRTUAL_CACHE_ADAPTERS = "virtual:vinext-cache-adapters";
+/** Request-stage module that cannot retain the data-cache adapter graph. */
+const VIRTUAL_CDN_CACHE_ADAPTER = "virtual:vinext-cdn-cache-adapter";
 const VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY = "__vinextCacheConfig";
 async function findVinextCacheConfigInPlugins(plugins) {
 	const flattened = await flattenPluginOptions(plugins);
@@ -54,6 +97,7 @@ function inlineOptions(adapter, options) {
 function generateCacheAdaptersModule(cache) {
 	const data = cache?.data;
 	const cdn = cache?.cdn;
+	const dataProvidesBuildIdentity = !cdn?.adapter && data?.capabilities?.buildIdentity === "response-header";
 	if (!data?.adapter && !cdn?.adapter) return [
 		"// vinext: no cache.cdn/cache.data adapter configured — registration is a no-op.",
 		"export function registerConfiguredCacheAdapters() {}",
@@ -62,17 +106,25 @@ function generateCacheAdaptersModule(cache) {
 	const lines = ["// vinext: generated from the `cache` option in your vinext() plugin config."];
 	if (data?.adapter) {
 		lines.push(`import __vinextDataAdapterFactory from ${JSON.stringify(data.adapter)};`);
-		lines.push(`import { setDataCacheHandler } from "vinext/shims/cache-handler";`);
+		lines.push(`import { registerDataCacheHandler } from "vinext/shims/cache-handler";`);
 	}
 	if (cdn?.adapter) {
 		lines.push(`import __vinextCdnAdapterFactory from ${JSON.stringify(cdn.adapter)};`);
-		lines.push(`import { setCdnCacheAdapter } from "vinext/shims/cdn-cache";`);
-	}
+		lines.push(`import { registerCdnCacheAdapter } from "vinext/shims/cdn-cache-state";`);
+	} else if (dataProvidesBuildIdentity) lines.push(`import { DefaultCdnCacheAdapter } from "vinext/shims/cdn-cache";`, `import { registerCdnCacheAdapter } from "vinext/shims/cdn-cache-state";`);
 	lines.push("", "// A factory that throws (e.g. a missing binding on an incompatible runtime)", "// is logged and skipped so the default handler stays in place.", "function __vinextFormatAdapterError(error) {", "  if (error instanceof Error && error.message) return error.message;", "  try {", "    return String(error);", "  } catch {", "    return '<unknown error>';", "  }", "}", "", "let __vinextCacheAdaptersRegistered = false;", "", "export function registerConfiguredCacheAdapters(env) {", "  if (typeof process !== 'undefined' && process.env?.__VINEXT_PRERENDER_PATH_DISCOVERY === '1') return;", "  if (__vinextCacheAdaptersRegistered) return;", "  __vinextCacheAdaptersRegistered = true;");
-	if (data?.adapter) lines.push("  try {", `    setDataCacheHandler(__vinextDataAdapterFactory({ env, options: ${inlineOptions(data.adapter, data.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured data cache adapter; using the default handler.\\n\" + __vinextFormatAdapterError(error));", "  }");
-	if (cdn?.adapter) lines.push("  try {", `    setCdnCacheAdapter(__vinextCdnAdapterFactory({ env, options: ${inlineOptions(cdn.adapter, cdn.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured CDN cache adapter; using the default adapter.\\n\" + __vinextFormatAdapterError(error));", "  }");
+	if (data?.adapter) {
+		lines.push("  try {", `    registerDataCacheHandler(() => __vinextDataAdapterFactory({ env, options: ${inlineOptions(data.adapter, data.options)} }));`);
+		if (dataProvidesBuildIdentity) lines.push("    registerCdnCacheAdapter(() => new DefaultCdnCacheAdapter(", "      process.env.__VINEXT_RSC_BUILD_IDENTITY || process.env.__VINEXT_BUILD_ID,", "    ));");
+		lines.push("  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured data cache adapter; using the default handler.\\n\" + __vinextFormatAdapterError(error));", "  }");
+	}
+	if (cdn?.adapter) lines.push("  try {", `    registerCdnCacheAdapter(() => __vinextCdnAdapterFactory({ env, options: ${inlineOptions(cdn.adapter, cdn.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured CDN cache adapter; using the default adapter.\\n\" + __vinextFormatAdapterError(error));", "  }");
 	lines.push("}", "");
 	return lines.join("\n");
 }
+/** Generate request-stage registration without importing a configured data adapter. */
+function generateCdnCacheAdapterModule(cache) {
+	return `${generateCacheAdaptersModule(cache?.cdn ? { cdn: cache.cdn } : void 0)}export const hasConfiguredDataCache = ${Boolean(cache?.data?.adapter)};\nexport const configuredCdnCacheAdapterOptions = ${inlineOptions(cache?.cdn?.adapter ?? "cdn", cache?.cdn?.options)};\n`;
+}
 //#endregion
-export { VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY, VIRTUAL_CACHE_ADAPTERS, findVinextCacheConfigInPlugins, generateCacheAdaptersModule, loadVinextCacheConfigFromViteConfig };
+export { VINEXT_CACHE_CONFIG_PLUGIN_PROPERTY, VIRTUAL_CACHE_ADAPTERS, VIRTUAL_CDN_CACHE_ADAPTER, cacheWarmupStatusSource, finalizeCacheAdapterPrerenderOutput, findVinextCacheConfigInPlugins, generateCacheAdaptersModule, generateCdnCacheAdapterModule, hasBuildIdentityResponseHeader, hasCacheAdapterPrerenderOutput, hasUncachedRequestRouting, hasVerbatimResponseVary, isConfiguredCdnResponsePolicyHeader, loadVinextCacheConfigFromViteConfig, requiresRouteCacheabilityProbeManifest, supportsCanonicalRscWarmup };

package/dist/check.d.ts

@@ -12,11 +12,13 @@ type CheckItem = {
   detail?: string;
   files?: string[];
 };
-type CheckResult = {
+export type CheckResult = {
   imports: CheckItem[];
   config: CheckItem[];
   libraries: CheckItem[];
   conventions: CheckItem[];
+  /** Whether app/ or src/app/ exists, which makes vinext() register the RSC plugin. */
+  hasAppDir?: boolean;
   summary: {
     supported: number;
     partial: number;
@@ -56,32 +58,31 @@ type CheckResult = {
  * case is unaffected (string scanning stops at the newline), and the check is only
  * advisory — so we accept it rather than pull in a full parser.
  */
-declare function hasFreeCjsGlobal(content: string): boolean;
+export declare function hasFreeCjsGlobal(content: string): boolean;
 /**
  * Scan source files for `import ... from 'next/...'` statements.
  */
-declare function scanImports(root: string): CheckItem[];
+export declare function scanImports(root: string): CheckItem[];
 /**
  * Analyze next.config.js/mjs/ts for supported and unsupported options.
  */
-declare function analyzeConfig(root: string): CheckItem[];
+export declare function analyzeConfig(root: string): CheckItem[];
 /**
  * Check package.json dependencies for known libraries.
  */
-declare function checkLibraries(root: string): CheckItem[];
+export declare function checkLibraries(root: string): CheckItem[];
 /**
  * Check file conventions (pages, app directory, middleware, etc.)
  */
-declare function checkConventions(root: string): CheckItem[];
+export declare function checkConventions(root: string): CheckItem[];
 /**
  * Run the full compatibility check.
  */
-declare function runCheck(root: string): CheckResult;
+export declare function runCheck(root: string): CheckResult;
 /**
  * Format the check result as a colored terminal report.
  */
-declare function formatReport(result: CheckResult, opts?: {
+export declare function formatReport(result: CheckResult, opts?: {
   calledFromInit?: boolean;
 }): string;
-//#endregion
-export { CheckResult, analyzeConfig, checkConventions, checkLibraries, formatReport, hasFreeCjsGlobal, runCheck, scanImports };
+//#endregion