@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,57 +0,0 @@
-/**
- * Router Revalidation Logic
- *
- * Evaluates whether segments should revalidate based on params, actions, and custom functions.
- */
-import type { ResolvedSegment, HandlerContext } from "../types";
-import type { ActionContext } from "./types";
-import type { RevalidationTraceEntry } from "./logging.js";
-/**
- * Options for revalidation evaluation
- */
-interface EvaluateRevalidationOptions<TEnv> {
-    /** Current segment to evaluate */
-    segment: ResolvedSegment;
-    /** Previous route params (from route match, not segment) */
-    prevParams: Record<string, string>;
-    /** Lazy function to get previous segment if needed */
-    getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
-    /** Current request */
-    request: Request;
-    /** Previous URL */
-    prevUrl: URL;
-    /** Next URL */
-    nextUrl: URL;
-    /** Custom revalidation functions */
-    revalidations: Array<{
-        name: string;
-        fn: any;
-    }>;
-    /** Current route key */
-    routeKey: string;
-    /** Handler context */
-    context: HandlerContext<any, TEnv>;
-    /** Action context if triggered by action */
-    actionContext?: ActionContext;
-    /** If true, this is a stale cache revalidation request */
-    stale?: boolean;
-    /** Trace source hint for the revalidation trace */
-    traceSource?: RevalidationTraceEntry["source"];
-    /**
-     * Override the segment-type-derived default. When set, the value is used as
-     * the seed `defaultShouldRevalidate` passed to user revalidate fns and the
-     * reason flows into the trace. Callers use this when client-knowledge
-     * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
-     * instead of the params/method-based heuristic.
-     */
-    defaultOverride?: {
-        value: boolean;
-        reason: string;
-    };
-}
-/**
- * Evaluate if a segment should revalidate using soft/hard decision pattern
- * Optimized to use prevParams directly and avoid building previous segments
- */
-export declare function evaluateRevalidation<TEnv>(options: EvaluateRevalidationOptions<TEnv>): Promise<boolean>;
-export {};

package/dist/types.backup/router/route-snapshot.d.ts

