@rangojs/router 0.4.0 → 0.4.1

package/dist/types.backup/router/lazy-includes.d.ts

@@ -1,26 +0,0 @@
-import type { UrlPatterns } from "../urls.js";
-import type { AllUseItems } from "../route-types.js";
-import type { RouteEntry } from "../types";
-export interface LazyEvalDeps<TEnv = any> {
-    routesEntries: RouteEntry<TEnv>[];
-    mergedRouteMap: Record<string, string>;
-    nextMountIndex: () => number;
-    getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
-    routerId?: string;
-}
-export declare function findLazyIncludes<TEnv = any>(items: AllUseItems[]): Array<{
-    prefix: string;
-    patterns: UrlPatterns<TEnv>;
-    context: {
-        urlPrefix: string;
-        namePrefix: string | undefined;
-        parent: unknown;
-        rootScoped?: boolean;
-    };
-}>;
-/**
- * Evaluate a lazy entry's patterns and populate its routes
- * This runs the lazy patterns handler and updates the entry in-place
- * Also detects nested lazy includes and registers them as new entries
- */
-export declare function evaluateLazyEntry<TEnv = any>(entry: RouteEntry<TEnv>, deps: LazyEvalDeps<TEnv>): void | Promise<void>;

package/dist/types.backup/router/loader-resolution.d.ts

@@ -1,63 +0,0 @@
-/**
- * Router Loader Resolution
- *
- * Loader execution, memoization, and error handling utilities.
- */
-import type { ReactNode } from "react";
-import type { EntryData } from "../server/context";
-import type { HandlerContext, LoaderDataResult, ErrorBoundaryHandler, ErrorInfo } from "../types";
-/**
- * Internal callback signature for loader error notifications.
- * This is a simplified callback for internal use in wrapLoaderWithErrorHandling.
- * The caller (wrapLoaderPromise in router.ts) bridges this to the full OnErrorCallback.
- */
-export type LoaderErrorCallback = (error: unknown, context: {
-    segmentId: string;
-    loaderName: string;
-    handledByBoundary: boolean;
-}) => void;
-/**
- * Wrap a loader promise with error handling for deferred client-side resolution.
- * Catches errors and converts them to LoaderDataResult objects that include
- * error info and pre-rendered fallback UI when an error boundary is available.
- *
- * @param onError - Optional callback invoked when loader errors occur.
- *   This has a simplified signature for internal use - the caller (typically
- *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
- *   OnErrorCallback with complete request context (request, url, env, etc.).
- */
-export declare function wrapLoaderWithErrorHandling<T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null, createErrorInfo: (error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]) => ErrorInfo, onError?: LoaderErrorCallback): Promise<LoaderDataResult<T>>;
-/**
- * Set up the use() method on handler context to access loaders and handles.
- *
- * For loaders: Lazily runs loaders, memoizes results per request.
- * For handles: Returns a push function bound to the current segment.
- *
- * Includes cycle detection: tracks dependency edges between loaders and
- * throws on circular dependencies to prevent deadlocks.
- */
-export declare function setupLoaderAccess<TEnv>(ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>): void;
-/**
- * Set up ctx.use() for pre-rendering (build-time).
- * Handles push to HandleStore; loaders throw with a clear error.
- */
-export declare function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void;
-/**
- * Set up ctx.use() for proactive caching (silent mode).
- * Handles are silently ignored (no push to HandleStore).
- * Loaders work normally but with fresh memoization and cycle detection.
- *
- * This prevents duplicate handle data (breadcrumbs, meta) from being
- * pushed to the response stream during background proactive caching.
- */
-export declare function setupLoaderAccessSilent<TEnv>(ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>): void;
-/**
- * Conditional execution based on revalidation
- * Evaluates revalidation logic lazily, then executes appropriate callback
- *
- * @param shouldRevalidate - Async function that determines if revalidation is needed
- * @param onRevalidate - Callback executed if revalidation returns true
- * @param onSkip - Callback executed if revalidation returns false
- * @returns Result from either onRevalidate or onSkip
- */
-export declare function revalidate<T>(shouldRevalidate: () => Promise<boolean>, onRevalidate: () => Promise<T>, onSkip: () => T): Promise<T>;

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

