@rangojs/router 0.0.0-experimental.0f44aca1

package/src/vite/plugins/use-cache-transform.ts

@@ -0,0 +1,323 @@
+/**
+ * "use cache" Vite Transform Plugin
+ *
+ * Detects "use cache" directives at file-level and function-level,
+ * then wraps exports with registerCachedFunction() from the cache runtime.
+ *
+ * File-level: "use cache" at top of file wraps all exports (except
+ * layout/template default exports which receive children).
+ *
+ * Function-level: "use cache: profileName" inside a function body
+ * hoists the function and wraps it.
+ *
+ * Uses transform helpers from @vitejs/plugin-rsc/transforms:
+ * - hasDirective() for file-level detection
+ * - transformWrapExport() for file-level wrapping
+ * - transformHoistInlineDirective() for function-level hoisting
+ */
+
+import type { Plugin } from "vite";
+import path from "node:path";
+import MagicString from "magic-string";
+import { normalizePath, hashId } from "./expose-id-utils.js";
+
+const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
+
+// Files whose default export receives {children} from the framework
+// and should not be wrapped (children can't be cache-keyed).
+const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+
+export function useCacheTransform(): Plugin {
+  let projectRoot = "";
+  let isBuild = false;
+  let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null =
+    null;
+
+  return {
+    name: "@rangojs/router:use-cache",
+    enforce: "post",
+
+    configResolved(config) {
+      projectRoot = config.root;
+      isBuild = config.command === "build";
+    },
+
+    async transform(code, id) {
+      // Only process in RSC environment
+      if (this.environment?.name !== "rsc") return;
+
+      // Quick bail: no "use cache" in source
+      if (!code.includes("use cache")) return;
+
+      // Skip node_modules and virtual modules
+      if (id.includes("/node_modules/") || id.startsWith("\0")) return;
+
+      // Only JS/TS files
+      if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
+
+      // Lazy-load transform helpers
+      if (!rscTransforms) {
+        try {
+          rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+        } catch {
+          return;
+        }
+      }
+
+      const {
+        hasDirective,
+        transformWrapExport,
+        transformHoistInlineDirective,
+      } = rscTransforms;
+
+      // Parse AST
+      let ast: any;
+      try {
+        const { parseAst } = await import("vite");
+        ast = parseAst(code);
+      } catch {
+        return;
+      }
+
+      const filePath = normalizePath(path.relative(projectRoot, id));
+      const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+
+      // Check for file-level "use cache"
+      if (hasDirective(ast.body, "use cache")) {
+        return transformFileLevelUseCache(
+          code,
+          ast,
+          filePath,
+          id,
+          isBuild,
+          isLayoutOrTemplate,
+          transformWrapExport,
+        );
+      }
+
+      // Check for function-level "use cache" / "use cache: profileName"
+      // (only if there's no file-level directive but code still contains the string)
+      const functionResult = transformFunctionLevelUseCache(
+        code,
+        ast,
+        filePath,
+        id,
+        isBuild,
+        transformHoistInlineDirective,
+      );
+
+      // Always check for near-miss directives, even when valid directives
+      // exist. A file may contain both valid and invalid "use cache" directives
+      // in different functions — the invalid ones should still warn.
+      warnOnNearMissDirectives(ast, id, this.warn.bind(this));
+
+      if (functionResult) return functionResult;
+    },
+  };
+}
+
+function transformFileLevelUseCache(
+  code: string,
+  ast: any,
+  filePath: string,
+  sourceId: string,
+  isBuild: boolean,
+  isLayoutOrTemplate: boolean,
+  transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
+) {
+  // Collect non-function exports to report after wrapping
+  const nonFunctionExports: string[] = [];
+
+  const { exportNames, output } = transformWrapExport(code, ast, {
+    runtime: (value: string, name: string) => {
+      const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
+    },
+    rejectNonAsyncFunction: false,
+    filter: (name: string, meta: { isFunction?: boolean }) => {
+      // Skip default export of layout/template files (they receive children)
+      if (name === "default" && isLayoutOrTemplate) return false;
+      // Non-function exports cannot be wrapped with registerCachedFunction
+      if (meta.isFunction === false) {
+        nonFunctionExports.push(name);
+        return false;
+      }
+      return true;
+    },
+  });
+
+  if (nonFunctionExports.length > 0) {
+    throw new Error(
+      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
+        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
+        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Only function exports can be cached. Either remove "use cache" from ` +
+        `the file level and add it inside individual functions, or move the ` +
+        `non-function exports to a separate module.`,
+    );
+  }
+
+  if (exportNames.length === 0) {
+    // Even if no exports were wrapped, strip the directive
+    const s = new MagicString(code);
+    const directive = findFileLevelDirective(ast);
+    if (directive) {
+      s.overwrite(
+        directive.start,
+        directive.end,
+        `/* "use cache" -- wrapped by rango */`,
+      );
+      return {
+        code: s.toString(),
+        map: s.generateMap({ source: sourceId, hires: "boundary" }),
+      };
+    }
+    return;
+  }
+
+  // Prepend the import
+  output.prepend(
+    `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
+  );
+
+  // Replace the directive with a comment
+  const directive = findFileLevelDirective(ast);
+  if (directive) {
+    output.overwrite(
+      directive.start,
+      directive.end,
+      `/* "use cache" -- wrapped by rango */`,
+    );
+  }
+
+  return {
+    code: output.toString(),
+    map: output.generateMap({ source: sourceId, hires: "boundary" }),
+  };
+}
+
+function transformFunctionLevelUseCache(
+  code: string,
+  ast: any,
+  filePath: string,
+  sourceId: string,
+  isBuild: boolean,
+  transformHoistInlineDirective: (typeof import("@vitejs/plugin-rsc/transforms"))["transformHoistInlineDirective"],
+) {
+  try {
+    const { output, names } = transformHoistInlineDirective(code, ast, {
+      directive: /^use cache(:\s*[\w-]+)?$/,
+      runtime: (
+        value: string,
+        name: string,
+        meta: { directiveMatch: RegExpMatchArray },
+      ) => {
+        const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+        const profileMatch = meta.directiveMatch[1];
+        const profileName = profileMatch
+          ? profileMatch.replace(/^:\s*/, "").trim()
+          : "default";
+        return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, ${JSON.stringify(profileName)})`;
+      },
+      rejectNonAsyncFunction: false,
+    });
+
+    if (names.length === 0) return;
+
+    // Use a top-level import instead of await import() — the hoisted wrapper
+    // may be placed in a non-async context (e.g., inside a synchronous
+    // urls() callback) where await is not allowed.
+    output.prepend(
+      `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
+    );
+
+    return {
+      code: output.toString(),
+      map: output.generateMap({ source: sourceId, hires: "boundary" }),
+    };
+  } catch {
+    // Transform failed (e.g., syntax not supported), skip
+    return;
+  }
+}
+
+/**
+ * Find the file-level "use cache" directive AST node for removal.
+ */
+function findFileLevelDirective(
+  ast: any,
+): { start: number; end: number } | null {
+  for (const node of ast.body ?? []) {
+    if (
+      node.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string" &&
+      node.expression.value.startsWith("use cache")
+    ) {
+      return { start: node.start, end: node.end };
+    }
+  }
+  return null;
+}
+
+/**
+ * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
+ */
+const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
+
+/**
+ * Regex for near-miss: starts with "use cache:" but has invalid tokens.
+ */
+const NEAR_MISS_RE = /^use cache:\s*.+$/;
+
+/**
+ * Walk the AST looking for string literals that look like malformed
+ * "use cache" directives and emit a Vite warning for each.
+ *
+ * This catches cases like `"use cache: bad.name"` or `"use cache: "`
+ * that the transform regex silently ignores.
+ */
+function warnOnNearMissDirectives(
+  ast: any,
+  fileId: string,
+  warn: (message: string) => void,
+): void {
+  const visit = (node: any) => {
+    if (!node || typeof node !== "object") return;
+
+    if (
+      node.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string"
+    ) {
+      const value = node.expression.value;
+      if (
+        value.startsWith("use cache") &&
+        NEAR_MISS_RE.test(value) &&
+        !VALID_DIRECTIVE_RE.test(value)
+      ) {
+        const profilePart = value.slice("use cache:".length).trim();
+        warn(
+          `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`,
+        );
+      }
+    }
+
+    // Walk into function bodies where directives appear
+    for (const key of Object.keys(node)) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          visit(item);
+        }
+      } else if (child && typeof child === "object" && child.type) {
+        visit(child);
+      }
+    }
+  };
+
+  for (const node of ast.body ?? []) {
+    visit(node);
+  }
+}