@@ -1,112 +0,0 @@
-/**
- * Route Snapshot
- *
- * Pure data type representing the fully-resolved state of a single route match.
- * Consolidates the duplicated findMatch + loadManifest + collectRouteMiddleware +
- * cacheScope derivation that previously lived separately in preview-match.ts
- * and match-api.ts.
- *
- * resolveRoute() is the factory: given a pathname and dependencies, it returns
- * a RouteSnapshot (or redirect/null). Consumers (createMatchContextForFull,
- * createMatchContextForPartial, previewMatch) read snapshot fields instead of
- * re-deriving them.
- */
-import type { CacheScope } from "../cache/cache-scope.js";
-import type { EntryData, MetricsStore } from "../server/context.js";
-import type { CollectedMiddleware } from "./middleware-types.js";
-import type { RouteMatchResult } from "./pattern-matching.js";
-/**
- * Immutable snapshot of a resolved route match.
- *
- * Contains everything derivable from (pathname, findMatch, loadManifest)
- * without request context, navigation state, or intercept logic.
- */
-export interface RouteSnapshot<TEnv = any> {
-    /** Raw match result from the trie/pattern matcher */
-    matched: RouteMatchResult<TEnv>;
-    /** Resolved manifest entry (with loaded handler, loader, etc.) */
-    manifestEntry: EntryData;
-    /** All entries in the route chain (from traverseBack) */
-    entries: EntryData[];
-    /** Canonical route key (e.g. "blog.detail") */
-    routeKey: string;
-    /** Last segment of a dotted route key (e.g. "detail" from "blog.detail") */
-    localRouteName: string;
-    /** Extracted route params */
-    params: Record<string, string>;
-    /** Collected route-level middleware from the entry tree */
-    routeMiddleware: CollectedMiddleware[];
-    /** Merged cache scope from the entry chain */
-    cacheScope: CacheScope | null;
-    /** Whether the matched route is a passthrough route */
-    isPassthrough: boolean;
-    /** Response type for non-RSC routes (e.g. "application/json") */
-    responseType?: string;
-    /**
-     * The isSSR flag the manifest was resolved with. Recorded so consumers can
-     * decide whether the snapshot is reusable: a snapshot resolved with isSSR
-     * differs (loading({ ssr: false }) entries) and is cached under a different
-     * manifest partition, so the full (document) path only reuses an isSSR:true
-     * snapshot and the partial path only reuses a non-isSSR one. Undefined on
-     * inline snapshots (redirect / not-found) that are never reused.
-     */
-    isSSR?: boolean;
-}
-export type ResolveRouteResult<TEnv = any> = {
-    type: "match";
-    snapshot: RouteSnapshot<TEnv>;
-} | {
-    type: "redirect";
-    redirectTo: string;
-} | null;
-export interface ResolveRouteDeps<TEnv = any> {
-    findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
-    metricsStore?: MetricsStore;
-    isSSR?: boolean;
-    /**
-     * When true, skip entries array and cacheScope chain construction.
-     * Used by previewMatch which only needs matched, manifestEntry,
-     * routeMiddleware, and responseType — avoids an extra traverseBack
-     * allocation and cacheScope composition on the hot classification path.
-     */
-    lite?: boolean;
-    /**
-     * When true, skip pushing the "route-matching" metric internally.
-     * Used by createMatchContextForPartial on the fresh path (no snapshot
-     * reuse) so it can measure current + prev + intercept-source findMatch
-     * calls under one combined "route-matching" metric. On the reuse path,
-     * the partial path emits "route-matching:nav" for the prev +
-     * intercept-source lookups only (current-route resolution was done
-     * during classification without metrics).
-     */
-    skipRouteMatchMetric?: boolean;
-}
-/**
- * Resolve a pathname into a RouteSnapshot.
- *
- * This is the single source of truth for route derivation. It performs:
- * 1. findMatch(pathname)
- * 2. Redirect check
- * 3. loadManifest
- * 4. Passthrough detection
- * 5. collectRouteMiddleware
- * 6. Cache scope chain
- * 7. responseType + localRouteName extraction
- *
- * Metrics timing is preserved identically to the previous inline code.
- */
-export declare function resolveRoute<TEnv = any>(pathname: string, deps: ResolveRouteDeps<TEnv>): Promise<ResolveRouteResult<TEnv>>;
-/**
- * Fill in the entries and cacheScope fields on a lite snapshot.
- *
- * When classifyRequest produces a lite snapshot (entries=[], cacheScope=null),
- * this function computes the missing fields from manifestEntry without
- * re-running findMatch, loadManifest, or collectRouteMiddleware.
- *
- * If the snapshot already has entries, returns it as-is.
- */
-export declare function ensureFullRouteSnapshot<TEnv = any>(snapshot: RouteSnapshot<TEnv>): RouteSnapshot<TEnv>;
-/**
- * Test helper: create a RouteSnapshot with sensible defaults and overrides.
- */
-export declare function createRouteSnapshot<TEnv = any>(overrides?: Partial<RouteSnapshot<TEnv>>): RouteSnapshot<TEnv>;

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