@@ -1,41 +0,0 @@
-export interface RevalidationTraceEntry {
-    segmentId: string;
-    segmentType: string;
-    belongsToRoute: boolean;
-    source: "segment-resolution" | "cache-hit" | "loader" | "parallel" | "orphan-layout" | "route-handler" | "layout-handler" | "intercept-loader";
-    defaultShouldRevalidate: boolean;
-    finalShouldRevalidate: boolean;
-    reason: string;
-    customRevalidators?: number;
-}
-export interface RevalidationTraceMeta {
-    method: string;
-    prevUrl: string;
-    nextUrl: string;
-    routeKey: string;
-    isAction: boolean;
-    stale?: boolean;
-}
-export interface RevalidationTrace {
-    meta: RevalidationTraceMeta;
-    entries: RevalidationTraceEntry[];
-}
-interface RouterLogOptions {
-    request: Request;
-    transaction: string;
-}
-interface LogDetails {
-    [key: string]: unknown;
-}
-export declare function getOrCreateRequestId(request: Request): string;
-export declare function runWithRouterLogContext<T>(options: RouterLogOptions, fn: () => T): T;
-export declare function withRouterLogScope<T>(label: string, fn: () => Promise<T>): Promise<T>;
-export declare function withRouterLogScope<T>(label: string, fn: () => T): T;
-export declare function isRouterDebugEnabled(): boolean;
-export declare function debugLog(scope: string, message: string, details?: LogDetails): void;
-export declare function debugWarn(scope: string, message: string, details?: LogDetails): void;
-export declare function isTraceActive(): boolean;
-export declare function startRevalidationTrace(meta: RevalidationTraceMeta): void;
-export declare function pushRevalidationTraceEntry(entry: RevalidationTraceEntry): void;
-export declare function flushRevalidationTrace(): RevalidationTrace | null;
-export {};

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

@@ -1,8 +0,0 @@
-import { type EntryData, type MetricsStore } from "../server/context";
-import type { RouteEntry } from "../types";
-/**
- * Clear the module-level manifest cache.
- * Called on HMR to ensure stale handler references are discarded.
- */
-export declare function clearManifestCache(): void;
-export declare function loadManifest(entry: RouteEntry<any>, routeKey: string, path: string, metricsStore?: MetricsStore, isSSR?: boolean): Promise<EntryData>;

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

