@wular/pnext 0.0.1

package/src/compat/cache/handler.ts

@@ -0,0 +1,100 @@
+// Pluggable CacheHandler (COMPAT - Next's classic cacheHandler config).
+//
+// Next's classic `cacheHandler` config points at a module exporting a class (CJS `module.exports =`,
+// CJS `.default`, or ESM default) with `get(key, ctx)` / `set(key, data, ctx)` methods, backing the
+// fetch data cache and the ISR page cache. pnext keeps an in-memory store of its own; when a handler is
+// configured the store defers to it so the handler observes every get/set and can persist across the
+// SWR window.
+//
+// Core owns the instance and the get/set/revalidate seams; compat loads the configured module and
+// installs it via setCacheHandler, so core never imports compat.
+
+export interface CacheHandlerEntry {
+  value: unknown;
+  lastModified: number;
+  tags?: readonly string[];
+}
+
+export interface CacheHandlerGetContext {
+  tags?: readonly string[];
+  softTags?: readonly string[];
+  kind?: string;
+}
+
+export interface CacheHandlerSetContext {
+  tags?: readonly string[];
+  revalidate?: number | false;
+  kind?: string;
+  /** Set for fetch data-cache writes (Next's incremental-cache fetch ctx). */
+  fetchCache?: boolean;
+  fetchUrl?: string;
+}
+
+/** The subset of Next's IncrementalCacheHandler contract pnext drives. */
+export interface CacheHandler {
+  get(
+    key: string,
+    ctx?: CacheHandlerGetContext,
+  ): Promise<CacheHandlerEntry | undefined | null> | CacheHandlerEntry | undefined | null;
+  set(
+    key: string,
+    data: unknown,
+    ctx?: CacheHandlerSetContext,
+  ): Promise<void> | void;
+  revalidateTag?(tag: string | string[]): Promise<void> | void;
+  resetRequestCache?(): void;
+}
+
+let handler: CacheHandler | undefined;
+
+/** Install the configured handler (compat calls this from an init hook). */
+export function setCacheHandler(instance: CacheHandler | undefined): void {
+  handler = instance;
+}
+
+export function getCacheHandler(): CacheHandler | undefined {
+  return handler;
+}
+
+export function hasCacheHandler(): boolean {
+  return handler !== undefined;
+}
+
+/** Read an entry from the configured handler, tolerating sync/async + throws. */
+export async function cacheHandlerGet(
+  key: string,
+  ctx?: CacheHandlerGetContext,
+): Promise<CacheHandlerEntry | undefined> {
+  if (!handler) return undefined;
+  try {
+    const entry = await handler.get(key, ctx);
+    return entry ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Write an entry to the configured handler, tolerating sync/async + throws. */
+export async function cacheHandlerSet(
+  key: string,
+  data: unknown,
+  ctx?: CacheHandlerSetContext,
+): Promise<void> {
+  if (!handler) return;
+  try {
+    await handler.set(key, data, ctx);
+  } catch {
+    // A handler failure must not break the response; the in-memory store is
+    // authoritative for correctness, the handler is a persistence layer.
+  }
+}
+
+/** Forward on-demand tag invalidation to the handler if it supports it. */
+export async function cacheHandlerRevalidateTag(tag: string): Promise<void> {
+  if (!handler?.revalidateTag) return;
+  try {
+    await handler.revalidateTag(tag);
+  } catch {
+    // best-effort
+  }
+}

package/src/compat/cache/modern-handler.ts

@@ -0,0 +1,275 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { format } from 'node:util';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { currentRequest } from '../../request/context';
+import { realNow } from '../../ppr';
+import { getNextConfig } from '../next/config-loader';
+
+interface ModernCacheEntry {
+  value: ReadableStream<Uint8Array>;
+  tags: string[];
+  stale: number;
+  timestamp: number;
+  expire: number;
+  revalidate: number;
+}
+
+interface ModernCacheHandler {
+  get?: (cacheKey: string, softTags: string[]) => Promise<ModernCacheEntry | undefined> | ModernCacheEntry | undefined;
+  set?: (cacheKey: string, pendingEntry: Promise<ModernCacheEntry>) => Promise<void> | void;
+  refreshTags?: () => Promise<void> | void;
+  getExpiration?: (tags: string[]) => Promise<number> | number;
+  updateTags?: (tags: string[], durations?: { expire?: number }) => Promise<void> | void;
+}
+
+interface ModernCacheHandlerState {
+  handler?: ModernCacheHandler;
+  installedFor?: string;
+}
+
+const MODERN_CACHE_HANDLER_STATE = Symbol.for('pnext.compat.modernCacheHandler');
+
+function state(): ModernCacheHandlerState {
+  const global = globalThis as typeof globalThis & {
+    [MODERN_CACHE_HANDLER_STATE]?: ModernCacheHandlerState;
+  };
+  return (global[MODERN_CACHE_HANDLER_STATE] ??= {});
+}
+
+export function installModernCacheHandlers(root: string): void {
+  const configured = defaultCacheHandlerPath();
+  const current = state();
+  if (!configured) {
+    current.handler = undefined;
+    current.installedFor = undefined;
+    return;
+  }
+  const filePath = resolveHandlerPath(configured, root);
+  if (current.installedFor === filePath) return;
+  const loaded = loadHandler(filePath, root);
+  if (!loaded) return;
+  current.handler = loaded;
+  current.installedFor = filePath;
+}
+
+export function hasModernCacheHandler(): boolean {
+  return state().handler !== undefined;
+}
+
+export async function modernCacheRefreshTags(): Promise<void> {
+  const refreshTags = state().handler?.refreshTags;
+  const handler = state().handler;
+  if (!handler || !refreshTags) return;
+  try {
+    await withNodeConsoleFormat(() => refreshTags.call(handler));
+  } catch {
+    // best-effort
+  }
+}
+
+export async function modernCacheGet(key: string, softTags = implicitSoftTags()): Promise<ModernCacheEntry | undefined> {
+  const handler = state().handler;
+  const get = handler?.get;
+  if (!handler || !get) return undefined;
+  try {
+    return await withNodeConsoleFormat(() => get.call(handler, key, softTags));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function modernCacheSet(key: string, pendingEntry: Promise<ModernCacheEntry>): Promise<void> {
+  const handler = state().handler;
+  const set = handler?.set;
+  if (!handler || !set) return;
+  try {
+    await withNodeConsoleFormat(() => set.call(handler, key, pendingEntry));
+  } catch {
+    // best-effort
+  }
+}
+
+export async function modernCacheGetExpiration(tags = implicitSoftTags()): Promise<number | undefined> {
+  const handler = state().handler;
+  const getExpiration = handler?.getExpiration;
+  if (!handler || !getExpiration) return undefined;
+  try {
+    return await withNodeConsoleFormat(() => getExpiration.call(handler, tags));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function modernCacheUpdateTags(tags: string[], durations?: { expire?: number }): Promise<void> {
+  const handler = state().handler;
+  const updateTags = handler?.updateTags;
+  if (!handler || !updateTags) return;
+  try {
+    await withNodeConsoleFormat(() => updateTags.call(handler, tags, durations));
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Run a user cache-handler method with Node-style console formatting. Bun's
+ * console.log inspects arguments with double quotes and a narrow wrap width;
+ * handlers log their raw arguments and the Next e2e suites match Node's
+ * single-quoted util.inspect output verbatim.
+ */
+async function withNodeConsoleFormat<T>(fn: () => Promise<T> | T): Promise<T> {
+  const original = console.log.bind(console);
+  console.log = (...args: unknown[]) => {
+    original(format(...args));
+  };
+  try {
+    return await fn();
+  } finally {
+    console.log = original;
+  }
+}
+
+export function modernCacheKey(id: string, argsJson: string): string {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const buildId = process.env.NODE_ENV === 'development' ? 'development' : 'pnext';
+  // Fixed-width hex: Next's cache keys are whole-byte hex strings and the e2e
+  // suites match them with `([0-9a-f]{2})+` — an odd-length (leading-zero
+  // trimmed) hash would never match.
+  const hash = Bun.hash.wyhash(`${id}:${argsJson}`).toString(16).padStart(16, '0');
+  return JSON.stringify([buildId, hash, JSON.parse(argsJson)]);
+}
+
+export function modernCacheEntry(input: {
+  value: unknown;
+  tags: string[];
+  staleSeconds?: number;
+  expireSeconds?: number;
+  revalidateSeconds?: number;
+  storedAt: number;
+}): ModernCacheEntry {
+  return {
+    value: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(JSON.stringify(input.value)));
+        controller.close();
+      },
+    }),
+    tags: input.tags,
+    stale: input.staleSeconds ?? 300,
+    timestamp: input.storedAt,
+    expire: input.expireSeconds ?? 31536000,
+    revalidate: input.revalidateSeconds ?? 900,
+  };
+}
+
+export function clearModernCacheHandlerForTest(): void {
+  const current = state();
+  current.handler = undefined;
+  current.installedFor = undefined;
+}
+
+function defaultCacheHandlerPath(): string | undefined {
+  const cacheHandlers = getNextConfig().cacheHandlers;
+  if (!cacheHandlers || typeof cacheHandlers !== 'object' || Array.isArray(cacheHandlers)) return undefined;
+  const configured = (cacheHandlers as Record<string, unknown>).default;
+  return typeof configured === 'string' && configured.length > 0 ? configured : undefined;
+}
+
+function resolveHandlerPath(configured: string, root: string): string {
+  const resolved = configured.startsWith('file:') ? fileURLToPath(configured) : configured;
+  if (path.isAbsolute(resolved)) return resolved;
+  return path.resolve(root, resolved);
+}
+
+function loadHandler(filePath: string, root: string): ModernCacheHandler | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const require = createRequire(pathToFileURL(`${root}/index.js`).href);
+    try {
+      return pickHandler(require(filePath));
+    } catch (error) {
+      if (!isNextDistMissing(error)) return undefined;
+      return loadCommonJsHandlerWithNextStubs(filePath, require);
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+function loadCommonJsHandlerWithNextStubs(
+  filePath: string,
+  rootRequire: NodeRequire,
+): ModernCacheHandler | undefined {
+  try {
+    const module = { exports: {} as unknown };
+    const localRequire = (specifier: string): unknown => {
+      if (specifier === 'next/dist/server/lib/cache-handlers/default.external') {
+        return { default: createDefaultExternalHandler() };
+      }
+      if (specifier.startsWith('next/dist/')) return {};
+      if (specifier.startsWith('./') || specifier.startsWith('../')) {
+        return rootRequire(path.resolve(path.dirname(filePath), specifier));
+      }
+      return rootRequire(specifier);
+    };
+    const source = readFileSync(filePath, 'utf8');
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    const evaluate = new Function('require', 'module', 'exports', '__filename', '__dirname', source) as (
+      require: (specifier: string) => unknown,
+      module: { exports: unknown },
+      exports: unknown,
+      filename: string,
+      dirname: string,
+    ) => void;
+    evaluate(localRequire, module, module.exports, filePath, path.dirname(filePath));
+    return pickHandler(module.exports);
+  } catch {
+    return undefined;
+  }
+}
+
+function isNextDistMissing(error: unknown): boolean {
+  const message = (error as { message?: unknown }).message;
+  return typeof message === 'string' && message.includes('next/dist/');
+}
+
+function pickHandler(mod: unknown): ModernCacheHandler | undefined {
+  const candidate =
+    mod && typeof mod === 'object' && 'default' in mod
+      ? (mod as { default?: unknown }).default
+      : mod;
+  return candidate && typeof candidate === 'object' ? candidate : undefined;
+}
+
+function createDefaultExternalHandler(): ModernCacheHandler {
+  const entries = new Map<string, ModernCacheEntry>();
+  const tagExpirations = new Map<string, number>();
+  return {
+    get(cacheKey) {
+      return entries.get(cacheKey);
+    },
+    async set(cacheKey, pendingEntry) {
+      entries.set(cacheKey, await pendingEntry);
+    },
+    refreshTags() {
+      return undefined;
+    },
+    getExpiration(tags) {
+      let value = 0;
+      for (const tag of tags) value = Math.max(value, tagExpirations.get(tag) ?? 0);
+      return value;
+    },
+    updateTags(tags) {
+      const now = realNow();
+      for (const tag of tags) tagExpirations.set(tag, now);
+    },
+  };
+}
+
+function implicitSoftTags(): string[] {
+  const pathname = new URL(currentRequest()?.url ?? 'http://pnext.local/').pathname || '/';
+  const leaf = pathname === '/' ? '/index' : pathname;
+  return ['_N_T_/layout', '_N_T_/page', '_N_T_/', `_N_T_${leaf}`];
+}

package/src/compat/cache/resume-data-cache.ts

@@ -0,0 +1,143 @@
+// Resume-data-cache (RDC) - COMPAT (may import core freely). Composes the per-cache capture/seed
+// helpers into the opaque render-lifecycle capability core drives; core never imports this file.
+//
+// Artifact format (the `.rdc` file emitted next to a PPR shell, plain JSON):
+//   { "v": 1,
+//     "useCache": [ { key, value, tags, revalidateSeconds?, expireSeconds?, staleSeconds?, storedAt,
+//                     tagSeq } ... ],
+//     "fetch":    [ { key, snapshot: { status, statusText, headers, body(b64), url }, tags,
+//                     revalidateSeconds?, storedAt } ... ] }
+//
+// `key` is the exact in-memory cache key so a serving-process read lands on the same key the dynamic
+// render computes. Values are plain data only; anything else was skipped at capture and is recomputed
+// at request time.
+
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  getRequestExtensions,
+  type PrerenderSidecarContext,
+  type PrerenderSidecarExtension,
+} from '../../extensions';
+import { pathRevalidatedSince, tagsRevalidatedSince, tagsStaleSince } from './revalidate';
+import {
+  beginUseCacheRdcCapture,
+  collectUseCacheRdcRecords,
+  collectUseCacheRdcTags,
+  seedUseCacheRdcRecords,
+  type UseCacheRdcRecord,
+} from './use-cache';
+import {
+  beginFetchRdcCapture,
+  collectFetchRdcRecords,
+  seedFetchRdcRecords,
+  type FetchRdcRecord,
+} from './fetch-patch';
+
+export interface ResumeDataArtifact {
+  v: 1;
+  useCache: UseCacheRdcRecord[];
+  fetch: FetchRdcRecord[];
+  /**
+   * Union of every captured cache tag - including tags of entries too complex to serialize as records
+   * (page-level `use cache` trees). isStale() must see them or updateTag()/revalidateTag() can never
+   * stale the prebuilt shell.
+   */
+  tags?: string[];
+}
+
+function isArtifact(value: unknown): value is ResumeDataArtifact {
+  const artifact = value as Partial<ResumeDataArtifact> | null;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    artifact?.v === 1 &&
+    Array.isArray(artifact.useCache) &&
+    Array.isArray(artifact.fetch)
+  );
+}
+
+function artifactPath(context: PrerenderSidecarContext): string {
+  return path.join(context.outPath, 'ppr', `${context.routeId}.rdc`);
+}
+
+function shellPath(context: PrerenderSidecarContext): string {
+  return path.join(context.outPath, 'ppr', `${context.routeId}.html`);
+}
+
+async function sidecarFreshnessAt(context: PrerenderSidecarContext): Promise<number | undefined> {
+  for (const file of [shellPath(context), artifactPath(context)]) {
+    try {
+      return (await stat(file)).mtimeMs;
+    } catch {
+      // Try the fallback artifact when unit-testing the extension directly.
+    }
+  }
+  return undefined;
+}
+
+async function readArtifact(context: PrerenderSidecarContext): Promise<ResumeDataArtifact | undefined> {
+  try {
+    const artifact = JSON.parse(await readFile(artifactPath(context), 'utf8')) as unknown;
+    return isArtifact(artifact) ? artifact : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export const resumeDataCacheExtension: PrerenderSidecarExtension = {
+  begin() {
+    beginUseCacheRdcCapture();
+    beginFetchRdcCapture();
+  },
+  async collect() {
+    const useCache = await collectUseCacheRdcRecords();
+    const fetch = await collectFetchRdcRecords();
+    const tags = await collectUseCacheRdcTags();
+    if (useCache.length === 0 && fetch.length === 0 && tags.length === 0) return undefined;
+    return {
+      v: 1,
+      useCache,
+      fetch,
+      ...(tags.length > 0 ? { tags } : {}),
+    } satisfies ResumeDataArtifact;
+  },
+  async persist(context, artifact) {
+    if (!isArtifact(artifact)) return;
+    const file = artifactPath(context);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(artifact));
+  },
+  async seed(context) {
+    const artifact = await readArtifact(context);
+    if (!artifact) return;
+    seedUseCacheRdcRecords(artifact.useCache, context.routePath);
+    seedFetchRdcRecords(artifact.fetch, context.routePath, artifact.tags ?? []);
+  },
+  async isStale(context) {
+    const freshnessAt = await sidecarFreshnessAt(context);
+    if (freshnessAt !== undefined && pathRevalidatedSince(context.routePath, freshnessAt)) {
+      return true;
+    }
+    const artifact = await readArtifact(context);
+    if (!artifact) return false;
+    const tags = [
+      ...(artifact.tags ?? []),
+      ...artifact.useCache.flatMap(record => record.tags),
+      ...artifact.fetch.flatMap(record => record.tags),
+    ];
+    if (
+      freshnessAt !== undefined &&
+      getRequestExtensions().staticStaleness(context.routePath, freshnessAt, tags)
+    ) {
+      return true;
+    }
+    // Soft revalidations (revalidateTag with a nonzero-expiry profile) mark tags stale rather than
+    // hard-revalidated. A PPR shell whose data carries a stale tag must regenerate on the next request -
+    // the shell IS the data, since the values are baked into the prerendered HTML, so unlike ISR there
+    // is no softer way to refresh it.
+    if (freshnessAt === undefined) return false;
+    if (tagsRevalidatedSince(tags, freshnessAt)) return true;
+    return tagsStaleSince(tags, freshnessAt) ? 'soft' : false;
+  },
+};