@@ -1,137 +0,0 @@
-import type { CacheScope } from "../cache/cache-scope.js";
-import type { EntryData, InterceptEntry, InterceptSelectorContext, MetricsStore } from "../server/context.js";
-import type { HandlerContext, ResolvedSegment, ShouldRevalidateFn } from "../types.js";
-import type { RouteMatchResult } from "./pattern-matching.js";
-import type { TelemetrySink } from "./telemetry.js";
-import type { ResolveSegmentOptions } from "./segment-resolution.js";
-/**
- * Revalidation context passed to segment resolution
- */
-export interface RevalidationContext {
-    clientSegmentIds: Set<string>;
-    prevParams: Record<string, string>;
-    request: Request;
-    prevUrl: URL;
-    nextUrl: URL;
-    routeKey: string;
-    actionContext?: {
-        actionId?: string;
-        actionUrl?: URL;
-        actionResult?: any;
-        formData?: FormData;
-    };
-    stale: boolean;
-}
-/**
- * Result from intercept lookup
- */
-export interface InterceptResult {
-    intercept: InterceptEntry;
-    entry: EntryData;
-}
-/**
- * Router context available via AsyncLocalStorage
- *
- * Contains closure functions from createRouter() that middleware needs access to.
- * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
- */
-export interface RouterContext<TEnv = any> {
-    findMatch: (pathname: string) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
-    loadManifest: (entry: any, routeKey: string, pathname: string, metricsStore?: MetricsStore, isSSR?: boolean) => Promise<EntryData>;
-    traverseBack: (entry: EntryData) => Generator<EntryData>;
-    createHandlerContext: (params: Record<string, string>, request: Request, searchParams: URLSearchParams, pathname: string, url: URL, bindings?: any, routeMap?: Record<string, string>, routeName?: string, responseType?: string, isPassthroughRoute?: boolean) => HandlerContext<any, TEnv>;
-    setupLoaderAccess: (ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>) => void;
-    setupLoaderAccessSilent: (ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>) => void;
-    getContext: () => {
-        getOrCreateStore: (key: string) => any;
-        runWithStore: <T>(store: any, namespace: string, parent: any, fn: () => T) => T;
-    };
-    getMetricsStore: () => MetricsStore | undefined;
-    createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean) => InterceptResult | null;
-    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: any | undefined, interceptResult: InterceptResult | null, localRouteName: string, pathname: string, stale?: boolean) => Promise<{
-        segments: ResolvedSegment[];
-        matchedIds: string[];
-    }>;
-    resolveAllSegmentsWithRevalidationGenerator?: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, loaderPromises: Map<string, Promise<any>>, actionContext?: any) => AsyncGenerator<ResolvedSegment | {
-        __type: "id";
-        id: string;
-    }>;
-    resolveInterceptEntry: (intercept: InterceptEntry, entry: EntryData, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, belongsToRoute: boolean, revalidationContext?: RevalidationContext, options?: {
-        skipMiddleware?: boolean;
-    }) => Promise<ResolvedSegment[]>;
-    collectWithMarkers?: <T>(gen: AsyncGenerator<T | {
-        __type: "id";
-        id: string;
-    }>) => Promise<{
-        items: T[];
-        matchedIds: string[];
-    }>;
-    evaluateRevalidation: (params: {
-        segment: ResolvedSegment;
-        prevParams: Record<string, string>;
-        getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
-        request: Request;
-        prevUrl: URL;
-        nextUrl: URL;
-        revalidations: Array<{
-            name: string;
-            fn: any;
-        }>;
-        routeKey: string;
-        context: HandlerContext<any, TEnv>;
-        actionContext?: any;
-        stale?: boolean;
-        traceSource?: "segment-resolution" | "cache-hit" | "loader" | "parallel" | "orphan-layout" | "route-handler" | "layout-handler" | "intercept-loader";
-    }) => Promise<boolean>;
-    getRequestContext: () => {
-        waitUntil: (fn: () => Promise<void>) => void;
-        _handleStore?: any;
-    } | undefined;
-    resolveAllSegments: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, options?: ResolveSegmentOptions) => Promise<ResolvedSegment[]>;
-    resolveAllSegmentsGenerator?: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>) => AsyncGenerator<ResolvedSegment | {
-        __type: "id";
-        id: string;
-    }>;
-    collectSegmentsFromGenerator?: <T>(gen: AsyncGenerator<T | {
-        __type: "id";
-        id: string;
-    }>) => Promise<T[]>;
-    createHandleStore: () => any;
-    resolveLoadersOnly?: (entries: EntryData[], handlerContext: HandlerContext<any, TEnv>) => Promise<ResolvedSegment[]>;
-    resolveLoadersOnlyWithRevalidation?: (entries: EntryData[], handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, actionContext?: any, stale?: boolean) => Promise<{
-        segments: ResolvedSegment[];
-        matchedIds: string[];
-    }>;
-    buildEntryRevalidateMap?: (entries: EntryData[]) => Map<string, {
-        revalidate: ShouldRevalidateFn[];
-    }>;
-    telemetry?: TelemetrySink;
-    requestId?: string;
-    resolveInterceptLoadersOnly?: (intercept: InterceptEntry, entry: EntryData, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, belongsToRoute: boolean, revalidationContext: {
-        clientSegmentIds: Set<string>;
-        prevParams: Record<string, string>;
-        request: Request;
-        prevUrl: URL;
-        nextUrl: URL;
-        routeKey: string;
-        actionContext?: any;
-        stale?: boolean;
-    }) => Promise<{
-        loaderDataPromise: Promise<any[]> | any[];
-        loaderIds: string[];
-    } | null>;
-}
-/**
- * Get router dependencies from AsyncLocalStorage context
- *
- * @throws Error if called outside of router context (runWithRouterContext)
- */
-export declare function getRouterContext<TEnv = any>(): RouterContext<TEnv>;
-/**
- * Run a function with router dependencies available via getRouterContext()
- *
- * All async code within fn() can call getRouterContext() to access router closures.
- * This works across async boundaries thanks to AsyncLocalStorage.
- */
-export declare function runWithRouterContext<T, TEnv = any>(deps: RouterContext<TEnv>, fn: () => T): T;