@rangojs/router 0.0.0-experimental.002d056c

package/src/router/match-middleware/segment-resolution.ts

@@ -0,0 +1,193 @@
+/**
+ * Segment Resolution Middleware
+ *
+ * Resolves route segments when cache misses. Skips if cache hit.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from cache-lookup)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Iterate source first!    |  <-- CRITICAL: Must drain source
+ *   | yield* source            |      to let cache-lookup run
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | state.cacheHit?     |──yes──> return (cache already yielded)
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +---------------------+
+ *   | isFullMatch?        |
+ *   +---------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  yes          no
+ *   |           |
+ *   v           v
+ * resolveAll  resolveAllWithRevalidation
+ * Segments    Segments
+ *   |           |
+ *   |           | (compares with prev state)
+ *   |           | (handles null components)
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Update state:             |
+ *   |  - state.segments         |
+ *   |  - state.matchedIds       |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   yield all resolved segments
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * RESOLUTION MODES
+ * ================
+ *
+ * Full Match (document request):
+ *   - Uses resolveAllSegments()
+ *   - No revalidation logic (nothing to compare against)
+ *   - Simple resolution of all route entries
+ *
+ * Partial Match (navigation):
+ *   - Uses resolveAllSegmentsWithRevalidation()
+ *   - Compares current vs previous params/URL
+ *   - Sets component = null for segments client already has
+ *   - Respects custom revalidation rules
+ *
+ *
+ * CRITICAL: SOURCE ITERATION
+ * ==========================
+ *
+ * The middleware MUST iterate the source generator before checking cacheHit:
+ *
+ *   for await (const segment of source) { yield segment; }
+ *
+ * This is because:
+ *   1. Generator middleware are lazy (don't execute until iterated)
+ *   2. cache-lookup sets state.cacheHit during iteration
+ *   3. Without draining source first, cache-lookup never runs
+ *
+ * Incorrect pattern:
+ *   if (!state.cacheHit) { ... }  // cacheHit still false!
+ *   yield* source;                // Too late, already resolved
+ *
+ * Correct pattern:
+ *   yield* source;                // Let cache-lookup set cacheHit
+ *   if (state.cacheHit) return;   // Now we can check
+ */
+import type { ResolvedSegment } from "../../types.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { getRouterContext } from "../router-context.js";
+import type { GeneratorMiddleware } from "./cache-lookup.js";
+
+/**
+ * Creates segment resolution middleware
+ *
+ * Only runs on cache miss (state.cacheHit === false).
+ * Uses resolveAllSegmentsWithRevalidation from RouterContext to resolve segments.
+ */
+export function withSegmentResolution<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): GeneratorMiddleware<ResolvedSegment> {
+  return async function* (
+    source: AsyncGenerator<ResolvedSegment>,
+  ): AsyncGenerator<ResolvedSegment> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
+    // IMPORTANT: Always iterate source first to give cache-lookup a chance
+    // to run and set state.cacheHit. Without this, cache-lookup never executes!
+    for await (const segment of source) {
+      yield segment;
+    }
+
+    // If cache hit, segments were already yielded by cache lookup
+    if (state.cacheHit) {
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:segment-resolve",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
+      }
+      return;
+    }
+
+    const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
+      getRouterContext<TEnv>();
+
+    const Store = ctx.Store;
+
+    if (ctx.isFullMatch) {
+      // Full match (document request) - simple resolution without revalidation
+      const segments = await Store.run(() =>
+        resolveAllSegments(
+          ctx.entries,
+          ctx.routeKey,
+          ctx.matched.params,
+          ctx.handlerContext,
+          ctx.loaderPromises,
+        ),
+      );
+
+      // Update state with resolved segments
+      state.segments = segments;
+      state.matchedIds = segments.map((s: { id: string }) => s.id);
+
+      // Yield all resolved segments
+      for (const segment of segments) {
+        yield segment;
+      }
+    } else {
+      // Partial match (navigation) - resolution with revalidation logic
+      const result = await Store.run(() =>
+        resolveAllSegmentsWithRevalidation(
+          ctx.entries,
+          ctx.routeKey,
+          ctx.matched.params,
+          ctx.handlerContext,
+          ctx.clientSegmentSet,
+          ctx.prevParams,
+          ctx.request,
+          ctx.prevUrl,
+          ctx.url,
+          ctx.loaderPromises,
+          ctx.actionContext,
+          ctx.interceptResult,
+          ctx.localRouteName,
+          ctx.pathname,
+          ctx.stale,
+        ),
+      );
+
+      // Update state with resolved segments
+      state.segments = result.segments;
+      state.matchedIds = result.matchedIds;
+
+      // Yield all resolved segments
+      for (const segment of result.segments) {
+        yield segment;
+      }
+    }
+
+    if (ms) {
+      ms.metrics.push({
+        label: "pipeline:segment-resolve",
+        duration: performance.now() - pipelineStart,
+        startTime: pipelineStart - ms.requestStart,
+      });
+    }
+  };
+}

