@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/intercept-resolution.ts

@@ -0,0 +1,395 @@
+/**
+ * Intercept Resolution
+ *
+ * Extracted from createRouter closure. Contains intercept detection and resolution
+ * functions for soft navigation (modals).
+ */
+
+import type { ReactNode } from "react";
+import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+} from "../server/context";
+import type { HandlerContext, 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 type { SegmentResolutionDeps } from "./types.js";
+import { debugLog } from "./logging.js";
+
+/**
+ * Check if an intercept's when conditions are satisfied.
+ * All when() functions must return true for the intercept to activate.
+ * If no when() conditions are defined, the intercept always activates.
+ *
+ * During action revalidation, when() is NOT evaluated.
+ */
+export function evaluateInterceptWhen(
+  intercept: InterceptEntry,
+  selectorContext: InterceptSelectorContext | null,
+  isAction: boolean,
+): boolean {
+  if (isAction) {
+    return true;
+  }
+
+  if (!intercept.when || intercept.when.length === 0) {
+    return true;
+  }
+
+  if (!selectorContext) {
+    return false;
+  }
+
+  return intercept.when.every((fn) => fn(selectorContext));
+}
+
+/**
+ * Find an intercept for the target route by walking up the entry chain.
+ * Returns the first (innermost) matching intercept along with the entry that defines it.
+ */
+export function findInterceptForRoute(
+  targetRouteKey: string,
+  fromEntry: EntryData | null,
+  selectorContext: InterceptSelectorContext | null = null,
+  isAction: boolean = false,
+): { intercept: InterceptEntry; entry: EntryData } | null {
+  let current: EntryData | null = fromEntry;
+
+  while (current) {
+    if (current.intercept && current.intercept.length > 0) {
+      for (const intercept of current.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 };
+            }
+          }
+        }
+      }
+    }
+
+    current = current.parent;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve an intercept entry and emit segment with the slot name.
+ */
+export async function resolveInterceptEntry<TEnv>(
+  interceptEntry: InterceptEntry,
+  parentEntry: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  belongsToRoute: boolean,
+  deps: SegmentResolutionDeps<TEnv>,
+  revalidationContext?: {
+    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<ResolvedSegment[]> {
+  const segments: ResolvedSegment[] = [];
+
+  if (interceptEntry.middleware.length > 0) {
+    const requestCtx = getRequestContext();
+    if (!requestCtx?.res) {
+      throw new Error(
+        "Request context with stubResponse is required for intercept middleware",
+      );
+    }
+    const middlewareResponse = await executeInterceptMiddleware(
+      interceptEntry.middleware,
+      context.request,
+      context.env,
+      params,
+      context.var as Record<string, any>,
+      requestCtx.res,
+      createReverseFunction(getGlobalRouteMap()),
+    );
+    if (middlewareResponse) throw middlewareResponse;
+  }
+
+  const loaderPromises: Promise<any>[] = [];
+  const loaderIds: string[] = [];
+
+  for (let i = 0; i < interceptEntry.loader.length; i++) {
+    const { loader, revalidate: loaderRevalidateFns } =
+      interceptEntry.loader[i];
+    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+
+    if (revalidationContext) {
+      const {
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        actionContext,
+        stale,
+      } = revalidationContext;
+
+      const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+      if (clientSegmentIds.has(interceptSegmentId)) {
+        const dummySegment: ResolvedSegment = {
+          id: segmentId,
+          namespace: `intercept:${interceptEntry.routeName}`,
+          type: "loader",
+          index: i,
+          component: null,
+          params,
+          loaderId: loader.$$id,
+          belongsToRoute,
+        };
+
+        const shouldRevalidate = await evaluateRevalidation({
+          segment: dummySegment,
+          prevParams,
+          getPrevSegment: null,
+          request,
+          prevUrl,
+          nextUrl,
+          revalidations: loaderRevalidateFns.map((fn, j) => ({
+            name: `intercept-loader-revalidate${j}`,
+            fn,
+          })),
+          routeKey,
+          context,
+          actionContext,
+          stale,
+        });
+
+        if (!shouldRevalidate) {
+          debugLog("intercept.loader", "skipped revalidation", {
+            loaderId: loader.$$id,
+          });
+          continue;
+        }
+        debugLog("intercept.loader", "revalidating", {
+          loaderId: loader.$$id,
+          stale,
+        });
+      }
+    }
+
+    loaderIds.push(loader.$$id);
+    loaderPromises.push(
+      deps.wrapLoaderPromise(
+        context.use(loader),
+        parentEntry,
+        segmentId,
+        context.pathname,
+      ),
+    );
+  }
+
+  const handlerResult =
+    typeof interceptEntry.handler === "function"
+      ? handleHandlerResult(interceptEntry.handler(context))
+      : interceptEntry.handler;
+
+  let layoutElement: ReactNode | undefined;
+  if (interceptEntry.layout) {
+    if (typeof interceptEntry.layout === "function") {
+      const layoutResult = await interceptEntry.layout(context);
+      if (layoutResult instanceof Response) {
+        throw layoutResult;
+      }
+      layoutElement = layoutResult;
+    } else {
+      layoutElement = interceptEntry.layout;
+    }
+  }
+
+  let component: ReactNode;
+  let loaderDataPromise: Promise<any[]> | any[] | undefined;
+
+  if (interceptEntry.loading && loaderPromises.length > 0) {
+    component =
+      handlerResult instanceof Promise
+        ? handlerResult
+        : (Promise.resolve(handlerResult) as ReactNode);
+    loaderDataPromise = Promise.all(loaderPromises);
+  } else if (loaderPromises.length > 0) {
+    loaderDataPromise = await Promise.all(loaderPromises);
+    component =
+      handlerResult instanceof Promise ? await handlerResult : handlerResult;
+  } else {
+    component =
+      interceptEntry.loading && handlerResult instanceof Promise
+        ? handlerResult
+        : handlerResult instanceof Promise
+          ? await handlerResult
+          : handlerResult;
+  }
+
+  const interceptSegment = {
+    id: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+    namespace: `intercept:${interceptEntry.routeName}`,
+    type: "parallel" as const,
+    index: 0,
+    component,
+    loading: interceptEntry.loading === false ? null : interceptEntry.loading,
+    layout: layoutElement,
+    params,
+    slot: interceptEntry.slotName,
+    belongsToRoute,
+    parallelName: `intercept:${interceptEntry.routeName}.${interceptEntry.slotName}`,
+    loaderDataPromise,
+    loaderIds: loaderIds.length > 0 ? loaderIds : undefined,
+  };
+  segments.push(interceptSegment);
+
+  return segments;
+}
+
+/**
+ * Resolve only the loaders for a cached intercept segment.
+ * Used on intercept cache hit to get fresh loader data while keeping cached component/layout.
+ */
+export async function resolveInterceptLoadersOnly<TEnv>(
+  interceptEntry: InterceptEntry,
+  parentEntry: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  belongsToRoute: boolean,
+  deps: SegmentResolutionDeps<TEnv>,
+  revalidationContext: {
+    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<{
+  loaderDataPromise: Promise<any[]> | any[];
+  loaderIds: string[];
+} | null> {
+  if (interceptEntry.loader.length === 0) {
+    return null;
+  }
+
+  const loaderPromises: Promise<any>[] = [];
+  const loaderIds: string[] = [];
+
+  const {
+    clientSegmentIds,
+    prevParams,
+    request,
+    prevUrl,
+    nextUrl,
+    routeKey,
+    actionContext,
+    stale,
+  } = revalidationContext;
+
+  for (let i = 0; i < interceptEntry.loader.length; i++) {
+    const { loader, revalidate: loaderRevalidateFns } =
+      interceptEntry.loader[i];
+    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+
+    const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+    if (clientSegmentIds.has(interceptSegmentId)) {
+      const dummySegment: ResolvedSegment = {
+        id: segmentId,
+        namespace: `intercept:${interceptEntry.routeName}`,
+        type: "loader",
+        index: i,
+        component: null,
+        params,
+        loaderId: loader.$$id,
+        belongsToRoute,
+      };
+
+      const shouldRevalidate = await evaluateRevalidation({
+        segment: dummySegment,
+        prevParams,
+        getPrevSegment: null,
+        request,
+        prevUrl,
+        nextUrl,
+        revalidations: loaderRevalidateFns.map((fn, j) => ({
+          name: `intercept-loader-revalidate${j}`,
+          fn,
+        })),
+        routeKey,
+        context,
+        actionContext,
+        stale,
+      });
+
+      if (!shouldRevalidate) {
+        debugLog("intercept.loader", "skipped on cache hit", {
+          loaderId: loader.$$id,
+        });
+        continue;
+      }
+      debugLog("intercept.loader", "revalidating on cache hit", {
+        loaderId: loader.$$id,
+        stale,
+      });
+    }
+
+    loaderIds.push(loader.$$id);
+    loaderPromises.push(
+      deps.wrapLoaderPromise(
+        context.use(loader),
+        parentEntry,
+        segmentId,
+        context.pathname,
+      ),
+    );
+  }
+
+  if (loaderPromises.length === 0) {
+    return null;
+  }
+
+  // Match fresh-path semantics: only defer (no await) when loading is truthy.
+  // `loading: false` means "no loading UI, await loaders before render" —
+  // same as the fresh path's `if (interceptEntry.loading && ...)` check.
+  const loaderDataPromise = interceptEntry.loading
+    ? Promise.all(loaderPromises)
+    : await Promise.all(loaderPromises);
+
+  return { loaderDataPromise, loaderIds };
+}

package/src/router/lazy-includes.ts

@@ -0,0 +1,234 @@
+import { registerRouteMap } from "../route-map-builder.js";
+import { extractStaticPrefix } from "./pattern-matching.js";
+import {
+  EntryData,
+  RSCRouterContext,
+  runWithPrefixes,
+} from "../server/context";
+import type { UrlPatterns } from "../urls.js";
+import type { AllUseItems, IncludeItem } from "../route-types.js";
+import type { ResolvedRouteMap, RouteEntry, TrailingSlashMode } from "../types";
+
+export interface LazyEvalDeps<TEnv = any> {
+  routesEntries: RouteEntry<TEnv>[];
+  mergedRouteMap: Record<string, string>;
+  nextMountIndex: () => number;
+  getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+}
+
+// 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<{
+  prefix: string;
+  patterns: UrlPatterns<TEnv>;
+  context: {
+    urlPrefix: string;
+    namePrefix: string | undefined;
+    parent: unknown;
+    rootScoped?: boolean;
+  };
+}> {
+  const lazyItems: Array<{
+    prefix: string;
+    patterns: UrlPatterns<TEnv>;
+    context: {
+      urlPrefix: string;
+      namePrefix: string | undefined;
+      parent: unknown;
+      rootScoped?: boolean;
+    };
+  }> = [];
+
+  for (const item of items) {
+    if (!item) continue;
+    if (item.type === "include") {
+      const includeItem = item as IncludeItem;
+      if (includeItem.lazy === true && includeItem._lazyContext) {
+        lazyItems.push({
+          prefix: includeItem.prefix,
+          patterns: includeItem.patterns as UrlPatterns<TEnv>,
+          context: includeItem._lazyContext,
+        });
+      }
+    }
+    // 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));
+    }
+  }
+
+  return lazyItems;
+}
+
+/**
+ * Evaluate a lazy entry's patterns and populate its routes
+ * This runs the lazy patterns handler and updates the entry in-place
+ * Also detects nested lazy includes and registers them as new entries
+ */
+export function evaluateLazyEntry<TEnv = any>(
+  entry: RouteEntry<TEnv>,
+  deps: LazyEvalDeps<TEnv>,
+): 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);
+    if (routes) {
+      const prefixIsShared =
+        deps.routesEntries.filter((e) => e.staticPrefix === entry.staticPrefix)
+          .length > 1;
+      if (!prefixIsShared) {
+        entry.lazyEvaluated = true;
+        entry.routes = routes as ResolvedRouteMap<any>;
+        for (const [name, pattern] of Object.entries(routes)) {
+          deps.mergedRouteMap[name] = pattern;
+        }
+        registerRouteMap(deps.mergedRouteMap);
+        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;
+
+  const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
+  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;
+    }
+  }
+
+  RSCRouterContext.run(
+    {
+      manifest,
+      patterns,
+      patternsByPrefix,
+      trailingSlash: trailingSlashMap,
+      namespace: "lazy",
+      parent: (lazyContext?.parent as EntryData | null) ?? null,
+      counters: lazyCounters,
+      cacheProfiles: (lazyContext as any)?.cacheProfiles,
+      rootScoped: (lazyContext as any)?.rootScoped,
+    },
+    () => {
+      // 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;
+
+      if (fullPrefix || lazyContext?.namePrefix) {
+        runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
+          handlerResult = lazyPatterns.handler() as AllUseItems[];
+        });
+      } else {
+        handlerResult = lazyPatterns.handler() as AllUseItems[];
+      }
+    },
+  );
+
+  // 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(
+        `[@rangojs/router] Route name conflict: "${name}" already maps to "${existingPattern}", ` +
+          `overwriting with "${pattern}" (from lazy include). Use unique route names to avoid this.`,
+      );
+    }
+    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 nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
+      prefix: "",
+      staticPrefix: extractStaticPrefix(fullPrefix),
+      routes: {} as ResolvedRouteMap<any>, // Empty until first match
+      trailingSlash: entry.trailingSlash,
+      handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
+      mountIndex: deps.nextMountIndex(),
+      // 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) {
+      for (let i = 0; i < deps.routesEntries.length; i++) {
+        const existing = deps.routesEntries[i]!;
+        if (
+          nestedPrefix.startsWith(existing.staticPrefix) &&
+          nestedPrefix.length > existing.staticPrefix.length
+        ) {
+          insertIndex = i;
+          break;
+        }
+      }
+    }
+    deps.routesEntries.splice(insertIndex, 0, nestedEntry);
+  }
+
+  // Re-register route map for runtime reverse() usage
+  registerRouteMap(deps.mergedRouteMap);
+}