@rangojs/router 0.0.0-experimental.1878aa49 → 0.0.0-experimental.190fb30d

package/src/router/lazy-includes.ts

@@ -1,14 +1,18 @@
 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>[];
@@ -18,9 +22,6 @@ export interface LazyEvalDeps<TEnv = any> {
   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<{
@@ -56,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));
     }
@@ -73,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);
@@ -99,40 +91,76 @@ 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,
@@ -141,14 +169,13 @@ export function evaluateLazyEntry<TEnv = any>(
       namespace: "lazy",
       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, () => {
@@ -160,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(
@@ -175,46 +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(),
       routerId: deps.routerId,
-      // Lazy evaluation fields
       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) {
@@ -232,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;
 }