@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bdaf10aa

package/src/router/intercept-resolution.ts

@@ -11,15 +11,24 @@ import type {
   InterceptEntry,
   InterceptSelectorContext,
 } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../types";
 import { evaluateRevalidation } from "./revalidation.js";
 import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
 import { createReverseFunction } from "./handler-context.js";
 import { getGlobalRouteMap } from "../route-map-builder.js";
-import { handleHandlerResult } from "./segment-resolution.js";
+import {
+  handleHandlerResult,
+  warnOnStreamedResponse,
+  buildLoaderErrorContext,
+} from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { runInsideLoaderScope } from "../server/context.js";
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -61,28 +70,14 @@ export function findInterceptForRoute(
   let current: EntryData | null = fromEntry;
 
   while (current) {
-    if (current.intercept && current.intercept.length > 0) {
-      for (const intercept of current.intercept) {
+    // current first, then its sibling layouts — same order as before.
+    for (const source of [current, ...current.layout]) {
+      for (const intercept of source.intercept) {
         if (
           intercept.routeName === targetRouteKey &&
           evaluateInterceptWhen(intercept, selectorContext, isAction)
         ) {
-          return { intercept, entry: current };
-        }
-      }
-    }
-
-    if (current.layout && current.layout.length > 0) {
-      for (const siblingLayout of current.layout) {
-        if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-          for (const intercept of siblingLayout.intercept) {
-            if (
-              intercept.routeName === targetRouteKey &&
-              evaluateInterceptWhen(intercept, selectorContext, isAction)
-            ) {
-              return { intercept, entry: siblingLayout };
-            }
-          }
+          return { intercept, entry: source };
         }
       }
     }
@@ -118,10 +113,25 @@ export async function resolveInterceptEntry<TEnv>(
     };
     stale?: boolean;
   },
+  options?: {
+    /**
+     * Skip the intercept's middleware execution. Set ONLY by the post-response
+     * background re-render paths (proactive caching, stale background
+     * revalidation), whose sole purpose is to re-render the segment tree to
+     * populate the cache. The foreground request already ran the intercept
+     * middleware before the response was sent — it validated auth, set cookies,
+     * and wrote context vars into the request context's shared `_variables`,
+     * which the background render reuses. Re-running middleware here would fire
+     * its side effects a SECOND time, and a middleware that short-circuits with
+     * a Response would `throw` and silently abort the cache write. Never set on
+     * the foreground path.
+     */
+    skipMiddleware?: boolean;
+  },
 ): Promise<ResolvedSegment[]> {
   const segments: ResolvedSegment[] = [];
 
-  if (interceptEntry.middleware.length > 0) {
+  if (!options?.skipMiddleware && interceptEntry.middleware.length > 0) {
     const requestCtx = getRequestContext();
     if (!requestCtx?.res) {
       throw new Error(
@@ -133,7 +143,7 @@ export async function resolveInterceptEntry<TEnv>(
       context.request,
       context.env,
       params,
-      context.var as Record<string, any>,
+      (context as InternalHandlerContext<any, TEnv>)._variables,
       requestCtx.res,
       createReverseFunction(getGlobalRouteMap()),
     );
@@ -188,6 +198,7 @@ export async function resolveInterceptEntry<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "intercept-loader",
         });
 
         if (!shouldRevalidate) {
@@ -206,10 +217,13 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
+        // Report a throwing intercept loader to onError + loader.error telemetry,
+        // matching the fresh/revalidation paths.
+        buildLoaderErrorContext(context),
       ),
     );
   }
@@ -236,6 +250,12 @@ export async function resolveInterceptEntry<TEnv>(
   let loaderDataPromise: Promise<any[]> | any[] | undefined;
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
+    if (handlerResult instanceof Promise) {
+      warnOnStreamedResponse(
+        handlerResult,
+        `intercept ${interceptEntry.slotName}`,
+      );
+    }
     component =
       handlerResult instanceof Promise
         ? handlerResult
@@ -355,6 +375,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
         context,
         actionContext,
         stale,
+        traceSource: "intercept-loader",
       });
 
       if (!shouldRevalidate) {
@@ -372,10 +393,15 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
+        // Report a throwing intercept loader to onError + loader.error telemetry,
+        // matching the fresh/revalidation paths. resolveInterceptLoadersOnly is
+        // only called on the cache-hit partial-update path (handleCacheHitIntercept),
+        // so flag isPartial:true exactly like revalidation.ts's partial path.
+        { ...buildLoaderErrorContext(context), isPartial: true },
       ),
     );
   }

package/src/router/lazy-includes.ts

@@ -1,24 +1,27 @@
 import { registerRouteMap } from "../route-map-builder.js";
-import { extractStaticPrefix } from "./pattern-matching.js";
+import { extractStaticPrefix, joinPrefix } from "./pattern-matching.js";
 import {
-  EntryData,
-  RSCRouterContext,
+  type EntryData,
+  RangoContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
 } from "../server/context";
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems, IncludeItem } from "../route-types.js";
 import type { ResolvedRouteMap, RouteEntry, TrailingSlashMode } from "../types";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+} from "../urls/include-provider.js";
 
 export interface LazyEvalDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   mergedRouteMap: Record<string, string>;
   nextMountIndex: () => number;
   getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+  routerId?: string;
 }
 
