@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/src/vite/__tests__/expose-loader-id.test.ts

@@ -1,117 +0,0 @@
-import { describe, it, expect } from "vitest";
-
-/**
- * Mock function to test createLoader detection patterns
- */
-function hasCreateLoaderImport(code: string): boolean {
-  const pattern = /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/;
-  return pattern.test(code);
-}
-
-/**
- * Extract loader exports from code
- */
-function extractLoaderExports(code: string): string[] {
-  const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
-  const exports: string[] = [];
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(code)) !== null) {
-    exports.push(match[1]);
-  }
-  return exports;
-}
-
-describe("exposeLoaderId plugin", () => {
-  describe("hasCreateLoaderImport", () => {
-    it("should detect direct import from rsc-router", () => {
-      const code = `import { createLoader } from "@rangojs/router";`;
-      expect(hasCreateLoaderImport(code)).toBe(true);
-    });
-
-    it("should detect import from rsc-router/server", () => {
-      const code = `import { createLoader } from "@rangojs/router/server";`;
-      expect(hasCreateLoaderImport(code)).toBe(true);
-    });
-
-    it("should detect createLoader with other imports", () => {
-      const code = `import { map, createLoader, route } from "@rangojs/router";`;
-      expect(hasCreateLoaderImport(code)).toBe(true);
-    });
-
-    it("should NOT detect aliased import", () => {
-      const code = `import { createLoader as cl } from "@rangojs/router";`;
-      // Our simple pattern doesn't support aliasing - this is intentional
-      expect(hasCreateLoaderImport(code)).toBe(true); // Still matches the word
-    });
-
-    it("should NOT detect import from other packages", () => {
-      const code = `import { createLoader } from "other-package";`;
-      expect(hasCreateLoaderImport(code)).toBe(false);
-    });
-
-    it("should NOT detect default import", () => {
-      const code = `import createLoader from "@rangojs/router";`;
-      expect(hasCreateLoaderImport(code)).toBe(false);
-    });
-
-    it("should NOT detect namespace import", () => {
-      const code = `import * as router from "@rangojs/router";`;
-      expect(hasCreateLoaderImport(code)).toBe(false);
-    });
-  });
-
-  describe("extractLoaderExports", () => {
-    it("should extract single loader export", () => {
-      const code = `export const MyLoader = createLoader("test", fn);`;
-      expect(extractLoaderExports(code)).toEqual(["MyLoader"]);
-    });
-
-    it("should extract multiple loader exports", () => {
-      const code = `
-        export const LoaderA = createLoader("a", fnA);
-        export const LoaderB = createLoader("b", fnB);
-        export const LoaderC = createLoader("c", fnC, true);
-      `;
-      expect(extractLoaderExports(code)).toEqual(["LoaderA", "LoaderB", "LoaderC"]);
-    });
-
-    it("should NOT extract non-exported loaders", () => {
-      const code = `const PrivateLoader = createLoader("private", fn);`;
-      expect(extractLoaderExports(code)).toEqual([]);
-    });
-
-    it("should NOT extract default exports", () => {
-      const code = `export default createLoader("default", fn);`;
-      expect(extractLoaderExports(code)).toEqual([]);
-    });
-
-    it("should handle multiline exports", () => {
-      const code = `
-        export const MyLoader = createLoader(
-          "my-loader",
-          async (ctx) => {
-            return { data: "test" };
-          },
-          true
-        );
-      `;
-      expect(extractLoaderExports(code)).toEqual(["MyLoader"]);
-    });
-  });
-
-  describe("$$id generation", () => {
-    it("should generate correct $$id format", () => {
-      const filePath = "src/loaders/test-loader.ts";
-      const exportName = "TestLoader";
-      const id = `${filePath}#${exportName}`;
-      expect(id).toBe("src/loaders/test-loader.ts#TestLoader");
-    });
-
-    it("should handle nested paths", () => {
-      const filePath = "src/handlers/shop/loaders/cart.ts";
-      const exportName = "CartLoader";
-      const id = `${filePath}#${exportName}`;
-      expect(id).toBe("src/handlers/shop/loaders/cart.ts#CartLoader");
-    });
-  });
-});

package/src/vite/expose-handle-id.ts

