refactor: extract shared types and helpers from seed-cache modules

The Node.js and Workers seed-cache modules duplicated manifest types,
revalidateCtx, and cache value construction. Extract to
seed-cache-shared.ts to prevent drift between the two strategies.

Also fixes stale JSDoc referencing "manifestPromise" (renamed to
"loadedPromise").

Author: NathanDrake2406

packages/vinext/src/server/seed-cache-shared.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared types and helpers for seed-cache modules (Node.js and Workers).
+ *
+ * Both `seed-cache.ts` (eager, fs-based) and `seed-cache-workers.ts`
+ * (lazy, fetch-based) read the same vinext-prerender.json manifest and
+ * produce identical cache entries. This module holds the shared contract.
+ */
+
+import type { CachedAppPageValue } from "../shims/cache.js";
+
+// ─── Manifest types ──────────────────────────────────────────────────────────
+
+export interface PrerenderManifest {
+  buildId: string;
+  trailingSlash?: boolean;
+  routes: PrerenderManifestRoute[];
+}
+
+export interface PrerenderManifestRoute {
+  route: string;
+  status: string;
+  revalidate?: number | false;
+  path?: string;
+  router?: "app" | "pages";
+}
+
+// ─── Cache value construction ────────────────────────────────────────────────
+
+/**
+ * Build the CacheHandler context object from a revalidate value.
+ * `revalidate: undefined` (static routes) → empty context → no expiry.
+ */
+export function revalidateCtx(seconds: number | undefined): Record<string, unknown> {
+  return seconds !== undefined ? { revalidate: seconds } : {};
+}
+
+/** Build an APP_PAGE cache value for an HTML entry. */
+export function makeHtmlCacheValue(html: string): CachedAppPageValue {
+  return {
+    kind: "APP_PAGE",
+    html,
+    rscData: undefined,
+    headers: undefined,
+    postponed: undefined,
+    status: undefined,
+  };
+}
+
+/** Build an APP_PAGE cache value for an RSC entry. */
+export function makeRscCacheValue(rscData: ArrayBuffer): CachedAppPageValue {
+  return {
+    kind: "APP_PAGE",
+    html: "",
+    rscData,
+    headers: undefined,
+    postponed: undefined,
+    status: undefined,
+  };
+}

packages/vinext/src/server/seed-cache-workers.ts

@@ -24,9 +24,9 @@
  *
  * Concurrency model:
  * - A single Workers isolate can process concurrent requests. The manifest
- *   load is deduplicated via a cached promise (manifestPromise). Two
+ *   load is deduplicated via a cached promise (loadedPromise). Two
  *   concurrent calls to loadManifest both await the same promise — no
- *   double-fetch is possible because the assignment to manifestPromise
+ *   double-fetch is possible because the assignment to loadedPromise
  *   happens synchronously before the first await.
  * - Per-route seeding is deduplicated via seedInFlight. Between the
  *   getCacheHandler().get() check (async, yields) and the seedInFlight.get()
@@ -35,25 +35,16 @@
  *   promise and the second joins it.
  */
 
-import { getCacheHandler, type CachedAppPageValue } from "../shims/cache.js";
+import { getCacheHandler } from "../shims/cache.js";
 import { isrCacheKey, setRevalidateDuration } from "./isr-cache.js";
 import { getOutputPath, getRscOutputPath } from "../build/prerender.js";
-
-// ─── Manifest types (mirrors seed-cache.ts) ──────────────────────────────────
-
-interface PrerenderManifest {
-  buildId: string;
-  trailingSlash?: boolean;
-  routes: PrerenderManifestRoute[];
-}
-
-interface PrerenderManifestRoute {
-  route: string;
-  status: string;
-  revalidate?: number | false;
-  path?: string;
-  router?: "app" | "pages";
-}
+import {
+  type PrerenderManifest,
+  type PrerenderManifestRoute,
+  revalidateCtx,
+  makeHtmlCacheValue,
+  makeRscCacheValue,
+} from "./seed-cache-shared.js";
 
 /** Loaded manifest + pre-built route lookup. Returned as a unit so they can't desync. */
 interface LoadedManifest {
@@ -157,14 +148,6 @@ async function loadManifest(fetchAsset: AssetFetcher): Promise<LoadedManifest |
   return loadedPromise;
 }
 
