@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/cache/read-through-swr.ts

@@ -13,10 +13,15 @@
 
 import type { CacheItemResult, CacheItemOptions } from "./types.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
 
-interface WaitUntilHost {
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
   waitUntil?: (fn: () => Promise<void>) => void;
-}
+} & CacheErrorReporter;
 
 export interface ReadThroughItemConfig<T> {
   /** Retrieve a cached item by key */
@@ -74,11 +79,20 @@ export async function readThroughItem<T>(
     host,
   } = config;
 
-  // Cache lookup
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
   try {
-    const cached = await getItem(key);
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
 
-    if (cached) {
+  if (cached) {
+    try {
       const data = await deserialize(cached.value);
 
       if (!cached.shouldRevalidate) {
@@ -97,16 +111,27 @@ export async function readThroughItem<T>(
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);
             }
-          } catch {
-            // Background revalidation failed silently
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
           }
         },
         true,
       );
       return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
     }
-  } catch {
-    // Cache lookup failed, fall through to fresh execution
   }
 
   // Cache miss
@@ -123,8 +148,13 @@ export async function readThroughItem<T>(
           await setItem(key, serialized, storeOptions);
           onCached?.();
         }
-      } catch {
-        // Cache write failed silently
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
       }
     },
     true,

package/src/cache/segment-codec.ts

@@ -16,10 +16,6 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
-// ============================================================================
-// Stream Utilities (internal)
-// ============================================================================
-
 /**
  * Convert a ReadableStream to a string.
  */
@@ -55,10 +51,6 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
   });
 }
 
-// ============================================================================
-// RSC Serialization Primitives (internal)
-// ============================================================================
-
 /**
  * RSC-serialize a value using React Server Components stream.
  * Used for serializing loaderData, layout, loading components etc.
@@ -90,10 +82,6 @@ export async function rscDeserialize<T>(
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Null-Preserving RSC Serialization (for caching)
-// ============================================================================
-
 /**
  * RSC-serialize any value including null.
  * Unlike rscSerialize(), this does NOT skip null — it serializes it through
@@ -122,10 +110,6 @@ export async function deserializeResult<T>(encoded: string): Promise<T> {
   return createFromReadableStream<T>(stream, { temporaryReferences });
 }
 
-// ============================================================================
-// Public API
-// ============================================================================
-
 /**
  * RSC-deserialize a single encoded component string back to a React element.
  * Used by the static handler runtime to revive pre-rendered components.

package/src/cache/types.ts

@@ -12,10 +12,6 @@
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
 
-// ============================================================================
-// Segment Cache Store (low-level storage interface)
-// ============================================================================
-
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -116,12 +112,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
    */
   clear?(): Promise<void>;
 
