@rangojs/router 0.20.0 → 0.22.0

package/src/urls/path-helper.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Handler } from "../types.js";
+import type { Handler, InternalHandlerContext } from "../types.js";
 import type { RouteItem, RouteUseItem, UseItems } from "../route-types.js";
 import {
   getUrlPrefix,
@@ -8,7 +8,7 @@ import {
   requireDslContext,
   stampStaticDefScope,
 } from "../server/context";
-import { invariant, DataNotFoundError } from "../errors";
+import { invariant, DataNotFoundError, isDevEnvironment } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
@@ -60,6 +60,41 @@ function resolveResponseType(
   return options?.[RESPONSE_TYPE];
 }
 
+const NO_PRERENDER_DATA_MESSAGE = "No prerender data found for this route";
+
+/**
+ * A retained on-demand producer must never render on a live production
+ * request: bundle eviction is skipped for onDemand routes (the producer body
+ * stays available for router.prerender()), so without this gate an
+ * overlay+manifest miss on a plain Prerender(..., { onDemand }) route would
+ * execute the producer in-request — uncached per-request renders with the
+ * personalization guard unarmed. Keep the pre-retention miss contract instead
+ * (DataNotFoundError -> 404). Producer runs (build-time bake and
+ * router.prerender()) arrive with ctx.build true (createPrerenderContext);
+ * Vite dev keeps the documented live fall-through on a dev-store miss, except
+ * for a page the overlay marks removed (`_prerenderRemoved`): a live render
+ * would show in dev a page production answers with a 404.
+ * Pass-through when the route is not onDemand.
+ *
+ * @internal Exported for the unit test.
+ */
+export function gateOnDemandProducer<TEnv>(
+  producer: Handler<any, any, TEnv>,
+  isOnDemand: boolean,
+): Handler<any, any, TEnv> {
+  if (!isOnDemand) return producer;
+  return (ctx) => {
+    if (
+      !ctx.build &&
+      (!isDevEnvironment() ||
+        (ctx as InternalHandlerContext<any, TEnv>)._prerenderRemoved)
+    ) {
+      throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
+    }
+    return producer(ctx);
+  };
+}
+
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -117,6 +152,31 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
+    // On-demand opt-in lives on the (inner) Prerender def's options for both
+    // plain Prerender and Passthrough-wrapped routes. Presence (truthy, not
+    // false) marks the route ISR-eligible; the trie od flag + producer retention
+    // key off it.
+    const onDemandDef = isPassthroughHandler(handler)
+      ? handler.prerenderDef
+      : isPrerenderHandler(handler)
+        ? handler
+        : undefined;
+    const onDemandOpt = onDemandDef?.options?.onDemand;
+    const isOnDemand = onDemandOpt != null && onDemandOpt !== false;
+
+    // onDemand routes are excluded from the PPR shell lane (a writable refresh
+    // cannot atomically replace the captured shell), so ppr has no effect there.
+    // Thrown ahead of the forRoute early return so lazy evaluation of another
+    // route cannot skip it.
+    if (isOnDemand && options?.ppr !== undefined && options.ppr !== false) {
+      throw new Error(
+        `[rango] Route "${routeName}" sets both ppr and onDemand: onDemand ` +
+          `routes are excluded from the PPR shell lane, so ppr has no ` +
+          `effect here and the route serves without the shell fast path. ` +
+          `Drop one of the two options.`,
+      );
+    }
+
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
@@ -129,17 +189,16 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
           ? typeof handler.prerenderDef.handler === "function"
             ? (handler.prerenderDef.handler as Handler<any, any, TEnv>)
             : () => {
-                throw new DataNotFoundError(
-                  "No prerender data found for this route",
-                );
+                throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
               }
           : isPrerenderHandler(handler)
             ? typeof handler.handler === "function"
-              ? (handler.handler as Handler<any, any, TEnv>)
+              ? gateOnDemandProducer(
+                  handler.handler as Handler<any, any, TEnv>,
+                  isOnDemand,
+                )
               : () => {
-                  throw new DataNotFoundError(
-                    "No prerender data found for this route",
-                  );
+                  throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
                 }
             : isStaticHandler(handler)
               ? (handler.handler as Handler<any, any, TEnv>)
@@ -168,6 +227,7 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
               prerenderDef: handler as PrerenderHandlerDefinition,
             }
           : {}),