@@ -1,19 +0,0 @@
-import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
-import type { ReactNode } from "react";
-import type { MatchContext } from "./match-context.js";
-import type { MatchApiDeps, ActionContext } from "./types.js";
-/**
- * Create match context for full requests (document/SSR).
- */
-export declare function createMatchContextForFull<TEnv>(request: Request, env: TEnv, deps: MatchApiDeps<TEnv>, findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"]): Promise<MatchContext<TEnv> | {
-    type: "redirect";
-    redirectUrl: string;
-}>;
-/**
- * Create match context for partial requests (navigation/actions).
- */
-export declare function createMatchContextForPartial<TEnv>(request: Request, env: TEnv, deps: MatchApiDeps<TEnv>, findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"], actionContext?: ActionContext): Promise<MatchContext<TEnv> | null>;
-/**
- * Match an error to the nearest error boundary and return error segments.
- */
-export declare function matchError<TEnv>(request: Request, _context: TEnv, error: unknown, deps: MatchApiDeps<TEnv>, defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined, segmentType?: ErrorInfo["segmentType"]): Promise<MatchResult | null>;

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

@@ -1,184 +0,0 @@
-/**
- * Match Context for Router Pipeline
- *
- * Encapsulates all state needed by the match pipeline middleware.
- * Created once at the start of match()/matchPartial() and passed through the pipeline.
- *
- * DATA FLOW ARCHITECTURE
- * ======================
- *
- * The router uses two complementary data structures:
- *
- *   MatchContext (ctx)        - Immutable request state
- *   MatchPipelineState (state) - Mutable pipeline state
- *
- *
- *   Request
- *      |
- *      v
- *   +-------------------+
- *   | Create Context    |  ctx = immutable snapshot of request
- *   +-------------------+
- *      |
- *      v
- *   +-------------------+
- *   | Create State      |  state = mutable accumulator
- *   +-------------------+
- *      |
- *      +---> [Pipeline Middleware]
- *      |           |
- *      |     ctx: read-only
- *      |     state: read/write
- *      |           |
- *      +<----------+
- *      |
- *      v
- *   +-------------------+
- *   | Build Result      |  Merge ctx + state into MatchResult
- *   +-------------------+
- *
- *
- * MATCHCONTEXT FIELDS
- * ===================
- *
- * Request Info:
- *   - request, url, pathname: The incoming HTTP request
- *
- * Environment:
- *   - env: Server environment (Cloudflare bindings, etc.)
- *
- * Client State (from RSC request headers):
- *   - clientSegmentIds: Segments the client currently has
- *   - clientSegmentSet: Set version for O(1) lookup
- *   - stale: Whether client considers its cache stale
- *
- * Navigation State:
- *   - prevUrl, prevParams, prevMatch: Previous navigation for comparison
- *
- * Current Match:
- *   - matched: Route match result (params, route key)
- *   - manifestEntry: Resolved manifest data
- *   - entries: All route entries (layouts, loaders, etc.)
- *   - routeKey, localRouteName: Route identifiers
- *
- * Handler Context:
- *   - handlerContext: Context passed to loaders
- *   - loaderPromises: Memoized loader promises
- *
- * Intercepts:
- *   - interceptResult: Detected intercept (if soft navigation)
- *   - interceptSelectorContext: Context for intercept matching
- *
- * Cache:
- *   - cacheScope: Cache configuration and methods
- *   - isIntercept: Whether this is an intercept request
- *
- * Flags:
- *   - isAction: POST/mutation request
- *   - isFullMatch: Document request vs navigation
- *
- *
- * MATCHPIPELINESTATE FIELDS
- * =========================
- *
- * State flags (set by middleware, read by others):
- *   - cacheHit: Cache lookup succeeded
- *   - shouldRevalidate: SWR revalidation needed
- *
- * Segment accumulation:
- *   - segments: Resolved segments from pipeline
- *   - matchedIds: All segment IDs in match order
- *   - cachedSegments: Segments from cache (if hit)
- *
- * Intercept data:
- *   - interceptSegments: Segments for modal slots
- *   - slots: Named slot data for client
- *
- *
- * IMMUTABILITY CONTRACT
- * =====================
- *
- * MatchContext is treated as immutable after creation.
- * Middleware should NEVER modify ctx properties.
- *
- * MatchPipelineState is explicitly mutable.
- * Middleware communicate by setting state flags.
- *
- * This separation ensures:
- *   - Request data is consistent across all middleware
- *   - Pipeline state changes are explicit and trackable
- *   - No hidden side effects in request handling
- */
-import type { CacheScope } from "../cache/cache-scope.js";
-import type { EntryData, InterceptSelectorContext, MetricsStore } from "../server/context.js";
-import type { HandlerContext, ResolvedSegment } from "../types.js";
-import type { RouteMatchResult } from "./pattern-matching.js";
-import type { InterceptResult } from "./router-context.js";
-/**
- * Action context passed to matchPartial
- */
-export interface ActionContext {
-    actionId?: string;
-    actionUrl?: URL;
-    actionResult?: any;
-    formData?: FormData;
-}
-/**
- * Match context containing all state for the match pipeline
- */
-export interface MatchContext<TEnv = any> {
-    request: Request;
-    url: URL;
-    pathname: string;
-    env: TEnv;
-    clientSegmentIds: string[];
-    clientSegmentSet: Set<string>;
-    stale: boolean;
-    prevUrl: URL;
-    prevParams: Record<string, string>;
-    prevMatch: RouteMatchResult | null;
-    matched: RouteMatchResult;
-    manifestEntry: EntryData;
-    entries: EntryData[];
-    routeKey: string;
-    localRouteName: string;
-    handlerContext: HandlerContext<any, TEnv>;
-    loaderPromises: Map<string, Promise<any>>;
-    routeMap: Record<string, string>;
-    metricsStore: MetricsStore | undefined;
-    Store: any;
-    interceptContextMatch: RouteMatchResult | null;
-    interceptSelectorContext: InterceptSelectorContext;
-    isSameRouteNavigation: boolean;
-    interceptResult: InterceptResult | null;
-    cacheScope: CacheScope | null;
-    isIntercept: boolean;
-    actionContext?: ActionContext;
-    isAction: boolean;
-    routeMiddleware: Array<{
-        handler: any;
-        params: Record<string, string>;
-    }>;
-    isFullMatch: boolean;
-}
-/**
- * Mutable state that flows through the pipeline
- */
-export interface MatchPipelineState {
-    cacheHit: boolean;
-    cachedSegments?: ResolvedSegment[];
-    cachedMatchedIds?: string[];
-    shouldRevalidate?: boolean;
-    cacheSource?: "runtime" | "prerender";
-    segments: ResolvedSegment[];
-    matchedIds: string[];
-    interceptSegments: ResolvedSegment[];
-    slots: Record<string, {
-        active: boolean;
-        segments: ResolvedSegment[];
-    }>;
-}
-/**
- * Create initial pipeline state
- */
-export declare function createPipelineState(): MatchPipelineState;

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

@@ -1,49 +0,0 @@
-import type { ReactNode } from "react";
-import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
-import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
-import type { MatchApiDeps } from "./types.js";
-import type { RouterContext } from "./router-context.js";
-import { type ActionContext } from "./match-context.js";
-import type { ErrorBoundaryHandler } from "../types";
-import type { MiddlewareFn } from "./middleware.js";
-import { type TelemetrySink } from "./telemetry.js";
-export interface MatchHandlerDeps<TEnv = any> {
-    buildRouterContext: () => RouterContext<TEnv>;
-    callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
-    matchApiDeps: MatchApiDeps<TEnv>;
-    defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
-    findMatch: (pathname: string, ms?: any) => any;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean) => {
-        intercept: InterceptEntry;
-        entry: EntryData;
-    } | null;
-    telemetry?: TelemetrySink;
-    /**
-     * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
-     * match/matchPartial stash a coarse route-level cache signal on the request
-     * context for the response-finalization path to emit. Default off.
-     */
-    cacheSignalEnabled?: boolean;
-}
-export interface MatchHandlers<TEnv = any> {
-    match: (request: Request, env: TEnv) => Promise<MatchResult>;
-    matchPartial: (request: Request, context: TEnv, actionContext?: ActionContext) => Promise<MatchResult | null>;
-    matchError: (request: Request, _context: TEnv, error: unknown, segmentType?: ErrorInfo["segmentType"]) => Promise<MatchResult | null>;
-    previewMatch: (request: Request, _context: TEnv) => Promise<{
-        routeMiddleware?: Array<{
-            handler: MiddlewareFn;
-            params: Record<string, string>;
-        }>;
-        responseType?: string;
-        handler?: Function;
-        params?: Record<string, string>;
-        negotiated?: boolean;
-        manifestEntry?: EntryData;
-    } | null>;
-}
-/**
- * Create match handler functions bound to router closure state.
- * These are the main request-handling entry points for SSR, navigation,
- * error recovery, and preview matching.
- */
-export declare function createMatchHandlers<TEnv = any>(deps: MatchHandlerDeps<TEnv>): MatchHandlers<TEnv>;