-// Detect lazy includes in handler result and create placeholder entries
-// Lazy includes are IncludeItem with lazy: true and _lazyContext
-// Moved to outer scope so it can be reused by evaluateLazyEntry for nested includes
 export function findLazyIncludes<TEnv = any>(
   items: AllUseItems[],
 ): Array<{
@@ -54,7 +57,6 @@ export function findLazyIncludes<TEnv = any>(
         });
       }
     }
-    // Recursively check nested items (in layouts, etc.)
     if ((item as any).uses && Array.isArray((item as any).uses)) {
       lazyItems.push(...findLazyIncludes((item as any).uses));
     }
@@ -71,19 +73,11 @@ export function findLazyIncludes<TEnv = any>(
 export function evaluateLazyEntry<TEnv = any>(
   entry: RouteEntry<TEnv>,
   deps: LazyEvalDeps<TEnv>,
-): void {
+): void | Promise<void> {
   if (!entry.lazy || entry.lazyEvaluated || !entry.lazyPatterns) {
     return;
   }
 
-  // Check for pre-computed routes from build-time data.
-  // Only leaf nodes (no nested includes) are precomputed, so entries with
-  // nested lazy includes fall through to the handler below.
-  // When multiple entries share the same staticPrefix (e.g., several
-  // include("/", ...) calls), the precomputed data merges all their routes
-  // into one entry. Assigning that merged set to the first matching entry
-  // causes findMatch to pick the wrong handler for routes belonging to a
-  // different include. Skip the shortcut when the prefix is shared.
   const currentPrecomputed = deps.getPrecomputedByPrefix();
   if (currentPrecomputed) {
     const routes = currentPrecomputed.get(entry.staticPrefix);
@@ -97,56 +91,91 @@ export function evaluateLazyEntry<TEnv = any>(
         for (const [name, pattern] of Object.entries(routes)) {
           deps.mergedRouteMap[name] = pattern;
         }
-        registerRouteMap(deps.mergedRouteMap);
+        // Register only this entry's routes (the delta): the full
+        // mergedRouteMap is seeded from the generated manifest at
+        // createRouter() time and already registered there — re-passing it
+        // made this request-path call O(total routes) (issue #666).
+        registerRouteMap(routes);
         return;
       }
     }
   }
 
-  // Mark as evaluated immediately to prevent concurrent evaluation.
-  // JS is single-threaded but handlers.handler() could theoretically yield,
-  // and the while-loop in findMatch retries after evaluation.
-  entry.lazyEvaluated = true;
+  // Async provider (`() => import("./routes")`): the route module is evaluated
+  // off the startup path, on the first request reaching this prefix. Concurrent
+  // first-hits share one in-flight promise so the import + expansion run exactly
+  // once. The eager path below stays fully synchronous (no Promise), so the
+  // per-entry match loop pays no microtask for normal includes.
+  const lazyPatterns = entry.lazyPatterns;
+  if (isIncludeProvider(lazyPatterns)) {
+    const inflight = (entry as { _lazyInflight?: Promise<void> })._lazyInflight;
+    if (inflight) return inflight;
+    const work = (async () => {
+      const resolved = resolveIncludeModule(
+        await lazyPatterns(),
+        entry.staticPrefix,
+      );
+      // Cache the resolved patterns: any later re-entry expands synchronously.
+      entry.lazyPatterns = resolved as unknown as UrlPatterns<TEnv>;
+      runExpansion(entry, deps, resolved as UrlPatterns<TEnv>);
+    })();
+    (entry as { _lazyInflight?: Promise<void> })._lazyInflight = work;
+    const clear = () => {
+      (entry as { _lazyInflight?: Promise<void> })._lazyInflight = undefined;
+    };
+    // On failure, clear the flag (lazyEvaluated stays false) so a later request
+    // can retry the import rather than wedging the route permanently.
+    work.then(clear, clear);
+    return work;
+  }
+
+  runExpansion(entry, deps, lazyPatterns as UrlPatterns<TEnv>);
+}
 