@@ -1,209 +0,0 @@
-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 handle ID
- * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short
- * Appends export name for easier debugging: "abc123#Breadcrumbs"
- */
-function hashHandleId(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 createHandle from rsc-router
- */
-function hasCreateHandleImport(code: string): boolean {
-  // Match: import { createHandle } from "@rangojs/router" or "@rangojs/router/..."
-  const pattern =
-    /import\s*\{[^}]*\bcreateHandle\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
-  return pattern.test(code);
-}
-
-/**
- * Analyze createHandle arguments to determine injection strategy
- * Returns: { hasArgs: boolean, firstArgIsString: boolean, firstArgIsFunction: boolean }
- */
-function analyzeCreateHandleArgs(
-  code: string,
-  startPos: number,
-  endPos: number
-): { hasArgs: boolean; firstArgIsString: boolean; firstArgIsFunction: boolean } {
-  // Extract the content between parentheses
-  const content = code.slice(startPos, endPos).trim();
-
-  if (!content) {
-    return { hasArgs: false, firstArgIsString: false, firstArgIsFunction: false };
-  }
-
-  // Check if first arg starts with a quote (string literal)
-  const firstArgIsString = /^["']/.test(content);
-
-  // Check if first arg starts with ( for arrow function or function keyword
-  const firstArgIsFunction =
-    content.startsWith("(") ||
-    content.startsWith("function") ||
-    // Check for identifier that could be a collect function reference
-    /^[a-zA-Z_$][a-zA-Z0-9_$]*\s*(?:,|$)/.test(content);
-
-  return { hasArgs: true, firstArgIsString, firstArgIsFunction };
-}
-
-/**
- * Transform export const X = createHandle(...) patterns to inject $$id
- *
- * Handles these cases:
- * 1. createHandle() - no args -> inject (undefined, "id")
- * 2. createHandle("name") - string name -> inject (, "id") after existing arg
- * 3. createHandle(collectFn) - collect function -> inject (collectFn, "id")
- * 4. createHandle("name", collectFn) - both -> inject (, "id") after existing args
- */
-function transformHandleExports(
-  code: string,
-  filePath: string,
-  sourceId?: string,
-  isBuild: boolean = false
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  // Quick bail-out
-  if (!code.includes("createHandle")) {
-    return null;
-  }
-
-  // Must have direct import from rsc-router
-  if (!hasCreateHandleImport(code)) {
-    return null;
-  }
-
-  // Match: export const X = createHandle<...>(
-  // Captures the export name (X)
-  const pattern = /export\s+const\s+(\w+)\s*=\s*createHandle\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 createHandle(...) 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;
-
-    // Analyze what arguments exist
-    const args = analyzeCreateHandleArgs(code, matchEnd, closeParenPos);
-
-    // Find the semicolon or end of statement
-    let statementEnd = i;
-    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
-      statementEnd++;
-    }
-    if (code[statementEnd] === ";") {
-      statementEnd++;
-    }
-
-    // Generate ID: hashed in production, readable in dev
-    const handleId = isBuild
-      ? hashHandleId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    // Inject $$id as the last parameter
-    let paramInjection: string;
-    if (!args.hasArgs) {
-      // No args: createHandle() -> createHandle(undefined, "id")
-      paramInjection = `undefined, "${handleId}"`;
-    } else {
-      // Has args: createHandle(x) -> createHandle(x, "id")
-      paramInjection = `, "${handleId}"`;
-    }
-    s.appendLeft(closeParenPos, paramInjection);
-
-    // Also set $$id property for external access
-    const propInjection = `\n${exportName}.$$id = "${handleId}";`;
-    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 $$id on createHandle calls.
- *
- * When users create handles with createHandle(), this plugin:
- * 1. Injects a $$id as the last parameter (used as the handle name)
- * 2. Sets $$id property on the exported constant for external access
- *
- * This allows handles to be created without explicit names:
- * - Before: export const Breadcrumbs = createHandle<Item>("breadcrumbs")
- * - After:  export const Breadcrumbs = createHandle<Item>()
- *
- * The name is auto-generated from file path + export name.
- *
- * Requirements:
- * - Must use direct import: import { createHandle } from "@rangojs/router"
- * - Must use named export: export const MyHandle = createHandle(...)
- */
-export function exposeHandleId(): Plugin {
-  let config: ResolvedConfig;
-  let isBuild = false;
-
-  return {
-    name: "@rangojs/router:expose-handle-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("createHandle")) {
-        return;
-      }
-
-      // Must have direct import from rsc-router
-      if (!hasCreateHandleImport(code)) {
-        return;
-      }
-
-      // Get relative path for the ID
-      const relativePath = normalizePath(path.relative(config.root, id));
-
-      // Transform: inject $$id
-      return transformHandleExports(code, relativePath, id, isBuild);
-    },
-  };
-}

package/src/vite/expose-loader-id.ts

