@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/src/router/revalidation.ts

@@ -6,6 +6,30 @@
 
 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
@@ -33,6 +57,8 @@ interface EvaluateRevalidationOptions<TEnv> {
   actionContext?: ActionContext;
   /** If true, this is a stale cache revalidation request */
   stale?: boolean;
+  /** Trace source hint for the revalidation trace */
+  traceSource?: RevalidationTraceEntry["source"];
 }
 
 /**
@@ -40,7 +66,7 @@ interface EvaluateRevalidationOptions<TEnv> {
  * Optimized to use prevParams directly and avoid building previous segments
  */
 export async function evaluateRevalidation<TEnv>(
-  options: EvaluateRevalidationOptions<TEnv>
+  options: EvaluateRevalidationOptions<TEnv>,
 ): Promise<boolean> {
   const {
     segment,
@@ -54,32 +80,54 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    traceSource,
   } = options;
   const nextParams = segment.params || {};
-  const paramsChanged =
-    Object.keys(nextParams).length !== Object.keys(prevParams).length ||
-    Object.keys(nextParams).some(
-      (key) => nextParams[key] !== prevParams[key]
-    );
+  const paramsChanged = !paramsEqual(nextParams, prevParams);
+
+  // 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
@@ -89,36 +137,41 @@ export async function evaluateRevalidation<TEnv>(
       // Route segments revalidate when params change
       // Routes are the primary param-dependent content and always need updates
       defaultShouldRevalidate = paramsChanged;
+      defaultReason = paramsChanged
+        ? "nav:params-changed"
+        : "nav:params-unchanged";
       if (paramsChanged) {
-        console.log(
-          `[Router.evaluateRevalidation] ${segment.id}: ROUTE - params changed, revalidating`
-        );
+        debugLog("revalidation", "route params changed, revalidating", {
+          segmentId: segment.id,
+        });
       }
     } else {
       // 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;
-      console.log(
-        `[Router.evaluateRevalidation] ${
-          segment.id
-        }: ${segment.type.toUpperCase()} segment - skipping (override with custom revalidation if needed)`
-      );
+      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) {
-      console.log(
-        `[Router.evaluateRevalidation] ${segment.id}: PARAMS CHANGED (default) - revalidating`,
-        { prev: prevParams, next: nextParams }
-      );
+      debugLog("revalidation", "default revalidate=true", {
+        segmentId: segment.id,
+        prevParams,
+        nextParams,
+      });
     } else {
-      console.log(
-        `[Router.evaluateRevalidation] ${segment.id}: UNCHANGED (default) - skipping`
-      );
+      debugLog("revalidation", "default revalidate=false", {
+        segmentId: segment.id,
+      });
     }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
     return defaultShouldRevalidate;
   }
 
@@ -129,6 +182,16 @@ export async function evaluateRevalidation<TEnv>(
   // 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
@@ -147,7 +210,9 @@ export async function evaluateRevalidation<TEnv>(
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
       method: request.method, // GET for navigation, POST for actions
-      routeName: routeKey, // User-friendly route name (e.g., "products.detail")
+      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,
     });
