@rangojs/router 0.4.0 → 0.4.1

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

@@ -1,112 +0,0 @@
-/**
- * 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.backup/router/match-middleware/index.d.ts

@@ -1,80 +0,0 @@
-/**
- * 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.backup/router/match-middleware/intercept-resolution.d.ts

@@ -1,116 +0,0 @@
-/**
- * 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.backup/router/match-middleware/segment-resolution.d.ts

@@ -1,94 +0,0 @@
-/**
- * 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.backup/router/match-pipelines.d.ts

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

package/dist/types.backup/router/match-result.d.ts

@@ -1,114 +0,0 @@
-/**
- * Match Result Collection
- *
- * Collects segments from the pipeline and builds the final MatchResult.
- * This is the final stage of the match pipeline.
- *
- * COLLECTION FLOW
- * ===============
- *
- *   Pipeline Generator
- *         |
- *         v
- *   +---------------------------+
- *   | collectSegments()        |  Drain async generator
- *   | for await...push         |
- *   +---------------------------+
- *         |
- *         v
- *   +---------------------------+
- *   | buildMatchResult()       |  Transform to MatchResult
- *   +---------------------------+
- *         |
- *         |
- *   +-----+-----+
- *   |           |
- * Full       Partial
- * Match      Match
- *   |           |
- *   v           v
- * All segs   Filter:
- * rendered   - null components out
- *            - keep loaders
- *            - handle intercepts
- *   |           |
- *   +-----------+
- *         |
- *         v
- *   MatchResult {
- *     segments,    // Segments to render
- *     matched,     // All segment IDs
- *     diff,        // Changed segment IDs
- *     params,      // Route params
- *     slots,       // Intercept slot data
- *     serverTiming // Performance metrics
- *   }
- *
- *
- * FULL VS PARTIAL MATCH
- * =====================
- *
- * Full Match (document request):
- *   - All segments are rendered
- *   - allIds = all segment IDs
- *   - No filtering needed
- *
- * Partial Match (navigation):
- *   - Filter out null components (client already has them)
- *   - BUT keep loader segments (they carry data)
- *   - Handle intercepts specially (preserve client page + add modal)
- *
- *
- * SEGMENT FILTERING RULES
- * =======================
- *
- * For partial match, segments are filtered:
- *
- *   Keep if:
- *     - component !== null (needs rendering)
- *     - type === "loader" (carries data even with null component)
- *     - client doesn't have the segment (structurally required parent node)
- *
- *   Skip if:
- *     - component === null AND type !== "loader" AND client has it cached
- *     - (Revalidation skip — client already has this segment's UI)
- *
- *
- * INTERCEPT HANDLING
- * ==================
- *
- * When intercepting (modal over current page):
- *
- *   allIds = client segments + intercept segments
- *
- * This tells the client:
- *   1. Keep your current segments
- *   2. Add these intercept segments to the modal slot
- *
- * The page stays visible, modal renders on top.
- *
- *
- * MATCHRESULT STRUCTURE
- * =====================
- *
- * {
- *   segments: ResolvedSegment[]  // Segments to serialize and render
- *   matched: string[]            // All segment IDs for this route
- *   diff: string[]               // Which segments changed (for client diffing)
- *   params: Record<string,string> // Route parameters
- *   slots?: Record<string, {...}> // Named slot data for intercepts
- *   serverTiming?: string         // Server-Timing header value
- *   routeMiddleware?: [...]       // Route middleware results
- * }
- *
- * The client uses this to:
- *   1. Render segments[] to the UI tree
- *   2. Update internal state with matched[]
- *   3. Diff against previous state with diff[]
- *   4. Render slot content if slots present
- */
-import type { MatchResult, ResolvedSegment } from "../types.js";
-import type { MatchContext, MatchPipelineState } from "./match-context.js";
-export declare function collectSegments(generator: AsyncGenerator<ResolvedSegment>): Promise<ResolvedSegment[]>;
-export declare function buildMatchResult<TEnv>(allSegments: ResolvedSegment[], ctx: MatchContext<TEnv>, state: MatchPipelineState): MatchResult;
-export declare function collectMatchResult<TEnv>(pipeline: AsyncGenerator<ResolvedSegment>, ctx: MatchContext<TEnv>, state: MatchPipelineState): Promise<MatchResult>;

package/dist/types.backup/router/metrics.d.ts

@@ -1,6 +0,0 @@
-import type { MetricsStore } from "../server/context";
-export declare function createMetricsStore(debugPerformance: boolean, requestStart?: number): MetricsStore | undefined;
-export declare function appendMetric(metricsStore: MetricsStore | undefined, label: string, start: number, duration: number, depth?: number, desc?: string): void;
-export declare function buildMetricsTiming(method: string, pathname: string, metricsStore: MetricsStore | undefined): string | undefined;
-export declare function logMetrics(method: string, pathname: string, metricsStore: MetricsStore): void;
-export declare function generateServerTiming(metricsStore: MetricsStore): string;