@rangojs/router 0.4.3 → 0.5.1

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

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

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

@@ -0,0 +1,137 @@
+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;