@rangojs/router 0.4.0 → 0.4.2

package/dist/router/match-middleware/cache-store.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 type { MatchContext, MatchPipelineState } from "../match-context.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 declare function withCacheStore<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;
+//# sourceMappingURL=cache-store.d.ts.map

package/dist/router/match-middleware/cache-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-store.d.ts","sourceRoot":"","sources":["../../../src/router/match-middleware/cache-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EACjC,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,EACvB,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAAC,eAAe,CAAC,CA+JtC"}

package/dist/router/match-middleware/cache-store.js

@@ -0,0 +1,108 @@
+import { getRequestContext } from "../../server/request-context.js";
+import { getRouterContext } from "../router-context.js";
+import { debugLog, debugWarn } from "../logging.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(ctx, state) {
+    return async function* (source) {
+        const pipelineStart = performance.now();
+        const ms = ctx.metricsStore;
+        // Collect all segments while passing them through
+        const allSegments = [];
+        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, setupLoaderAccessSilent, resolveAllSegments, resolveInterceptEntry, } = getRouterContext();
+        // 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,
+                    });
+                    try {
+                        // Create fresh context for proactive caching
+                        // This prevents handle data from polluting the response stream
+                        const proactiveHandlerContext = createHandlerContext(ctx.matched.params, ctx.request, ctx.url.searchParams, ctx.pathname, ctx.url, ctx.bindings, ctx.routeMap, ctx.matched.routeKey);
+                        const proactiveLoaderPromises = new Map();
+                        // Set up loader access that ignores handle pushes
+                        setupLoaderAccessSilent(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 = [];
+                        if (ctx.interceptResult) {
+                            freshInterceptSegments = await Store.run(() => resolveInterceptEntry(ctx.interceptResult.intercept, ctx.interceptResult.entry, ctx.matched.params, proactiveHandlerContext, true));
+                        }
+                        const completeSegments = [
+                            ...freshSegments,
+                            ...freshInterceptSegments,
+                        ];
+                        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),
+                        });
+                    }
+                });
+            }
+            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 });
+        }
+    };
+}
+//# sourceMappingURL=cache-store.js.map

package/dist/router/match-middleware/cache-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-store.js","sourceRoot":"","sources":["../../../src/router/match-middleware/cache-store.ts"],"names":[],"mappings":"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"}

package/dist/router/match-middleware/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/router/match-middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/router/match-middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/router/match-middleware/index.js

@@ -0,0 +1,80 @@
+/**
+ * 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";
+//# sourceMappingURL=index.js.map

package/dist/router/match-middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/router/match-middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/router/match-middleware/intercept-resolution.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 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 declare function withInterceptResolution<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;
+//# sourceMappingURL=intercept-resolution.d.ts.map

package/dist/router/match-middleware/intercept-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intercept-resolution.d.ts","sourceRoot":"","sources":["../../../src/router/match-middleware/intercept-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAC1C,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,EACvB,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAAC,eAAe,CAAC,CA0FtC"}

package/dist/router/match-middleware/intercept-resolution.js

@@ -0,0 +1,134 @@
+import { getRouterContext } from "../router-context.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(ctx, state) {
+    return async function* (source) {
+        const pipelineStart = performance.now();
+        const ms = ctx.metricsStore;
+        // First, yield all segments from the source (main segment resolution or cache)
+        const segments = [];
+        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();
+        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(ctx, state, segments) {
+    if (!ctx.interceptResult)
+        return;
+    const { resolveInterceptLoadersOnly } = getRouterContext();
+    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,
+    };
+}
+//# sourceMappingURL=intercept-resolution.js.map