@rangojs/router 0.22.1 → 0.24.0

package/src/handles/pushed-by.ts

@@ -0,0 +1,148 @@
+import { LOADER_SEGMENT_ID } from "../browser/react/filter-segment-order.js";
+import type { HandleData } from "../server/handle-store.js";
+
+/**
+ * Which run pushed each handle value, so a partial response replaces only the
+ * pushes of what it re-ran (#1103).
+ *
+ * A segment's handle bucket holds its handler's pushes and those of the
+ * loaders registered on it: a loader pushes under its owning segment's id
+ * (fresh.ts, revalidation.ts pin `_currentSegmentId`). A navigation or an
+ * action response decides each of them on its own: the handler re-runs and a
+ * loader whose revalidate() answers false keeps its data on the client. The
+ * response carries only what re-ran, so replacing the whole bucket with it
+ * dropped the pushes of the loader whose data the page still shows (the
+ * document title, a breadcrumb), and a loader re-run under a handler that did
+ * not re-run took the handler's pushes with it.
+ *
+ * The record rides in the snapshot itself, beside each handle, under a name
+ * no handle has: `data[pushedByKey(h)][segmentId][i]` is the $$id of the
+ * loader whose run pushed `data[h][segmentId][i]`, or null for the segment's
+ * handler. A bucket without a loader push has no entry. Inside the snapshot it
+ * crosses Flight and every clone and history-cache copy with the values;
+ * collectHandleData reads a handle by its $$id, so no collect sees it.
+ * resolveDeferredHandleValues keeps it aligned when it drops a value.
+ */
+const PUSHED_BY_SUFFIX = "\u0000pushedBy";
+
+/** The snapshot key holding `handleName`'s pushedBy record. */
+export function pushedByKey(handleName: string): string {
+  return handleName + PUSHED_BY_SUFFIX;
+}
+
+/** True for a pushedBy record's key, false for a handle's. */
+export function isPushedByKey(name: string): boolean {
+  return name.endsWith(PUSHED_BY_SUFFIX);
+}
+
+/** `data` without its pushedBy records, as a reader outside the router sees it. */
+export function withoutPushedBy(data: HandleData): HandleData {
+  const out: HandleData = {};
+  for (const name in data) {
+    if (!isPushedByKey(name)) out[name] = data[name];
+  }
+  return out;
+}
+
+type PushedBy = readonly (string | null)[] | undefined;
+
+const keysOf = (a: object | undefined, b: object | undefined): Set<string> =>
+  new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+
+/**
+ * `target` with the buckets of the segments in `ids` taken from `source`.
+ * A pushedBy record is a snapshot key like a handle's, so a bucket's values
+ * and the record of the runs that pushed them always come from the same
+ * snapshot. New containers; the value arrays are shared, as cloneHandleData
+ * (navigation-store.ts) shares them.
+ */
+export function withSegmentHandles(
+  target: HandleData,
+  source: HandleData,
+  ids: ReadonlySet<string>,
+): HandleData {
+  const out: HandleData = {};
+  for (const name of keysOf(target, source)) {
+    const buckets: Record<string, unknown[]> = {};
+    for (const [id, values] of Object.entries(target[name] ?? {})) {
+      if (!ids.has(id)) buckets[id] = values;
+    }
+    for (const [id, values] of Object.entries(source[name] ?? {})) {
+      if (ids.has(id)) buckets[id] = values;
+    }
+    if (Object.keys(buckets).length > 0) out[name] = buckets;
+  }
+  return out;
+}
+
+/**
+ * The handle data after a partial response's snapshot `incoming` (each stream
+ * yield holds everything the response pushed so far). A segment outside
+ * `segmentOrder` loses its buckets. In the others a value stands for the run
+ * that pushed it: the segment's handler, or a loader `matched` registers on
+ * the segment (`${shortCode}D${index}.${$$id}`, a loader's pushes being filed
+ * under its shortCode; an id it does not register, a dependency or a loader a
+ * handler read, counts as the handler's). A run that has values in the
+ * response, or ran for it (`resolvedIds`: the handlers and loaders that ran),
+ * replaces its values with the ones it delivered, nothing when it delivered
+ * none. The other runs keep theirs in place, and the response's values take
+ * the position of the first value they replace (the end when they replace
+ * none). New containers throughout: an object a reader was handed (a history
+ * entry's data) is never written to.
+ */
+export function mergePartialHandleData(
+  current: HandleData,
+  incoming: HandleData,
+  segmentOrder: readonly string[],
+  matched: readonly string[],
+  resolvedIds: readonly string[] | undefined,
+): HandleData {
+  // A run's key: a segment's id for its handler, `${segmentId}\0${$$id}` for
+  // a loader (its segment id with the `D${index}.` marker replaced).
+  const runKey = (id: string): string =>
+    id.replace(LOADER_SEGMENT_ID, "\u0000");
+  const inOrder = new Set(segmentOrder);
+  const registered = new Set(matched.map(runKey));
+  const ran = new Set(resolvedIds?.map(runKey));
+  const out: HandleData = {};
+  for (const name of keysOf(current, incoming)) {
+    if (isPushedByKey(name)) continue;
+    const byName = pushedByKey(name);
+    const buckets: Record<string, unknown[]> = (out[name] = {});
+    for (const segmentId of keysOf(current[name], incoming[name])) {
+      if (!inOrder.has(segmentId)) continue;
+      const run = (by: PushedBy, i: number): string => {
+        const key = `${segmentId}\u0000${by?.[i]}`;
+        return registered.has(key) ? key : segmentId;
+      };
+      const currentBy = current[byName]?.[segmentId] as PushedBy;
+      const incomingValues = incoming[name]?.[segmentId] ?? [];
+      const incomingBy = incoming[byName]?.[segmentId] as PushedBy;
+      const delivered = new Set(
+        incomingValues.map((_, i) => run(incomingBy, i)),
+      );
+      const values: unknown[] = [];
+      const by: (string | null)[] = [];
+      let at = -1;
+      (current[name]?.[segmentId] ?? []).forEach((value, i) => {
+        const key = run(currentBy, i);
+        if (delivered.has(key) || ran.has(key)) {
+          if (at < 0) at = values.length;
+        } else {
+          values.push(value);
+          by.push(currentBy?.[i] ?? null);
+        }
+      });
+      if (at < 0) at = values.length;
+      values.splice(at, 0, ...incomingValues);
+      by.splice(
+        at,
+        0,
+        ...incomingValues.map((_, i) => incomingBy?.[i] ?? null),
+      );
+      if (values.length > 0) buckets[segmentId] = values;
+      if (by.some((run) => run !== null)) (out[byName] ??= {})[segmentId] = by;
+    }
+  }
+  return out;
+}

