@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/vite/debug.ts

@@ -0,0 +1,185 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+
+import debugFactory from "debug";
+
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+  chunks: "rango:chunks",
+} as const;
+
+// Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
+// console.logs in this plugin. Map it to `rango:*` so those call sites can
+// be migrated to the `debug` pipeline without breaking existing setups.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): Debugger | undefined {
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
+  return undefined;
+}
+
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
 import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -71,12 +72,12 @@ export function postprocessBundle(state: DiscoveryState): void {
           writeFileSync(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
-            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+            `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
           );
         }
       } catch (replaceErr: any) {
         console.warn(
-          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
+          `[rango] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
     }
@@ -104,7 +105,7 @@ export function postprocessBundle(state: DiscoveryState): void {
         }
 
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           "",
@@ -121,11 +122,11 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
+          `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write prerender assets: ${err.message}`,
+          `[rango] Failed to write prerender assets: ${err.message}`,
         );
       }
     }
@@ -169,11 +170,11 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
+          `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write static assets: ${err.message}`,
+          `[rango] Failed to write static assets: ${err.message}`,
         );
       }
     }

package/src/vite/discovery/dev-prerender-cache.ts

@@ -0,0 +1,117 @@
+/**
+ * Dev prerender result cache — memoizes /__rsc_prerender responses between
+ * HMR edits (issue #654).
+ *
+ * Freshness invariant (why identity keying is correct): the endpoint
+ * re-imports the user's entry module through a Vite module runner on every
+ * request. When ANY module in the entry → router → urls → handler chain was
+ * invalidated (file edit propagates up the importer graph), that import
+ * re-executes the entry, `createRouter()` re-runs, and `RouterRegistry.set`
+ * (router.ts) replaces the router instance with a NEW object. When nothing
+ * was invalidated, the import is a module-cache hit and the instance is the
+ * SAME object. Router-instance identity therefore IS the HMR generation:
+ * keying the cache on it gives "serve cached until an edit invalidates the
+ * chain" without any watcher bookkeeping, and the WeakMap lets every stale
+ * generation's bucket be garbage-collected the moment the registry drops
+ * the old instance.
+ *
+ * Staleness envelope: a cached body can only go stale through NON-module
+ * inputs (a getParams() reading a database, fs content outside the module
+ * graph). Production freezes those at build time, so serving them frozen
+ * between edits makes dev MORE faithful to production, not less — the
+ * pre-#654 behavior of re-rendering per request was the anomaly.
+ */
+
+import type { SerializedSegmentData } from "../../cache/types.js";
+
+/** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
+export interface DevPrerenderMatchPayloadSource {
+  segments: SerializedSegmentData[];
+  handles: string;
+  interceptSegments?: SerializedSegmentData[];
+  interceptHandles?: string;
+}
+
+/** Serialized response bodies for the two endpoint variants of one render. */
+export interface DevPrerenderPayloadBodies {
+  /** `intercept != 1` response: the route's own segments + handles. */
+  main: string;
+  /**
+   * `intercept=1` response: main + intercept segments with the MERGED handle
+   * string. Falls back to `main` byte-for-byte when the route has no
+   * intercept segments — mirroring the endpoint's historical behavior.
+   */
+  intercept: string;
+}
+
+export interface DevPrerenderCache {
+  get(router: object, key: string): string | undefined;
+  set(router: object, key: string, body: string): void;
+}
+
+/**
+ * Derive both variant bodies from one matchForPrerender result, so a single
+ * render warms the main AND intercept cache keys (matchForPrerender computes
+ * intercept segments unconditionally either way — see prerender-match.ts
+ * step 14).
+ */
+export function payloadBodiesFromResult(
+  result: DevPrerenderMatchPayloadSource,
+): DevPrerenderPayloadBodies {
+  const main = JSON.stringify({
+    segments: result.segments,
+    handles: result.handles,
+  });
+  const intercept = result.interceptSegments?.length
+    ? JSON.stringify({
+        segments: [...result.segments, ...result.interceptSegments],
+        handles: result.interceptHandles ?? "",
+      })
+    : main;
+  return { main, intercept };
+}
+
+/**
+ * Cache key for one endpoint request shape. `pathname` and `routeName` come
+ * straight from the query; `passthrough` selects the getParams-checked match
+ * path; `intercept` selects which variant body is served. All four dimensions
+ * change the response, so all four are in the key.
+ */
+export function devPrerenderCacheKey(
+  pathname: string,
+  opts: { intercept: boolean; passthrough: boolean; routeName: string | null },
+): string {
+  return `${pathname}|i=${opts.intercept ? 1 : 0}|p=${opts.passthrough ? 1 : 0}|r=${opts.routeName ?? ""}`;
+}
+
+/**
+ * Per-router FIFO cap: a dev session that visits an unbounded set of
+ * prerendered pathnames (e.g. crawling param routes) must not grow one
+ * bucket without limit. 500 rendered payloads is far beyond any interactive
+ * session; eviction order does not matter for correctness (a miss just
+ * re-renders).
+ */
+const MAX_ENTRIES_PER_ROUTER = 500;
+
+export function createDevPrerenderCache(
+  maxEntriesPerRouter: number = MAX_ENTRIES_PER_ROUTER,
+): DevPrerenderCache {
+  const buckets = new WeakMap<object, Map<string, string>>();
+  return {
+    get(router: object, key: string): string | undefined {
+      return buckets.get(router)?.get(key);
+    },
+    set(router: object, key: string, body: string): void {
+      let bucket = buckets.get(router);
+      if (!bucket) {
+        bucket = new Map();
+        buckets.set(router, bucket);
+      }
+      if (!bucket.has(key) && bucket.size >= maxEntriesPerRouter) {
+        const oldest = bucket.keys().next().value;
+        if (oldest !== undefined) bucket.delete(oldest);
+      }
+      bucket.set(key, body);
+    },
+  };
+}