-  // ============================================================================
-  // Document Cache Methods (optional)
-  // ============================================================================
-  // These methods are for caching full HTTP responses (document-level caching).
-  // Stores that support response caching should implement these methods.
-
   /**
    * Get a cached Response by key.
    * Returns the response and whether it should be revalidated (SWR).
@@ -146,12 +136,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<void>;
 
-  // ============================================================================
-  // Function Cache Methods (optional, for "use cache" directive)
-  // ============================================================================
-  // These methods cache individual function/component return values.
-  // Stores that support "use cache" should implement these methods.
-
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -170,10 +154,6 @@ export interface SegmentCacheStore<TEnv = unknown> {
     options?: CacheItemOptions,
   ): Promise<void>;
 
-  // ============================================================================
-  // Tag-based Invalidation (optional)
-  // ============================================================================
-
   /**
    * Invalidate every cache entry (segment, response, item) tagged with any of
    * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
@@ -264,10 +244,6 @@ export interface CachedEntryData {
   taggedAt?: number;
 }
 
-// ============================================================================
-// Cache Configuration
-// ============================================================================
-
 /**
  * Default cache options applied to all cache() boundaries.
  * Individual cache() calls can override any of these values.
@@ -292,82 +268,8 @@ export interface CacheDefaults {
   swr?: number;
 }
 
-/**
- * Cache configuration for RSC handler
- */
-export interface CacheConfig {
-  /** Cache store implementation (includes defaults) */
-  store: SegmentCacheStore;
-  /** Enable/disable caching (default: true) */
-  enabled?: boolean;
-}
-
-/**
- * Cache configuration - can be static or a function receiving env
- */
-export type CacheConfigOrFactory<TEnv> =
-  | CacheConfig
-  | ((env: TEnv) => CacheConfig);
-
-// ============================================================================
-// Segment Cache Provider (request-level interface)
-// ============================================================================
-
 /**
  * Handle data for a single segment
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
-
-/**
- * Result from cache get() including segments and their handle data
- * Each entry can produce multiple segments (main + parallels)
- */
-export interface CachedEntryResult {
-  /** All segments for this entry (main segment + parallels) */
-  segments: ResolvedSegment[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
-}
-
-/**
- * Segment cache provider interface
- *
- * Used by router to check/store segment cache during matching.
- * Accessed via request context - if not present, caching is disabled.
- *
- * @internal Not currently implemented - CacheScope is used directly.
- * Reserved for future extensibility.
- */
-export interface SegmentCacheProvider {
-  /** Whether caching is enabled for this request */
-  readonly enabled: boolean;
-
-  /**
-   * Get cached segments and restore handles/loaders.
-   *
-   * Combines cache get with handle replay and loader data restoration.
-   * Returns tuple of [segments, segmentIds] if cache hit, null if miss or disabled.
-   *
-   * @param cacheKey - Cache key to look up
-   * @param params - Route params for cache key generation
-   * @param loaderPromises - Map to restore loader data into
-   * @returns Tuple of [segments, segmentIds] or null if miss
-   */
-  restore(
-    cacheKey: string,
-    params: Record<string, string>,
-    loaderPromises: Map<string, Promise<any>>,
-  ): Promise<[ResolvedSegment[], string[]] | null>;
-
-  /**
-   * Cache entry with automatic handle collection (non-blocking).
-   *
-   * Schedules caching via waitUntil - handles are collected after they settle.
-   * Validates segments have actual components before caching.
-   *
-   * @param cacheKey - The cache key to store under
-   * @param segments - All resolved segments for this entry
-   */
-  cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
-}

package/src/client.rsc.tsx

@@ -14,60 +14,43 @@
 export {
   Outlet,
   ParallelOutlet,
-  OutletProvider,
   useOutlet,
   useLoader,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
 
-// Re-export the server's createLoader for RSC context
-// This version includes the actual loader function
 export { createLoader } from "./route-definition.js";
 
-// Re-export Link component (can be used in server components)
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
 } from "./browser/react/Link.js";
 
-// Re-export ScrollRestoration (can be used in server components)
 export {
   ScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Re-export NavigationProvider (needed for setup)
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Re-export href function (can be used in server components)
 export { href } from "./href-client.js";
 
-// Mount context re-exports (useMount is client-only, but MountContext can be referenced)
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Note: useNavigation and useAction are NOT re-exported here
-// because they use client-side state and should only be used in client components
+// useNavigation and useAction are NOT re-exported here because they use client-side state
 
-// Handle API - for accumulating data across route segments
-// Works in both RSC and client contexts
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
-// Built-in handles
-// Meta handle works in RSC context
 export { Meta } from "./handles/meta.js";
-// MetaTags is a "use client" component that can be imported from RSC
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
-// Breadcrumbs handle works in RSC context
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - createLocationState works in RSC (just creates definition)
-// useLocationState is NOT exported here as it uses client hooks
 export {
   createLocationState,
   type LocationStateDefinition,
@@ -75,14 +58,13 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
-// Re-export useReverse - it's a "use client" hook
 export { useReverse } from "./browser/react/use-reverse.js";
 
-// Re-export useHandle - it's a "use client" hook
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
-// Re-export useLocationState - it's a "use client" hook
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -111,6 +111,11 @@ function useSlotSegment(
  * the parallel segment with that slot name instead of the default content.
  * This is used for parallel routes and intercepting routes.
  *
+ * For a named slot, `<Outlet name="@x" />` is equivalent to
+ * `<ParallelOutlet name="@x" />` — both run the same resolution + wrapping
+ * pipeline. Convention: use bare `<Outlet />` for default content and
+ * `<ParallelOutlet name="@x" />` for named slots.
+ *
  * @param name - Optional slot name for parallel/intercept content (must start with @)
  *
  * @example
@@ -163,6 +168,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  * is wrapped in Suspense with the loading component as fallback.
  * This enables streaming and navigation loading states for parallels.
  *
+ * Equivalent to `<Outlet name="@x" />` for a named slot; ParallelOutlet
+ * requires `name` and is named-slot-only, which reads clearer at the call site.
+ *
  * @param name - The slot name (must start with @, e.g., "@modal", "@sidebar")
  *
  * @example
@@ -186,10 +194,9 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
-// dependency between client.tsx and route-content-wrapper.tsx.
-// Imported at the top of this file for local use in Outlet/ParallelOutlet,
-// and re-exported here for backwards compatibility.
-export { OutletProvider };
+// dependency between client.tsx and route-content-wrapper.tsx. It is imported
+// at the top of this file for local use in Outlet/ParallelOutlet only; it is an
+// internal component and is intentionally not part of the public ./client API.
 
 /**
  * Hook to access outlet content programmatically
@@ -210,7 +217,6 @@ export function useOutlet(): ReactNode {
   return context?.content ?? null;
 }
 
-// Loader hooks - re-exported from dedicated file
 export {
   useLoader,
   useFetchLoader,
@@ -329,12 +335,6 @@ export class ErrorBoundary extends Component<
   }
 }
 
-// ============================================================================
-// Re-exports from browser/react for convenience
-// These are the most commonly used client-side navigation utilities
-// ============================================================================
-
-// Navigation hooks
 export { useNavigation } from "./browser/react/use-navigation.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
@@ -344,58 +344,55 @@ export type {
   RouterInstance,
   RouterNavigateOptions,
   ReadonlyURLSearchParams,
+  ActionState,
+  ActionLifecycleState,
 } from "./browser/types.js";
 
-// Action state tracking hook
 export {
   useAction,
   type ServerActionFunction,
 } from "./browser/react/use-action.js";
 
-// Segments state hook
 export {
   useSegments,
   type SegmentsState,
 } from "./browser/react/use-segments.js";
 
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./browser/react/NavigationProvider.js";
 
-// Link component
 export {
   Link,
   type LinkProps,
   type PrefetchStrategy,
   type StateOrGetter,
+  type LinkState,
 } from "./browser/react/Link.js";
 
-// Link status hook
 export {
   useLinkStatus,
   type LinkStatus,
 } from "./browser/react/use-link-status.js";
 
-// Scroll restoration
 export {
   ScrollRestoration,
   useScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
-// Built-in handles
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
-// Location state - type-safe navigation state
 export {
   createLocationState,
   useLocationState,
@@ -404,29 +401,19 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation. The path and response types
-// are ambient as `Rango.Path` / `Rango.PathResponse` (declared in
-// href-client.ts) — no import needed.
+// Ambient Rango.Path / Rango.PathResponse types (declared in href-client.ts)
 export { href, type PatternToPath } from "./href-client.js";
 
-// Problem Details (RFC 9457) error body type for consuming JSON response routes.
-// On a non-2xx response, `await res.json()` yields this shape; on success the
-// body is the bare value (no envelope). Discriminate on `res.ok` / status.
+// RFC 9457 error type for JSON response routes
 export type { ProblemDetails } from "./urls.js";
 
-// Mount context for include() scoped components
 export { useMount } from "./browser/react/use-mount.js";
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
-// Mount-aware reverse hook - resolves dot-prefixed names against an imported
-// generated routes map (from a urls() module's .gen.ts).
 export { useReverse } from "./browser/react/use-reverse.js";
 
-// Type-safe scoped reverse function for scopedReverse<typeof patterns>()
 export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
-// Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/context-var.ts

@@ -70,6 +70,18 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export function hasContextVars(variables: object): boolean {
+  return (
+    Object.keys(variables).length > 0 ||
+    Object.getOwnPropertySymbols(variables).length > 0
+  );
+}
+
 /**
  * Symbol used as a Set stored on the variables object to track
  * which keys hold non-cacheable values (from write-level { cache: false }).