@rangojs/router 0.0.0-experimental.77 → 0.0.0-experimental.77ed8945

package/src/cache/cf/index.ts

@@ -13,6 +13,8 @@
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
   type KVNamespace,
 } from "./cf-cache-store.js";
 
@@ -20,6 +22,7 @@ export {
 export {
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
 } from "./cf-cache-store.js";
 
 // Internal exports (re-exported for backwards compatibility, marked @internal in source)

package/src/cache/handle-snapshot.ts

@@ -9,6 +9,109 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
+import { serializeResult, deserializeResult } from "./segment-codec.js";
+
+/**
+ * Bound on the background cache-write encode of handle data. A pushed handle
+ * value can be a Promise (request-context push-a-promise) or a Promise<ReactNode>
+ * (Breadcrumbs content), which the Flight encoder awaits while draining. The
+ * encode runs in waitUntil/runBackground, so a never-resolving handle value
+ * would otherwise pin a background slot indefinitely; on timeout the entry's
+ * handles coalesce to empty rather than hanging or poisoning the whole write.
+ */
+const HANDLE_ENCODE_TIMEOUT_MS = 5000;
+
+type HandleRecord = Record<string, SegmentHandleData>;
+
+// captureHandles builds a per-segment map keyed by every cached segment id, even
+// segments that pushed nothing (their entry is an empty object). "No handle data"
+// means no segment has any handle, in which case we skip the Flight encode and
+// store an empty string — so the common handle-free route pays neither an encode
+// on write nor a decode on every cache hit.
+function hasHandleData(handles: HandleRecord): boolean {
+  for (const segId in handles) {
+    for (const _ in handles[segId]) return true;
+  }
+  return false;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout), ms);
+  });
+  return Promise.race([
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        return v;
+      },
+      (e) => {
+        clearTimeout(timer);
+        throw e;
+      },
+    ),
+    timeout,
+  ]);
+}
+
+/**
+ * Encode a captured handle map to a string for cache storage.
+ *
+ * Handle values can be Promises or React elements (e.g. Breadcrumbs `content`).
+ * JSON.stringify destroys those (Promise -> {}, ReactNode non-representable), so
+ * persisting the raw map silently corrupts non-scalar handle values on stores
+ * that serialize to JSON (the Cloudflare cache). Routing the map through the same
+ * RSC-Flight codec the segments/value already use awaits Promises and serializes
+ * React elements, so the stored field is a lossless, JSON-safe string. The
+ * in-memory store keeps the same string by reference, so both backends replay
+ * identical decoded values.
+ */
+export async function encodeHandles(handles: HandleRecord): Promise<string> {
+  // No handle was pushed anywhere — store an empty marker (decoded as "skip").
+  if (!hasHandleData(handles)) return "";
+  return encodeHandleValue(handles);
+}
+
+/**
+ * Decode a stored handle string back to a handle map. Returns null on any
+ * decode failure (e.g. a cross-version entry read under a pinned static
+ * version), so the caller can skip handle restore without discarding the
+ * otherwise-valid cached segments alongside it.
+ */
+export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
+  return decodeHandleValue<HandleRecord>(encoded);
+}
+
+/**
+ * Encode an arbitrary handle-data value to a Flight string. Used directly by the
+ * prerender/static pipeline, whose static path holds a single segment's
+ * `SegmentHandleData` (not a segId-keyed map). Bounded by the same timeout as
+ * encodeHandles; failure/timeout coalesces to "". The caller owns the empty
+ * check (an empty value still encodes to a non-empty Flight string, so skip the
+ * call when there is nothing to store).
+ */
+export async function encodeHandleValue(value: unknown): Promise<string> {
+  const encoded = await withTimeout(
+    serializeResult(value),
+    HANDLE_ENCODE_TIMEOUT_MS,
+    null,
+  );
+  return encoded ?? "";
+}
+
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
+  try {
+    return await deserializeResult<T>(encoded);
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Capture handle data for a set of segments from the handle store.

package/src/cache/index.ts

@@ -29,9 +29,12 @@ export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
   type KVNamespace,
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
 } from "./cf/index.js";
 
 // Cache scope

package/src/cache/memory-segment-store.ts

@@ -12,7 +12,6 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
-  SegmentHandleData,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 import {
@@ -56,7 +55,9 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data (see handle-snapshot.ts encodeHandles). Stored as
+   *  the encoded string by reference, identical to the JSON-serializing stores. */
+  handles?: string;
   expiresAt: number;
   staleAt: number;
 }

package/src/cache/types.ts

