@rangojs/router 0.0.0-experimental.0f44aca1

package/src/vite/plugins/expose-ids/handler-transform.ts

@@ -0,0 +1,179 @@
+import MagicString from "magic-string";
+import { hashId } from "../expose-id-utils.js";
+import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
+import { isExportOnlyFile } from "./export-analysis.js";
+
+function analyzeCreateHandleArgs(
+  code: string,
+  startPos: number,
+  endPos: number,
+): { hasArgs: boolean } {
+  const content = code.slice(startPos, endPos).trim();
+  return { hasArgs: content.length > 0 };
+}
+
+export function transformHandles(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const args = analyzeCreateHandleArgs(
+      code,
+      binding.callOpenParenPos + 1,
+      binding.callCloseParenPos,
+    );
+
+    const handleId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    let paramInjection: string;
+    if (!args.hasArgs) {
+      paramInjection = `undefined, "${handleId}"`;
+    } else {
+      paramInjection = `, "${handleId}"`;
+    }
+    s.appendLeft(binding.callCloseParenPos, paramInjection);
+
+    const propInjection = `\n${binding.localName}.$$id = "${handleId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}
+
+export function transformLocationState(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const stateKey = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Key is injected as a property assignment (not as a function argument).
+    // This allows createLocationState to accept options like { flash: true }
+    // without conflicting with key injection.
+    const propInjection = `\n${binding.localName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}
+
+/**
+ * Replace the entire file with lightweight stubs when ALL non-type exports are
+ * handler calls of the given type. Returns null for files with mixed exports.
+ */
+export function generateWholeFileStubs(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): { code: string; map: null } | null {
+  if (!isExportOnlyFile(code, bindings)) return null;
+
+  const exportNames = bindings.flatMap((b) => b.exportNames);
+  const stubs = exportNames.map((name) => {
+    const handlerId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+    return `export const ${name} = { __brand: "${cfg.brand}", $$id: "${handlerId}" };`;
+  });
+
+  return { code: stubs.join("\n") + "\n", map: null };
+}
+
+/**
+ * Replace handler call expressions with lightweight stub objects in non-RSC
+ * environments. Other exports, imports, and module-level code remain untouched.
+ */
+export function generateExprStubs(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  code: string,
+  filePath: string,
+  sourceId: string,
+  isBuild: boolean,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  if (bindings.length === 0) return null;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    s.overwrite(
+      binding.callExprStart,
+      binding.callCloseParenPos + 1,
+      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
+    );
+    hasChanges = true;
+  }
+
+  if (!hasChanges) return null;
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({
+      source: sourceId,
+      includeContent: true,
+      hires: "boundary",
+    }),
+  };
+}
+
+/**
+ * Inject $$id into export const handler calls in RSC environments.
+ */
+export function transformHandlerIds(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Injection strategy matches the runtime overload signatures:
+    //   0 args                              -> inject undefined, "id"
+    //   1 arg  (handler)                    -> inject , undefined, "id"
+    //   2+ args                             -> inject , "id"
+    let paramInjection: string;
+    if (binding.argCount === 0) {
+      paramInjection = `undefined, "${handlerId}"`;
+    } else if (binding.argCount === 1) {
+      paramInjection = `, undefined, "${handlerId}"`;
+    } else {
+      paramInjection = `, "${handlerId}"`;
+    }
+    s.appendLeft(binding.callCloseParenPos, paramInjection);
+
+    const propInjection = `\n${binding.localName}.$$id = "${handlerId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}

package/src/vite/plugins/expose-ids/loader-transform.ts

@@ -0,0 +1,74 @@
+import type MagicString from "magic-string";
+import { hashId } from "../expose-id-utils.js";
+import type { CreateExportBinding } from "./types.js";
+import { isExportOnlyFile } from "./export-analysis.js";
+
+export function hasCreateLoaderImport(code: string): boolean {
+  return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
+    code,
+  );
+}
+
+/**
+ * Generate lightweight client stubs for loader files.
+ *
+ * When a loader file is imported from a client component (e.g., for useLoader()),
+ * the client only needs { __brand: "loader", $$id: "..." } objects.
+ * This function replaces the entire file contents with just those stub exports,
+ * preventing server-only data (constants, DB queries, etc.) from leaking into
+ * the client bundle.
+ *
+ * Only applies when ALL named exports are createLoader() calls (plus type exports
+ * which are erased at compile time). Files with mixed exports are left untouched.
+ */
+export function generateClientLoaderStubs(
+  bindings: CreateExportBinding[],
+  code: string,
+  filePath: string,
+  isBuild: boolean,
+): { code: string; map?: undefined } | null {
+  if (!isExportOnlyFile(code, bindings)) return null;
+
+  const lines: string[] = [];
+
+  for (const binding of bindings) {
+    for (const name of binding.exportNames) {
+      const loaderId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      lines.push(
+        `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`,
+      );
+    }
+  }
+
+  return { code: lines.join("\n") + "\n" };
+}
+
+export function transformLoaders(
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+
+    const loaderId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    // Inject $$id as hidden third parameter.
+    // createLoader(fn) -> createLoader(fn, undefined, "id")
+    // createLoader(fn, true) -> createLoader(fn, true, "id")
+    const paramInjection =
+      binding.argCount === 1 ? `, undefined, "${loaderId}"` : `, "${loaderId}"`;
+    s.appendLeft(binding.callCloseParenPos, paramInjection);
+
+    const propInjection = `\n${binding.localName}.$$id = "${loaderId}";`;
+    s.appendRight(binding.statementEnd, propInjection);
+    hasChanges = true;
+  }
+
+  return hasChanges;
+}

package/src/vite/plugins/expose-ids/router-transform.ts

@@ -0,0 +1,110 @@
+import type { Plugin } from "vite";
+import MagicString from "magic-string";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { normalizePath, findMatchingParen } from "../expose-id-utils.js";
+import { getImportedFnNames } from "./export-analysis.js";
+
+export function transformRouter(
+  code: string,
+  filePath: string,
+  routerFnNames: string[],
+  absolutePath?: string,
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  const pat = new RegExp(
+    `\\b(?:${routerFnNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`,
+    "g",
+  );
+  let match: RegExpExecArray | null;
+  const s = new MagicString(code);
+  let changed = false;
+
+  // Compute the import path for the generated route names file.
+  // filePath is relative to project root (e.g., "src/router.tsx")
+  const basename = path.basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
+  const routeNamesImport = `./${basename}.named-routes.gen.js`;
+  const routeNamesVar = `__rsc_rn`;
+
+  while ((match = pat.exec(code)) !== null) {
+    const callStart = match.index;
+    const parenPos = match.index + match[0].length - 1;
+
+    // Scope the $$id check to within this call's arguments only,
+    // not the entire remaining file.
+    const closeParen = findMatchingParen(code, parenPos + 1);
+    const callArgs = code.slice(parenPos + 1, closeParen);
+
+    // Skip if $$id is already present in this call
+    if (callArgs.includes("$$id")) continue;
+
+    // Compute line number for this call
+    const lineNumber = code.slice(0, callStart).split("\n").length;
+    const hash = createHash("sha256")
+      .update(`${filePath}:${lineNumber}`)
+      .digest("hex")
+      .slice(0, 8);
+
+    changed = true;
+    // $$sourceFile uses the absolute path so that downstream consumers
+    // (virtual-module-codegen, runtime-discovery) can resolve gen file
+    // imports correctly via path.dirname / path.join.
+    const sourceFilePath = absolutePath ?? filePath;
+    const injected = ` $$id: "${hash}", $$sourceFile: "${sourceFilePath}", $$routeNames: ${routeNamesVar},`;
+
+    const afterParen = callArgs.trimStart();
+    if (afterParen.startsWith("{")) {
+      const bracePos = code.indexOf("{", parenPos + 1);
+      s.appendRight(bracePos + 1, injected);
+    } else if (afterParen.startsWith(")")) {
+      s.appendRight(parenPos + 1, `{${injected} }`);
+    }
+  }
+
+  if (!changed) return null;
+
+  // Prepend the static import as the first line. MagicString tracks the
+  // offset so all downstream source maps remain correct.
+  s.prepend(
+    `import { NamedRoutes as ${routeNamesVar} } from "${routeNamesImport}";\n`,
+  );
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true }),
+  };
+}
+
+/**
+ * Inject stable $$id into createRouter() calls at compile time.
+ * This must be a separate plugin without enforce:"post" because running
+ * at "post" priority changes Vite's dep optimization timing and can cause
+ * ERR_OUTDATED_OPTIMIZED_DEP / React dual-instance issues.
+ */
+export function exposeRouterId(): Plugin {
+  let projectRoot = "";
+  return {
+    name: "@rangojs/router:expose-router-id",
+    configResolved(config) {
+      projectRoot = config.root;
+    },
+    transform(code, id) {
+      if (!code.includes("createRouter")) return null;
+      // Accepts both @rangojs/router and @rangojs/router/server subpath.
+      // NOTE: detectImports in expose-id-utils has a stricter check that
+      // excludes /server for its router flag -- that's intentional since
+      // detectImports is only used in exposeInternalIds, not here.
+      if (
+        !/import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
+          code,
+        )
+      ) {
+        return null;
+      }
+      if (id.includes("node_modules")) return null;
+
+      const filePath = normalizePath(path.relative(projectRoot, id));
+      const routerFnNames = getImportedFnNames(code, "createRouter");
+      return transformRouter(code, filePath, routerFnNames, normalizePath(id));
+    },
+  };
+}

package/src/vite/plugins/expose-ids/types.ts

@@ -0,0 +1,45 @@
+export interface HandlerTransformConfig {
+  fnName: string;
+  brand: string;
+}
+
+export interface CreateExportBinding {
+  localName: string;
+  exportNames: string[];
+  callExprStart: number;
+  callOpenParenPos: number;
+  callCloseParenPos: number;
+  argCount: number;
+  statementEnd: number;
+}
+
+export interface StrictCreateTransformConfig {
+  fnName: "createLoader" | "createHandle" | "createLocationState";
+}
+
+export const PRERENDER_CONFIG: HandlerTransformConfig = {
+  fnName: "Prerender",
+  brand: "prerenderHandler",
+};
+
+export const STATIC_CONFIG: HandlerTransformConfig = {
+  fnName: "Static",
+  brand: "staticHandler",
+};
+
+export const STRICT_CREATE_CONFIGS: StrictCreateTransformConfig[] = [
+  { fnName: "createLoader" },
+  { fnName: "createHandle" },
+  { fnName: "createLocationState" },
+];
+
+export interface ExposeInternalIdsApi {
+  /** 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[]>;
+  /** Tracks absolute module IDs that contain static handler exports.
+   *  key: absolute module ID (filesystem path)
+   *  value: array of export names (e.g., ["DocsNav", "DocShell"]) */
+  staticHandlerModules: Map<string, string[]>;
+}