package/src/vite/plugins/version-injector.ts

@@ -0,0 +1,83 @@
+import type { Plugin } from "vite";
+import { resolve } from "node:path";
+import * as Vite from "vite";
+
+/**
+ * Plugin that auto-injects VERSION and routes-manifest into custom entry.rsc files.
+ * If a custom entry.rsc file uses createRSCHandler but doesn't pass version,
+ * this transform adds the import and property automatically.
+ * Also ensures the routes-manifest virtual module is always imported.
+ * @internal
+ */
+export function createVersionInjectorPlugin(
+  rscEntryPath: string | undefined,
+): Plugin {
+  let resolvedEntryPath = "";
+
+  return {
+    name: "@rangojs/router:version-injector",
+    enforce: "pre",
+
+    configResolved(config) {
+      let entryPath = rscEntryPath;
+      // Cloudflare preset: read entry from resolved environment config.
+      // The @cloudflare/vite-plugin reads wrangler config (toml/json/jsonc)
+      // and sets optimizeDeps.entries on the RSC environment.
+      if (!entryPath) {
+        const rscEnvConfig = (config.environments as any)?.["rsc"];
+        const entries = rscEnvConfig?.optimizeDeps?.entries;
+        if (typeof entries === "string") {
+          entryPath = entries;
+        } else if (Array.isArray(entries) && entries.length > 0) {
+          entryPath = entries[0];
+        }
+      }
+      if (entryPath) {
+        resolvedEntryPath = resolve(config.root, entryPath);
+      }
+    },
+
+    transform(code, id) {
+      if (!resolvedEntryPath) return null;
+      // Only transform the RSC entry file
+      const normalizedId = Vite.normalizePath(id);
+      const normalizedEntry = Vite.normalizePath(resolvedEntryPath);
+
+      if (normalizedId !== normalizedEntry) {
+        return null;
+      }
+
+      // Prepend imports at the top of the file. ES imports are hoisted
+      // by the module system, so source position is irrelevant.
+      const prepend: string[] = [];
+      let newCode = code;
+
+      if (!code.includes("virtual:rsc-router/routes-manifest")) {
+        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
+      }
+
+      // Auto-inject VERSION if file uses createRSCHandler without version
+      const needsVersion =
+        code.includes("createRSCHandler") &&
+        !code.includes("@rangojs/router:version") &&
+        /createRSCHandler\s*\(\s*\{/.test(code);
+
+      if (needsVersion) {
+        prepend.push(`import { VERSION } from "@rangojs/router:version";`);
+        newCode = newCode.replace(
+          /createRSCHandler\s*\(\s*\{/,
+          "createRSCHandler({\n  version: VERSION,",
+        );
+      }
+
+      if (prepend.length === 0 && newCode === code) return null;
+
+      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+
+      return {
+        code: newCode,
+        map: null,
+      };
+    },
+  };
+}

package/src/vite/plugins/version-plugin.ts

@@ -0,0 +1,254 @@
+import { parseAst, type Plugin } from "vite";
+import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
+
+interface ClientModuleSignature {
+  key: string;
+}
+
+function isCodeModule(id: string): boolean {
+  return /\.(tsx?|jsx?)($|\?)/.test(id);
+}
+
+function normalizeModuleId(id: string): string {
+  return id.split("?", 1)[0];
+}
+
+function getClientModuleSignature(
+  source: string,
+): ClientModuleSignature | undefined {
+  let program: any;
+  try {
+    program = parseAst(source, { jsx: true });
+  } catch {
+    return undefined;
+  }
+
+  let isUseClient = false;
+  for (const node of program.body ?? []) {
+    if (
+      node?.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string"
+    ) {
+      if (node.expression.value === "use client") {
+        isUseClient = true;
+      }
+      continue;
+    }
+    break;
+  }
+
+  if (!isUseClient) return undefined;
+
+  const exports = new Set<string>();
+  let hasDefault = false;
+  let hasExportAll = false;
+
+  const collectBindingNames = (pattern: any) => {
+    if (!pattern) return;
+    if (pattern.type === "Identifier") {
+      exports.add(pattern.name);
+    } else if (pattern.type === "ObjectPattern") {
+      for (const prop of pattern.properties ?? []) {
+        if (prop?.type === "RestElement") {
+          collectBindingNames(prop.argument);
+        } else {
+          collectBindingNames(prop?.value);
+        }
+      }
+    } else if (pattern.type === "ArrayPattern") {
+      for (const el of pattern.elements ?? []) {
+        if (el?.type === "RestElement") {
+          collectBindingNames(el.argument);
+        } else {
+          collectBindingNames(el);
+        }
+      }
+    }
+  };
+
+  const collectDeclarationNames = (declaration: any) => {
+    if (!declaration) return;
+    if (declaration.type === "VariableDeclaration") {
+      for (const decl of declaration.declarations ?? []) {
+        collectBindingNames(decl?.id);
+      }
+      return;
+    }
+    collectBindingNames(declaration.id);
+  };
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") {
+      hasDefault = true;
+      continue;
+    }
+    if (node?.type === "ExportAllDeclaration") {
+      hasExportAll = true;
+      continue;
+    }
+    if (node?.type !== "ExportNamedDeclaration") continue;
+
+    collectDeclarationNames(node.declaration);
+
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") {
+        hasDefault = true;
+      } else if (typeof exportedName === "string") {
+        exports.add(exportedName);
+      }
+    }
+  }
+
+  return {
+    key: JSON.stringify({
+      default: hasDefault,
+      exportAll: hasExportAll,
+      exports: [...exports].sort(),
+    }),
+  };
+}
+
+/**
+ * Plugin providing rsc-router:version virtual module.
+ * Exports VERSION that changes when RSC modules change (dev) or at build time (production).
+ *
+ * The version is used for:
+ * 1. Cache invalidation - CFCacheStore uses VERSION to invalidate stale cache
+ * 2. Version mismatch detection - client sends version, server reloads on mismatch
+ *
+ * In dev mode, the version updates when:
+ * - Server starts (initial version)
+ * - RSC modules change via HMR (triggers version module invalidation)
+ *
+ * Client-only HMR changes don't update the version since they don't affect
+ * server-rendered content or cached RSC payloads.
+ * @internal
+ */
+export function createVersionPlugin(): Plugin {
+  // Generate version at plugin creation time (build/server start)
+  const buildVersion = Date.now().toString(16);
+  let currentVersion = buildVersion;
+  let isDev = false;
+  let server: any = null;
+  const clientModuleSignatures = new Map<string, ClientModuleSignature>();
+
+  const bumpVersion = (reason: string) => {
+    currentVersion = Date.now().toString(16);
+    console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
+
+    const rscEnv = server?.environments?.rsc;
+    const versionMod = rscEnv?.moduleGraph?.getModuleById(
+      "\0" + VIRTUAL_IDS.version,
+    );
+    if (versionMod) {
+      rscEnv.moduleGraph.invalidateModule(versionMod);
+    }
+  };
+
+  return {
+    name: "@rangojs/router:version",
+    enforce: "pre",
+
+    configResolved(config) {
+      isDev = config.command === "serve";
+    },
+
+    configureServer(devServer) {
+      server = devServer;
+
+      devServer.watcher.on("unlink", (filePath) => {
+        if (!isDev) return;
+        if (!clientModuleSignatures.has(filePath)) return;
+        clientModuleSignatures.delete(filePath);
+        bumpVersion("Client module removed");
+      });
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_IDS.version) {
+        return "\0" + id;
+      }
+      return null;
+    },
+
+    load(id) {
+      if (id === "\0" + VIRTUAL_IDS.version) {
+        return getVirtualVersionContent(currentVersion);
+      }
+      return null;
+    },
+
+    transform(code, id) {
+      if (!isDev || !isCodeModule(id)) return null;
+      const normalizedId = normalizeModuleId(id);
+      if (
+        !code.includes("use client") &&
+        !clientModuleSignatures.has(normalizedId)
+      ) {
+        return null;
+      }
+
+      const signature = getClientModuleSignature(code);
+      if (signature) {
+        clientModuleSignatures.set(normalizedId, signature);
+      } else {
+        clientModuleSignatures.delete(normalizedId);
+      }
+      return null;
+    },
+
+    // Track RSC module changes and update version
+    async hotUpdate(ctx) {
+      if (!isDev) return;
+
+      // Check if this is an RSC environment update (not client/ssr)
+      // RSC modules affect server-rendered content and cached payloads
+      // In Vite 6, environment is accessed via `this.environment`
+      const isRscModule = this.environment?.name === "rsc";
+
+      if (!isRscModule) return;
+
+      if (isCodeModule(ctx.file)) {
+        const filePath = normalizeModuleId(ctx.file);
+        const previousSignature = clientModuleSignatures.get(filePath);
+        try {
+          const source = await ctx.read();
+          const nextSignature = getClientModuleSignature(source);
+          if (nextSignature) {
+            // "use client" file — compare export signatures.
+            // client-component-hmr may have cleared ctx.modules, so we
+            // cannot rely on ctx.modules.length for these files.
+            clientModuleSignatures.set(filePath, nextSignature);
+            if (
+              previousSignature &&
+              previousSignature.key === nextSignature.key
+            ) {
+              return;
+            }
+          } else {
+            clientModuleSignatures.delete(filePath);
+            if (!previousSignature) {
+              // Not and never was "use client" — use module graph check.
+              // ctx.modules is reliable for pure server files (only
+              // client-component-hmr clears it for "use client" modules).
+              if (ctx.modules.length === 0) return;
+            }
+            // Was "use client" but directive removed — boundary changed,
+            // bump below.
+          }
+        } catch {
+          // Fail open: if we can't read or parse the update, invalidate.
+        }
+      } else {
+        // Non-code file (json, css, etc.) — only bump if it's actually
+        // referenced by the RSC module graph.
+        if (ctx.modules.length === 0) return;
+      }
+
+      bumpVersion("RSC module changed");
+    },
+  };
+}

package/src/vite/plugins/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Type declarations for rsc-router:version virtual module.
+ * This module is provided by the Vite plugin at build/dev time.
+ */
+
+declare module "@rangojs/router:version" {
+  /**
+   * Auto-generated version string for cache invalidation.
+   * Changes on server restart (dev) or build (prod).
+   */
+  export const VERSION: string;
+}