@@ -158,9 +223,12 @@ export async function evaluateRevalidation<TEnv>(
     // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
       // Hard decision - short-circuit
-      console.log(
-        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) HARD: ${result}`
-      );
+      debugLog("revalidation", "hard decision", {
+        segmentId: segment.id,
+        revalidator: name,
+        revalidate: result,
+      });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
       return result;
     } else if (
       result &&
@@ -169,22 +237,33 @@ export async function evaluateRevalidation<TEnv>(
     ) {
       // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
-      console.log(
-        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) SOFT: ${currentSuggestion}`
-      );
+      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"
-      console.log(
-        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) DEFER to default: ${currentSuggestion}`
-      );
+      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
-  console.log(
-    `[Router.evaluateRevalidation] ${segment.id}: Final decision: ${currentSuggestion}`
+  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

@@ -2,7 +2,7 @@
  * Router Context using AsyncLocalStorage
  *
  * Provides clean dependency injection for router middleware without parameter drilling.
- * All closure functions from createRSCRouter() are made available via getRouterContext().
+ * All closure functions from createRouter() are made available via getRouterContext().
  */
 import { AsyncLocalStorage } from "async_hooks";
 import type { CacheScope } from "../cache/cache-scope.js";
@@ -18,6 +18,7 @@ import type {
   ShouldRevalidateFn,
 } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -49,7 +50,7 @@ export interface InterceptResult {
 /**
  * Router context available via AsyncLocalStorage
  *
- * Contains closure functions from createRSCRouter() that middleware needs access to.
+ * 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> {
@@ -62,7 +63,7 @@ export interface RouterContext<TEnv = any> {
     routeKey: string,
     pathname: string,
     metricsStore?: MetricsStore,
-    isSSR?: boolean
+    isSSR?: boolean,
   ) => Promise<EntryData>;
 
   // Entry traversal
@@ -75,18 +76,22 @@ export interface RouterContext<TEnv = any> {
     searchParams: URLSearchParams,
     pathname: string,
     url: URL,
-    env: TEnv
+    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>>
+    loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
   setupLoaderAccessSilent: (
     ctx: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>
+    loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
   // Context access
@@ -96,7 +101,7 @@ export interface RouterContext<TEnv = any> {
       store: any,
       namespace: string,
       parent: any,
-      fn: () => T
+      fn: () => T,
     ) => T;
   };
 
@@ -106,7 +111,7 @@ export interface RouterContext<TEnv = any> {
   // Cache
   createCacheScope: (
     cacheConfig: any,
-    parent: CacheScope | null
+    parent: CacheScope | null,
   ) => CacheScope | null;
 
   // Intercept detection
@@ -114,7 +119,7 @@ export interface RouterContext<TEnv = any> {
     routeKey: string,
     parentEntry: EntryData | null,
     selectorContext: InterceptSelectorContext,
-    isAction: boolean
+    isAction: boolean,
   ) => InterceptResult | null;
 
   // Segment resolution (with revalidation)
@@ -132,7 +137,7 @@ export interface RouterContext<TEnv = any> {
     actionContext: any | undefined,
     interceptResult: InterceptResult | null,
     localRouteName: string,
-    pathname: string
+    pathname: string,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)
@@ -147,7 +152,7 @@ export interface RouterContext<TEnv = any> {
     prevUrl: URL,
     nextUrl: URL,
     loaderPromises: Map<string, Promise<any>>,
-    actionContext?: any
+    actionContext?: any,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
   // Intercept resolution
@@ -157,12 +162,12 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     belongsToRoute: boolean,
-    revalidationContext?: RevalidationContext
+    revalidationContext?: RevalidationContext,
   ) => Promise<ResolvedSegment[]>;
 
   // Collect with markers
   collectWithMarkers?: <T>(
-    gen: AsyncGenerator<T | { __type: "id"; id: string }>
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
   // Revalidation evaluation
@@ -178,6 +183,12 @@ export interface RouterContext<TEnv = any> {
     context: HandlerContext<any, TEnv>;
     actionContext?: any;
     stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout";
   }) => Promise<boolean>;
 
   // Request context
@@ -194,7 +205,7 @@ export interface RouterContext<TEnv = any> {
     routeKey: string,
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>
+    loaderPromises: Map<string, Promise<any>>,
   ) => Promise<ResolvedSegment[]>;
 
   // Generator-based simple resolution
@@ -203,12 +214,12 @@ export interface RouterContext<TEnv = any> {
     routeKey: string,
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>
+    loaderPromises: Map<string, Promise<any>>,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
   // Collect segments from generator
   collectSegmentsFromGenerator?: <T>(
-    gen: AsyncGenerator<T | { __type: "id"; id: string }>
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<T[]>;
 
   // Handle store
@@ -217,7 +228,7 @@ export interface RouterContext<TEnv = any> {
   // Loaders-only resolution (for full match cache hit - no revalidation)
   resolveLoadersOnly?: (
     entries: EntryData[],
-    handlerContext: HandlerContext<any, TEnv>
+    handlerContext: HandlerContext<any, TEnv>,
   ) => Promise<ResolvedSegment[]>;
 
   // Loaders-only resolution (for cache hit scenarios)
@@ -230,14 +241,21 @@ export interface RouterContext<TEnv = any> {
     prevUrl: URL,
     nextUrl: URL,
     routeKey: string,
-    actionContext?: any
+    actionContext?: any,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Entry revalidation map
   buildEntryRevalidateMap?: (
-    entries: EntryData[]
+    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,
@@ -254,7 +272,7 @@ export interface RouterContext<TEnv = any> {
       routeKey: string;
       actionContext?: any;
       stale?: boolean;
-    }
+    },
   ) => Promise<{
     loaderDataPromise: Promise<any[]> | any[];
     loaderIds: string[];
@@ -274,7 +292,7 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
   if (!deps) {
     throw new Error(
       "getRouterContext() called outside of router context. " +
-        "Ensure code is running inside runWithRouterContext()."
+        "Ensure code is running inside runWithRouterContext().",
     );
   }
   return deps as RouterContext<TEnv>;
@@ -292,8 +310,7 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
  */
 export function runWithRouterContext<T, TEnv = any>(
   deps: RouterContext<TEnv>,
-  fn: () => T
+  fn: () => T,
 ): T {
   return routerContext.run(deps, fn);
 }
-