package/src/router/match-pipelines.ts

@@ -0,0 +1,179 @@
+/**
+ * Match Pipelines
+ *
+ * Composes async generator middleware into pipelines for route matching.
+ * The pipeline transforms navigation requests into resolved UI segments.
+ *
+ * PIPELINE ARCHITECTURE OVERVIEW
+ * ==============================
+ *
+ * The router uses a pipeline of async generator middleware to process requests.
+ * Each middleware can:
+ *   1. Produce segments (yield)
+ *   2. Transform segments from upstream
+ *   3. Observe segments without modifying them
+ *   4. Trigger side effects (caching, background revalidation)
+ *
+ * REQUEST FLOW DIAGRAM
+ * ====================
+ *
+ *   Navigation Request
+ *         |
+ *         v
+ *   +------------------+
+ *   | Create Context   |  MatchContext: routes, params, client state
+ *   +------------------+
+ *         |
+ *         v
+ *   +------------------+
+ *   | Select Pipeline  |  Full (document) vs Partial (navigation)
+ *   +------------------+
+ *         |
+ *         v
+ *   ==================== PIPELINE EXECUTION ====================
+ *   |                                                          |
+ *   |  empty() ─────> [1] ─────> [2] ─────> [3] ─────> [4] ───>|───> segments
+ *   |    |            |          |          |          |       |
+ *   |    |    cache   |  segment |intercept | cache   | bg     |
+ *   |    |   lookup   | resolve  | resolve  | store   | reval  |
+ *   |                                                          |
+ *   ============================================================
+ *         |
+ *         v
+ *   +------------------+
+ *   | Collect Result   |  Filter segments, build MatchResult
+ *   +------------------+
+ *         |
+ *         v
+ *   RSC Stream Response
+ *
+ *
+ * MIDDLEWARE EXECUTION ORDER
+ * ==========================
+ *
+ * Middleware compose in reverse order (rightmost = innermost, runs first):
+ *
+ *   compose(A, B, C)(source)  =>  source -> C -> B -> A -> output
+ *
+ * For the partial match pipeline:
+ *
+ *   compose(
+ *     withBackgroundRevalidation,  // [5] Outermost - triggers SWR
+ *     withCacheStore,              // [4] Stores segments in cache
+ *     withInterceptResolution,     // [3] Resolves intercept segments
+ *     withSegmentResolution,       // [2] Resolves on cache miss
+ *     withCacheLookup              // [1] Innermost - checks cache first
+ *   )
+ *
+ * Execution flow for cache MISS:
+ *
+ *   empty() yields nothing
+ *     -> [1] cache-lookup: no cache, passes through
+ *     -> [2] segment-resolution: resolves segments, yields them
+ *     -> [3] intercept-resolution: resolves intercepts, yields them
+ *     -> [4] cache-store: observes all, stores in cache
+ *     -> [5] bg-revalidation: no-op (wasn't stale)
+ *     -> output: all segments
+ *
+ * Execution flow for cache HIT (stale):
+ *
+ *   empty() yields nothing
+ *     -> [1] cache-lookup: HIT! yields cached segments + fresh loaders
+ *     -> [2] segment-resolution: sees cacheHit=true, skips
+ *     -> [3] intercept-resolution: extracts intercepts from cache
+ *     -> [4] cache-store: sees cacheHit=true, skips
+ *     -> [5] bg-revalidation: triggers waitUntil() to revalidate
+ *     -> output: cached segments + fresh loader data
+ *
+ *
+ * PIPELINE VARIANT
+ * ================
+ *
+ * createMatchPartialPipeline handles both full (document) and partial
+ * (navigation) requests. The middleware steps adapt based on ctx.isFullMatch:
+ * - cache-lookup/store work for both
+ * - background-revalidation is a no-op for full matches (no stale state)
+ * - intercept-resolution is a no-op for full matches (no previous navigation)
+ */
+import type { ResolvedSegment } from "../types.js";
+import type { MatchContext, MatchPipelineState } from "./match-context.js";
+import type { GeneratorMiddleware } from "./match-middleware/index.js";
+import {
+  withBackgroundRevalidation,
+  withCacheLookup,
+  withCacheStore,
+  withInterceptResolution,
+  withSegmentResolution,
+} from "./match-middleware/index.js";
+
+/**
+ * Compose multiple async generator middleware into a single middleware
+ *
+ * Middleware are applied in reverse order (rightmost runs first, innermost).
+ * For the pipeline:
+ *   compose(A, B, C)(source)
+ *
+ * The flow is: source -> C -> B -> A -> output
+ * Where C is the innermost (runs first on input) and A is outermost (runs last).
+ */
+export function compose<T>(
+  ...middleware: GeneratorMiddleware<T>[]
+): GeneratorMiddleware<T> {
+  if (middleware.length === 0) {
+    return (source) => source;
+  }
+  if (middleware.length === 1) {
+    return middleware[0];
+  }
+  return (source) => {
+    // Apply middleware in reverse order (rightmost first)
+    return middleware.reduceRight((prev, fn) => fn(prev), source);
+  };
+}
+
+/**
+ * Create an empty async generator (source for pipeline)
+ */
+export async function* empty<T>(): AsyncGenerator<T> {
+  // Yields nothing - used as the initial source for the pipeline
+}
+
+/**
+ * Create the match partial pipeline
+ *
+ * Pipeline order (innermost to outermost):
+ * 1. cache-lookup    - Check cache first, yield cached segments if hit
+ * 2. segment-resolution - Resolve segments if cache miss
+ * 3. intercept-resolution - Resolve intercept segments
+ * 4. cache-store     - Store segments in cache
+ * 5. background-revalidation - Trigger SWR if cache was stale
+ *
+ * Data flow:
+ * - empty() produces no segments
+ * - cache-lookup either yields cached segments OR passes through to segment-resolution
+ * - segment-resolution resolves fresh segments on cache miss
+ * - intercept-resolution adds intercept segments
+ * - cache-store observes and caches segments
+ * - background-revalidation triggers SWR revalidation if needed
+ */
+export function createMatchPartialPipeline<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): AsyncGenerator<ResolvedSegment> {
+  // Build the middleware chain
+  const pipeline = compose<ResolvedSegment>(
+    // Outermost - observes segments and triggers background revalidation
+    withBackgroundRevalidation(ctx, state),
+    // Observes and stores segments in cache
+    withCacheStore(ctx, state),
+    // Adds intercept segments after main segments
+    withInterceptResolution(ctx, state),
+    // Resolves segments on cache miss
+    withSegmentResolution(ctx, state),
+    // Innermost - checks cache first
+    withCacheLookup(ctx, state),
+  );
+
+  // Start with empty source - cache lookup or segment resolution will produce segments
+  return pipeline(empty());
+}

