@rangojs/router 0.0.0-experimental.10

package/src/use-loader.tsx

@@ -0,0 +1,346 @@
+"use client";
+
+import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import type { LoaderDefinition, LoadOptions } from "./types.js";
+
+/**
+ * Payload returned by loader RSC requests
+ */
+interface LoaderRscPayload<T = unknown> {
+  loaderResult: T;
+  loaderError?: { message: string; name: string };
+}
+
+/**
+ * Load function type with form action support
+ */
+export type LoadFunction<T> = ((options?: LoadOptions) => Promise<T>) & {
+  /** Form action for progressive enhancement - can be passed to form action prop */
+  action: (formData: FormData) => Promise<void>;
+};
+
+/**
+ * Result type for useLoader hook (strict - data is required)
+ */
+export interface UseLoaderResult<T> {
+  /** The loaded data - guaranteed to exist when loader is registered on route */
+  data: T;
+  /** True while a load() is in progress */
+  isLoading: boolean;
+  /** Error from the most recent load attempt, null if successful */
+  error: Error | null;
+  /** Function to trigger a fetch (only works if loader is fetchable) */
+  load: LoadFunction<T>;
+  /** Alias for load */
+  refetch: LoadFunction<T>;
+}
+
+/**
+ * Result type for useFetchLoader hook (flexible - data is optional)
+ */
+export interface UseFetchLoaderResult<T> {
+  /** The loaded data - may be undefined if not yet fetched or not in context */
+  data: T | undefined;
+  /** True while a load() is in progress */
+  isLoading: boolean;
+  /** Error from the most recent load attempt, null if successful */
+  error: Error | null;
+  /** Function to trigger a fetch (only works if loader is fetchable) */
+  load: LoadFunction<T>;
+  /** Alias for load */
+  refetch: LoadFunction<T>;
+}
+
+/**
+ * Options for useLoader hook
+ */
+export interface UseLoaderOptions {
+  /**
+   * If true (default), errors from load() will be thrown to the nearest error boundary.
+   * If false, errors are only captured in the `error` state.
+   * @default true
+   */
+  throwOnError?: boolean;
+}
+
+/**
+ * Internal hook implementation shared by useLoader and useFetchLoader
+ */
+function useLoaderInternal<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions
+): UseFetchLoaderResult<T> {
+  const context = useContext(OutletContext);
+
+  // Get data from context (SSR/navigation)
+  const getContextData = useCallback((): T | undefined => {
+    let current: OutletContextValue | null | undefined = context;
+    while (current) {
+      if (current.loaderData && loader.$$id in current.loaderData) {
+        return current.loaderData[loader.$$id] as T;
+      }
+      current = current.parent;
+    }
+    return undefined;
+  }, [context, loader.$$id]);
+
+  const contextData = getContextData();
+
+  // Local state for fetched data (from load() calls)
+  const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Track context data changes to reset fetched data on navigation
+  const prevContextDataRef = useRef(contextData);
+  useEffect(() => {
+    if (prevContextDataRef.current !== contextData) {
+      // Navigation happened, clear fetched data so context takes precedence
+      setFetchedData(undefined);
+      setError(null);
+      prevContextDataRef.current = contextData;
+    }
+  }, [contextData]);
+
+  // Data priority: fetched data (if any) > context data
+  const data = fetchedData ?? contextData;
+
+  const throwOnError = options?.throwOnError ?? true;
+
+  // Load function for fetching data
+  const load = useCallback(
+    async (loadOptions?: LoadOptions): Promise<T> => {
+      // Verify the loader has $$id
+      if (!loader.$$id) {
+        throw new Error(
+          `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`
+        );
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const url = new URL(window.location.pathname, window.location.origin);
+        url.searchParams.set("_rsc_loader", loader.$$id);
+
+        const method = loadOptions?.method ?? "GET";
+        const isBodyMethod = method !== "GET";
+
+        let fetchOptions: RequestInit;
+
+        if (isBodyMethod) {
+          // POST/PUT/PATCH/DELETE - send params and body as JSON
+          const bodyPayload: { params?: Record<string, string>; body?: unknown } = {};
+          if (loadOptions?.params && Object.keys(loadOptions.params).length > 0) {
+            bodyPayload.params = loadOptions.params;
+          }
+          if ("body" in (loadOptions ?? {}) && (loadOptions as any).body !== undefined) {
+            bodyPayload.body = (loadOptions as any).body;
+          }
+
+          fetchOptions = {
+            method,
+            headers: {
+              Accept: "text/x-component",
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify(bodyPayload),
+          };
+        } else {
+          // GET - send params in query string
+          if (loadOptions?.params && Object.keys(loadOptions.params).length > 0) {
+            url.searchParams.set(
+              "_rsc_loader_params",
+              JSON.stringify(loadOptions.params)
+            );
+          }
+
+          fetchOptions = {
+            method: "GET",
+            headers: {
+              Accept: "text/x-component",
+            },
+          };
+        }
+
+        const response = fetch(url.toString(), fetchOptions);
+
+        const { createFromFetch } = await import("./deps/browser.js");
+        const payload = await createFromFetch<LoaderRscPayload<T>>(response);
+
+        if (payload.loaderError) {
+          throw new Error(payload.loaderError.message);
+        }
+
+        const result = payload.loaderResult;
+        setFetchedData(result);
+        return result;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        if (throwOnError) {
+          throw err;
+        }
+        // When throwOnError is false, return the current data (previous successful
+        // value or undefined). Caller should check error state for error handling.
+        return data as T;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [throwOnError]
+  );
+
+  // Form action for progressive enhancement
+  // This wrapper is for useFetchLoader's load.action - it manages state internally
+  // and doesn't use React's useActionState. For true PE, use loader.action directly
+  // with useActionState.
+  const action = useCallback(
+    async (formData: FormData): Promise<void> => {
+      if (!loader.action) {
+        throw new Error(
+          `Loader "${loader.$$id}" does not have an action. ` +
+            `Make sure the loader is created with fetchable: true.`
+        );
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        // Pass null as prevState - this wrapper manages state internally
+        const result = await loader.action(null, formData);
+        setFetchedData(result);
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        if (throwOnError) {
+          throw err;
+        }
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [throwOnError]
+  );
+
+  // Attach action to load function
+  const loadWithAction = load as LoadFunction<T>;
+  loadWithAction.action = action;
+
+  // Throw during render if there's an error and throwOnError is true
+  // This allows ErrorBoundaries to catch async errors from load()
+  if (error && throwOnError) {
+    throw error;
+  }
+
+  return {
+    data,
+    isLoading,
+    error,
+    load: loadWithAction,
+    refetch: loadWithAction,
+  };
+}
+
+/**
+ * Hook to access loader data from route context (strict version)
+ *
+ * Use this when the loader is registered on the route via `loader()`.
+ * The data is guaranteed to exist - throws an error if not found.
+ *
+ * For on-demand fetching or when loader might not be in context,
+ * use `useFetchLoader` instead.
+ *
+ * @param loader - The loader definition (must be registered on route)
+ * @param options - Optional configuration
+ * @returns Object with data (guaranteed), isLoading, error, load, and refetch
+ * @throws Error if loader data is not found in context
+ *
+ * @example Basic usage - accessing route loader data
+ * ```tsx
+ * "use client";
+ * import { useLoader } from "rsc-router/client";
+ * import { CartLoader } from "../loaders/cart";
+ *
+ * // In route definition: loader(CartLoader)
+ *
+ * export function CartIcon() {
+ *   const { data } = useLoader(CartLoader);
+ *   // data is guaranteed to be CartData, not CartData | undefined
+ *   return <span>Cart ({data.items.length})</span>;
+ * }
+ * ```
+ */
+export function useLoader<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions
+): UseLoaderResult<T> {
+  const result = useLoaderInternal(loader, options);
+
+  // Strict mode: throw if data is not in context
+  if (result.data === undefined) {
+    throw new Error(
+      `useLoader: Loader "${loader.$$id}" data not found in context. ` +
+        `Make sure the loader is registered on the route with loader(). ` +
+        `If you need on-demand fetching, use useFetchLoader() instead.`
+    );
+  }
+
+  return result as UseLoaderResult<T>;
+}
+
+/**
+ * Hook to access loader data with optional fetching (flexible version)
+ *
+ * Use this when:
+ * - The loader might not be registered on the route
+ * - You want to fetch data on-demand from the client
+ * - You're building a reusable component that doesn't assume route context
+ *
+ * If the loader IS registered on the route, it will still get the initial
+ * data from context - you just have to handle the `undefined` case in types.
+ *
+ * @param loader - The loader definition
+ * @param options - Optional configuration
+ * @returns Object with data (may be undefined), isLoading, error, load, and refetch
+ *
+ * @example On-demand fetching
+ * ```tsx
+ * "use client";
+ * import { useFetchLoader } from "rsc-router/client";
+ * import { SearchLoader } from "../loaders/search";
+ *
+ * export function SearchResults() {
+ *   const { data, load, isLoading } = useFetchLoader(SearchLoader);
+ *
+ *   const handleSearch = async (query: string) => {
+ *     await load({ params: { query } });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => handleSearch("test")}>Search</button>
+ *       {isLoading && <span>Loading...</span>}
+ *       {data?.results.map(r => <div key={r.id}>{r.name}</div>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With route context (hybrid usage)
+ * ```tsx
+ * // Loader registered on route: loader(UserLoader)
+ * // useFetchLoader still works - gets initial data from context
+ * const { data, load } = useFetchLoader(UserLoader);
+ * // data is UserData | undefined (even though it will have initial value)
+ * ```
+ */
+export function useFetchLoader<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions
+): UseFetchLoaderResult<T> {
+  return useLoaderInternal(loader, options);
+}

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

@@ -0,0 +1,344 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import MagicString from "magic-string";
+import path from "node:path";
+import fs from "node:fs";
+
+/**
+ * Type for the RSC plugin's manager API
+ */
+interface RscPluginManager {
+  serverReferenceMetaMap: Record<
+    string,
+    {
+      importId: string;
+      referenceKey: string;
+      exportNames: string[];
+    }
+  >;
+  config: ResolvedConfig;
+}
+
+interface RscPluginApi {
+  manager: RscPluginManager;
+}
+
+/**
+ * Get the RSC plugin's API from Vite config
+ */
+function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
+  // Try by name first
+  let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
+
+  // Fallback: find by API structure if name lookup fails
+  if (!plugin) {
+    plugin = config.plugins.find(
+      (p) =>
+        (p.api as RscPluginApi | undefined)?.manager?.serverReferenceMetaMap !==
+        undefined
+    );
+    if (plugin) {
+      console.warn(
+        `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
+          `Consider updating the name lookup if the plugin was renamed.`
+      );
+    }
+  }
+
+  return plugin?.api as RscPluginApi | undefined;
+}
+
+/**
+ * Normalize path to forward slashes
+ */
+function normalizePath(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * Check if a file is a "use server" module (has the directive at the module level).
+ * This distinguishes module-level server action files from files with inline actions.
+ *
+ * Module-level "use server" files should have their hash replaced with file paths
+ * for revalidation matching. Inline actions (defined in RSC components) should
+ * keep their hashed IDs for client security.
+ */
+function isUseServerModule(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    // Remove leading comments and whitespace to find the first meaningful content
+    const trimmed = content
+      .replace(/^\s*\/\/[^\n]*\n/gm, "") // Remove single-line comments
+      .replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "") // Remove multi-line comments
+      .trimStart();
+
+    // Check if the file starts with "use server" directive
+    return (
+      trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Transform code to expose action IDs on createServerReference calls.
+ * Wraps each call with an IIFE that attaches $id to the returned function.
+ *
+ * @param code - The source code to transform
+ * @param sourceId - The source file identifier (for sourcemap)
+ * @param hashToFileMap - Optional mapping from hash to file path (for server bundles)
+ */
+function transformServerReferences(
+  code: string,
+  sourceId?: string,
+  hashToFileMap?: Map<string, string>
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  if (!code.includes("createServerReference(")) {
+    return null;
+  }
+
+  // Match: createServerReference("hash#actionName", ...) or $$ReactClient.createServerReference(...)
+  // The RSC plugin uses $$ReactClient namespace in transformed code
+  const pattern =
+    /((?:\$\$\w+\.)?createServerReference)\(("[^"]+#[^"]+")([^)]*)\)/g;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(code)) !== null) {
+    hasChanges = true;
+    const [fullMatch, fnCall, idArg, rest] = match;
+    const start = match.index;
+    const end = start + fullMatch.length;
+
+    // Parse the ID to potentially replace hash with file path
+    let finalIdArg = idArg;
+    if (hashToFileMap) {
+      // idArg is like '"hash#actionName"', extract the parts
+      const idValue = idArg.slice(1, -1); // Remove quotes
+      const hashMatch = idValue.match(/^([^#]+)#(.+)$/);
+      if (hashMatch) {
+        const [, hash, actionName] = hashMatch;
+        const filePath = hashToFileMap.get(hash);
+        if (filePath) {
+          // Replace hash with file path for server-side
+          finalIdArg = `"${filePath}#${actionName}"`;
+        }
+      }
+    }
+
+    // Wrap the createServerReference call to attach $$id to the returned function
+    const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
+    s.overwrite(start, end, replacement);
+  }
+
+  if (!hasChanges) {
+    return null;
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true }),
+  };
+}
+
+/**
+ * Transform registerServerReference calls in server bundles to use file paths instead of hashes.
+ * Pattern: registerServerReference(fn, "hash", "exportName")
+ * React's registerServerReference sets $$id = hash + "#" + exportName
+ * By replacing the hash with file path, $$id will contain the file path for revalidation matching.
+ *
+ * Only actions from module-level "use server" files are transformed.
+ * Inline actions (defined in RSC components with "use server" inside a function) are NOT in
+ * hashToFileMap and keep their hashed IDs. This is intentional for client security:
+ * - Module-level "use server" files: shared action modules, file path helps revalidation
+ * - Inline actions: one-off actions in RSC, hash ID prevents file path exposure to client
+ *
+ * @param code - The source code to transform
+ * @param sourceId - The source file identifier (for sourcemap)
+ * @param hashToFileMap - Mapping from hash to file path (only module-level "use server" files)
+ */
+function transformRegisterServerReference(
+  code: string,
+  sourceId?: string,
+  hashToFileMap?: Map<string, string>
+): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
+  if (!hashToFileMap || !code.includes("registerServerReference(")) {
+    return null;
+  }
+
+  // Match: registerServerReference(fn, "hash", "exportName")
+  // The hash is the second argument, exportName is the third
+  const pattern = /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+
+  const s = new MagicString(code);
+  let hasChanges = false;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(code)) !== null) {
+    const [fullMatch, fnArg, hash, exportName] = match;
+    const start = match.index;
+    const end = start + fullMatch.length;
+
+    // Look up the file path for this hash
+    const filePath = hashToFileMap.get(hash);
+    if (filePath) {
+      hasChanges = true;
+      // WRAP the call to add $id property with file path
+      // Keep the original hash for React's action registry (so loadServerAction works)
+      // Add $id (single dollar) with file path for revalidation matching
+      // Note: We use $id instead of $$id because React's registerServerReference
+      // sets $$id as a non-writable property
+      const filePathId = `${filePath}#${exportName}`;
+      const replacement = `(function(fn) { fn.$id = "${filePathId}"; return fn; })(registerServerReference(${fnArg}, "${hash}", "${exportName}"))`;
+      s.overwrite(start, end, replacement);
+    }
+  }
+
+  if (!hasChanges) {
+    return null;
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ source: sourceId, includeContent: true }),
+  };
+}
+
+/**
+ * Vite plugin that exposes action IDs on server reference functions.
+ *
+ * When React Server Components creates server references via createServerReference(),
+ * the action ID (format: "hash#actionName") is passed as the first argument but not
+ * exposed on the returned function. This plugin transforms the output to attach
+ * the $id property to each server reference function, enabling the router to
+ * identify which action was called during revalidation.
+ *
+ * Server bundles (RSC/SSR) get file paths in $id for filtering (e.g., "src/actions.ts#add").
+ * Client bundles keep hashed IDs for security (e.g., "ec387bc704d4#add").
+ *
+ * Works in:
+ * - Build mode: uses renderChunk to transform bundled chunks
+ * - Dev mode: uses transform with enforce:"post" to transform after RSC plugin
+ */
+export function exposeActionId(): Plugin {
+  let config: ResolvedConfig;
+  let isBuild = false;
+  let hashToFileMap: Map<string, string> | undefined;
+  let rscPluginApi: RscPluginApi | undefined;
+
+  return {
+    name: "@rangojs/router:expose-action-id",
+    // Run after all other plugins (including RSC plugin's transforms)
+    enforce: "post",
+
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isBuild = config.command === "build";
+
+      // Get RSC plugin API - rsc-router requires @vitejs/plugin-rsc
+      rscPluginApi = getRscPluginApi(config);
+    },
+
+    buildStart() {
+      // Verify RSC plugin is present at build start (after all config hooks have run)
+      // This allows rsc-router:rsc-integration to dynamically add the RSC plugin
+      if (!rscPluginApi) {
+        rscPluginApi = getRscPluginApi(config);
+      }
+
+      if (!rscPluginApi) {
+        throw new Error(
+          "[rsc-router] Could not find @vitejs/plugin-rsc. " +
+            "@rangojs/router requires the Vite RSC plugin.\n" +
+            "The RSC plugin should be included automatically. If you disabled it with\n" +
+            "rango({ rsc: false }), add rsc() before rango() in your config."
+        );
+      }
+
+      if (!isBuild) return;
+
+      hashToFileMap = new Map();
+      const { serverReferenceMetaMap } = rscPluginApi.manager;
+
+      for (const [absolutePath, meta] of Object.entries(
+        serverReferenceMetaMap
+      )) {
+        // Only include module-level "use server" files
+        // Inline actions (defined in RSC components) should keep hashed IDs for client security
+        if (!isUseServerModule(absolutePath)) {
+          continue;
+        }
+
+        const relativePath = normalizePath(
+          path.relative(config.root, absolutePath)
+        );
+
+        // The referenceKey in build mode is the hash
+        // Map hash -> relative file path
+        hashToFileMap.set(meta.referenceKey, relativePath);
+      }
+    },
+
+
+    // Dev mode only: transform hook runs after RSC plugin creates server references
+    // In dev mode, IDs already contain file paths, not hashes
+    transform(code, id) {
+      // Skip in build mode - renderChunk handles it
+      if (isBuild) {
+        return;
+      }
+
+      // Quick bail-out: only process if code has createServerReference
+      if (!code.includes("createServerReference(")) {
+        return;
+      }
+
+      // Skip node_modules
+      if (id.includes("/node_modules/")) {
+        return;
+      }
+
+      // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
+      return transformServerReferences(code, id);
+    },
+
+    // Build mode: renderChunk runs after all transforms and bundling complete
+    renderChunk(code, chunk) {
+      // Only RSC bundle should get file paths for revalidation matching
+      // SSR bundle must NOT use file paths because client components run there
+      // and need to match the client bundle during hydration (otherwise: error #418)
+      const isRscEnv = this.environment?.name === "rsc";
+
+      // Only use file path mapping for RSC environment
+      const effectiveMap = isRscEnv ? hashToFileMap : undefined;
+
+      // Transform createServerReference calls (client-side)
+      const result = transformServerReferences(
+        code,
+        chunk.fileName,
+        effectiveMap
+      );
+
+      // For RSC bundles, also transform registerServerReference calls
+      // This replaces hashed IDs with file paths so $id contains the actual path
+      if (isRscEnv && hashToFileMap) {
+        const codeToTransform = result ? result.code : code;
+        const registerResult = transformRegisterServerReference(
+          codeToTransform,
+          chunk.fileName,
+          hashToFileMap
+        );
+        if (registerResult) {
+          return { code: registerResult.code, map: registerResult.map };
+        }
+      }
+
+      if (result) {
+        return { code: result.code, map: result.map };
+      }
+      return null;
+    },
+  };
+}