@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/dist/types/router/match-middleware/cache-lookup.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Cache Lookup Middleware
+ *
+ * First middleware in the pipeline. Checks cache before segment resolution.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (empty)
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Is action request?  |──yes──> yield* source (pass through)
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +---------------------+
+ *   | Cache enabled?      |──no───> yield* source (pass through)
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +---------------------+
+ *   | Lookup cache        |
+ *   | (pathname, params)  |
+ *   +---------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  miss        hit
+ *   |           |
+ *   v           v
+ * yield*    Set state.cacheHit = true
+ * source    Set state.shouldRevalidate
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | For each cached segment:  |
+ *   |    |  - Apply revalidation     |
+ *   |    |  - Set component = null   |
+ *   |    |    if client has it       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | Resolve fresh loaders     |  <-- Loaders are NEVER cached
+ *   |    | (always fresh data)       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    yield cached segments
+ *   |    yield fresh loader segments
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * CACHE BEHAVIOR
+ * ==============
+ *
+ * Cache HIT:
+ *   - state.cacheHit = true signals downstream middleware to skip
+ *   - Cached segments have their components nullified if client already has them
+ *   - Loaders are always re-resolved for fresh data
+ *   - state.shouldRevalidate triggers background SWR if cache was stale
+ *
+ * Cache MISS:
+ *   - Passes through to segment-resolution middleware
+ *   - No segments yielded from this middleware
+ *
+ * Loaders:
+ *   - NEVER cached in the segment cache
+ *   - Always resolved fresh on every request
+ *   - Ensures data freshness even with cached UI components
+ *   - Segment cache staleness does NOT propagate to loader revalidation;
+ *     loaders use their own revalidation rules (actionId, user-defined)
+ *
+ *
+ * REVALIDATION RULES
+ * ==================
+ *
+ * Each cached segment is evaluated against its revalidation rules:
+ *
+ *   1. No rules defined -> use default (skip if client has segment)
+ *   2. Rules return false -> skip re-render (nullify component)
+ *   3. Rules return true -> re-render (keep component)
+ *
+ * Revalidation context includes:
+ *   - Previous/next URL and params
+ *   - Request object
+ *   - Action context (if POST)
+ */
+import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+/**
+ * Whether the prerender store holds a baked entry for this route + params.
+ * Consulted by the PPR replay gate (matchPartialWithPprReplay), which must
+ * only report `prerender-store` when the short-circuit below will actually
+ * serve: a Passthrough(Prerender()) route with an unbaked/passthrough param
+ * misses the store and renders live, and replay — including its heal
+ * capture — must stay available for it (withCacheStore records the doc
+ * record on that path; state.cacheSource is not "prerender"). The store
+ * memoizes per routeKey/paramHash, so this probe and tryPrerenderLookup's
+ * subsequent get() share one underlying load.
+ */
+export declare function prerenderEntryExists(routeKey: string | undefined, params: Record<string, string>, pathname: string, entries: EntryData[]): Promise<boolean>;
+/**
+ * Async generator middleware type
+ */
+export type GeneratorMiddleware<T> = (source: AsyncGenerator<T>) => AsyncGenerator<T>;
+/**
+ * Creates cache lookup middleware
+ *
+ * Checks cache for segments. If cache hit:
+ * - Applies revalidation to determine which segments need re-rendering
+ * - Resolves loaders fresh (loaders are NOT cached by design)
+ * - Sets state.cacheHit = true
+ * - Sets state.shouldRevalidate if SWR needed
+ * - Yields cached segments + fresh loader segments
+ *
+ * If cache miss:
+ * - Passes through to next middleware
+ */
+export declare function withCacheLookup<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;

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

@@ -0,0 +1,112 @@
+/**
+ * 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>;

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

@@ -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";
+export type { GeneratorMiddleware } from "./cache-lookup.js";

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

@@ -0,0 +1,116 @@
+/**
+ * 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>;

package/dist/types/router/match-middleware/segment-resolution.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 { EntryData } from "../../server/context.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import type { GeneratorMiddleware } from "./cache-lookup.js";
+export declare function treeHasStreaming(entries: EntryData[]): boolean;
+export declare function withSegmentResolution<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;

package/dist/types/router/match-pipelines.d.ts

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