package/dist/types.backup/router/match-middleware/background-revalidation.d.ts

@@ -1,113 +0,0 @@
-/**
- * Background Revalidation Middleware
- *
- * Implements SWR (stale-while-revalidate) pattern.
- * Triggers background refresh when cached data is stale.
- *
- * FLOW DIAGRAM
- * ============
- *
- *   source (from cache-store)
- *         |
- *         v
- *   +---------------------------+
- *   | yield* source            |  Pure pass-through
- *   | (no modifications)       |
- *   +---------------------------+
- *         |
- *         v
- *   +---------------------+
- *   | Should revalidate?  |
- *   | - shouldRevalidate  |──no───> return
- *   | - cacheHit          |
- *   | - cacheScope        |
- *   +---------------------+
- *         | yes
- *         v
- *   +---------------------------+
- *   | requestCtx.waitUntil()   |  Non-blocking background task
- *   +---------------------------+
- *         |
- *         v (async, doesn't block response)
- *   +---------------------------+
- *   | Create fresh context     |  Fresh handleStore, handlerContext,
- *   | (full isolation)         |  and loaderPromises map
- *   +---------------------------+
- *         |
- *         v
- *   +---------------------------+
- *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
- *   | + resolveIntercepts()   |  Ensures complete components
- *   +---------------------------+
- *         |
- *         v
- *   +---------------------------+
- *   | cacheScope.cacheRoute()  |  Update cache with fresh data
- *   +---------------------------+
- *
- *
- * SWR PATTERN
- * ===========
- *
- * Stale-While-Revalidate provides fast responses with eventual consistency:
- *
- *   Timeline:
- *   ---------
- *   T0: Request arrives
- *   T1: Cache lookup finds stale entry
- *   T2: Return stale data immediately (fast!)
- *   T3: Response sent to client
- *   T4: waitUntil() triggers background revalidation
- *   T5: Fresh data resolved
- *   T6: Cache updated with fresh data
- *   T7: Next request gets fresh data from cache
- *
- * Benefits:
- *   - Fast initial response (cached data)
- *   - Eventually consistent (background refresh)
- *   - No blocking on revalidation
- *
- *
- * WHEN IS CACHE STALE?
- * ====================
- *
- * The cache-lookup middleware sets state.shouldRevalidate based on:
- *   - TTL (time-to-live) expiration
- *   - Cache entry metadata
- *   - Configured staleness rules
- *
- * This middleware only acts on the flag, it doesn't determine staleness.
- *
- *
- * ISOLATION FROM RESPONSE
- * =======================
- *
- * Background revalidation creates fully isolated context:
- *   - Fresh handleStore (prevents polluting the response stream)
- *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
- *     loader results from the foreground pass)
- *   - handleStore is saved/restored in try/finally
- *
- * This matches the proactive caching pattern in cache-store.ts.
- *
- *
- * FRESH RESOLUTION (NO REVALIDATION)
- * ===================================
- *
- * Both full and partial requests use resolveAllSegments() (without
- * revalidation logic) to ensure all segments have complete components.
- * Using revalidation-aware resolution would produce null components
- * for skipped segments, which would corrupt the cache entry.
- */
-import type { ResolvedSegment } from "../../types.js";
-import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import type { GeneratorMiddleware } from "./cache-lookup.js";
-/**
- * Creates background revalidation middleware
- *
- * If cache was stale (state.shouldRevalidate === true):
- * - Triggers background resolution via waitUntil
- * - Observes segments but doesn't modify them
- * - Updates cache with fresh segments after revalidation completes
- */
-export declare function withBackgroundRevalidation<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;

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

@@ -1,113 +0,0 @@
-/**
- * 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 { MatchContext, MatchPipelineState } from "../match-context.js";
-/**
- * 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>;