package/src/router/match-result.ts

@@ -0,0 +1,219 @@
+/**
+ * Match Result Collection
+ *
+ * Collects segments from the pipeline and builds the final MatchResult.
+ * This is the final stage of the match pipeline.
+ *
+ * COLLECTION FLOW
+ * ===============
+ *
+ *   Pipeline Generator
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | collectSegments()        |  Drain async generator
+ *   | for await...push         |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | buildMatchResult()       |  Transform to MatchResult
+ *   +---------------------------+
+ *         |
+ *         |
+ *   +-----+-----+
+ *   |           |
+ * Full       Partial
+ * Match      Match
+ *   |           |
+ *   v           v
+ * All segs   Filter:
+ * rendered   - null components out
+ *            - keep loaders
+ *            - handle intercepts
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *   MatchResult {
+ *     segments,    // Segments to render
+ *     matched,     // All segment IDs
+ *     diff,        // Changed segment IDs
+ *     params,      // Route params
+ *     slots,       // Intercept slot data
+ *     serverTiming // Performance metrics
+ *   }
+ *
+ *
+ * FULL VS PARTIAL MATCH
+ * =====================
+ *
+ * Full Match (document request):
+ *   - All segments are rendered
+ *   - allIds = all segment IDs
+ *   - No filtering needed
+ *
+ * Partial Match (navigation):
+ *   - Filter out null components (client already has them)
+ *   - BUT keep loader segments (they carry data)
+ *   - Handle intercepts specially (preserve client page + add modal)
+ *
+ *
+ * SEGMENT FILTERING RULES
+ * =======================
+ *
+ * For partial match, segments are filtered:
+ *
+ *   Keep if:
+ *     - component !== null (needs rendering)
+ *     - type === "loader" (carries data even with null component)
+ *
+ *   Skip if:
+ *     - component === null AND type !== "loader"
+ *     - (Client already has this segment's UI)
+ *
+ *
+ * INTERCEPT HANDLING
+ * ==================
+ *
+ * When intercepting (modal over current page):
+ *
+ *   allIds = client segments + intercept segments
+ *
+ * This tells the client:
+ *   1. Keep your current segments
+ *   2. Add these intercept segments to the modal slot
+ *
+ * The page stays visible, modal renders on top.
+ *
+ *
+ * MATCHRESULT STRUCTURE
+ * =====================
+ *
+ * {
+ *   segments: ResolvedSegment[]  // Segments to serialize and render
+ *   matched: string[]            // All segment IDs for this route
+ *   diff: string[]               // Which segments changed (for client diffing)
+ *   params: Record<string,string> // Route parameters
+ *   slots?: Record<string, {...}> // Named slot data for intercepts
+ *   serverTiming?: string         // Server-Timing header value
+ *   routeMiddleware?: [...]       // Route middleware results
+ * }
+ *
+ * The client uses this to:
+ *   1. Render segments[] to the UI tree
+ *   2. Update internal state with matched[]
+ *   3. Diff against previous state with diff[]
+ *   4. Render slot content if slots present
+ */
+import type { MatchResult, ResolvedSegment } from "../types.js";
+import type { MatchContext, MatchPipelineState } from "./match-context.js";
+import { debugLog } from "./logging.js";
+
+/**
+ * Collect all segments from an async generator
+ */
+export async function collectSegments(
+  generator: AsyncGenerator<ResolvedSegment>,
+): Promise<ResolvedSegment[]> {
+  const segments: ResolvedSegment[] = [];
+  for await (const segment of generator) {
+    segments.push(segment);
+  }
+  return segments;
+}
+
+/**
+ * Build the final MatchResult from collected segments and context
+ */
+export function buildMatchResult<TEnv>(
+  allSegments: ResolvedSegment[],
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): MatchResult {
+  const logPrefix = ctx.isFullMatch
+    ? "[Router.match]"
+    : "[Router.matchPartial]";
+
+  let allIds: string[];
+  let segmentsToRender: ResolvedSegment[];
+
+  if (ctx.isFullMatch) {
+    // Full match (document request) - all segments are rendered
+    // Deduplicate by segment ID (defense-in-depth). The primary dedup is in
+    // resolveAllSegments, but this guards against any path that bypasses it.
+    // include() scopes can produce entries that resolve the same shared layout,
+    // and duplicate IDs change the client's React tree depth causing remounts.
+    const seen = new Set<string>();
+    segmentsToRender = [];
+    for (const s of allSegments) {
+      if (!seen.has(s.id)) {
+        seen.add(s.id);
+        segmentsToRender.push(s);
+      }
+    }
+    allIds = segmentsToRender.map((s) => s.id);
+  } else {
+    // Partial match (navigation) - filter and handle intercepts
+    // When intercepting, tell browser to keep its current segments + add modal
+    // This prevents the browser from discarding the current page content
+    // If client sent empty segments (HMR recovery), use segment IDs from allSegments
+    allIds = ctx.interceptResult
+      ? ctx.clientSegmentIds.length > 0
+        ? [...ctx.clientSegmentIds, ...state.interceptSegments.map((s) => s.id)]
+        : allSegments.map((s) => s.id) // Use actual segments, not matchedIds
+      : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
+
+    // Deduplicate allIds (defense-in-depth for partial match path)
+    allIds = [...new Set(allIds)];
+
+    // Filter out segments with null components (client already has them)
+    // BUT always include loader segments - they carry data even with null component
+    segmentsToRender = allSegments.filter(
+      (s) => s.component !== null || s.type === "loader",
+    );
+  }
+
+  debugLog(logPrefix, "all segments", {
+    segments: allSegments.map((s) => ({
+      id: s.id,
+      type: s.type,
+      hasComponent: s.component !== null,
+    })),
+  });
+  debugLog(logPrefix, "segments to render", {
+    segmentIds: segmentsToRender.map((s) => s.id),
+  });
+
+  return {
+    segments: segmentsToRender,
+    matched: allIds,
+    diff: segmentsToRender.map((s) => s.id),
+    params: ctx.matched.params,
+    routeName: ctx.routeKey,
+    slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
+    routeMiddleware:
+      ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
+  };
+}
+
+/**
+ * Collect segments from pipeline and build MatchResult
+ *
+ * This is the main entry point for building the final result after
+ * the pipeline has processed all segments.
+ */
+export async function collectMatchResult<TEnv>(
+  pipeline: AsyncGenerator<ResolvedSegment>,
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): Promise<MatchResult> {
+  const allSegments = await collectSegments(pipeline);
+
+  // Update state with collected segments if not already set
+  if (state.segments.length === 0) {
+    state.segments = allSegments;
+  }
+
+  return buildMatchResult(allSegments, ctx, state);
+}