package/src/index.rsc.ts

@@ -119,6 +119,14 @@ export {
   transition,
 } from "./route-definition.js";
 
+// Render another route at the same URL from middleware (throw rewrite()).
+export {
+  rewrite,
+  type Rewrite,
+  type RewriteFunction,
+} from "./route-definition/rewrite.js";
+export { RewriteLoopError } from "./errors.js";
+
 // Composition types for reusable callback factories
 export type {
   RouteUseItem,

package/src/index.ts

@@ -155,6 +155,13 @@ export function redirect(): never {
   throw serverOnlyStubError("redirect");
 }
 
+/**
+ * Error-throwing stub for server-only `rewrite` function.
+ */
+export function rewrite(): never {
+  throw serverOnlyStubError("rewrite");
+}
+
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
 export {

package/src/loader-store.ts

@@ -36,6 +36,7 @@
  */
 
 import { unwrapsSynchronously } from "./thenable-status.js";
+import { asStream } from "./browser/defer.js";
 
 /** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
 export interface PendingStreamSource {
@@ -538,14 +539,23 @@ export class LoaderStore {
       this.pendingStreams.set(loaderId, set);
     }
     set.add(stream);
-    const release = () => {
-      const current = this.pendingStreams.get(loaderId);
-      if (!current || !current.delete(stream)) return;
-      if (current.size === 0) this.pendingStreams.delete(loaderId);
-    };
+    const release = () => this.releasePendingStream(loaderId, stream);
     stream.then(release, release);
   }
 
+  /**
+   * Stop tracking a stream. trackPendingStream does it as the stream settles;
+   * an abandoned fill's hole (browser/partial-update.ts releaseHoles) never
+   * settles, and
+   * left tracked it would pin the family's held readers on every later
+   * transition.
+   */
+  releasePendingStream(loaderId: string, stream: Promise<unknown>): void {
+    const current = this.pendingStreams.get(loaderId);
+    if (!current || !current.delete(stream)) return;
+    if (current.size === 0) this.pendingStreams.delete(loaderId);
+  }
+
   /** True while any navigation stream for `loaderId` is still pending. */
   isStreamPending(loaderId: string): boolean {
     return this.pendingStreams.has(loaderId);
@@ -566,12 +576,13 @@ export class LoaderStore {
    */
   announcePendingStreams(segments: readonly PendingStreamSource[]): void {
     for (const segment of segments) {
+      const data = asStream(segment.loaderData);
       if (
         segment.type === "loader" &&
         segment.loaderId &&
-        segment.loaderData instanceof Promise
+        data instanceof Promise
       ) {
-        this.trackPendingStream(segment.loaderId, segment.loaderData);
+        this.trackPendingStream(segment.loaderId, data);
       }
     }
     for (const loaderId of this.pendingStreams.keys()) {

package/src/prefetch-markers.ts

@@ -0,0 +1,13 @@
+/**
+ * The wire markers of `prefetch: false` (docs/design/prefetch-false.md):
+ * shared by the browser that sends them and the server that reads them
+ * (router/segment-resolution/prefetch-deferral.ts requestKind). Dependency
+ * free, like segment-fragments.ts: the browser must not import the server
+ * module that reads them.
+ */
+
+/** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
+export const PREFETCH_HEADER = "X-Rango-Prefetch";
+
+/** Query param of a fill request (browser/navigation-client.ts). */
+export const FILL_PARAM = "_rsc_fill";

package/src/response-utils.ts

@@ -60,3 +60,22 @@ export function isRedirectResponse(response: Response): boolean {
     Boolean(response.headers.get("Location"))
   );
 }
+
+/**
+ * Set a header on a response the router hands to the host, skipping a
+ * WebSocket upgrade (its headers are not to be touched) and swallowing the
+ * TypeError of immutable headers (a passed-through platform Response):
+ * instrumentation and debug headers never fail a request.
+ */
+export function trySetHeader(
+  response: Response,
+  name: string,
+  value: string,
+): void {
+  if (isWebSocketUpgradeResponse(response)) return;
+  try {
+    response.headers.set(name, value);
+  } catch {
+    // Immutable headers: drop the header, never the response.
+  }
+}

package/src/reverse.ts

@@ -149,6 +149,7 @@ export type ReverseFunction<TRoutes> = {
 export type ScopedReverseFunction<
   TLocalRoutes,
   TGlobalRoutes = TLocalRoutes,
+  TResult = string,
 > = {
   /**
    * Global route without params
@@ -159,7 +160,7 @@ export type ScopedReverseFunction<
     > extends true
       ? TName
       : never,
-  ): string;
+  ): TResult;
 
   /**
    * Global route with params
@@ -167,7 +168,7 @@ export type ScopedReverseFunction<
   <TName extends keyof TGlobalRoutes & string>(
     name: TName,
     params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Global route with params and search
@@ -176,7 +177,7 @@ export type ScopedReverseFunction<
     name: TName,
     params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route without params
@@ -187,7 +188,7 @@ export type ScopedReverseFunction<
     > extends true
       ? `.${TName}`
       : never,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route with params
@@ -195,7 +196,7 @@ export type ScopedReverseFunction<
   <TName extends keyof TLocalRoutes & string>(
     name: `.${TName}`,
     params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route with params and search
@@ -204,7 +205,7 @@ export type ScopedReverseFunction<
     name: `.${TName}`,
     params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
-  ): string;
+  ): TResult;
 };
 
 /**
@@ -235,14 +236,16 @@ export type ScopedReverseFunction<
  * reverse(".post", { slug: "hello" })     // compile error: no include() scope
  * ```
  */
-export type GlobalReverseFunction<TGlobalRoutes> =
-  string extends keyof TGlobalRoutes
-    ? <TName extends string>(
-        name: Exclude<TName, `.${string}`>,
-        params?: Record<string, string>,
-        search?: Record<string, unknown>,
-      ) => string
-    : ScopedReverseFunction<{}, TGlobalRoutes>;
+export type GlobalReverseFunction<
+  TGlobalRoutes,
+  TResult = string,
+> = string extends keyof TGlobalRoutes
+  ? <TName extends string>(
+      name: Exclude<TName, `.${string}`>,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => TResult
+  : ScopedReverseFunction<{}, TGlobalRoutes, TResult>;
 
 /**
  * Extract local routes type from UrlPatterns

package/src/route-content-wrapper.tsx

@@ -10,12 +10,14 @@ import {
   LOADER_REDIRECT,
 } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
+import { Defer, readDefer } from "./browser/defer.js";
 import type { BoundaryAudit } from "./suspense-audit.js";
 import {
   AuditedFallback,
   useBoundaryAudit,
   useRevealAudit,
 } from "./suspense-audit-react.js";
+import { SETTLED_THENABLE } from "./thenable-status.js";
 
 /**
  * Router-owned error boundary for read-site loader errors. segment-system
@@ -141,7 +143,7 @@ export function AuditedRouteContent({
   const audit = useBoundaryAudit(
     `content:${segmentId}`,
     segmentId ?? "",
-    content,
+    content instanceof Defer ? content.promise : content,
   );
   return (
     <Suspense
@@ -174,8 +176,16 @@ const Suspender = ({
   // A pending promise suspends here and the wrapping Suspense shows the
   // loading() fallback; a node renders without suspending. The wrapper tree
   // (RouteContentWrapper > Suspense > Suspender) is identical either way (see
-  // docs/tree-structure.md), like LoaderResolver's resolved-data branch.
-  return content instanceof Promise ? use(content) : content;
+  // docs/tree-structure.md), like LoaderResolver's resolved-data branch. A
+  // `prefetch: false` hole is read here, by the read rule, so the filled
+  // page's node later takes the same place. The content can be a pending
+  // promise in one tree and its node in the next: use() at this place on
+  // every render, as LoaderResolver does.
+  return content instanceof Defer
+    ? (readDefer(content) as ReactNode)
+    : content instanceof Promise
+      ? use(content)
+      : (use(SETTLED_THENABLE), content);
 };
 
 /**
@@ -329,10 +339,14 @@ function LoaderResolver({
     );
   }
 
+  // A slot's aggregate can be a pending promise on one render and its arrived
+  // array on the next (segment-loader-promise.ts): use() at this place on
+  // every render, or React reports a component that suspended in use() and
+  // then finished without it (the useLoader pattern, use-loader.tsx).
   const resolvedData =
     loaderDataPromise instanceof Promise
       ? use(loaderDataPromise)
-      : loaderDataPromise;
+      : (use(SETTLED_THENABLE), loaderDataPromise);
 
   const { loaderData, errorFallback } = decodeLoaderResults(
     resolvedData,

package/src/route-definition/dsl-helpers.ts

@@ -22,7 +22,7 @@ import {
   type InterceptConfig,
   type LoaderEntry,
 } from "../server/context";
-import { invariant } from "../errors";
+import { assertBooleanOption, invariant } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import { isCachedFunction } from "../cache/taint.js";
 import { RangoContext } from "../server/context";
@@ -44,6 +44,7 @@ import type {
   TransitionItem,
   UseItems,
 } from "../route-types.js";
+import { isRenderableLoading } from "../types/boundaries.js";
 import type { RouteHelpers } from "./helpers-types.js";
 import {
   resolveHandlerUse,
@@ -899,9 +900,15 @@ const loader: RouteHelpers<any, any>["loader"] = (
     (optionsGiven as { stream?: unknown } | undefined)?.stream === undefined,
     "loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
   );
-  invariant(
-    optionsGiven?.ssr === undefined || typeof optionsGiven.ssr === "boolean",
-    `loader() ssr must be a boolean (got ${JSON.stringify(optionsGiven?.ssr)}). Omit it (or pass true) to stream on every render.`,
+  assertBooleanOption(
+    optionsGiven?.ssr,
+    "loader() ssr",
+    "stream on every render",
+  );
+  assertBooleanOption(
+    optionsGiven?.prefetch,
+    "loader() prefetch",
+    "run the loader in prefetches",
   );
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
@@ -917,6 +924,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
     ...(optionsGiven?.ssr === false && { bake: true as const }),
     ...(optionsGiven?.ssr === false &&
       ctx.isSSR && { awaitBeforeFlush: true as const }),
+    ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use
@@ -969,6 +977,12 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
     invariant(false, "No parent entry available for loading()");
   }
 
+  assertBooleanOption(
+    options?.prefetch,
+    "loading() prefetch",
+    "render what the fallback covers in prefetches",
+  );
+
   // Unwrap function form: loading(() => <Skeleton />) → loading(<Skeleton />)
   const resolved =
     typeof component === "function" ? (component as () => any)() : component;
@@ -980,6 +994,15 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
     parent.loading = resolved;
   }
 
+  // The flag means "what this fallback covers": without a fallback to show
+  // there is nothing to defer behind. Recorded from `resolved`, not
+  // `parent.loading`, so the document evaluation (ssr: false) agrees with
+  // the navigation one. Last loading() wins, like `loading` itself.
+  parent.loadingPrefetch =
+    options?.prefetch === false && isRenderableLoading(resolved)
+      ? false
+      : undefined;
+
   const name = `$${store.getNextIndex("loading")}`;
   return { name, type: "loading" } as LoadingItem;
 };

package/src/route-definition/helpers-types.ts

@@ -328,6 +328,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *
+   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+   * prefetch skips it and the click that adopts the prefetch fetches it in
+   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * client does not have yet: a loader the client already holds runs in the
+   * prefetch when it revalidates.
+   *
+   * ```typescript
+   * loader(ReviewsLoader, { prefetch: false }),
+   * ```
+   *
    * @param loaderDef - Loader created with createLoader()
    * @param optionsOrUse - Delivery options, or the use() callback when passing none
    * @param use - Optional callback for loader-specific revalidation rules
@@ -345,14 +355,30 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *
    * // Skip loading on SSR, only show on client navigation
    * loading(<Skeleton />, { ssr: false })
+   *
+   * // Keep everything behind this fallback out of prefetches
+   * loading(<Skeleton />, { prefetch: false })
    * ```
    * @param component - The loading UI to show during navigation
    * @param options - Configuration options
    * @param options.ssr - If false, skip showing loading on document requests (SSR)
+   * @param options.prefetch - If false, the flag applies when this entry's
+   *   segment is new to the client. A prefetch then skips the whole unit: the
+   *   handler, its loaders, its orphan layouts and parallel slots and, for a
+   *   layout, every deeper entry; the click that adopts the prefetch shows
+   *   this fallback and fetches them in one follow-up request, which reads
+   *   cache() and "use cache" as any request does (a prefetch reads neither
+   *   for skipped work). A segment the client already holds is never
+   *   deferred: a prefetch renders it as usual when it revalidates, and what
+   *   is below it follows its own flags. To keep a child out of prefetches
+   *   while moving inside a section, flag the child's own loading(). An entry
+   *   whose handler output is stored (cache(), ppr, Prerender/Static) is
+   *   served as usual and only its loaders are skipped. Loaders behind the
+   *   fallback cannot call ctx.rendered().
    */
   loading: (
     component: ReactNode | (() => ReactNode),
-    options?: { ssr?: boolean },
+    options?: { ssr?: boolean; prefetch?: boolean },
   ) => LoadingItem;
   /**
    * Attach an error boundary to catch errors in this segment and children

package/src/route-definition/redirect.ts

@@ -8,6 +8,7 @@ import {
   attachRedirectState,
   markExternalRedirect,
 } from "../redirect-origin.js";
+import { prefixBasename } from "../router/basename.js";
 
 /**
  * Create a soft redirect Response for middleware short-circuit
@@ -84,21 +85,7 @@ export function redirect(
   }
 
   // Auto-prefix root-relative URLs with basename for app-local redirects.
-  // Treat the URL as already-prefixed when the basename is followed by a path
-  // separator, a query, a fragment, or end-of-string, so "/admin?tab=x" and
-  // "/admin#frag" are not double-prefixed into "/admin/admin?tab=x".
-  const bn = _getRequestContext()?._basename;
-  let resolvedUrl = url;
-  if (
-    bn &&
-    url.startsWith("/") &&
-    url !== bn &&
-    !url.startsWith(bn + "/") &&
-    !url.startsWith(bn + "?") &&
-    !url.startsWith(bn + "#")
-  ) {
-    resolvedUrl = url === "/" ? bn : bn + url;
-  }
+  const resolvedUrl = prefixBasename(url, _getRequestContext()?._basename);
 
   const headers: Record<string, string> = {
     Location: resolvedUrl,