@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/revalidation.ts

@@ -0,0 +1,289 @@
+/**
+ * Router Revalidation Logic
+ *
+ * Evaluates whether segments should revalidate based on params, actions, and custom functions.
+ */
+
+import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ActionContext } from "./types";
+import {
+  debugLog,
+  pushRevalidationTraceEntry,
+  isTraceActive,
+} from "./logging.js";
+import type { RevalidationTraceEntry } from "./logging.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+
+function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Options for revalidation evaluation
+ */
+interface EvaluateRevalidationOptions<TEnv> {
+  /** Current segment to evaluate */
+  segment: ResolvedSegment;
+  /** Previous route params (from route match, not segment) */
+  prevParams: Record<string, string>;
+  /** Lazy function to get previous segment if needed */
+  getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
+  /** Current request */
+  request: Request;
+  /** Previous URL */
+  prevUrl: URL;
+  /** Next URL */
+  nextUrl: URL;
+  /** Custom revalidation functions */
+  revalidations: Array<{ name: string; fn: any }>;
+  /** Current route key */
+  routeKey: string;
+  /** Handler context */
+  context: HandlerContext<any, TEnv>;
+  /** Action context if triggered by action */
+  actionContext?: ActionContext;
+  /** If true, this is a stale cache revalidation request */
+  stale?: boolean;
+  /** Trace source hint for the revalidation trace */
+  traceSource?: RevalidationTraceEntry["source"];
+}
+
+/**
+ * Evaluate if a segment should revalidate using soft/hard decision pattern
+ * Optimized to use prevParams directly and avoid building previous segments
+ */
+export async function evaluateRevalidation<TEnv>(
+  options: EvaluateRevalidationOptions<TEnv>,
+): Promise<boolean> {
+  const {
+    segment,
+    prevParams,
+    getPrevSegment,
+    request,
+    prevUrl,
+    nextUrl,
+    revalidations,
+    routeKey,
+    context,
+    actionContext,
+    stale,
+    traceSource,
+  } = options;
+  const nextParams = segment.params || {};
+  const paramsChanged = !paramsEqual(nextParams, prevParams);
+  const searchChanged = prevUrl.search !== nextUrl.search;
+
+  // Trace helper: push a structured entry to the request-scoped trace buffer.
+  // Guarded by isTraceActive() so object construction is skipped in production.
+  function pushTrace(
+    defaultVal: boolean,
+    finalVal: boolean,
+    reason: string,
+  ): void {
+    if (!isTraceActive()) return;
+    pushRevalidationTraceEntry({
+      segmentId: segment.id,
+      segmentType: segment.type,
+      belongsToRoute: segment.belongsToRoute ?? false,
+      source: traceSource ?? "segment-resolution",
+      defaultShouldRevalidate: defaultVal,
+      finalShouldRevalidate: finalVal,
+      reason,
+      customRevalidators: revalidations.length || undefined,
+    });
+  }
+
+  // Calculate default revalidation based on segment type and request method
+  let defaultShouldRevalidate: boolean;
+  let defaultReason: string;
+
+  if (request.method === "POST") {
+    // Actions: revalidate segments that belong to the route, skip parent chain
+    if (segment.type === "route") {
+      // Route segment always revalidates on actions
+      defaultShouldRevalidate = true;
+      defaultReason = "action:route-segment";
+    } else if (segment.type === "loader") {
+      // Loaders always revalidate on actions - they often contain action-sensitive data
+      // (e.g., cart count after add-to-cart action)
+      defaultShouldRevalidate = true;
+      defaultReason = "action:loader-segment";
+    } else if (segment.belongsToRoute) {
+      // Segment belongs to route (orphan layouts/parallels) - revalidate
+      defaultShouldRevalidate = true;
+      defaultReason = "action:belongs-to-route";
+    } else {
+      // Parent chain segment (shared layouts/parallels) - don't revalidate
+      defaultShouldRevalidate = false;
+      defaultReason = "action:parent-chain-skip";
+    }
+  } else {
+    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
+    // Only the route segment revalidates by default - all others require explicit opt-in
+
+    if (segment.type === "route") {
+      // Route segments revalidate when path params OR search params change.
+      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
+      // so the handler must re-execute to produce updated content.
+      const routeChanged = paramsChanged || searchChanged;
+      defaultShouldRevalidate = routeChanged;
+      defaultReason = paramsChanged
+        ? "nav:params-changed"
+        : searchChanged
+          ? "nav:search-changed"
+          : "nav:params-unchanged";
+      if (routeChanged) {
+        debugLog("revalidation", "route revalidating", {
+          segmentId: segment.id,
+          paramsChanged,
+          searchChanged,
+        });
+      }
+    } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
+      // Children of the route path (loaders, orphan layouts/parallels)
+      // revalidate when path params or search params change
+      defaultShouldRevalidate = true;
+      defaultReason = paramsChanged
+        ? "nav:route-child-params-changed"
+        : "nav:route-child-search-changed";
+      debugLog("revalidation", "route child revalidating", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+        paramsChanged,
+        searchChanged,
+      });
+    } else {
+      // Parent layouts and parallels default to no revalidation
+      // Cannot assume these segments depend on params without explicit declaration
+      // Use custom revalidation functions to opt-in when needed
+      defaultShouldRevalidate = false;
+      defaultReason = "nav:non-route-skip";
+      debugLog("revalidation", "non-route segment skipped by default", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+      });
+    }
+  }
+
+  // No custom revalidations defined - return default behavior without prev segment
+  if (revalidations.length === 0) {
+    if (defaultShouldRevalidate) {
+      debugLog("revalidation", "default revalidate=true", {
+        segmentId: segment.id,
+        prevParams,
+        nextParams,
+      });
+    } else {
+      debugLog("revalidation", "default revalidate=false", {
+        segmentId: segment.id,
+      });
+    }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
+    return defaultShouldRevalidate;
+  }
+
+  // Custom revalidations exist - may need full prev segment
+  // Lazy load prev segment only if getPrevSegment provided
+  const prevSegment = getPrevSegment ? await getPrevSegment() : null;
+
+  // Execute revalidation functions with soft/hard decision pattern
+  let currentSuggestion = defaultShouldRevalidate;
+
+  // Compute public route names (filtered: undefined for auto-generated routes)
+  const toRouteName =
+    routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
+  const reqCtx = _getRequestContext();
+  const prevRouteKey = reqCtx?._prevRouteKey;
+  const fromRouteName =
+    prevRouteKey && !isAutoGeneratedRouteName(prevRouteKey)
+      ? prevRouteKey
+      : undefined;
+
+  for (const { name, fn } of revalidations) {
+    const result = fn({
+      currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
+      currentUrl: prevUrl,
+      nextParams,
+      nextUrl,
+      defaultShouldRevalidate: currentSuggestion,
+      context,
+      // Segment metadata (which segment is being evaluated)
+      segmentType: segment.type,
+      layoutName: segment.layoutName,
+      slotName: segment.slot,
+      // Action context (only populated when triggered by server action)
+      actionId: actionContext?.actionId,
+      actionUrl: actionContext?.actionUrl,
+      actionResult: actionContext?.actionResult,
+      formData: actionContext?.formData,
+      method: request.method, // GET for navigation, POST for actions
+      routeName: toRouteName, // Navigation target route name (filtered)
+      fromRouteName, // Navigation source route name (filtered)
+      toRouteName, // Navigation target route name (filtered)
+      // Stale cache context (only true for background revalidation after stale cache render)
+      stale,
+    });
+
+    // Check return type:
+    // - boolean: hard decision, short-circuit immediately
+    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
+    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
+    if (typeof result === "boolean") {
+      // Hard decision - short-circuit
+      debugLog("revalidation", "hard decision", {
+        segmentId: segment.id,
+        revalidator: name,
+        revalidate: result,
+      });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
+      return result;
+    } else if (
+      result &&
+      typeof result === "object" &&
+      "defaultShouldRevalidate" in result
+    ) {
+      // Soft decision - update suggestion and continue
+      currentSuggestion = result.defaultShouldRevalidate;
+      debugLog("revalidation", "soft decision", {
+        segmentId: segment.id,
+        revalidator: name,
+        revalidate: currentSuggestion,
+      });
+    } else if (result === null || result === undefined) {
+      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
+      // This means "I don't care, use whatever the default is"
+      debugLog("revalidation", "deferred to current default", {
+        segmentId: segment.id,
+        revalidator: name,
+        revalidate: currentSuggestion,
+      });
+      // currentSuggestion stays the same, continue to next function
+    }
+  }
+
+  // All revalidators completed - use final suggestion
+  debugLog("revalidation", "final decision", {
+    segmentId: segment.id,
+    revalidate: currentSuggestion,
+  });
+  const softNames = revalidations.map((r) => r.name).join(",");
+  pushTrace(
+    defaultShouldRevalidate,
+    currentSuggestion,
+    `soft-chain:${softNames}`,
+  );
+  return currentSuggestion;
+}