-  const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
+/**
+ * Synchronously expand a lazy entry's (already-resolved) patterns into routes
+ * and splice any nested lazy includes as new entries. Runs once per entry.
+ */
+function runExpansion<TEnv = any>(
+  entry: RouteEntry<TEnv>,
+  deps: LazyEvalDeps<TEnv>,
+  lazyPatterns: UrlPatterns<TEnv>,
+): void {
+  // lazyEvaluated is set at the END, only after the handler ran and the routes
+  // (and any nested includes) were spliced. Setting it up-front would mark the
+  // entry done even if the handler throws mid-expansion: the async provider
+  // path clears _lazyInflight on rejection so a later request can retry, but a
+  // premature lazyEvaluated=true would make evaluateLazyEntry short-circuit
+  // (line ~77) forever, wedging the route at 404 until the isolate restarts.
   const lazyContext = entry.lazyContext;
 
-  // Create a new context for evaluating the lazy patterns
   const manifest = new Map<string, EntryData>();
   const patterns = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
   const trailingSlashMap = new Map<string, TrailingSlashMode>();
 
-  // Capture the handler result to detect nested lazy includes
   let handlerResult: AllUseItems[] = [];
 
-  // Merge captured counters from include() to maintain consistent
-  // shortCode indices with sibling entries from pattern extraction
-  const lazyCounters: Record<string, number> = {};
-  if (lazyContext && (lazyContext as any).counters) {
-    const captured = (lazyContext as any).counters as Record<string, number>;
-    for (const [key, value] of Object.entries(captured)) {
-      lazyCounters[key] = value;
-    }
-  }
+  const lazyCounters: Record<string, number> = lazyContext?.counters
+    ? { ...lazyContext.counters }
+    : {};
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns,
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
       namespace: "lazy",
-      parent: (lazyContext?.parent as EntryData | null) ?? null,
+      parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
       counters: lazyCounters,
-      cacheProfiles: (lazyContext as any)?.cacheProfiles,
-      rootScoped: (lazyContext as any)?.rootScoped,
+      cacheProfiles: lazyContext?.cacheProfiles,
+      rootScoped: lazyContext?.rootScoped,
+      includeScope: lazyContext?.includeScope,
     },
     () => {
-      // Run the lazy patterns handler with the original context prefixes
-      // The prefix comes from the IncludeItem stored in lazyPatterns
       const includePrefix = (entry as any)._lazyPrefix || "";
-      const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+      const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
       if (fullPrefix || lazyContext?.namePrefix) {
         runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
@@ -158,11 +187,9 @@ export function evaluateLazyEntry<TEnv = any>(
     },
   );
 
-  // Populate the entry's routes from the patterns
   const routesObject: Record<string, string> = {};
   for (const [name, pattern] of patterns.entries()) {
     routesObject[name] = pattern;
-    // Also add to merged route map for reverse() support
     const existingPattern = deps.mergedRouteMap[name];
     if (existingPattern !== undefined && existingPattern !== pattern) {
       console.warn(
@@ -173,45 +200,38 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.mergedRouteMap[name] = pattern;
   }
 
-  // Update the entry in-place
   entry.routes = routesObject as ResolvedRouteMap<any>;
 
-  // Note: Do NOT clear lazyPatterns/lazyContext here.
-  // loadManifest() needs them on every request to re-run the handler
-  // in the correct AsyncLocalStorage context (Store.manifest).
-
-  // Update trailing slash config if available
   if (trailingSlashMap.size > 0) {
     entry.trailingSlash = Object.fromEntries(trailingSlashMap);
   }
 
-  // Detect nested lazy includes and register them as new entries
   const nestedLazyIncludes = findLazyIncludes(handlerResult);
   for (const lazyInclude of nestedLazyIncludes) {
-    // Compute the full URL prefix (combining parent prefix if any)
-    const fullPrefix = lazyInclude.context.urlPrefix
-      ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-      : lazyInclude.prefix;
+    const fullPrefix = joinPrefix(
+      lazyInclude.context.urlPrefix,
+      lazyInclude.prefix,
+    );
 
     const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
       prefix: "",
       staticPrefix: extractStaticPrefix(fullPrefix),
-      routes: {} as ResolvedRouteMap<any>, // Empty until first match
+      routes: {} as ResolvedRouteMap<any>,
       trailingSlash: entry.trailingSlash,
-      handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
+      // include entries don't invoke their own handler (real handlers come from
+      // the expanded routes); use the parent's placeholder. A provider has no
+      // `.handler` until resolved, so never read it here.
+      handler: isIncludeProvider(lazyInclude.patterns)
+        ? entry.handler
+        : (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
-      // Lazy evaluation fields
+      routerId: deps.routerId,
       lazy: true,
       lazyPatterns: lazyInclude.patterns,
       lazyContext: lazyInclude.context,
       lazyEvaluated: false,
-      // Store the include prefix for evaluation
       _lazyPrefix: lazyInclude.prefix,
     };
-    // Insert nested lazy entry before any entry whose staticPrefix is a
-    // prefix of (but shorter than) this lazy entry's staticPrefix.
-    // This ensures more specific lazy includes are matched before
-    // less specific eager entries (e.g., "/href/nested" before "/href/:id").
     const nestedPrefix = nestedEntry.staticPrefix;
     let insertIndex = deps.routesEntries.length;
     if (nestedPrefix) {
@@ -229,6 +249,12 @@ export function evaluateLazyEntry<TEnv = any>(
     deps.routesEntries.splice(insertIndex, 0, nestedEntry);
   }
 
-  // Re-register route map for runtime reverse() usage
-  registerRouteMap(deps.mergedRouteMap);
+  // Delta only — see the matching comment on the precomputed branch above and
+  // the WHY block on registerRouteMap (issue #666).
+  registerRouteMap(routesObject);
+
+  // Expansion fully succeeded (handler ran, routes + nested includes spliced) —
+  // mark done now so a mid-expansion throw above leaves lazyEvaluated=false and
+  // the entry retriable.
+  entry.lazyEvaluated = true;
 }