@@ -175,8 +175,10 @@ export interface SegmentCacheStore<TEnv = unknown> {
 export interface CacheItemResult {
   /** RSC-serialized return value */
   value: string;
-  /** Handle data captured during execution (breadcrumbs, metadata, etc.) */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data captured during execution (breadcrumbs, metadata,
+   *  etc.). Encoded via the Flight codec so Promise/ReactNode handle values
+   *  survive JSON-serializing stores — see handle-snapshot.ts encodeHandles. */
+  handles?: string;
   /** Whether the entry is stale and should be revalidated */
   shouldRevalidate: boolean;
 }
@@ -185,8 +187,8 @@ export interface CacheItemResult {
  * Options for setItem() for function-level caching ("use cache").
  */
 export interface CacheItemOptions {
-  /** Handle data to store alongside the value */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data to store alongside the value (see encodeHandles). */
+  handles?: string;
   /** Time-to-live in seconds */
   ttl?: number;
   /** Stale-while-revalidate window in seconds */
@@ -227,8 +229,10 @@ export interface SerializedSegmentData {
 export interface CachedEntryData {
   /** Serialized segments for this entry */
   segments: SerializedSegmentData[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data keyed by segment ID. Encoded via the Flight codec
+   *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
+   *  round-trip through JSON-serializing stores instead of being flattened. */
+  handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
 }

package/src/client.rsc.tsx

@@ -78,6 +78,9 @@ export {
 // 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";
 

package/src/client.tsx

@@ -21,6 +21,83 @@ import {
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+
+/**
+ * Render the content for a named parallel/intercept slot segment.
+ *
+ * Shared by Outlet (with `name` prop) and ParallelOutlet — both resolve a
+ * segment from context.parallel by slot name and then render it through the
+ * same layout/loader/mountPath wrapping pipeline.
+ */
+function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
+  if (!segment) return null;
+
+  const content: ReactNode =
+    segment.loading || segment.component instanceof Promise ? (
+      <RouteContentWrapper
+        content={getMemoizedContentPromise(segment.component)}
+        fallback={segment.loading}
+        segmentId={segment.id}
+      />
+    ) : (
+      (segment.component ?? null)
+    );
+
+  const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
+  const loaderWrapped = hasOwnLoaders ? (
+    <LoaderBoundary
+      loaderDataPromise={segment.loaderDataPromise!}
+      loaderIds={segment.loaderIds!}
+      fallback={segment.loading}
+      outletKey={segment.id + "-loader"}
+      outletContent={null}
+      segment={segment}
+    >
+      {content}
+    </LoaderBoundary>
+  ) : null;
+
+  let result: ReactNode;
+  if (segment.layout) {
+    // Layout renders immediately; if loaders exist, the LoaderBoundary becomes
+    // the outlet content so layout's <Outlet /> suspends until loaders resolve.
+    result = (
+      <OutletProvider
+        content={hasOwnLoaders ? loaderWrapped : content}
+        segment={segment}
+      >
+        {segment.layout}
+      </OutletProvider>
+    );
+  } else if (hasOwnLoaders) {
+    // No layout but has loaders — wrap content with LoaderBoundary for useLoader context.
+    // Common for intercept routes that use useLoader without a custom layout.
+    result = loaderWrapped;
+  } else {
+    result = content;
+  }
+
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
+}
+
+function useSlotSegment(
+  context: OutletContextValue | null,
+  name: `@${string}` | undefined,
+): ResolvedSegment | null {
+  return useMemo(() => {
+    if (!name || !context?.parallel) return null;
+    return context.parallel.find((seg) => seg.slot === name) ?? null;
+  }, [context, name]);
+}
 
 /**
  * Outlet component - renders child content in layouts
@@ -61,95 +138,10 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
  */
 export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
   const context = useContext(OutletContext);
+  const namedSegment = useSlotSegment(context, name);
 
-  // If name provided, render parallel/intercept content for that slot
   if (name) {
-    const segment = context?.parallel?.find((seg) => seg.slot === name) ?? null;
-
-    if (!segment) return null;
-
-    // Determine the content to render
-    let content: ReactNode;
-    if (segment.loading || segment.component instanceof Promise) {
-      // Use RouteContentWrapper to handle Suspense wrapping properly
-      content = (
-        <RouteContentWrapper
-          content={
-            segment.component instanceof Promise
-              ? segment.component
-              : Promise.resolve(segment.component)
-          }
-          fallback={segment.loading}
-          segmentId={segment.id}
-        />
-      );
-    } else {
-      content = segment.component ?? null;
-    }
-
-    let result: ReactNode;
-
-    // If segment has a layout, wrap appropriately
-    if (segment.layout) {
-      // Check if this segment has loaders that need streaming
-      // The layout renders immediately, LoaderBoundary becomes the outlet content
-      // When layout renders <Outlet />, it gets the LoaderBoundary which suspends
-      if (segment.loaderDataPromise && segment.loaderIds) {
-        const loaderAwareContent = (
-          <LoaderBoundary
-            loaderDataPromise={segment.loaderDataPromise}
-            loaderIds={segment.loaderIds}
-            fallback={segment.loading}
-            outletKey={segment.id + "-loader"}
-            outletContent={null}
-            segment={segment}
-          >
-            {content}
-          </LoaderBoundary>
-        );
-
-        result = (
-          <OutletProvider content={loaderAwareContent} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      } else {
-        // No loaders - wrap in OutletProvider so layout can use <Outlet />
-        result = (
-          <OutletProvider content={content} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      }
-    } else if (segment.loaderDataPromise && segment.loaderIds) {
-      // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-      // This is common for intercept routes that use useLoader without a custom layout
-      result = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-    } else {
-      result = content;
-    }
-
-    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-    if (segment.mountPath) {
-      return (
-        <MountContextProvider value={segment.mountPath}>
-          {result}
-        </MountContextProvider>
-      );
-    }
-
-    return result;
+    return renderSlotContent(namedSegment);
   }
 
   // Default: render child content
@@ -163,6 +155,7 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
 
   return content;
 }
+
 /**
  * ParallelOutlet component - renders content for a named parallel slot
  *
@@ -187,94 +180,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  */
 export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
   const context = useContext(OutletContext);
-  const segment = useMemo(() => {
-    if (!context?.parallel) return null;
-    return context.parallel.find((seg) => seg.slot === name) ?? null;
-  }, [context, name]);
-
-  if (!segment) return null;
-
-  // Determine the content to render
-  let content: ReactNode;
-  if (segment.loading || segment.component instanceof Promise) {
-    // Use RouteContentWrapper to handle Suspense wrapping properly
-    content = (
-      <RouteContentWrapper
-        content={
-          segment.component instanceof Promise
-            ? segment.component
-            : Promise.resolve(segment.component)
-        }
-        fallback={segment.loading}
-        segmentId={segment.id}
-      />
-    );
-  } else {
-    content = segment.component ?? null;
-  }
-
-  let result: ReactNode;
-
-  // If segment has a layout, wrap appropriately
-  if (segment.layout) {
-    // Check if this segment has loaders that need streaming
-    // The layout renders immediately, LoaderBoundary becomes the outlet content
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      const loaderAwareContent = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-
-      result = (
-        <OutletProvider content={loaderAwareContent} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    } else {
-      // No loaders - wrap in OutletProvider so layout can use <Outlet />
-      result = (
-        <OutletProvider content={content} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    }
-  } else if (segment.loaderDataPromise && segment.loaderIds) {
-    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-    // This is common for intercept routes that use useLoader without a custom layout
-    result = (
-      <LoaderBoundary
-        loaderDataPromise={segment.loaderDataPromise}
-        loaderIds={segment.loaderIds}
-        fallback={segment.loading}
-        outletKey={segment.id + "-loader"}
-        outletContent={null}
-        segment={segment}
-      >
-        {content}
-      </LoaderBoundary>
-    );
-  } else {
-    result = content;
-  }
-
-  // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-  if (segment.mountPath) {
-    return (
-      <MountContextProvider value={segment.mountPath}>
-        {result}
-      </MountContextProvider>
-    );
-  }
+  const segment = useSlotSegment(context, name);
 
-  return result;
+  return renderSlotContent(segment);
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -306,6 +214,7 @@ export function useOutlet(): ReactNode {
 export {
   useLoader,
   useFetchLoader,
+  useRefreshLoaders,
   type LoadFunction,
   type UseLoaderResult,
   type UseFetchLoaderResult,
@@ -501,37 +410,15 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation
-export {
-  href,
-  type ValidPaths,
-  type PatternToPath,
-  type PathResponse,
-} from "./href-client.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.
+export { href, type PatternToPath } from "./href-client.js";
 
-// Response envelope types for consuming JSON response routes
-export type { ResponseEnvelope, ResponseError } from "./urls.js";
-
-/**
- * Type guard for checking if a response envelope contains an error.
- *
- * @example
- * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (isResponseError(result)) {
- *   console.log(result.error.message, result.error.code);
- *   return;
- * }
- * result.data // fully typed as Product
- * ```
- */
-export function isResponseError<T>(
-  result: import("./urls.js").ResponseEnvelope<T>,
-): result is import("./urls.js").ResponseEnvelope<T> & {
-  error: import("./urls.js").ResponseError;
-} {
-  return result.error !== undefined;
-}
+// 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.
+export type { ProblemDetails } from "./urls.js";
 
 // Mount context for include() scoped components
 export { useMount } from "./browser/react/use-mount.js";
@@ -540,8 +427,12 @@ 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 } from "./reverse.js";
+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

@@ -12,7 +12,7 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
- * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
  * export const User = createVar<UserData>({ cache: false });
  *
  * // handler
@@ -26,7 +26,7 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
-  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  /** When false, ctx.get(var) throws inside a cache() boundary. */
   readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
@@ -35,9 +35,9 @@ export interface ContextVar<T> {
 export interface ContextVarOptions {
   /**
    * When false, marks this variable as non-cacheable.
-   * Setting or getting this var inside a cache() boundary or "use cache"
-   * function will throw. Use for inherently request-specific data (user
-   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+   * inherently request-specific data (user sessions, auth tokens, etc.) that
+   * must never be baked into cached segments.
    *
    * @default true
    */

package/src/decode-loader-results.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}