-/**
- * Build the CacheHandler context object from a revalidate value.
- * `revalidate: undefined` (static routes) → empty context → no expiry.
- */
-function revalidateCtx(seconds: number | undefined): Record<string, unknown> {
-  return seconds !== undefined ? { revalidate: seconds } : {};
-}
-
 async function doSeedRoute(
   manifest: PrerenderManifest,
   pathname: string,
@@ -181,17 +164,8 @@ async function doSeedRoute(
   const htmlRes = await fetchAsset(`/__prerender/${htmlRelPath}`);
   if (!htmlRes.ok) return;
 
-  const html = await htmlRes.text();
-  const htmlValue: CachedAppPageValue = {
-    kind: "APP_PAGE",
-    html,
-    rscData: undefined,
-    headers: undefined,
-    postponed: undefined,
-    status: undefined,
-  };
   const htmlKey = baseKey + ":html";
-  await handler.set(htmlKey, htmlValue, ctx);
+  await handler.set(htmlKey, makeHtmlCacheValue(await htmlRes.text()), ctx);
   if (revalidateSeconds !== undefined) {
     setRevalidateDuration(htmlKey, revalidateSeconds);
   }
@@ -201,17 +175,8 @@ async function doSeedRoute(
   const rscRes = await fetchAsset(`/__prerender/${rscRelPath}`);
   if (!rscRes.ok) return;
 
-  const rscData = await rscRes.arrayBuffer();
-  const rscValue: CachedAppPageValue = {
-    kind: "APP_PAGE",
-    html: "",
-    rscData,
-    headers: undefined,
-    postponed: undefined,
-    status: undefined,
-  };
   const rscKey = baseKey + ":rsc";
-  await handler.set(rscKey, rscValue, ctx);
+  await handler.set(rscKey, makeRscCacheValue(await rscRes.arrayBuffer()), ctx);
   if (revalidateSeconds !== undefined) {
     setRevalidateDuration(rscKey, revalidateSeconds);
   }

packages/vinext/src/server/seed-cache.ts

@@ -31,25 +31,15 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { getCacheHandler, type CachedAppPageValue } from "../shims/cache.js";
+import { getCacheHandler } from "../shims/cache.js";
 import { isrCacheKey, setRevalidateDuration } from "./isr-cache.js";
 import { getOutputPath, getRscOutputPath } from "../build/prerender.js";
-
-// ─── Manifest types ───────────────────────────────────────────────────────────
-
-interface PrerenderManifest {
-  buildId: string;
-  trailingSlash?: boolean;
-  routes: PrerenderManifestRoute[];
-}
-
-interface PrerenderManifestRoute {
-  route: string;
-  status: string;
-  revalidate?: number | false;
-  path?: string;
-  router?: "app" | "pages";
-}
+import {
+  type PrerenderManifest,
+  revalidateCtx,
+  makeHtmlCacheValue,
+  makeRscCacheValue,
+} from "./seed-cache-shared.js";
 
 // ─── Public API ───────────────────────────────────────────────────────────────
 
@@ -103,14 +93,6 @@ export async function seedMemoryCacheFromPrerender(serverDir: string): Promise<n
 
 // ─── Internals ────────────────────────────────────────────────────────────────
 
-/**
- * Build the CacheHandler context object from a revalidate value.
- * `revalidate: undefined` (static routes) → empty context → no expiry.
- */
-function revalidateCtx(seconds: number | undefined): Record<string, unknown> {
-  return seconds !== undefined ? { revalidate: seconds } : {};
-}
-
 /**
  * Seed the HTML cache entry for a single route.
  * Returns true if the file existed and was seeded.
@@ -127,17 +109,12 @@ async function seedHtml(
   const fullPath = path.join(prerenderDir, relPath);
   if (!fs.existsSync(fullPath)) return false;
 
-  const htmlValue: CachedAppPageValue = {
-    kind: "APP_PAGE",
-    html: fs.readFileSync(fullPath, "utf-8"),
-    rscData: undefined,
-    headers: undefined,
-    postponed: undefined,
-    status: undefined,
-  };
-
   const key = baseKey + ":html";
-  await handler.set(key, htmlValue, revalidateCtx(revalidateSeconds));
+  await handler.set(
+    key,
+    makeHtmlCacheValue(fs.readFileSync(fullPath, "utf-8")),
+    revalidateCtx(revalidateSeconds),
+  );
 
   if (revalidateSeconds !== undefined) {
     setRevalidateDuration(key, revalidateSeconds);
@@ -162,20 +139,12 @@ async function seedRsc(
   if (!fs.existsSync(fullPath)) return;
 
   const rscBuffer = fs.readFileSync(fullPath);
-  const rscValue: CachedAppPageValue = {
-    kind: "APP_PAGE",
-    html: "",
-    rscData: rscBuffer.buffer.slice(
-      rscBuffer.byteOffset,
-      rscBuffer.byteOffset + rscBuffer.byteLength,
-    ),
-    headers: undefined,
-    postponed: undefined,
-    status: undefined,
-  };
-
+  const rscData = rscBuffer.buffer.slice(
+    rscBuffer.byteOffset,
+    rscBuffer.byteOffset + rscBuffer.byteLength,
+  );
   const key = baseKey + ":rsc";
-  await handler.set(key, rscValue, revalidateCtx(revalidateSeconds));
+  await handler.set(key, makeRscCacheValue(rscData), revalidateCtx(revalidateSeconds));
 
   if (revalidateSeconds !== undefined) {
     setRevalidateDuration(key, revalidateSeconds);