package/src/router/router-context.ts

@@ -0,0 +1,316 @@
+/**
+ * Router Context using AsyncLocalStorage
+ *
+ * Provides clean dependency injection for router middleware without parameter drilling.
+ * All closure functions from createRouter() are made available via getRouterContext().
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import type { CacheScope } from "../cache/cache-scope.js";
+import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+  MetricsStore,
+} from "../server/context.js";
+import type {
+  HandlerContext,
+  ResolvedSegment,
+  ShouldRevalidateFn,
+} from "../types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { TelemetrySink } from "./telemetry.js";
+
+/**
+ * Revalidation context passed to segment resolution
+ */
+export interface 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;
+}
+
+/**
+ * Result from intercept lookup
+ */
+export interface InterceptResult {
+  intercept: InterceptEntry;
+  entry: EntryData;
+}
+
+/**
+ * Router context available via AsyncLocalStorage
+ *
+ * Contains closure functions from createRouter() that middleware needs access to.
+ * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
+ */
+export interface RouterContext<TEnv = any> {
+  // Route matching
+  findMatch: (pathname: string) => RouteMatchResult | null;
+
+  // Manifest loading
+  loadManifest: (
+    entry: any,
+    routeKey: string,
+    pathname: string,
+    metricsStore?: MetricsStore,
+    isSSR?: boolean,
+  ) => Promise<EntryData>;
+
+  // Entry traversal
+  traverseBack: (entry: EntryData) => Generator<EntryData>;
+
+  // Handler context creation
+  createHandlerContext: (
+    params: Record<string, string>,
+    request: Request,
+    searchParams: URLSearchParams,
+    pathname: string,
+    url: URL,
+    bindings?: any,
+    routeMap?: Record<string, string>,
+    routeName?: string,
+    responseType?: string,
+    isPassthroughRoute?: boolean,
+  ) => HandlerContext<any, TEnv>;
+
+  // Loader setup
+  setupLoaderAccess: (
+    ctx: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+  ) => void;
+
+  setupLoaderAccessSilent: (
+    ctx: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+  ) => void;
+
+  // Context access
+  getContext: () => {
+    getOrCreateStore: (key: string) => any;
+    runWithStore: <T>(
+      store: any,
+      namespace: string,
+      parent: any,
+      fn: () => T,
+    ) => T;
+  };
+
+  // Metrics
+  getMetricsStore: () => MetricsStore | undefined;
+
+  // Cache
+  createCacheScope: (
+    cacheConfig: any,
+    parent: CacheScope | null,
+  ) => CacheScope | null;
+
+  // Intercept detection
+  findInterceptForRoute: (
+    routeKey: string,
+    parentEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext,
+    isAction: boolean,
+  ) => InterceptResult | null;
+
+  // Segment resolution (with revalidation)
+  resolveAllSegmentsWithRevalidation: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext: any | undefined,
+    interceptResult: InterceptResult | null,
+    localRouteName: string,
+    pathname: string,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+
+  // Generator-based segment resolution (for pipeline)
+  resolveAllSegmentsWithRevalidationGenerator?: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext?: any,
+  ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
+
+  // Intercept resolution
+  resolveInterceptEntry: (
+    intercept: InterceptEntry,
+    entry: EntryData,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean,
+    revalidationContext?: RevalidationContext,
+  ) => Promise<ResolvedSegment[]>;
+
+  // Collect with markers
+  collectWithMarkers?: <T>(
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>,
+  ) => Promise<{ items: T[]; matchedIds: string[] }>;
+
+  // Revalidation evaluation
+  evaluateRevalidation: (params: {
+    segment: ResolvedSegment;
+    prevParams: Record<string, string>;
+    getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
+    request: Request;
+    prevUrl: URL;
+    nextUrl: URL;
+    revalidations: Array<{ name: string; fn: any }>;
+    routeKey: string;
+    context: HandlerContext<any, TEnv>;
+    actionContext?: any;
+    stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout";
+  }) => Promise<boolean>;
+
+  // Request context
+  getRequestContext: () =>
+    | {
+        waitUntil: (fn: () => Promise<void>) => void;
+        _handleStore?: any;
+      }
+    | undefined;
+
+  // Simple segment resolution (without revalidation - for full match)
+  resolveAllSegments: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+  ) => Promise<ResolvedSegment[]>;
+
+  // Generator-based simple resolution
+  resolveAllSegmentsGenerator?: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+  ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
+
+  // Collect segments from generator
+  collectSegmentsFromGenerator?: <T>(
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>,
+  ) => Promise<T[]>;
+
+  // Handle store
+  createHandleStore: () => any;
+
+  // Loaders-only resolution (for full match cache hit - no revalidation)
+  resolveLoadersOnly?: (
+    entries: EntryData[],
+    handlerContext: HandlerContext<any, TEnv>,
+  ) => Promise<ResolvedSegment[]>;
+
+  // Loaders-only resolution (for cache hit scenarios)
+  resolveLoadersOnlyWithRevalidation?: (
+    entries: EntryData[],
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: any,
+    stale?: boolean,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+
+  // Entry revalidation map
+  buildEntryRevalidateMap?: (
+    entries: EntryData[],
+  ) => Map<string, { revalidate: ShouldRevalidateFn[] }>;
+
+  // Telemetry sink (optional, no-op when undefined)
+  telemetry?: TelemetrySink;
+
+  // Request ID for telemetry span correlation (set per-request in match handlers)
+  requestId?: string;
+
+  // Intercept loaders only (for cache hit + intercept scenarios)
+  resolveInterceptLoadersOnly?: (
+    intercept: InterceptEntry,
+    entry: EntryData,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean,
+    revalidationContext: {
+      clientSegmentIds: Set<string>;
+      prevParams: Record<string, string>;
+      request: Request;
+      prevUrl: URL;
+      nextUrl: URL;
+      routeKey: string;
+      actionContext?: any;
+      stale?: boolean;
+    },
+  ) => Promise<{
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+  } | null>;
+}
+
+// AsyncLocalStorage instance for router context
+const routerContext = new AsyncLocalStorage<RouterContext<any>>();
+
+/**
+ * Get router dependencies from AsyncLocalStorage context
+ *
+ * @throws Error if called outside of router context (runWithRouterContext)
+ */
+export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
+  const deps = routerContext.getStore();
+  if (!deps) {
+    throw new Error(
+      "getRouterContext() called outside of router context. " +
+        "Ensure code is running inside runWithRouterContext().",
+    );
+  }
+  return deps as RouterContext<TEnv>;
+}
+
+/**
+ * Run a function with router dependencies available via getRouterContext()
+ *
+ * All async code within fn() can call getRouterContext() to access router closures.
+ * This works across async boundaries thanks to AsyncLocalStorage.
+ *
+ * @param deps Router dependencies to make available
+ * @param fn Function to run with dependencies available
+ * @returns Result of fn()
+ */
+export function runWithRouterContext<T, TEnv = any>(
+  deps: RouterContext<TEnv>,
+  fn: () => T,
+): T {
+  return routerContext.run(deps, fn);
+}