@ivogt/rsc-router 0.0.0-experimental.1

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/__tests__/expose-loader-id.test.ts

@@ -0,0 +1,117 @@
+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*["']rsc-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 "rsc-router";`;
+      expect(hasCreateLoaderImport(code)).toBe(true);
+    });
+
+    it("should detect import from rsc-router/server", () => {
+      const code = `import { createLoader } from "rsc-router/server";`;
+      expect(hasCreateLoaderImport(code)).toBe(true);
+    });
+
+    it("should detect createLoader with other imports", () => {
+      const code = `import { map, createLoader, route } from "rsc-router";`;
+      expect(hasCreateLoaderImport(code)).toBe(true);
+    });
+
+    it("should NOT detect aliased import", () => {
+      const code = `import { createLoader as cl } from "rsc-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 "rsc-router";`;
+      expect(hasCreateLoaderImport(code)).toBe(false);
+    });
+
+    it("should NOT detect namespace import", () => {
+      const code = `import * as router from "rsc-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");
+    });
+  });
+});