@@ -1,357 +0,0 @@
-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 loader ID
- * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short
- * Appends export name for easier debugging in production: "abc123#CartLoader"
- */
-function hashLoaderId(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 createLoader from rsc-router
- */
-function hasCreateLoaderImport(code: string): boolean {
-  // Match: import { createLoader } from "@rangojs/router" or "@rangojs/router/server"
-  // Must be exact - no aliasing support
-  const pattern =
-    /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/;
-  return pattern.test(code);
-}
-
-/**
- * Count the number of arguments in a createLoader call
- * Returns the count of top-level arguments (not counting nested commas)
- */
-function countCreateLoaderArgs(code: string, startPos: number, endPos: number): number {
-  let depth = 0;
-  let argCount = 0;
-  let hasContent = false;
-
-  for (let i = startPos; i < endPos; i++) {
-    const char = code[i];
-
-    // Track nested structures
-    if (char === "(" || char === "[" || char === "{") {
-      depth++;
-      hasContent = true;
-    } else if (char === ")" || char === "]" || char === "}") {
-      depth--;
-    } else if (char === "," && depth === 0) {
-      // Top-level comma means another argument
-      argCount++;
-    } else if (!/\s/.test(char)) {
-      hasContent = true;
-    }
-  }
-
-  // If there's content, we have at least one argument
-  return hasContent ? argCount + 1 : 0;
-}
-
-/**
- * Find all export const X = createLoader(...) patterns and inject $$id
- * In production, IDs are hashed to avoid exposing file paths.
- * In dev, IDs use filePath#exportName for easier debugging.
- *
- * The ID is injected in two ways:
- * 1. As a hidden third parameter to createLoader() for registry registration
- * 2. As a property assignment X.$$id = "..." for external access
- *
- * IMPORTANT: The $$id must always be the THIRD parameter to createLoader.
- * createLoader(fn, fetchable?, __injectedId?)
- * If the user only provides fn, we inject: undefined, "id"
- * If the user provides fn and fetchable, we inject: , "id"
- */
-function transformLoaderExports(
-  code: string,
-  filePath: string,
-  sourceId?: string,
-  isBuild: boolean = false
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  // Quick bail-out
-  if (!code.includes("createLoader")) {
-    return null;
-  }
-
-  // Must have direct import from rsc-router
-  if (!hasCreateLoaderImport(code)) {
-    return null;
-  }
-
-  // Match: export const X = createLoader(
-  // Captures the export name (X)
-  const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\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 createLoader(...) call
-    // Need to count parentheses to find matching close
-    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;
-
-    // Count existing arguments
-    const argCount = countCreateLoaderArgs(code, matchEnd, closeParenPos);
-
-    // Find the semicolon or end of statement
-    let statementEnd = i;
-    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
-      statementEnd++;
-    }
-    if (code[statementEnd] === ";") {
-      statementEnd++;
-    }
-
-    // In production: hash ID to avoid exposing file paths
-    // In dev: use readable format for easier debugging
-    const loaderId = isBuild
-      ? hashLoaderId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    // Inject $$id as hidden third parameter before the closing paren
-    // If user only has 1 arg (fn), we need to add undefined for fetchable
-    // createLoader(fn) -> createLoader(fn, undefined, "id")
-    // createLoader(fn, true) -> createLoader(fn, true, "id")
-    const paramInjection = argCount === 1
-      ? `, undefined, "${loaderId}"`
-      : `, "${loaderId}"`;
-    s.appendLeft(closeParenPos, paramInjection);
-
-    // Also set $$id property for external access (useLoader, useFetchLoader)
-    const propInjection = `\n${exportName}.$$id = "${loaderId}";`;
-    s.appendRight(statementEnd, propInjection);
-    hasChanges = true;
-  }
-
-  if (!hasChanges) {
-    return null;
-  }
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({ source: sourceId, includeContent: true }),
-  };
-}
-
-const VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
-const RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
-
-// Store for deferred manifest generation - populated during transform, used after build
-let manifestGenerated = false;
-
-/**
- * Vite plugin that exposes $$id on createLoader calls and generates a loader manifest.
- *
- * When users create loaders with createLoader(), this plugin:
- * 1. Injects a $$id property containing the file path and export name
- * 2. Tracks all loaders and generates a virtual manifest module
- *
- * The manifest can be imported by the RSC handler to get all loaders.
- *
- * Requirements:
- * - Must use direct import: import { createLoader } from "@rangojs/router"
- * - No aliasing support (import { createLoader as cl } won't work)
- * - Must use named export: export const MyLoader = createLoader(...)
- */
-export function exposeLoaderId(): Plugin {
-  let config: ResolvedConfig;
-  let isBuild = false;
-
-  // Track discovered loaders: hashedId -> { filePath, exportName }
-  const loaderRegistry = new Map<
-    string,
-    { filePath: string; exportName: string }
-  >();
-
-  // For build mode: pre-scan for loaders during buildStart
-  const pendingLoaderScans = new Map<string, Promise<void>>();
-
-  return {
-    name: "@rangojs/router:expose-loader-id",
-    enforce: "post",
-
-    configResolved(resolvedConfig) {
-      config = resolvedConfig;
-      isBuild = config.command === "build";
-    },
-
-    async buildStart() {
-      if (!isBuild) return;
-
-      // Pre-scan for loader files to populate registry before manifest is loaded
-      // This runs before module resolution, so manifest will have access to all loaders
-      const fs = await import("node:fs/promises");
-
-      async function scanDir(dir: string): Promise<string[]> {
-        const results: string[] = [];
-        try {
-          const entries = await fs.readdir(dir, { withFileTypes: true });
-          for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-              if (entry.name !== "node_modules") {
-                results.push(...(await scanDir(fullPath)));
-              }
-            } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
-              results.push(fullPath);
-            }
-          }
-        } catch {
-          // Directory doesn't exist or not readable
-        }
-        return results;
-      }
-
-      try {
-        const srcDir = path.join(config.root, "src");
-        const files = await scanDir(srcDir);
-
-        for (const filePath of files) {
-          const content = await fs.readFile(filePath, "utf-8");
-
-          // Quick check for createLoader
-          if (!content.includes("createLoader")) continue;
-          if (!hasCreateLoaderImport(content)) continue;
-
-          // Extract loader exports
-          const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
-          const relativePath = normalizePath(
-            path.relative(config.root, filePath)
-          );
-          let match: RegExpExecArray | null;
-
-          while ((match = pattern.exec(content)) !== null) {
-            const exportName = match[1];
-            const hashedId = hashLoaderId(relativePath, exportName);
-            loaderRegistry.set(hashedId, {
-              filePath: relativePath,
-              exportName,
-            });
-          }
-        }
-      } catch (error) {
-        // Fall back to transform-time discovery
-        console.warn("[exposeLoaderId] Pre-scan failed:", error);
-      }
-    },
-
-    resolveId(id) {
-      if (id === VIRTUAL_LOADER_MANIFEST) {
-        return RESOLVED_VIRTUAL_LOADER_MANIFEST;
-      }
-    },
-
-    load(id) {
-      if (id === RESOLVED_VIRTUAL_LOADER_MANIFEST) {
-        // Generate a lazy import map for on-demand loader loading
-        // This avoids importing all loader modules at startup
-
-        if (!isBuild) {
-          // Dev mode: empty map - use fallback path parsing in loader registry
-          // IDs in dev mode are "filePath#exportName" format for easier debugging
-          return `import { setLoaderImports } from "@rangojs/router/server";
-
-// Dev mode: empty map, loaders are resolved dynamically via path parsing
-setLoaderImports({});
-`;
-        }
-
-        // Build mode: generate lazy import map
-        // Each loader is only imported when first requested
-        // Keys are hashed IDs to avoid exposing file paths
-        const lazyImports: string[] = [];
-
-        for (const [hashedId, { filePath, exportName }] of loaderRegistry) {
-          // Create a lazy import function for each loader
-          lazyImports.push(
-            `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`
-          );
-        }
-
-        // If no loaders discovered, set empty map
-        if (lazyImports.length === 0) {
-          return `import { setLoaderImports } from "@rangojs/router/server";
-
-// No fetchable loaders discovered during build
-setLoaderImports({});
-`;
-        }
-
-        const code = `import { setLoaderImports } from "@rangojs/router/server";
-
-// Lazy import map - loaders are loaded on-demand when first requested
-setLoaderImports({
-${lazyImports.join(",\n")}
-});
-`;
-        return code;
-      }
-    },
-
-    transform(code, id) {
-      // Skip node_modules
-      if (id.includes("/node_modules/")) {
-        return;
-      }
-
-      // Quick bail-out
-      if (!code.includes("createLoader")) {
-        return;
-      }
-
-      // Must have direct import from rsc-router
-      if (!hasCreateLoaderImport(code)) {
-        return;
-      }
-
-      // Check if we're in RSC environment (server-side)
-      const envName = this.environment?.name;
-      const isRscEnv = envName === "rsc";
-
-      // Get relative path for the ID
-      const relativePath = normalizePath(path.relative(config.root, id));
-
-      // Track loaders for manifest (only in RSC env to avoid duplicate entries)
-      if (isRscEnv) {
-        const pattern = /export\s+const\s+(\w+)\s*=\s*createLoader\s*\(/g;
-        let match: RegExpExecArray | null;
-        while ((match = pattern.exec(code)) !== null) {
-          const exportName = match[1];
-          const hashedId = hashLoaderId(relativePath, exportName);
-          loaderRegistry.set(hashedId, { filePath: relativePath, exportName });
-        }
-      }
-
-      // Transform: inject $$id in all environments
-      // In build mode, IDs are hashed; in dev mode, they're readable
-      return transformLoaderExports(code, relativePath, id, isBuild);
-    },
-  };
-}