@ivogt/rsc-router 0.0.0-experimental.1

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

@@ -0,0 +1,268 @@
+/**
+ * Intercept Resolution Middleware
+ *
+ * Resolves intercept (modal slot) segments for soft navigation.
+ * Yields intercept segments after main route segments.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from segment-resolution)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Collect + yield source   |  Pass through main segments
+ *   | segments[]               |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | isFullMatch?        |──yes──> return (no intercepts on doc requests)
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +---------------------+
+ *   | Has interceptResult |──no───> return
+ *   | AND not cached?     |
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +----------------------+    +----------------------------+
+ *   | Fresh intercept?     |yes>| resolveInterceptEntry()    |
+ *   | (!cacheHit or        |    | - middleware, loaders, UI  |
+ *   |  no intercept segs)  |    +----------------------------+
+ *   +----------------------+              |
+ *         | no                            v
+ *         v                    yield intercept segments
+ *   +----------------------------+        |
+ *   | Cache hit with intercept   |        |
+ *   | handleCacheHitIntercept()  |        |
+ *   | - Extract from cache       |        |
+ *   | - Re-resolve loaders only  |        |
+ *   +----------------------------+        |
+ *         |                               |
+ *         +-------------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Update state:             |
+ *   |  - interceptSegments      |
+ *   |  - slots[slotName]        |
+ *   +---------------------------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * INTERCEPT SCENARIOS
+ * ===================
+ *
+ * 1. Fresh intercept (no cache):
+ *    - Full resolution of intercept entry
+ *    - Resolves middleware, loaders, and component
+ *    - Yields all intercept segments
+ *
+ * 2. Cache hit with intercept:
+ *    - Extracts intercept segments from cached data
+ *    - Re-resolves ONLY loaders for fresh data
+ *    - Keeps cached component/layout
+ *
+ * 3. No intercept:
+ *    - Passes through unchanged
+ *    - No intercept segments yielded
+ *
+ *
+ * WHAT ARE INTERCEPTS?
+ * ====================
+ *
+ * Intercepts enable "soft navigation" patterns like modals:
+ *
+ *   1. User clicks a link (e.g., /photos/123)
+ *   2. Instead of full navigation, content renders in a modal slot
+ *   3. Background page remains visible and interactive
+ *   4. Hard navigation (direct URL) shows full page
+ *
+ * Configuration:
+ *   intercept("@modal", "photos", <PhotoModal />, () => [...])
+ *
+ * The intercept resolves to segments that render in the named slot
+ * instead of replacing the main content.
+ *
+ *
+ * SLOT STRUCTURE
+ * ==============
+ *
+ * state.slots[slotName] = {
+ *   active: true,
+ *   segments: [...intercept segments]
+ * }
+ *
+ * The client uses this to:
+ *   1. Keep current page segments
+ *   2. Render intercept segments in named <Outlet name="@modal" />
+ */
+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 intercept resolution middleware
+ *
+ * If ctx.interceptResult exists and we're not in a cache-hit-with-intercept scenario:
+ * - Resolves intercept segments
+ * - Updates state.interceptSegments
+ * - Updates state.slots with the intercept slot
+ * - Yields intercept segments after main segments
+ */
+export function withInterceptResolution<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState
+): GeneratorMiddleware<ResolvedSegment> {
+  return async function* (
+    source: AsyncGenerator<ResolvedSegment>
+  ): AsyncGenerator<ResolvedSegment> {
+    // First, yield all segments from the source (main segment resolution or cache)
+    const segments: ResolvedSegment[] = [];
+    for await (const segment of source) {
+      segments.push(segment);
+      yield segment;
+    }
+
+    // Skip intercept resolution for full match (document requests don't have intercepts)
+    if (ctx.isFullMatch) {
+      return;
+    }
+
+    // Skip intercept resolution if:
+    // 1. No intercept result
+    // 2. Already have intercept segments (from cache hit with intercept key)
+    // 3. Cache hit with intercept key
+    const skipInterceptResolution =
+      !ctx.interceptResult ||
+      state.interceptSegments.length > 0 ||
+      (state.cacheHit && ctx.isIntercept);
+
+    if (skipInterceptResolution) {
+      // For cache hit with intercept, extract intercept segments from cached data for slots
+      // and re-resolve loaders for fresh data
+      if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
+        await handleCacheHitIntercept(ctx, state, segments);
+      }
+      return;
+    }
+
+    // Resolve intercept segments
+    const { resolveInterceptEntry } = getRouterContext<TEnv>();
+
+    const slotName = ctx.interceptResult!.intercept.slotName;
+    console.log(
+      `[Router.matchPartial] Found intercept for "${ctx.localRouteName}" -> slot "${slotName}"`
+    );
+
+    // Resolve intercept entry (middleware, loaders, handler)
+    const Store = ctx.Store;
+    const interceptSegments = await Store.run(() =>
+      resolveInterceptEntry(
+        ctx.interceptResult!.intercept,
+        ctx.interceptResult!.entry,
+        ctx.matched.params,
+        ctx.handlerContext,
+        true, // belongsToRoute
+        {
+          clientSegmentIds: ctx.clientSegmentSet,
+          prevParams: ctx.prevParams,
+          request: ctx.request,
+          prevUrl: ctx.prevUrl,
+          nextUrl: ctx.url,
+          routeKey: ctx.routeKey,
+          actionContext: ctx.actionContext,
+          stale: ctx.stale,
+        }
+      )
+    );
+
+    // Update state
+    state.interceptSegments = interceptSegments;
+    state.slots[slotName] = {
+      active: true,
+      segments: interceptSegments,
+    };
+
+    // Yield intercept segments
+    for (const segment of interceptSegments) {
+      yield segment;
+    }
+  };
+}
+
+/**
+ * Handle cache hit with intercept scenario
+ *
+ * Extract intercept segments from cached data and re-resolve loaders for fresh data.
+ */
+async function handleCacheHitIntercept<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  segments: ResolvedSegment[]
+): Promise<void> {
+  if (!ctx.interceptResult) return;
+
+  const { resolveInterceptLoadersOnly } = getRouterContext<TEnv>();
+
+  const slotName = ctx.interceptResult.intercept.slotName;
+
+  // Find intercept segments from cached segments (namespace starts with "intercept:")
+  const interceptSegments = segments.filter((s) =>
+    s.namespace?.startsWith("intercept:")
+  );
+  state.interceptSegments = interceptSegments;
+
+  // Re-resolve intercept loaders for fresh data on cache hit
+  // This keeps cached component/layout but fetches fresh loader data
+  if (resolveInterceptLoadersOnly) {
+    const Store = ctx.Store;
+    const freshLoaderResult = await Store.run(() =>
+      resolveInterceptLoadersOnly(
+        ctx.interceptResult!.intercept,
+        ctx.interceptResult!.entry,
+        ctx.matched.params,
+        ctx.handlerContext,
+        true, // belongsToRoute
+        {
+          clientSegmentIds: ctx.clientSegmentSet,
+          prevParams: ctx.prevParams,
+          request: ctx.request,
+          prevUrl: ctx.prevUrl,
+          nextUrl: ctx.url,
+          routeKey: ctx.routeKey,
+          actionContext: ctx.actionContext,
+          stale: ctx.stale,
+        }
+      )
+    );
+
+    // Update intercept segment's loaderDataPromise with fresh data
+    if (freshLoaderResult) {
+      const interceptMainSegment = interceptSegments.find(
+        (s) => s.type === "parallel" && s.slot
+      );
+      if (interceptMainSegment) {
+        interceptMainSegment.loaderDataPromise = freshLoaderResult.loaderDataPromise;
+        interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
+        console.log(
+          `[Router.matchPartial] Cache HIT + fresh loaders for intercept "${ctx.localRouteName}" -> slot "${slotName}"`
+        );
+      }
+    } else {
+      console.log(
+        `[Router.matchPartial] Cache HIT for intercept "${ctx.localRouteName}" -> slot "${slotName}" (no loader revalidation)`
+      );
+    }
+  }
+
+  state.slots[slotName] = {
+    active: true,
+    segments: interceptSegments,
+  };
+}

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

