@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/match-middleware/cache-store.ts

@@ -0,0 +1,295 @@
+/**
+ * Cache Store Middleware
+ *
+ * Stores resolved segments in cache for future requests.
+ * Implements proactive caching for partial navigation scenarios.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from intercept-resolution)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Collect + yield all      |  Observer pattern: pass through
+ *   | allSegments[]            |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Should skip cache?  |
+ *   | - !cacheScope       |──yes──> return
+ *   | - isAction          |
+ *   | - cacheHit          |
+ *   | - method !== GET    |
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +-------------------------------+
+ *   | Any null components?          |
+ *   | (client already has segment)  |
+ *   +-------------------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  yes          no
+ *   |           |
+ *   v           v
+ * PROACTIVE   DIRECT
+ * CACHE       CACHE
+ *   |           |
+ *   v           v
+ * waitUntil()  cacheRoute()
+ * re-render    immediately
+ * fresh        |
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * CACHING STRATEGIES
+ * ==================
+ *
+ * 1. Direct Cache (all components present):
+ *    - Immediate cacheRoute() call
+ *    - All segments have valid components
+ *    - Used for fresh full-page renders
+ *
+ * 2. Proactive Cache (null components present):
+ *    - Background re-render via waitUntil()
+ *    - Creates fresh context to avoid polluting response
+ *    - Re-resolves ALL segments without revalidation
+ *    - Ensures cache has complete components for future requests
+ *
+ *
+ * WHY PROACTIVE CACHING?
+ * ======================
+ *
+ * During partial navigation, some segments have null components:
+ *
+ *   Request: /products/123 -> /products/456
+ *   Segments: [ProductLayout(null), ProductPage(component)]
+ *
+ * The null means "client already has this, don't re-send."
+ * But if we cache these null components, future document requests
+ * would fail (no component to render).
+ *
+ * Solution: Background re-render all segments fresh, then cache.
+ * This ensures the cache always has complete, renderable segments.
+ *
+ *
+ * PROACTIVE CACHE FLOW
+ * ====================
+ *
+ *   1. Current request returns (fast, with nulls)
+ *   2. waitUntil() triggers background work
+ *   3. Create fresh handler context (silent, no stream pollution)
+ *   4. Re-resolve all entries without revalidation logic
+ *   5. Also resolve intercept segments if applicable
+ *   6. Store complete segments in cache
+ *
+ *
+ * SKIP CONDITIONS
+ * ===============
+ *
+ * Caching is skipped when:
+ *   - Cache scope disabled (no caching configured)
+ *   - This is an action request (mutations shouldn't cache)
+ *   - Cache was already hit (no need to re-cache same data)
+ *   - Non-GET request (only GET requests are cacheable)
+ */
+import type { ResolvedSegment } from "../../types.js";
+import { getRequestContext } from "../../server/request-context.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { getRouterContext } from "../router-context.js";
+import { debugLog, debugWarn } from "../logging.js";
+import type { GeneratorMiddleware } from "./cache-lookup.js";
+
+/**
+ * Creates cache store middleware
+ *
+ * Observes all segments passing through and stores them in cache after pipeline completes.
+ * Handles proactive caching for null-component segments.
+ */
+export function withCacheStore<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): GeneratorMiddleware<ResolvedSegment> {
+  return async function* (
+    source: AsyncGenerator<ResolvedSegment>,
+  ): AsyncGenerator<ResolvedSegment> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
+    // Collect all segments while passing them through
+    const allSegments: ResolvedSegment[] = [];
+    for await (const segment of source) {
+      allSegments.push(segment);
+      yield segment;
+    }
+
+    // Skip caching if:
+    // 1. Cache miss but cache scope is disabled
+    // 2. This is an action (actions don't cache)
+    // 3. Cache was already hit (no need to re-cache)
+    // 4. Non-GET request (only cache GET requests)
+    if (
+      !ctx.cacheScope?.enabled ||
+      ctx.isAction ||
+      state.cacheHit ||
+      ctx.request.method !== "GET"
+    ) {
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:cache-store",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
+      }
+      return;
+    }
+
+    const {
+      createHandlerContext,
+      setupLoaderAccess,
+      resolveAllSegments,
+      resolveInterceptEntry,
+      createHandleStore,
+    } = getRouterContext<TEnv>();
+
+    // Combine main segments with intercept segments
+    const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
+
+    // Check if any non-loader segments have null components
+    // This happens when client already had those segments (partial navigation)
+    const hasNullComponents = allSegmentsToCache.some(
+      (s) => s.component === null && s.type !== "loader",
+    );
+
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return;
+
+    const cacheScope = ctx.cacheScope;
+
+    // Register onResponse callback to skip caching for non-200 responses
+    // Note: error/notFound status codes are set elsewhere (not caching-specific)
+    requestCtx.onResponse((response) => {
+      // Only cache successful responses
+      if (response.status !== 200) {
+        debugLog("cacheStore", "skipping cache for non-200 response", {
+          status: response.status,
+          pathname: ctx.pathname,
+        });
+        return response;
+      }
+
+      if (hasNullComponents) {
+        // Proactive caching: render all segments fresh in background
+        // This ensures cache has complete components for future requests
+        requestCtx.waitUntil(async () => {
+          debugLog("cacheStore", "proactive caching started", {
+            pathname: ctx.pathname,
+          });
+          // Swap to a fresh HandleStore so handle.push() calls from
+          // proactive resolution are captured (not silenced). The original
+          // store's stream is already sent by waitUntil time.
+          // cacheRoute reads from requestCtx._handleStore, so this ensures
+          // complete handle data (e.g. breadcrumbs) is cached.
+          const originalHandleStore = requestCtx._handleStore;
+          requestCtx._handleStore = createHandleStore();
+          try {
+            // Create fresh context for proactive caching
+            const proactiveHandlerContext = createHandlerContext(
+              ctx.matched.params,
+              ctx.request,
+              ctx.url.searchParams,
+              ctx.pathname,
+              ctx.url,
+              ctx.env,
+              ctx.routeMap,
+              ctx.matched.routeKey,
+              ctx.matched.responseType,
+              ctx.matched.pt === true,
+            );
+            const proactiveLoaderPromises = new Map<string, Promise<any>>();
+
+            // Use normal loader access so handle data is captured
+            setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
+
+            // Re-resolve ALL segments without revalidation
+            const Store = ctx.Store;
+            const freshSegments = await Store.run(() =>
+              resolveAllSegments(
+                ctx.entries,
+                ctx.routeKey,
+                ctx.matched.params,
+                proactiveHandlerContext,
+                proactiveLoaderPromises,
+              ),
+            );
+
+            // Also resolve intercept segments fresh if applicable
+            let freshInterceptSegments: ResolvedSegment[] = [];
+            if (ctx.interceptResult) {
+              freshInterceptSegments = await Store.run(() =>
+                resolveInterceptEntry(
+                  ctx.interceptResult!.intercept,
+                  ctx.interceptResult!.entry,
+                  ctx.matched.params,
+                  proactiveHandlerContext,
+                  true, // belongsToRoute
+                  // No revalidationContext = render fresh
+                ),
+              );
+            }
+
+            const completeSegments = [
+              ...freshSegments,
+              ...freshInterceptSegments,
+            ];
+            requestCtx._handleStore.seal();
+            await cacheScope.cacheRoute(
+              ctx.pathname,
+              ctx.matched.params,
+              completeSegments,
+              ctx.isIntercept,
+            );
+            debugLog("cacheStore", "proactive caching complete", {
+              pathname: ctx.pathname,
+            });
+          } catch (error) {
+            debugWarn("cacheStore", "proactive caching failed", {
+              pathname: ctx.pathname,
+              error: String(error),
+            });
+          } finally {
+            requestCtx._handleStore = originalHandleStore;
+          }
+        });
+      } else {
+        // All segments have components - cache directly
+        // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        requestCtx.waitUntil(async () => {
+          await cacheScope.cacheRoute(
+            ctx.pathname,
+            ctx.matched.params,
+            allSegmentsToCache,
+            ctx.isIntercept,
+          );
+        });
+      }
+
+      return response;
+    });
+
+    if (ms) {
+      ms.metrics.push({
+        label: "pipeline:cache-store",
+        duration: performance.now() - pipelineStart,
+        startTime: pipelineStart - ms.requestStart,
+      });
+    }
+  };
+}

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,306 @@
+/**
+ * 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";
+import { debugLog } from "../logging.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;
+    debugLog("matchPartial.intercept", "intercept resolved", {
+      routeName: ctx.localRouteName,
+      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;
+        debugLog(
+          "matchPartial.intercept",
+          "cache hit with fresh intercept loaders",
+          {
+            routeName: ctx.localRouteName,
+            slotName,
+          },
+        );
+      }
+    } else {
+      debugLog(
+        "matchPartial.intercept",
+        "cache hit without intercept loader revalidation",
+        {
+          routeName: ctx.localRouteName,
+          slotName,
+        },
+      );
+    }
+  }
+
+  state.slots[slotName] = {
+    active: true,
+    segments: interceptSegments,
+  };
+}