+      ...(isOnDemand ? { isOnDemand: true as const } : {}),
       ...(isStaticHandler(handler)
         ? {
             isStaticPrerender: true as const,

package/src/use-loader.tsx

@@ -14,9 +14,17 @@ import {
   type ReactNode,
 } from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
-import { loaderStore, type LoaderEntry } from "./loader-store.js";
+import {
+  EMPTY_LOADER_SNAPSHOT,
+  type LoaderEntry,
+  type LoaderStore,
+} from "./loader-store.js";
+import { NavigationStoreContext } from "./browser/react/context.js";
 import { decodeLoaderEntry } from "./decode-loader-results.js";
 import { warnAwaitedSsrSuspension } from "./ssr-suspension-warning.js";
+import { SETTLED_THENABLE } from "./thenable-status.js";
+import { useReadAudit } from "./suspense-audit-react.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
 function isShareableGet(options: LoadOptions | undefined): boolean {
@@ -202,15 +210,18 @@ function useLoaderInternal<T>(
     }
     return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
-
   // 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
+  // the implicit-suspense read. On replay after resolution use() 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;
+  // Dev only (suspense-audit.ts): the stream this reader is handed. The test
+  // is a build-time constant, so the hook is called on every render or never.
+  if (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT) {
+    useReadAudit(loader.$$id, walk.pendingStream);
+  }
   if (walk.pendingStream) {
     warnAwaitedSsrSuspension(
       loader.$$id,
@@ -218,6 +229,10 @@ function useLoaderInternal<T>(
       walk.pendingStream,
     );
     contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  } else if (hasContextData) {
+    // React logs a render that finishes without use() at a place whose reader
+    // suspended in use() on mount, so every read with route context calls it.
+    use(SETTLED_THENABLE);
   }
 
   const loaderId = loader.$$id;
@@ -245,10 +260,15 @@ function useLoaderInternal<T>(
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
+  // The router store's loader data (loader-store.ts). None on the server,
+  // where the hook reads the route's loader data only.
+  const loaders: LoaderStore | undefined = useContext(NavigationStoreContext)
+    ?.store?.loaders;
+
   const groupRefetch = useCallback(async (): Promise<void> => {
-    if (!loaderId) return;
-    const requestId = loaderStore.reserveRequestId(bucketKey);
-    loaderStore.beginRequest(bucketKey, requestId);
+    if (!loaderId || !loaders) return;
+    const requestId = loaders.reserveRequestId(bucketKey);
+    loaders.beginRequest(bucketKey, requestId);
     try {
       const url = new URL(window.location.href);
       url.searchParams.set("_rsc_loader", loaderId);
@@ -261,15 +281,15 @@ function useLoaderInternal<T>(
       if (payload.loaderError) {
         throw new Error(payload.loaderError.message);
       }
-      loaderStore.finishData(bucketKey, requestId, payload.loaderResult);
+      loaders.finishData(bucketKey, requestId, payload.loaderResult);
     } catch (e) {
       const err = e instanceof Error ? e : new Error(String(e));
-      loaderStore.finishError(bucketKey, requestId, err);
+      loaders.finishError(bucketKey, requestId, err);
       throw err;
     } finally {
-      loaderStore.setLoading(bucketKey, requestId, false);
+      loaders.setLoading(bucketKey, requestId, false);
     }
-  }, [loaderId, bucketKey]);
+  }, [loaderId, bucketKey, loaders]);
 
   // Held-navigation pin: a transition commit whose stream for this loader is
   // still pending announces it (loader-store.ts announcePendingStreams, which
@@ -283,14 +303,17 @@ function useLoaderInternal<T>(
     snapshot: LoaderEntry;
   }>(() => ({
     bucketKey,
-    snapshot: loaderStore.getSnapshot(bucketKey),
+    snapshot: loaders?.getSnapshot(bucketKey) ?? EMPTY_LOADER_SNAPSHOT,
   }));
+  // A new bucket (its key changed) reads nothing from the store during
+  // render: it renders empty until the effect below delivers its snapshot.
   const sharedSnapshot =
     sharedState.bucketKey === bucketKey
       ? sharedState.snapshot
-      : loaderStore.getSnapshot(bucketKey);
+      : EMPTY_LOADER_SNAPSHOT;
   useEffect(() => {
-    const initial = loaderStore.getSnapshot(bucketKey);
+    if (!loaders) return;
+    const initial = loaders.getSnapshot(bucketKey);
     if (initial !== sharedSnapshot) {
       startTransition(() => {
         setSharedState({ bucketKey, snapshot: initial });
@@ -299,10 +322,10 @@ function useLoaderInternal<T>(
     // 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(
+    return loaders.subscribe(
       bucketKey,
       () => {
-        const next = loaderStore.getSnapshot(bucketKey);
+        const next = loaders.getSnapshot(bucketKey);
         startTransition(() => {
           setSharedState({ bucketKey, snapshot: next });
         });
@@ -323,7 +346,7 @@ function useLoaderInternal<T>(
     // 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]);
+  }, [bucketKey, hasContextData, groupKey, groupRefetch, loaders]);
 
   // Local state holds the result of:
   //   - parameterized / mutation `load()` calls (load({ params }), POST,
@@ -369,10 +392,10 @@ function useLoaderInternal<T>(
       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);
+      loaders?.clearFamily(loaderId);
       prevContextDataRef.current = contextData;
     }
-  }, [contextData, loaderId]);
+  }, [contextData, loaderId, loaders]);
 
   // Read priority: a committed parameterized load() result overrides the shared
   // snapshot; a committed shared snapshot overrides the server-seeded context.
@@ -408,15 +431,17 @@ function useLoaderInternal<T>(
       const bucket = bucketKeyRef.current;
       const hasDedicatedBucket = bucket !== id;
 
-      const shared = hasDedicatedBucket
-        ? isShareableGet(loadOptions)
-        : isPlainRefetch(loadOptions) && hasContextDataRef.current;
+      const shared =
+        loaders !== undefined &&
+        (hasDedicatedBucket
+          ? isShareableGet(loadOptions)
+          : isPlainRefetch(loadOptions) && hasContextDataRef.current);
       let sharedRequestId = -1;
       let localRequestId = -1;
       if (shared) {
-        sharedRequestId = loaderStore.reserveRequestId(bucket);
+        sharedRequestId = loaders.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        loaderStore.beginRequest(bucket, sharedRequestId);
+        loaders.beginRequest(bucket, sharedRequestId);
       } else {
         localRequestId = ++localRequestIdRef.current;
         setLocalIsLoading(true);
@@ -503,7 +528,7 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (shared) {
-          loaderStore.finishData(bucket, sharedRequestId, result);
+          loaders.finishData(bucket, sharedRequestId, result);
         } else if (localRequestId === localRequestIdRef.current) {
           startTransition(() => {
             setLocalFetchedData({ has: true, value: result });
@@ -514,7 +539,7 @@ function useLoaderInternal<T>(
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
         if (shared) {
-          loaderStore.finishError(bucket, sharedRequestId, err);
+          loaders.finishError(bucket, sharedRequestId, err);
         } else if (localRequestId === localRequestIdRef.current) {
           setLocalError(err);
           setLocalIsLoading(false);
@@ -525,11 +550,11 @@ function useLoaderInternal<T>(
         return dataRef.current as T;
       } finally {
         if (shared) {
-          loaderStore.setLoading(bucket, sharedRequestId, false);
+          loaders.setLoading(bucket, sharedRequestId, false);
         }
       }
     },
-    [throwOnError],
+    [throwOnError, loaders],
   );
 
   if (throwOnError) {
@@ -708,8 +733,10 @@ export function useFetchLoader<T>(
 export function useRefreshLoaders(): (
   groups: string | string[],
 ) => Promise<void> {
+  const loaders = useContext(NavigationStoreContext)?.store?.loaders;
   return useCallback(
-    (groups: string | string[]) => loaderStore.refreshGroups(groups),
-    [],
+    (groups: string | string[]) =>
+      loaders ? loaders.refreshGroups(groups) : Promise.resolve(),
+    [loaders],
   );
 }