@@ -0,0 +1,174 @@
+/**
+ * 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> {
+    // 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) {
+      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) => 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
+        )
+      );
+
+      // 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;
+      }
+    }
+  };
+}

package/src/router/match-pipelines.ts

@@ -0,0 +1,214 @@
+/**
+ * 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
+ *
+ *
+ * TWO PIPELINE VARIANTS
+ * =====================
+ *
+ * 1. createMatchPipeline (Full Match)
+ *    - Used for document requests (initial page load)
+ *    - No revalidation logic (no previous state to compare)
+ *    - Simpler segment resolution
+ *
+ * 2. createMatchPartialPipeline (Partial Match)
+ *    - Used for client-side navigation
+ *    - Includes revalidation for SWR
+ *    - Compares with previous params/URL
+ *    - Supports intercepts (soft navigation modals)
+ */
+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());
+}
+
+/**
+ * Create the full match pipeline (simpler, no revalidation)
+ *
+ * Used for document requests (initial page load) where we don't need
+ * revalidation logic since there's no previous state to compare against.
+ */
+export function createMatchPipeline<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState
+): AsyncGenerator<ResolvedSegment> {
+  // For full match, we only need:
+  // 1. Cache lookup
+  // 2. Segment resolution (without revalidation)
+  // 3. Intercept resolution
+  // 4. Cache store
+
+  // Note: Full match uses different resolution logic (resolveAllSegments instead of
+  // resolveAllSegmentsWithRevalidation). This will be handled by the segment resolution
+  // middleware checking ctx.isFullMatch or similar flag.
+
+  const pipeline = compose<ResolvedSegment>(
+    withCacheStore(ctx, state),
+    withInterceptResolution(ctx, state),
+    withSegmentResolution(ctx, state),
+    withCacheLookup(ctx, state)
+  );
+
+  return pipeline(empty());
+}