@rangojs/router 0.27.0 → 0.29.0

package/src/router/segment-resolution/streamed-handler-boundary.ts

@@ -44,6 +44,8 @@ export interface StreamedHandlerOptions<TEnv> {
   context: HandlerContext<any, TEnv>;
   routeKey?: string;
   params: Record<string, string>;
+  /** onError's `isPartial`, as the walk reports a sync handler's error. */
+  isPartial: true | undefined;
   /** False where the rejection must reach the caller (prerender, intercept background re-render). */
   recover: boolean;
 }
@@ -64,6 +66,7 @@ export function trackStreamedHandler<TEnv>(
   const tracked = deps.trackHandler(result as Promise<ReactNode>, {
     segmentId,
     segmentType,
+    isPartial: options.isPartial,
   });
   observeStreamedHandler(
     tracked,

package/src/router/segment-resolution.ts

@@ -5,20 +5,11 @@ export {
   buildLoaderErrorContext,
 } from "./segment-resolution/helpers.js";
 export {
-  resolveLoaders,
-  type ResolveSegmentOptions,
+  resolveLoadersOnly,
+  buildEntryRevalidateMap,
+  resolveParallelSegments,
+  resolveEntryHandler,
   resolveSegment,
   resolveOrphanLayout,
-  resolveParallelEntry,
   resolveAllSegments,
-  resolveLoadersOnly,
-} from "./segment-resolution/fresh.js";
-export {
-  resolveLoadersOnlyWithRevalidation,
-  buildEntryRevalidateMap,
-  resolveParallelSegmentsWithRevalidation,
-  resolveEntryHandlerWithRevalidation,
-  resolveSegmentWithRevalidation,
-  resolveOrphanLayoutWithRevalidation,
-  resolveAllSegmentsWithRevalidation,
 } from "./segment-resolution/revalidation.js";

package/src/router/segment-wrappers.ts

@@ -1,19 +1,14 @@
-import type { EntryData, InterceptEntry } from "../server/context";
-import type {
-  HandlerContext,
-  ResolvedSegment,
-  ShouldRevalidateFn,
-} from "../types";
 import type { SegmentResolutionDeps } from "./types.js";
-import type { ResolveSegmentOptions } from "./segment-resolution.js";
-import type { RevalidationContext } from "./router-context.js";
+import type { RouterContext } from "./router-context.js";
+import type {
+  ResolutionPass,
+  ResolutionPassInput,
+} from "./segment-resolution/resolution-pass.js";
 
 import {
-  resolveAllSegments as _resolveAllSegments,
   resolveLoadersOnly as _resolveLoadersOnly,
-  resolveLoadersOnlyWithRevalidation as _resolveLoadersOnlyWithRevalidation,
   buildEntryRevalidateMap as _buildEntryRevalidateMap,
-  resolveAllSegmentsWithRevalidation as _resolveAllSegmentsWithRevalidation,
+  resolveAllSegments as _resolveAllSegments,
 } from "./segment-resolution.js";
 
 import {
@@ -22,270 +17,57 @@ import {
   resolveInterceptLoadersOnly as _resolveInterceptLoadersOnly,
 } from "./intercept-resolution.js";
 
-import type { InterceptSelectorContext } from "../server/context";
-
-export interface SegmentWrappers<TEnv = any> {
-  resolveAllSegments: (
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>,
-    options?: ResolveSegmentOptions,
-  ) => Promise<ResolvedSegment[]>;
-  resolveLoadersOnly: (
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-  ) => Promise<ResolvedSegment[]>;
-  resolveLoadersOnlyWithRevalidation: (
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-    clientSegmentIds: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    routeKey: string,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-    stale?: boolean,
-  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
-  buildEntryRevalidateMap: (
-    entries: EntryData[],
-  ) => Map<
-    string,
-    { entry: EntryData; revalidate: ShouldRevalidateFn<any, any>[] }
-  >;
-  resolveAllSegmentsWithRevalidation: (
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    clientSegmentSet: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    actionContext:
-      | {
-          actionId?: string;
-          actionUrl?: URL;
-          actionResult?: any;
-          formData?: FormData;
-        }
-      | undefined,
-    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
-    localRouteName: string,
-    pathname: string,
-    stale?: boolean,
-    chain?: readonly EntryData[],
-  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
-  findInterceptForRoute: (
-    targetRouteKey: string,
-    fromEntry: EntryData | null,
-    selectorContext?: InterceptSelectorContext | null,
-    isAction?: boolean,
-  ) => { intercept: InterceptEntry; entry: EntryData } | null;
-  resolveInterceptEntry: (
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute?: boolean,
-    revalidationContext?: any,
-    options?: { background?: boolean },
-  ) => Promise<ResolvedSegment[]>;
-  resolveInterceptLoadersOnly: (
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean,
-    revalidationContext: RevalidationContext,
-  ) => Promise<ResolvedSegment[]>;
-}
+/** The resolvers RouterContext exposes, with the router's deps bound. */
+export type SegmentWrappers<TEnv = any> = Pick<
+  RouterContext<TEnv>,
+  "resolveAllSegments" | "resolveInterceptEntry"
+> &
+  Required<
+    Pick<
+      RouterContext<TEnv>,
+      | "resolveLoadersOnly"
+      | "buildEntryRevalidateMap"
+      | "resolveInterceptLoadersOnly"
+    >
+  > & {
+    /** Its own signature: a null selector context, isAction defaulting to false. */
+    findInterceptForRoute: typeof _findInterceptForRoute;
+  };
 
 /**
- * Create thin wrapper functions that bind segmentDeps to extracted
- * segment resolution and intercept resolution functions.
- *
- * These maintain the same signatures as the original inline functions
- * so that RouterContext and call sites don't need to change.
+ * Bind the router's segment deps into the extracted segment and intercept
+ * resolvers. Each gets a ResolutionPass: the caller's request-side input with
+ * the deps added here, once per call.
  */
 export function createSegmentWrappers<TEnv = any>(
-  segmentDeps: SegmentResolutionDeps<TEnv>,
+  deps: SegmentResolutionDeps<TEnv>,
 ): SegmentWrappers<TEnv> {
-  function resolveAllSegments(
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>,
-    options?: ResolveSegmentOptions,
-  ): ReturnType<typeof _resolveAllSegments> {
-    return _resolveAllSegments(
-      entries,
-      routeKey,
-      params,
-      context,
-      loaderPromises,
-      segmentDeps,
-      options,
-    );
-  }
-
-  function resolveLoadersOnly(
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-  ): ReturnType<typeof _resolveLoadersOnly> {
-    return _resolveLoadersOnly(entries, context, segmentDeps);
-  }
-
-  function resolveLoadersOnlyWithRevalidation(
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-    clientSegmentIds: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    routeKey: string,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-    stale?: boolean,
-  ): ReturnType<typeof _resolveLoadersOnlyWithRevalidation> {
-    return _resolveLoadersOnlyWithRevalidation(
-      entries,
-      context,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      segmentDeps,
-      actionContext,
-      stale,
-    );
-  }
-
-  function buildEntryRevalidateMap(
-    entries: EntryData[],
-  ): ReturnType<typeof _buildEntryRevalidateMap> {
-    return _buildEntryRevalidateMap(entries);
-  }
-
-  function resolveAllSegmentsWithRevalidation(
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    clientSegmentSet: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    actionContext:
-      | {
-          actionId?: string;
-          actionUrl?: URL;
-          actionResult?: any;
-          formData?: FormData;
-        }
-      | undefined,
-    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
-    localRouteName: string,
-    pathname: string,
-    stale?: boolean,
-    chain?: readonly EntryData[],
-  ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
-    return _resolveAllSegmentsWithRevalidation(
-      entries,
-      routeKey,
-      params,
-      context,
-      clientSegmentSet,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      actionContext,
-      interceptResult,
-      localRouteName,
-      pathname,
-      segmentDeps,
-      stale,
-      chain,
-    );
-  }
-
-  function findInterceptForRoute(
-    targetRouteKey: string,
-    fromEntry: EntryData | null,
-    selectorContext: InterceptSelectorContext | null = null,
-    isAction: boolean = false,
-  ): ReturnType<typeof _findInterceptForRoute> {
-    return _findInterceptForRoute(
-      targetRouteKey,
-      fromEntry,
-      selectorContext,
-      isAction,
-    );
-  }
-
-  function resolveInterceptEntry(
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean = true,
-    revalidationContext?: any,
-    options?: { background?: boolean },
-  ): ReturnType<typeof _resolveInterceptEntry> {
-    return _resolveInterceptEntry(
-      interceptEntry,
-      parentEntry,
-      params,
-      context,
-      belongsToRoute,
-      segmentDeps,
-      revalidationContext,
-      options,
-    );
-  }
-
-  function resolveInterceptLoadersOnly(
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean,
-    revalidationContext: RevalidationContext,
-  ): ReturnType<typeof _resolveInterceptLoadersOnly> {
-    return _resolveInterceptLoadersOnly(
-      interceptEntry,
-      parentEntry,
-      context,
-      belongsToRoute,
-      segmentDeps,
-      revalidationContext,
-    );
-  }
+  const pass = (input: ResolutionPassInput<TEnv>): ResolutionPass<TEnv> => ({
+    ...input,
+    deps,
+  });
 
   return {
-    resolveAllSegments: resolveAllSegments,
-    resolveLoadersOnly: resolveLoadersOnly,
-    resolveLoadersOnlyWithRevalidation: resolveLoadersOnlyWithRevalidation,
-    buildEntryRevalidateMap: buildEntryRevalidateMap,
-    resolveAllSegmentsWithRevalidation: resolveAllSegmentsWithRevalidation,
-    findInterceptForRoute: findInterceptForRoute,
-    resolveInterceptEntry: resolveInterceptEntry,
-    resolveInterceptLoadersOnly: resolveInterceptLoadersOnly,
+    resolveLoadersOnly: (input, entries, walk) =>
+      _resolveLoadersOnly(pass(input), entries, walk),
+    buildEntryRevalidateMap: _buildEntryRevalidateMap,
+    resolveAllSegments: (input, entries, walk) =>
+      _resolveAllSegments(pass(input), entries, walk),
+    findInterceptForRoute: _findInterceptForRoute,
+    resolveInterceptEntry: (input, intercept, entry, belongsToRoute, options) =>
+      _resolveInterceptEntry(
+        pass(input),
+        intercept,
+        entry,
+        belongsToRoute,
+        options,
+      ),
+    resolveInterceptLoadersOnly: (input, intercept, entry, belongsToRoute) =>
+      _resolveInterceptLoadersOnly(
+        pass(input),
+        intercept,
+        entry,
+        belongsToRoute,
+      ),
   };
 }

package/src/router/telemetry.ts

@@ -317,6 +317,11 @@ export function getRequestId(request: Request): string {
   return id;
 }
 
+/** Make `id` the id getRequestId returns for `request`. */
+export function setRequestId(request: Request, id: string): void {
+  requestIds.set(request, id);
+}
+
 /**
  * Built-in console sink that logs events in a structured format.
  * Designed as the default sink for development / debugging.

package/src/router/types.ts

@@ -32,6 +32,16 @@ export type ActionContext = {
   actionUrl?: URL;
   actionResult?: any;
   formData?: FormData;
+  /**
+   * A thrown action's error segment (matchError), set on the action's
+   * revalidation (rsc/server-action.ts matchBoundaryRevalidation). The walk
+   * (resolveAllSegments) resolves every entry above the segment's outlet as on
+   * a success, emits the segment in the outlet's place and stops, so nothing
+   * at or below the outlet runs. The pass skips the prerender store
+   * (cache-lookup.ts): the evicted handler is under the cut. No revalidate()
+   * predicate sees it.
+   */
+  boundary?: ResolvedSegment;
 };
 
 export interface SegmentResolutionDeps<TEnv = any> {
@@ -47,7 +57,6 @@ export interface SegmentResolutionDeps<TEnv = any> {
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     /** An `ssr: false` loader on a document or capture render. */
     useDefaultErrorBoundary?: boolean,
@@ -57,6 +66,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ) => Promise<T>;
   findNearestErrorBoundary: (

package/src/router.ts

@@ -44,6 +44,7 @@ import { createHandleStore, type HandleStore } from "./server/handle-store.js";
 import {
   getRequestContext,
   _getRequestContext,
+  reportedErrorsOf,
 } from "./server/request-context.js";
 import type {
   ErrorPhase,
@@ -315,7 +316,8 @@ export function createRouter<TEnv = any>(
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
    *
-   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * Deduplicates via per-request WeakSet stored on the ALS request context
+   * (background work keeps its own, reportedErrorsOf).
    * A closure-level WeakSet would silently swallow errors if the same object
    * instance is thrown across separate requests (e.g. a singleton error).
    */
@@ -325,7 +327,8 @@ export function createRouter<TEnv = any>(
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
     if (error != null && typeof error === "object") {
-      const reportedErrors = _getRequestContext()?._reportedErrors;
+      const reqCtx = _getRequestContext();
+      const reportedErrors = reqCtx && reportedErrorsOf(reqCtx);
       if (reportedErrors) {
         if (reportedErrors.has(error)) return;
         reportedErrors.add(error);
@@ -488,6 +491,7 @@ export function createRouter<TEnv = any>(
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ): Promise<T> => {
     // One ALS read serves both the store lookup and the onError closure.
@@ -520,6 +524,7 @@ export function createRouter<TEnv = any>(
           env: reqCtx.env as TEnv,
           segmentId: errorContext?.segmentId,
           segmentType: errorContext?.segmentType as any,
+          isPartial: errorContext?.isPartial,
           handledByBoundary: true,
         });
       });
@@ -542,22 +547,24 @@ export function createRouter<TEnv = any>(
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     useDefaultErrorBoundary?: boolean,
   ): Promise<LoaderDataResult<T>> {
-    const loaderStart = telemetrySink ? performance.now() : 0;
-    const loaderRequestId = telemetrySink
+    // A PPR shell capture sends nothing to the sink: the same switch as match().
+    const emitTelemetry =
+      !!telemetrySink && !_getRequestContext()?._shellCaptureState?.run;
+    const loaderStart = emitTelemetry ? performance.now() : 0;
+    const loaderRequestId = emitTelemetry
       ? errorContext?.request
         ? getRequestId(errorContext.request)
         : undefined
       : undefined;
     // Derived once here for both the loader.start and loader.end emits (the
     // loader.error emit uses ctx.loaderName from wrapLoaderWithErrorHandling).
-    const loaderName = telemetrySink
+    const loaderName = emitTelemetry
       ? segmentId.split(".").pop() || "unknown"
       : "";
-    if (telemetrySink) {
+    if (emitTelemetry) {
       safeEmit(telemetry, {
         type: "loader.start",
         timestamp: loaderStart,
@@ -589,9 +596,8 @@ export function createRouter<TEnv = any>(
               env: errorContext.env,
               isPartial: errorContext.isPartial,
               handledByBoundary: ctx.handledByBoundary,
-              requestStartTime: errorContext.requestStartTime,
             });
-            if (telemetrySink) {
+            if (emitTelemetry) {
               const errorObj =
                 error instanceof Error ? error : new Error(String(error));
               safeEmit(telemetry, {
@@ -618,7 +624,7 @@ export function createRouter<TEnv = any>(
     );
 
     // Emit loader.end after the promise settles (fire-and-forget)
-    if (telemetrySink) {
+    if (emitTelemetry) {
       result.then((r) => {
         safeEmit(telemetry, {
           type: "loader.end",
@@ -663,11 +669,9 @@ export function createRouter<TEnv = any>(
 
   // Create segment resolution wrappers bound to segmentDeps
   const {
-    resolveAllSegments,
     resolveLoadersOnly,
-    resolveLoadersOnlyWithRevalidation,
     buildEntryRevalidateMap,
-    resolveAllSegmentsWithRevalidation,
+    resolveAllSegments,
     findInterceptForRoute,
     resolveInterceptEntry,
     resolveInterceptLoadersOnly,
@@ -713,16 +717,14 @@ export function createRouter<TEnv = any>(
       getMetricsStore,
       createCacheScope,
       findInterceptForRoute,
-      resolveAllSegmentsWithRevalidation,
+      resolveAllSegments,
       resolveInterceptEntry,
       evaluateRevalidation,
       getRequestContext,
-      resolveAllSegments,
       createHandleStore,
       buildEntryRevalidateMap,
-      resolveLoadersOnlyWithRevalidation,
-      resolveInterceptLoadersOnly,
       resolveLoadersOnly,
+      resolveInterceptLoadersOnly,
       telemetry: telemetrySink,
     };
   }

package/src/rsc/full-payload.ts

@@ -61,7 +61,7 @@ export function buildFullPayload(
       // capture renders from what its record keeps (resolvedHandleStream).
       handles: resolvedHandleStream(
         handleStore,
-        reqCtx._shellCaptureRun === true,
+        reqCtx._shellCaptureState?.run === true,
       ),
       // Post-handler-barrier pushes (streaming loader ctx.handle() writes)
       // stream here; the client applies them after hydration. Instantly
@@ -105,8 +105,7 @@ export function renderedLocation(
     | Pick<
         RequestContext<any>,
         | "_variables"
-        | "_shellCaptureRun"
-        | "_shellCaptureForVisitor"
+        | "_shellCaptureState"
         | "_documentCacheRender"
         | "_payloadVisitorLocation"
         | "res"
@@ -116,7 +115,9 @@ export function renderedLocation(
 ): URL {
   if (!reqCtx || !rewriteTrail(reqCtx)) return url;
   if (rendersForSharedAudience(reqCtx)) {
-    return reqCtx._shellCaptureForVisitor ? visitorUrl(reqCtx, url) : url;
+    return reqCtx._shellCaptureState?.forVisitor
+      ? visitorUrl(reqCtx, url)
+      : url;
   }
   reqCtx._payloadVisitorLocation = true;
   return visitorUrl(reqCtx, url);
@@ -163,7 +164,7 @@ export function payloadInitialTheme(
   reqCtx: Pick<
     RequestContext<any>,
     | "_themeConfig"
-    | "_shellCaptureRun"
+    | "_shellCaptureState"
     | "_readTheme"
     | "_documentCacheRender"
     | "_payloadVisitorTheme"

package/src/rsc/handler-context.ts

@@ -7,12 +7,17 @@
  */
 
 import type { RangoInternal } from "../router/router-interfaces.js";
-import type { ErrorPhase } from "../types.js";
-import type { InvokeOnErrorContext } from "../router/error-handling.js";
 import type { RSCDependencies, LoadSSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
+import type { RequestStageContext } from "./request-stages.js";
 
-export interface HandlerContext<TEnv = unknown> {
+/**
+ * Extends what the request stages (rsc/request-stages.ts) call back into, so
+ * the handler hands this one bundle to them as well.
+ */
+export interface HandlerContext<
+  TEnv = unknown,
+> extends RequestStageContext<TEnv> {
   router: RangoInternal<TEnv, any>;
   /**
    * The router's DOCUMENT version (router-versions.ts): payload metadata, the
@@ -28,17 +33,6 @@ export interface HandlerContext<TEnv = unknown> {
   decodeAction: RSCDependencies["decodeAction"];
   decodeFormState: RSCDependencies["decodeFormState"];
   loadSSRModule: LoadSSRModule;
-  callOnError: (
-    error: unknown,
-    phase: ErrorPhase,
-    context: InvokeOnErrorContext<TEnv>,
-  ) => void;
-  getRequiredRouteMap: () => Record<string, string>;
-  createRedirectFlightResponse: (
-    redirectUrl: string,
-    locationState?: Record<string, unknown>,
-    external?: boolean,
-  ) => Response;
 
   /**
    * Resolve the SSR stream mode for a given request.