@rangojs/router 0.0.0-experimental.10

package/src/vite/expose-location-state-id.ts

@@ -0,0 +1,177 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import MagicString from "magic-string";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * Normalize path to forward slashes
+ */
+function normalizePath(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * Generate a short hash for a location state key
+ * Uses first 8 chars of SHA-256 hash for uniqueness while keeping keys short
+ * Appends export name for easier debugging: "abc123#ProductState"
+ */
+function hashLocationStateKey(filePath: string, exportName: string): string {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+
+/**
+ * Check if file imports createLocationState from rsc-router
+ */
+function hasCreateLocationStateImport(code: string): boolean {
+  // Match: import { createLocationState } from "@rangojs/router" or "@rangojs/router/client"
+  const pattern =
+    /import\s*\{[^}]*\bcreateLocationState\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
+  return pattern.test(code);
+}
+
+/**
+ * Transform export const X = createLocationState<...>() patterns to inject key
+ *
+ * The key is injected as the first parameter if not present:
+ * - createLocationState() -> createLocationState("id")
+ * - createLocationState<T>() -> createLocationState<T>("id")
+ */
+function transformLocationStateExports(
+  code: string,
+  filePath: string,
+  sourceId?: string,
+  isBuild: boolean = false
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  // Quick bail-out
+  if (!code.includes("createLocationState")) {
+    return null;
+  }
+
+  // Must have direct import from rsc-router
+  if (!hasCreateLocationStateImport(code)) {
+    return null;
+  }
+
+  // Match: export const X = createLocationState<...>(
+  // Captures the export name (X)
+  const pattern = /export\s+const\s+(\w+)\s*=\s*createLocationState\s*(?:<[^>]*>)?\s*\(/g;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+
+    // Find the end of the createLocationState(...) call
+    let parenDepth = 1;
+    let i = matchEnd;
+    while (i < code.length && parenDepth > 0) {
+      if (code[i] === "(") parenDepth++;
+      if (code[i] === ")") parenDepth--;
+      i++;
+    }
+
+    // i now points just after the closing )
+    const closeParenPos = i - 1;
+
+    // Check if there are any arguments (content between open and close paren)
+    const content = code.slice(matchEnd, closeParenPos).trim();
+    const hasArgs = content.length > 0;
+
+    // Find the semicolon or end of statement
+    let statementEnd = i;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+
+    // Generate key: hashed in production, readable in dev
+    const stateKey = isBuild
+      ? hashLocationStateKey(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Inject key as the first (and only) parameter
+    // createLocationState() -> createLocationState("id")
+    if (!hasArgs) {
+      s.appendLeft(closeParenPos, `"${stateKey}"`);
+    } else {
+      // Already has a key, skip (shouldn't happen with new API, but be safe)
+      continue;
+    }
+
+    // Also set __rsc_ls_key property for verification
+    const propInjection = `\n${exportName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  if (!hasChanges) {
+    return null;
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true }),
+  };
+}
+
+/**
+ * Vite plugin that exposes location state keys on createLocationState calls.
+ *
+ * When users create location states with createLocationState(), this plugin:
+ * 1. Injects an auto-generated key as the first parameter
+ * 2. Sets __rsc_ls_key property for verification
+ *
+ * This allows location states to be created without explicit keys:
+ * - Before: export const ProductState = createLocationState<Product>("product")
+ * - After:  export const ProductState = createLocationState<Product>()
+ *
+ * The key is auto-generated from file path + export name.
+ *
+ * Requirements:
+ * - Must use direct import: import { createLocationState } from "@rangojs/router"
+ * - Must use named export: export const MyState = createLocationState(...)
+ */
+export function exposeLocationStateId(): Plugin {
+  let config: ResolvedConfig;
+  let isBuild = false;
+
+  return {
+    name: "@rangojs/router:expose-location-state-id",
+    enforce: "post",
+
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+
+    transform(code, id) {
+      // Skip node_modules
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+
+      // Quick bail-out
+      if (!code.includes("createLocationState")) {
+        return;
+      }
+
+      // Must have direct import from rsc-router
+      if (!hasCreateLocationStateImport(code)) {
+        return;
+      }
+
+      // Get relative path for the key
+      const relativePath = normalizePath(path.relative(config.root, id));
+
+      // Transform: inject key
+      return transformLocationStateExports(code, relativePath, id, isBuild);
+    },
+  };
+}

package/src/vite/expose-prerender-handler-id.ts

@@ -0,0 +1,429 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import MagicString from "magic-string";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * Normalize path to forward slashes
+ */
+function normalizePath(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * Generate a short hash for a prerender handler ID.
+ * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short.
+ * Appends export name for easier debugging: "abc123#DocsPage"
+ */
+function hashPrerenderHandlerId(filePath: string, exportName: string): string {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+
+/**
+ * Check if file imports createPrerenderHandler from @rangojs/router
+ */
+function hasCreatePrerenderHandlerImport(code: string): boolean {
+  const pattern =
+    /import\s*\{[^}]*\bcreatePrerenderHandler\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
+  return pattern.test(code);
+}
+
+/**
+ * Skip past a string literal, template literal, or comment starting at pos.
+ * Returns the index after the closing delimiter, or pos if not at a
+ * string/comment start. Handles escape sequences and nested ${} in templates.
+ */
+function skipStringOrComment(code: string, pos: number): number {
+  const ch = code[pos];
+
+  if (ch === '"' || ch === "'") {
+    for (let j = pos + 1; j < code.length; j++) {
+      if (code[j] === "\\") { j++; continue; }
+      if (code[j] === ch) return j + 1;
+    }
+    return code.length;
+  }
+
+  if (ch === "`") {
+    let j = pos + 1;
+    while (j < code.length) {
+      if (code[j] === "\\") { j += 2; continue; }
+      if (code[j] === "`") return j + 1;
+      if (code[j] === "$" && j + 1 < code.length && code[j + 1] === "{") {
+        j += 2;
+        let braceDepth = 1;
+        while (j < code.length && braceDepth > 0) {
+          const inner = skipStringOrComment(code, j);
+          if (inner > j) { j = inner; continue; }
+          if (code[j] === "{") braceDepth++;
+          else if (code[j] === "}") braceDepth--;
+          if (braceDepth > 0) j++;
+        }
+        if (braceDepth === 0) j++;
+        continue;
+      }
+      j++;
+    }
+    return j;
+  }
+
+  if (ch === "/" && pos + 1 < code.length) {
+    if (code[pos + 1] === "/") {
+      const eol = code.indexOf("\n", pos + 2);
+      return eol === -1 ? code.length : eol + 1;
+    }
+    if (code[pos + 1] === "*") {
+      const end = code.indexOf("*/", pos + 2);
+      return end === -1 ? code.length : end + 2;
+    }
+  }
+
+  return pos;
+}
+
+/**
+ * Find the matching closing paren starting after an already-opened paren.
+ * Skips strings, template literals, and comments so parens inside them
+ * don't affect depth tracking. Returns the index after the closing paren.
+ */
+function findMatchingParen(code: string, startPos: number): number {
+  let depth = 1;
+  let i = startPos;
+  while (i < code.length && depth > 0) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) { i = skipped; continue; }
+    if (code[i] === "(") depth++;
+    if (code[i] === ")") depth--;
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Count the number of top-level arguments in a function call.
+ * Skips nested parens, brackets, braces, strings, and comments.
+ */
+function countArgs(code: string, startPos: number, endPos: number): number {
+  let depth = 0;
+  let argCount = 0;
+  let hasContent = false;
+  let i = startPos;
+
+  while (i < endPos) {
+    const skipped = skipStringOrComment(code, i);
+    if (skipped > i) { hasContent = true; i = skipped; continue; }
+
+    const char = code[i];
+    if (char === "(" || char === "[" || char === "{") {
+      depth++;
+      hasContent = true;
+    } else if (char === ")" || char === "]" || char === "}") {
+      depth--;
+    } else if (char === "," && depth === 0) {
+      argCount++;
+    } else if (!/\s/.test(char)) {
+      hasContent = true;
+    }
+    i++;
+  }
+
+  return hasContent ? argCount + 1 : 0;
+}
+
+/**
+ * Transform export const X = createPrerenderHandler(...) patterns to inject $$id.
+ *
+ * Overload shapes:
+ *   1 arg  (handler)                 -> inject undefined, "id"  (pad for options + id)
+ *   2 args (getParams+handler OR handler+options) -> inject , "id"
+ *   3 args (getParams+handler+options)            -> inject , "id"
+ *
+ * The __injectedId is always the LAST parameter.
+ */
+function transformPrerenderHandlerExports(
+  code: string,
+  filePath: string,
+  sourceId?: string,
+  isBuild: boolean = false,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  if (!code.includes("createPrerenderHandler")) {
+    return null;
+  }
+
+  if (!hasCreatePrerenderHandlerImport(code)) {
+    return null;
+  }
+
+  // Match: export const X = createPrerenderHandler<...>(
+  const pattern =
+    /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    const matchEnd = match.index + match[0].length;
+
+    // Find the matching closing paren (string/comment aware)
+    const afterClose = findMatchingParen(code, matchEnd);
+    const closeParenPos = afterClose - 1;
+    const argCount = countArgs(code, matchEnd, closeParenPos);
+
+    // Find statement end (after ; or whitespace)
+    let statementEnd = afterClose;
+    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
+      statementEnd++;
+    }
+    if (code[statementEnd] === ";") {
+      statementEnd++;
+    }
+
+    const handlerId = isBuild
+      ? hashPrerenderHandlerId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Inject $$id as the last parameter.
+    // createPrerenderHandler(handler) -> createPrerenderHandler(handler, undefined, "id")
+    // createPrerenderHandler(handler, opts) -> createPrerenderHandler(handler, opts, "id")
+    // createPrerenderHandler(getP, handler) -> createPrerenderHandler(getP, handler, undefined, "id")
+    // createPrerenderHandler(getP, handler, opts) -> createPrerenderHandler(getP, handler, opts, "id")
+    //
+    // The runtime implementation accepts __injectedId as:
+    //   Overload 1 (1 fn): 3rd param (after handler, options)
+    //   Overload 2 (2 fn): 4th param (after getParams, handler, options)
+    //
+    // We cannot statically distinguish between (handler, options) and (getParams, handler)
+    // when there are 2 args. However the runtime resolves this by checking typeof of the
+    // second arg. The __injectedId is always a string, so it can appear in either the
+    // options or id slot — the runtime handles both via typeof checks.
+    let paramInjection: string;
+    if (argCount === 0) {
+      paramInjection = `undefined, "${handlerId}"`;
+    } else if (argCount === 1) {
+      // 1 arg (handler only): need to pad for options slot
+      paramInjection = `, undefined, "${handlerId}"`;
+    } else {
+      // 2+ args: just append id
+      paramInjection = `, "${handlerId}"`;
+    }
+    s.appendLeft(closeParenPos, paramInjection);
+
+    // Set $$id property for external access
+    const propInjection = `\n${exportName}.$$id = "${handlerId}";`;
+    s.appendRight(statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  if (!hasChanges) {
+    return null;
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" }),
+  };
+}
+
+/**
+ * Replace the entire file with lightweight stubs when ALL non-type exports are
+ * createPrerenderHandler calls. This is the most aggressive eviction — all imports,
+ * module-level data, and handler bodies are removed from non-RSC bundles.
+ *
+ * Returns null for files with mixed exports (non-handler value exports),
+ * falling back to per-expression replacement.
+ */
+function generateWholeFileHandlerStubs(
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): { code: string; map: null } | null {
+  const handlerPattern =
+    /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+  const handlers: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = handlerPattern.exec(code)) !== null) {
+    handlers.push(match[1]);
+  }
+
+  if (handlers.length === 0) return null;
+
+  // Bail out if the file has re-exports or destructured exports that
+  // the declaration pattern below wouldn't catch. Replacing the whole
+  // file would silently drop these exports.
+  if (/export\s*\{/.test(code) || /export\s*\*/.test(code)) {
+    return null;
+  }
+
+  // Check that every non-type export declaration is a createPrerenderHandler call.
+  const allExports =
+    /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
+  let exportMatch: RegExpExecArray | null;
+
+  while ((exportMatch = allExports.exec(code)) !== null) {
+    const name = exportMatch[2];
+    if (!handlers.includes(name)) {
+      // Mixed exports — can't replace the whole file
+      return null;
+    }
+  }
+
+  const stubs = handlers.map((name) => {
+    const handlerId = isBuild
+      ? hashPrerenderHandlerId(filePath, name)
+      : `${filePath}#${name}`;
+    return `export const ${name} = { __brand: "prerenderHandler", $$id: "${handlerId}" };`;
+  });
+
+  return { code: stubs.join("\n") + "\n", map: null };
+}
+
+/**
+ * Replace createPrerenderHandler(...) call expressions with lightweight stub objects
+ * in non-RSC environments. Other exports, imports, and module-level code remain
+ * untouched — only the call expression is replaced.
+ *
+ * This prevents handler rendering code and build-only dependencies from shipping
+ * to client/SSR bundles where handlers never execute.
+ */
+function generatePrerenderHandlerStubs(
+  code: string,
+  filePath: string,
+  sourceId?: string,
+  isBuild: boolean = false,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  // Match: export const X = createPrerenderHandler<...>(
+  const pattern =
+    /export\s+const\s+(\w+)\s*=\s*(createPrerenderHandler\s*(?:<[^>]*>)?\s*\()/g;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(code)) !== null) {
+    const exportName = match[1];
+    // callStart points to 'c' in 'createPrerenderHandler'
+    const callStart = match.index + match[0].length - match[2].length;
+
+    // Find the matching closing paren (string/comment aware)
+    const openParenPos = match.index + match[0].length;
+    const afterCloseParen = findMatchingParen(code, openParenPos);
+
+    const handlerId = isBuild
+      ? hashPrerenderHandlerId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Replace createPrerenderHandler<...>(...) with stub object
+    s.overwrite(
+      callStart,
+      afterCloseParen,
+      `{ __brand: "prerenderHandler", $$id: "${handlerId}" }`,
+    );
+    hasChanges = true;
+  }
+
+  if (!hasChanges) return null;
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true, hires: "boundary" }),
+  };
+}
+
+/**
+ * Plugin API type for expose-prerender-handler-id.
+ * Accessed by other plugins via config.plugins.find(p => p.name === "...").api
+ */
+export interface ExposePrerenderHandlerIdApi {
+  /** Tracks absolute module IDs that contain prerender handler exports.
+   *  key: absolute module ID (filesystem path)
+   *  value: array of export names (e.g., ["ArticlesIndex", "ArticleDetail"]) */
+  prerenderHandlerModules: Map<string, string[]>;
+}
+
+/**
+ * Vite plugin that exposes $$id on createPrerenderHandler calls.
+ *
+ * When users create prerender handlers with createPrerenderHandler(), this plugin:
+ * - RSC environment: Injects $$id into the call and sets a $$id property on the export
+ * - Non-RSC environments (client/SSR): Replaces createPrerenderHandler(...) call
+ *   expressions with lightweight { __brand, $$id } stubs, keeping other exports intact
+ *
+ * Requirements:
+ * - Must use direct import: import { createPrerenderHandler } from "@rangojs/router"
+ * - Must use named export: export const MyPage = createPrerenderHandler(...)
+ *
+ * Other plugins can read handler module data via the plugin API:
+ *   config.plugins.find(p => p.name === "@rangojs/router:expose-prerender-handler-id")?.api
+ */
+export function exposePrerenderHandlerId(): Plugin {
+  let config: ResolvedConfig;
+  let isBuild = false;
+  const prerenderHandlerModules: Map<string, string[]> = new Map();
+
+  return {
+    name: "@rangojs/router:expose-prerender-handler-id",
+    enforce: "post",
+
+    api: {
+      prerenderHandlerModules,
+    } satisfies ExposePrerenderHandlerIdApi,
+
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+    },
+
+    transform(code, id) {
+      // Skip node_modules
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+
+      // Quick bail-out
+      if (!code.includes("createPrerenderHandler")) {
+        return;
+      }
+
+      // Must have direct import from @rangojs/router
+      if (!hasCreatePrerenderHandlerImport(code)) {
+        return;
+      }
+
+      // Get relative path for the ID
+      const relativePath = normalizePath(path.relative(config.root, id));
+
+      const isRscEnv = this.environment?.name === "rsc";
+
+      if (!isRscEnv) {
+        // Non-RSC: try whole-file replacement first (all exports are handlers),
+        // fall back to per-expression replacement for mixed-export files
+        return (
+          generateWholeFileHandlerStubs(code, relativePath, isBuild) ??
+          generatePrerenderHandlerStubs(code, relativePath, id, isBuild)
+        );
+      }
+
+      // RSC build: record this module and its handler export names for chunk isolation
+      if (isBuild) {
+        const handlerPattern =
+          /export\s+const\s+(\w+)\s*=\s*createPrerenderHandler\s*(?:<[^>]*>)?\s*\(/g;
+        const exportNames: string[] = [];
+        let m: RegExpExecArray | null;
+        while ((m = handlerPattern.exec(code)) !== null) {
+          exportNames.push(m[1]);
+        }
+        if (exportNames.length > 0) {
+          prerenderHandlerModules.set(id, exportNames);
+        }
+      }
+
+      // RSC: inject $$id into calls (existing behavior)
+      return transformPrerenderHandlerExports(code, relativePath, id, isBuild);
+    },
+  };
+}