@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/use-loader.tsx

@@ -1,139 +1,388 @@
 "use client";
 
-import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import {
+  isValidElement,
+  startTransition,
+  use,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import { loaderStore, type LoaderEntry } from "./loader-store.js";
+import { decodeLoaderEntry } from "./decode-loader-results.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
+function isShareableGet(options: LoadOptions | undefined): boolean {
+  if (!options) return true;
+  if (options.method && options.method !== "GET") return false;
+  if ("body" in options && (options as { body?: unknown }).body !== undefined) {
+    return false;
+  }
+  return true;
+}
+
+function isPlainRefetch(options: LoadOptions | undefined): boolean {
+  if (!isShareableGet(options)) return false;
+  if (options?.params && Object.keys(options.params).length > 0) return false;
+  return true;
+}
+
+let privateGroupBucketSeq = 0;
+
+const NOT_FOUND = Symbol("not-found");
+
 /**
- * Payload returned by loader RSC requests
+ * SPIKE (streaming useLoader): lookup results distinguish a synchronously
+ * available value from a still-streaming per-loader promise. A pending stream
+ * is `use()`d at the read site (implicit suspension); the promise identity is
+ * stable per commit (it comes from the provider's memoized context value /
+ * element props), which use() requires across replays.
  */
+type LoaderLookup =
+  | typeof NOT_FOUND
+  | { value: unknown }
+  | { stream: Promise<unknown> };
+
+function lookupLoaderStreams(
+  loaderStreams: Record<string, unknown> | undefined,
+  loaderId: string,
+): LoaderLookup {
+  if (!loaderStreams || !(loaderId in loaderStreams)) return NOT_FOUND;
+  const entry = loaderStreams[loaderId];
+  // Within the loaderStreams channel a Promise always means "still streaming";
+  // settled entries are undecoded result values, never promises.
+  return entry instanceof Promise
+    ? { stream: entry }
+    : { value: decodeLoaderEntry(entry) };
+}
+
+function extractContentLoaderData(
+  node: ReactNode,
+  loaderId: string,
+): LoaderLookup {
+  if (!isValidElement(node)) return NOT_FOUND;
+  const props = node.props as Record<string, any> | undefined;
+  if (!props) return NOT_FOUND;
+
+  // Direct OutletProvider with loaderData
+  if (props.loaderData && loaderId in props.loaderData) {
+    return { value: props.loaderData[loaderId] };
+  }
+
+  const streamed = lookupLoaderStreams(props.loaderStreams, loaderId);
+  if (streamed !== NOT_FOUND) return streamed;
+
+  if (
+    props.loaderIds &&
+    Array.isArray(props.loaderIds) &&
+    props.loaderDataPromise &&
+    !(props.loaderDataPromise instanceof Promise)
+  ) {
+    const idx = (props.loaderIds as string[]).indexOf(loaderId);
+    if (idx !== -1) {
+      const data = (props.loaderDataPromise as any[])[idx];
+      if (data && typeof data === "object" && "ok" in data) {
+        return data.ok ? { value: data.data } : NOT_FOUND;
+      }
+      return { value: data };
+    }
+  }
+
+  if (props.children) return extractContentLoaderData(props.children, loaderId);
+  return NOT_FOUND;
+}
+
 interface LoaderRscPayload<T = unknown> {
   loaderResult: T;
   loaderError?: { message: string; name: string };
 }
 
-/**
- * Load function type for fetching loader data from the client
- */
 export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
-/**
- * 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;
+  key?: string;
+  refreshGroup?: string | string[];
 }
 
-/**
- * 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 => {
+  const walk = useMemo((): {
+    contextData: T | undefined;
+    hasContextData: boolean;
+    pendingStream?: Promise<unknown>;
+  } => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
       if (current.loaderData && loader.$$id in current.loaderData) {
-        return current.loaderData[loader.$$id] as T;
+        return {
+          contextData: current.loaderData[loader.$$id] as T,
+          hasContextData: true,
+        };
+      }
+      const streamed = lookupLoaderStreams(current.loaderStreams, loader.$$id);
+      if (streamed !== NOT_FOUND) {
+        if ("stream" in streamed) {
+          return {
+            contextData: undefined,
+            hasContextData: true,
+            pendingStream: streamed.stream,
+          };
+        }
+        return { contextData: streamed.value as T, hasContextData: true };
+      }
+      const contentData = extractContentLoaderData(
+        current.content,
+        loader.$$id,
+      );
+      if (contentData !== NOT_FOUND) {
+        if ("stream" in contentData) {
+          return {
+            contextData: undefined,
+            hasContextData: true,
+            pendingStream: contentData.stream,
+          };
+        }
+        return { contextData: contentData.value as T, hasContextData: true };
       }
       current = current.parent;
     }
-    return undefined;
+    return { contextData: undefined, hasContextData: false };
   }, [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);
-  const requestIdRef = useRef(0);
+  // SPIKE (streaming useLoader): a pending per-loader stream suspends HERE —
+  // the implicit-suspense read. use() is exempt from hook-order rules, so the
+  // conditional call is legal; on replay after resolution it returns
+  // synchronously and the decoded value takes the contextData slot. Hooks
+  // below never run in a suspended render, so their order is stable across
+  // every COMPLETED render.
+  const { hasContextData } = walk;
+  let contextData = walk.contextData;
+  if (walk.pendingStream) {
+    contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  }
 
-  // Track context data changes to reset fetched data on navigation
+  const loaderId = loader.$$id;
+  const key = options?.key;
+  const refreshGroupOption = options?.refreshGroup;
+  const groupKey =
+    refreshGroupOption === undefined
+      ? ""
+      : JSON.stringify(
+          typeof refreshGroupOption === "string"
+            ? [refreshGroupOption]
+            : [...new Set(refreshGroupOption)].sort(),
+        );
+  const groupList = useMemo<string[]>(
+    () => (groupKey === "" ? [] : (JSON.parse(groupKey) as string[])),
+    [groupKey],
+  );
+  const hasGroups = groupList.length > 0;
+  const privateBucketIdRef = useRef<string | null>(null);
+  if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
+    privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
+  }
+  const effectiveKey =
+    key ?? (hasGroups ? privateBucketIdRef.current! : undefined);
+  const bucketKey =
+    effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
+
+  const groupRefetch = useCallback(async (): Promise<void> => {
+    if (!loaderId) return;
+    const requestId = loaderStore.reserveRequestId(bucketKey);
+    loaderStore.beginRequest(bucketKey, requestId);
+    try {
+      const url = new URL(window.location.href);
+      url.searchParams.set("_rsc_loader", loaderId);
+      const response = fetch(url.toString(), {
+        method: "GET",
+        headers: { Accept: "text/x-component" },
+      });
+      const { createFromFetch } = await import("./deps/browser.js");
+      const payload = await createFromFetch<LoaderRscPayload<T>>(response);
+      if (payload.loaderError) {
+        throw new Error(payload.loaderError.message);
+      }
+      loaderStore.finishData(bucketKey, requestId, payload.loaderResult);
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      loaderStore.finishError(bucketKey, requestId, err);
+      throw err;
+    } finally {
+      loaderStore.setLoading(bucketKey, requestId, false);
+    }
+  }, [loaderId, bucketKey]);
+
+  const [sharedState, setSharedState] = useState<{
+    bucketKey: string;
+    snapshot: LoaderEntry;
+  }>(() => ({
+    bucketKey,
+    snapshot: loaderStore.getSnapshot(bucketKey),
+  }));
+  const sharedSnapshot =
+    sharedState.bucketKey === bucketKey
+      ? sharedState.snapshot
+      : loaderStore.getSnapshot(bucketKey);
+  useEffect(() => {
+    const initial = loaderStore.getSnapshot(bucketKey);
+    if (initial !== sharedSnapshot) {
+      startTransition(() => {
+        setSharedState({ bucketKey, snapshot: initial });
+      });
+    }
+    // ephemeral: a reader with no route context has no route-context reset
+    // trigger, so its keyed bucket is reference-counted by the store. A
+    // route-registered reader makes the bucket sticky (reset via clearFamily).
+    return loaderStore.subscribe(
+      bucketKey,
+      () => {
+        const next = loaderStore.getSnapshot(bucketKey);
+        startTransition(() => {
+          setSharedState({ bucketKey, snapshot: next });
+        });
+      },
+      {
+        loaderId,
+        ephemeral: !hasContextData,
+        group: hasGroups ? groupList : undefined,
+        refetch: hasGroups ? groupRefetch : undefined,
+      },
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
+    // sharedSnapshot is captured for the one-shot init sync; we don't want
+    // to re-subscribe on every snapshot change. bucketKey, hasContextData,
+    // groupKey, and groupRefetch are the only inputs that require a fresh
+    // subscription (groupList is memoized on groupKey; groupRefetch is stable
+    // per bucketKey).
+  }, [bucketKey, hasContextData, groupKey, groupRefetch]);
+
+  // Local state holds the result of:
+  //   - parameterized / mutation `load()` calls (load({ params }), POST,
+  //     etc.) — stay scoped so concurrent same-loader different-params
+  //     fetches don't clobber each other through the shared store;
+  //   - any `load()` made by hooks that are NOT in route context (i.e.
+  //     useFetchLoader of an unregistered loader) — keeping those local
+  //     prevents two unrelated components from accidentally sharing data
+  //     through the global store just because they reference the same
+  //     loader id.
+  // `has` distinguishes a committed local result (including `null`/`undefined`)
+  // from "no local load yet", so a load() that resolves to a falsy value is not
+  // discarded in favor of the shared snapshot or the seeded context.
+  const [localFetchedData, setLocalFetchedData] = useState<{
+    has: boolean;
+    value: T | undefined;
+  }>({ has: false, value: undefined });
+  const [localIsLoading, setLocalIsLoading] = useState(false);
+  const [localError, setLocalError] = useState<Error | null>(null);
+
+  // Local request id, mirrors the per-hook gating the previous
+  // implementation provided. Two quick parameterized loads from the same
+  // hook (e.g. load({ params: { q: "a" } }) then load({ params: { q: "b" } }))
+  // can resolve out of order — only the latest must commit.
+  const localRequestIdRef = useRef(0);
+
+  // Tracks the request id of the most recent SHARED load() this hook
+  // initiated. The render-throw rule below uses it to scope the throw
+  // to the originating hook only — sibling readers see the error in
+  // `error` but don't blow up their own boundaries.
+  const lastSharedRequestIdRef = useRef<number | null>(null);
+
+  // Reset on navigation. clear() bumps the entry's latest request id so
+  // any pre-navigation load() promise that resolves later fails its gate
+  // and is dropped — fixes the race where a stale fetch overwrites the
+  // new route's context.
   const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
-      // Navigation happened, clear fetched data so context takes precedence
-      setFetchedData(undefined);
-      setError(null);
+      setLocalFetchedData({ has: false, value: undefined });
+      setLocalIsLoading(false);
+      setLocalError(null);
+      lastSharedRequestIdRef.current = null;
+      // Reset every sticky bucket of this loader (keyed or not). Ephemeral
+      // (unregistered keyed) buckets are left to their refcount lifecycle.
+      loaderStore.clearFamily(loaderId);
       prevContextDataRef.current = contextData;
     }
-  }, [contextData]);
-
-  // Data priority: fetched data (if any) > context data
-  const data = fetchedData ?? contextData;
+  }, [contextData, loaderId]);
+
+  // Read priority: a committed parameterized load() result overrides the shared
+  // snapshot; a committed shared snapshot overrides the server-seeded context.
+  // `has`/`hasValue` gate each level so a committed falsy value is not skipped.
+  const data = localFetchedData.has
+    ? localFetchedData.value
+    : sharedSnapshot.hasValue
+      ? (sharedSnapshot.value as T | undefined)
+      : contextData;
+  const isLoading = localIsLoading || sharedSnapshot.isLoading;
+  const error = localError ?? sharedSnapshot.error;
 
   const throwOnError = options?.throwOnError ?? true;
 
-  // Refs for values used inside load() that should NOT cause callback identity
-  // churn. loader.$$id can change if a reusable component receives a different
-  // loader without remounting; data changes on every navigation. Refs keep the
-  // callback stable while always reading the latest values.
-  const loaderIdRef = useRef(loader.$$id);
-  loaderIdRef.current = loader.$$id;
+  const loaderIdRef = useRef(loaderId);
+  loaderIdRef.current = loaderId;
+  const bucketKeyRef = useRef(bucketKey);
+  bucketKeyRef.current = bucketKey;
   const dataRef = useRef(data);
   dataRef.current = data;
+  const hasContextDataRef = useRef(hasContextData);
+  hasContextDataRef.current = hasContextData;
 
-  // Load function for fetching data via the ?_rsc_loader endpoint.
-  // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
-      const requestId = ++requestIdRef.current;
-      const loaderId = loaderIdRef.current;
-      // Verify the loader has $$id
-      if (!loaderId) {
+      const id = loaderIdRef.current;
+      if (!id) {
         throw new Error(
           `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`,
         );
       }
 
-      setIsLoading(true);
-      setError(null);
+      const bucket = bucketKeyRef.current;
+      const hasDedicatedBucket = bucket !== id;
+
+      const shared = hasDedicatedBucket
+        ? isShareableGet(loadOptions)
+        : isPlainRefetch(loadOptions) && hasContextDataRef.current;
+      let sharedRequestId = -1;
+      let localRequestId = -1;
+      if (shared) {
+        sharedRequestId = loaderStore.reserveRequestId(bucket);
+        lastSharedRequestIdRef.current = sharedRequestId;
+        loaderStore.beginRequest(bucket, sharedRequestId);
+      } else {
+        localRequestId = ++localRequestIdRef.current;
+        setLocalIsLoading(true);
+        setLocalError(null);
+      }
 
       try {
         const url = new URL(window.location.href);
-        url.searchParams.set("_rsc_loader", loaderId);
+        url.searchParams.set("_rsc_loader", id);
 
         const method = loadOptions?.method ?? "GET";
         const isBodyMethod = method !== "GET";
@@ -149,8 +398,6 @@ function useLoaderInternal<T>(
             loadOptions?.params && Object.keys(loadOptions.params).length > 0;
 
           if (bodyValue instanceof FormData) {
-            // FormData body — send as multipart/form-data (preserves File objects).
-            // Params are appended as a JSON string in a special field.
             if (hasParams) {
               bodyValue.set(
                 "_rsc_loader_params",
@@ -163,7 +410,6 @@ function useLoaderInternal<T>(
               body: bodyValue,
             };
           } else {
-            // JSON body — send params and body as JSON
             const bodyPayload: {
               params?: Record<string, string>;
               body?: unknown;
@@ -185,7 +431,6 @@ function useLoaderInternal<T>(
             };
           }
         } else {
-          // GET - send params in query string
           if (
             loadOptions?.params &&
             Object.keys(loadOptions.params).length > 0
@@ -214,34 +459,45 @@ function useLoaderInternal<T>(
         }
 
         const result = payload.loaderResult;
-        if (requestId === requestIdRef.current) {
-          setFetchedData(result);
+        if (shared) {
+          loaderStore.finishData(bucket, sharedRequestId, result);
+        } else if (localRequestId === localRequestIdRef.current) {
+          startTransition(() => {
+            setLocalFetchedData({ has: true, value: result });
+            setLocalIsLoading(false);
+          });
         }
         return result;
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
-        if (requestId === requestIdRef.current) {
-          setError(err);
+        if (shared) {
+          loaderStore.finishError(bucket, sharedRequestId, err);
+        } else if (localRequestId === localRequestIdRef.current) {
+          setLocalError(err);
+          setLocalIsLoading(false);
         }
         if (throwOnError) {
           throw err;
         }
-        // When throwOnError is false, return the latest data snapshot (previous
-        // successful value or undefined). Caller should check error state.
         return dataRef.current as T;
       } finally {
-        if (requestId === requestIdRef.current) {
-          setIsLoading(false);
+        if (shared) {
+          loaderStore.setLoading(bucket, sharedRequestId, false);
         }
       }
     },
     [throwOnError],
   );
 
-  // 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;
+  if (throwOnError) {
+    if (localError) throw localError;
+    if (
+      sharedSnapshot.error &&
+      lastSharedRequestIdRef.current !== null &&
+      sharedSnapshot.requestId === lastSharedRequestIdRef.current
+    ) {
+      throw sharedSnapshot.error;
+    }
   }
 
   return {
@@ -285,7 +541,7 @@ function useLoaderInternal<T>(
 export function useLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseLoaderResult<T> {
+): UseLoaderResult<Rango.FlightSerialize<T>> {
   const result = useLoaderInternal(loader, options);
 
   // Strict mode: throw if data is not in context
@@ -297,7 +553,7 @@ export function useLoader<T>(
     );
   }
 
-  return result as UseLoaderResult<T>;
+  return result as UseLoaderResult<Rango.FlightSerialize<T>>;
 }
 
 /**
@@ -349,6 +605,68 @@ export function useLoader<T>(
 export function useFetchLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseFetchLoaderResult<T> {
-  return useLoaderInternal(loader, options);
+): UseFetchLoaderResult<Rango.FlightSerialize<T>> {
+  return useLoaderInternal(loader, options) as UseFetchLoaderResult<
+    Rango.FlightSerialize<T>
+  >;
+}
+
+/**
+ * Get a stable function that refreshes loaders by cross-loader group tag.
+ *
+ * The returned `refresh(groups)` takes one group name or an array of names and
+ * re-runs every currently-mounted read tagged with ANY of them, with a plain GET
+ * against the current route URL. This is the cross-loader counterpart to the
+ * single-loader `key`: use it to refresh a set of DIFFERENT loaders together
+ * (e.g. profile + orders after an account switch). Members are tagged via
+ * `useLoader(Loader, { refreshGroup })` / `useFetchLoader(Loader, { refreshGroup })`,
+ * where `refreshGroup` is one name or several.
+ *
+ * Passing the group(s) to the returned function rather than to the hook lets a
+ * single `useRefreshLoaders()` instance refresh different groups depending on
+ * context, and lets one call refresh several groups at once — their members are
+ * unioned and deduped, so a loader tagged into two of the named groups is fetched
+ * exactly once.
+ *
+ * Group refresh never render-throws: a failing member surfaces its error via
+ * that read's `error` state, and the returned promise rejects with an
+ * `AggregateError` of the failures so the caller can handle them at the await
+ * site. Each loader is refreshed in place — no params, no body, no mutations.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ *
+ * function Profile() {
+ *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });
+ *   return <span>{data.name}</span>;
+ * }
+ * function Orders() {
+ *   // Tagged into two groups: refreshed by "account" (the whole set) or "orders".
+ *   const { data } = useLoader(OrdersLoader, {
+ *     key: userId,
+ *     refreshGroup: ["account", "orders"],
+ *   });
+ *   return <span>{data.count} orders</span>;
+ * }
+ * function RefreshButtons() {
+ *   const refresh = useRefreshLoaders();
+ *   return (
+ *     <>
+ *       <button onClick={() => refresh("account")}>Refresh account</button>
+ *       <button onClick={() => refresh("orders")}>Refresh orders</button>
+ *       <button onClick={() => refresh(["account", "orders"])}>Refresh both</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useRefreshLoaders(): (
+  groups: string | string[],
+) => Promise<void> {
+  return useCallback(
+    (groups: string | string[]) => loaderStore.refreshGroups(groups),
+    [],
+  );
 }

package/src/vercel/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Vercel preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/vercel`. Vercel-only helpers live here so
+ * Node/other-platform consumers never pull them in. The Vercel cache store
+ * (`VercelCacheStore`) is exported from `@rangojs/router/cache`, mirroring the
+ * Cloudflare split where the store lives in `/cache` and the tracing helper in
+ * the platform subpath.
+ */
+
+export { createVercelTracing, type VercelTracingOptions } from "./tracing.js";