@rangojs/router 0.0.0-experimental.10

package/src/router/match-middleware/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Match Middleware
+ *
+ * Async generator middleware for the match pipeline.
+ * Each middleware transforms or enriches the segment stream.
+ *
+ * MIDDLEWARE OVERVIEW
+ * ===================
+ *
+ * The pipeline consists of 5 middleware layers, each with a specific role:
+ *
+ * +-------------------------------------------------------------------------+
+ * |                         MIDDLEWARE PIPELINE                             |
+ * +-------------------------------------------------------------------------+
+ * |                                                                         |
+ * |  [1] CACHE LOOKUP (innermost)                                           |
+ * |      Purpose: Check cache before resolving                              |
+ * |      On hit:  Yield cached segments + fresh loaders                     |
+ * |      On miss: Pass through to segment resolution                        |
+ * |      Side effects: Sets state.cacheHit, state.shouldRevalidate          |
+ * |                                                                         |
+ * |  [2] SEGMENT RESOLUTION                                                 |
+ * |      Purpose: Resolve segments when cache misses                        |
+ * |      Skips if: state.cacheHit === true                                  |
+ * |      Produces: All route segments (layouts, routes, loaders)            |
+ * |      Two modes: Full (simple) vs Partial (with revalidation)            |
+ * |                                                                         |
+ * |  [3] INTERCEPT RESOLUTION                                               |
+ * |      Purpose: Resolve intercept segments (modal slots)                  |
+ * |      Triggers: When ctx.interceptResult exists                          |
+ * |      Produces: Additional segments for named slots                      |
+ * |      Updates: state.slots[slotName] with intercept segments             |
+ * |                                                                         |
+ * |  [4] CACHE STORE                                                        |
+ * |      Purpose: Store segments in cache for future requests               |
+ * |      Skips if: Cache hit, actions, or cache disabled                    |
+ * |      Strategy: Direct cache if all components present                   |
+ * |                Proactive cache if null components (via waitUntil)       |
+ * |                                                                         |
+ * |  [5] BACKGROUND REVALIDATION (outermost)                                |
+ * |      Purpose: SWR - serve stale, revalidate in background               |
+ * |      Triggers: When state.shouldRevalidate === true                     |
+ * |      Action: Async resolution via waitUntil(), updates cache            |
+ * |                                                                         |
+ * +-------------------------------------------------------------------------+
+ *
+ *
+ * MIDDLEWARE INTERACTION PATTERNS
+ * ===============================
+ *
+ * Pattern 1: Producer Middleware (cache-lookup, segment-resolution)
+ *   - Yields segments into the stream
+ *   - Creates new data for downstream middleware
+ *
+ * Pattern 2: Transformer Middleware (intercept-resolution)
+ *   - Passes through existing segments
+ *   - Adds additional segments (intercepts)
+ *
+ * Pattern 3: Observer Middleware (cache-store, background-revalidation)
+ *   - Passes through all segments unchanged
+ *   - Triggers side effects based on state
+ *
+ *
+ * STATE FLAGS
+ * ===========
+ *
+ * The middleware communicate through MatchPipelineState:
+ *
+ *   state.cacheHit        - Set by cache-lookup, read by others to skip work
+ *   state.shouldRevalidate - Set by cache-lookup, triggers bg-revalidation
+ *   state.segments        - Accumulated segments from pipeline
+ *   state.interceptSegments - Segments for intercept slots
+ *   state.slots           - Named slot data for client
+ */
+
+export { withCacheLookup } from "./cache-lookup.js";
+export { withSegmentResolution } from "./segment-resolution.js";
+export { withInterceptResolution } from "./intercept-resolution.js";
+export { withCacheStore } from "./cache-store.js";
+export { withBackgroundRevalidation } from "./background-revalidation.js";
+export type { GeneratorMiddleware } from "./cache-lookup.js";

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

@@ -0,0 +1,281 @@
+/**
+ * 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> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
+    // 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) {
+      if (ms) {
+        ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      }
+      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);
+      }
+      if (ms) {
+        ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      }
+      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;
+    }
+
+    if (ms) {
+      ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+    }
+  };
+}
+
+/**
+ * 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,184 @@
+/**
+ * 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
+        )
+      );
+
+      // 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 });
+    }
+  };
+}