@rangojs/router 0.0.0-experimental.6 → 0.0.0-experimental.60

package/src/cache/segment-codec.ts

@@ -0,0 +1,256 @@
+/**
+ * Segment Codec
+ *
+ * RSC serialization/deserialization for cached segments.
+ * Handles the Flight protocol stream <-> string conversion
+ * and the segment-level encode/decode lifecycle.
+ */
+
+/// <reference types="@vitejs/plugin-rsc/types" />
+
+import type { ResolvedSegment } from "../types.js";
+import type { SerializedSegmentData } from "./types.js";
+import {
+  renderToReadableStream,
+  createTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/rsc";
+import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
+
+// ============================================================================
+// Stream Utilities (internal)
+// ============================================================================
+
+/**
+ * Convert a ReadableStream to a string.
+ */
+export async function streamToString(
+  stream: ReadableStream<Uint8Array>,
+): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let result = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    result += decoder.decode(value, { stream: true });
+  }
+
+  result += decoder.decode(); // flush
+  return result;
+}
+
+/**
+ * Convert a string to a ReadableStream.
+ */
+export function stringToStream(str: string): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const uint8 = encoder.encode(str);
+
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(uint8);
+      controller.close();
+    },
+  });
+}
+
+// ============================================================================
+// RSC Serialization Primitives (internal)
+// ============================================================================
+
+/**
+ * RSC-serialize a value using React Server Components stream.
+ * Used for serializing loaderData, layout, loading components etc.
+ *
+ * Returns undefined for null/undefined inputs (component fields that are absent).
+ * For contexts where null is a valid result (loader caching, "use cache"),
+ * use serializeResult() instead which preserves null through RSC Flight.
+ */
+export async function rscSerialize(
+  value: unknown,
+): Promise<string | undefined> {
+  if (value === undefined || value === null) return undefined;
+
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = renderToReadableStream(value, { temporaryReferences });
+  return streamToString(stream);
+}
+
+/**
+ * RSC-deserialize a value from a stored string.
+ */
+export async function rscDeserialize<T>(
+  encoded: string | undefined,
+): Promise<T | undefined> {
+  if (!encoded) return undefined;
+
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = stringToStream(encoded);
+  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
+ * RSC Flight so that a loader returning null produces a valid cached entry
+ * rather than a permanent cache miss.
+ *
+ * Returns null only on serialization failure.
+ */
+export async function serializeResult(value: unknown): Promise<string | null> {
+  try {
+    const temporaryReferences = createTemporaryReferenceSet();
+    const stream = renderToReadableStream(value, { temporaryReferences });
+    return await streamToString(stream);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * RSC-deserialize a cached result string.
+ * Counterpart to serializeResult() — always receives a non-empty string.
+ */
+export async function deserializeResult<T>(encoded: string): Promise<T> {
+  const temporaryReferences = createTemporaryReferenceSet();
+  const stream = stringToStream(encoded);
+  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.
+ * Identical to deserializeResult<unknown>.
+ */
+export const deserializeComponent: (encoded: string) => Promise<unknown> =
+  deserializeResult;
+
+/**
+ * Serialize segments for storage.
+ * Each segment's component, layout, loading, and loaderData are RSC-serialized.
+ * Metadata is preserved as-is.
+ */
+export async function serializeSegments(
+  segments: ResolvedSegment[],
+): Promise<SerializedSegmentData[]> {
+  return Promise.all(
+    segments.map(async (segment): Promise<SerializedSegmentData> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Await component if it's a Promise (intercepts with loading keep component as Promise)
+      const componentResolved =
+        segment.component instanceof Promise
+          ? await segment.component
+          : segment.component;
+
+      // Serialize the component to RSC stream
+      const stream = renderToReadableStream(componentResolved, {
+        temporaryReferences,
+      });
+
+      // RSC-serialize loading: "null" string distinguishes explicit null from undefined
+      const encodedLoading =
+        segment.loading !== undefined
+          ? segment.loading === null
+            ? "null"
+            : await rscSerialize(segment.loading)
+          : undefined;
+
+      // Await loaderData / loaderDataPromise if they're Promises
+      const loaderDataResolved =
+        segment.loaderData instanceof Promise
+          ? await segment.loaderData
+          : segment.loaderData;
+      const loaderDataPromiseResolved =
+        segment.loaderDataPromise instanceof Promise
+          ? await segment.loaderDataPromise
+          : segment.loaderDataPromise;
+
+      // Parallelize stream-to-string and RSC serialization of sub-fields
+      const [
+        encoded,
+        encodedLayout,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+      ] = await Promise.all([
+        streamToString(stream),
+        segment.layout ? rscSerialize(segment.layout) : undefined,
+        rscSerialize(loaderDataResolved),
+        rscSerialize(loaderDataPromiseResolved),
+      ]);
+
+      return {
+        encoded,
+        encodedLayout,
+        encodedLoading,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+        metadata: {
+          id: segment.id,
+          type: segment.type,
+          namespace: segment.namespace,
+          index: segment.index,
+          params: segment.params,
+          slot: segment.slot,
+          belongsToRoute: segment.belongsToRoute,
+          layoutName: segment.layoutName,
+          parallelName: segment.parallelName,
+          loaderId: segment.loaderId,
+          loaderIds: segment.loaderIds,
+          transition: segment.transition,
+          mountPath: segment.mountPath,
+        },
+      };
+    }),
+  );
+}
+
+/**
+ * Deserialize segments from storage.
+ * Reconstructs ResolvedSegment objects from RSC-serialized data.
+ */
+export async function deserializeSegments(
+  data: SerializedSegmentData[],
+): Promise<ResolvedSegment[]> {
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Handle the "null" sentinel for loading before RSC deserialization.
+      // During serialization, loading: null is stored as the string "null" to
+      // distinguish it from undefined.
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+
+      const [component, layout, loaderData, loaderDataPromise, loadingData] =
+        await Promise.all([
+          createFromReadableStream(stringToStream(item.encoded), {
+            temporaryReferences,
+          }),
+          rscDeserialize(item.encodedLayout),
+          rscDeserialize(item.encodedLoaderData),
+          rscDeserialize(item.encodedLoaderDataPromise),
+          loadingIsNullSentinel
+            ? (null as any)
+            : rscDeserialize(item.encodedLoading),
+        ]);
+
+      return {
+        ...item.metadata,
+        component,
+        layout,
+        loading: loadingData,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
+}

package/src/cache/taint.ts

@@ -0,0 +1,153 @@
+/**
+ * Taint symbol for request-scoped objects.
+ *
+ * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * "use cache" cache keys and trigger handle capture mode so that side
+ * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
+ */
+
+export const NOCACHE_SYMBOL: unique symbol = Symbol.for("rango:nocache") as any;
+
+/**
+ * Check if a value is tainted (request-scoped, should not be in cache key).
+ */
+export function isTainted(value: unknown): boolean {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    (NOCACHE_SYMBOL as symbol) in (value as Record<symbol, unknown>)
+  );
+}
+
+/**
+ * Symbol stamped on tainted ctx during "use cache" function execution.
+ * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
+ * throw if present — reads would cache per-request data under a shared key,
+ * and side effects would be lost on cache hit.
+ *
+ * The value is a numeric reference count, not a boolean. Multiple concurrent
+ * cached functions sharing the same ctx/requestCtx each increment on entry
+ * and decrement on exit. Guards fire when count > 0.
+ */
+export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
+  "rango:inside-cache-exec",
+) as any;
+
+/**
+ * Increment the INSIDE_CACHE_EXEC ref count on an object.
+ */
+export function stampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  (obj as any)[INSIDE_CACHE_EXEC] = current + 1;
+}
+
+/**
+ * Decrement the INSIDE_CACHE_EXEC ref count on an object.
+ * Deletes the symbol when the count reaches zero so the `in` check
+ * used by guards no longer fires.
+ */
+export function unstampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_EXEC];
+  } else {
+    (obj as any)[INSIDE_CACHE_EXEC] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a "use cache" execution.
+ * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
+ */
+export function assertNotInsideCacheExec(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a "use cache" function. ` +
+        `Side effects on the request context are lost on cache hit because ` +
+        `the function body is skipped. Extract the data fetch into a separate ` +
+        `cached function and call ctx.${methodName}() outside it, or use the ` +
+        `route-level cache() DSL which caches all segments (handler + children) ` +
+        `together.`,
+    );
+  }
+}
+
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
+/**
+ * Brand symbol for functions wrapped by registerCachedFunction().
+ * Used at runtime to detect when a "use cache" function is misused
+ * (e.g., passed as middleware).
+ */
+export const CACHED_FN_SYMBOL: unique symbol = Symbol.for(
+  "rango:cached-fn",
+) as any;
+
+/**
+ * Check if a value is a "use cache" wrapped function.
+ */
+export function isCachedFunction(value: unknown): boolean {
+  return typeof value === "function" && (CACHED_FN_SYMBOL as symbol) in value;
+}

package/src/cache/types.ts

@@ -75,14 +75,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @example Using cookies for locale
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
    */
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
-    defaultKey: string
+    defaultKey: string,
   ) => string | Promise<string>;
 
   /**
@@ -98,7 +98,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
    */
-  set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+  set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    swr?: number,
+  ): Promise<void>;
 
   /**
    * Delete a cached entry
@@ -121,7 +126,9 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * Get a cached Response by key.
    * Returns the response and whether it should be revalidated (SWR).
    */
-  getResponse?(key: string): Promise<{ response: Response; shouldRevalidate: boolean } | null>;
+  getResponse?(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null>;
 
   /**
    * Store a Response with TTL and optional SWR window.
@@ -130,7 +137,62 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
    */
-  putResponse?(key: string, response: Response, ttl: number, swr?: number): Promise<void>;
+  putResponse?(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+  ): 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.
+   */
+  getItem?(key: string): Promise<CacheItemResult | null>;
+
+  /**
+   * Store a function result with TTL and optional SWR window.
+   * @param key - Cache key (format: use-cache:{functionId}:{serializedArgs})
+   * @param value - RSC-serialized return value
+   * @param options - TTL, SWR, handle data, and tags
+   */
+  setItem?(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void>;
+}
+
+/**
+ * Result from getItem() for function-level caching ("use cache").
+ */
+export interface CacheItemResult {
+  /** RSC-serialized return value */
+  value: string;
+  /** Handle data captured during execution (breadcrumbs, metadata, etc.) */
+  handles?: Record<string, SegmentHandleData>;
+  /** Whether the entry is stale and should be revalidated */
+  shouldRevalidate: boolean;
+}
+
+/**
+ * Options for setItem() for function-level caching ("use cache").
+ */
+export interface CacheItemOptions {
+  /** Handle data to store alongside the value */
+  handles?: Record<string, SegmentHandleData>;
+  /** Time-to-live in seconds */
+  ttl?: number;
+  /** Stale-while-revalidate window in seconds */
+  swr?: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
 }
 
 /**
@@ -151,7 +213,10 @@ export interface SerializedSegmentData {
   /** RSC-encoded loaderDataPromise (if present) */
   encodedLoaderDataPromise?: string;
   /** Segment metadata (everything except component, layout, loading, and loader data) */
-  metadata: Omit<ResolvedSegment, "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise">;
+  metadata: Omit<
+    ResolvedSegment,
+    "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise"
+  >;
 }
 
 /**
@@ -234,7 +299,6 @@ export interface CachedEntryResult {
   handles: Record<string, SegmentHandleData>;
 }
 
-
 /**
  * Segment cache provider interface
  *
@@ -262,7 +326,7 @@ export interface SegmentCacheProvider {
   restore(
     cacheKey: string,
     params: Record<string, string>,
-    loaderPromises: Map<string, Promise<any>>
+    loaderPromises: Map<string, Promise<any>>,
   ): Promise<[ResolvedSegment[], string[]] | null>;
 
   /**
@@ -276,117 +340,3 @@ export interface SegmentCacheProvider {
    */
   cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
 }
-
-// ============================================================================
-// Generic Cache Store (for future extensibility)
-// ============================================================================
-// These types support a general-purpose cache interface that can be used
-// for caching arbitrary values (responses, streams, objects). Currently,
-// the segment caching system uses SegmentCacheStore directly, but these
-// types enable future use cases like response caching or data caching.
-
-/**
- * Supported cache value types for the generic CacheStore interface.
- * @internal Reserved for future extensibility
- */
-export type CacheValue =
-  | ReadableStream<Uint8Array>
-  | Response
-  | ArrayBuffer
-  | string
-  | unknown[] // JSON-serializable array
-  | Record<string, unknown>; // JSON-serializable object
-
-/**
- * Cache entry returned by match().
- * @internal Reserved for future extensibility
- */
-export interface CacheEntry<T = CacheValue> {
-  /** The cached value */
-  value: T;
-  /** Optional metadata stored with the entry */
-  metadata?: CacheMetadata;
-}
-
-/**
- * Original value type for reconstruction.
- * @internal Reserved for future extensibility
- */
-export type CacheValueType =
-  | "stream"
-  | "response"
-  | "arraybuffer"
-  | "string"
-  | "object";
-
-/**
- * Metadata associated with a cache entry.
- * @internal Reserved for future extensibility
- */
-export interface CacheMetadata {
-  /** Timestamp when entry expires (ms since epoch) */
-  expiresAt?: number;
-  /** Tags for bulk invalidation */
-  tags?: string[];
-  /** Original value type for reconstruction on read */
-  valueType?: CacheValueType;
-  /** Response headers (preserved when caching Response) */
-  responseHeaders?: Record<string, string>;
-  /** Response status (preserved when caching Response) */
-  responseStatus?: number;
-  /** Custom metadata */
-  [key: string]: unknown;
-}
-
-/**
- * Options for put().
- * @internal Reserved for future extensibility
- */
-export interface CachePutOptions {
-  /** Time-to-live in seconds */
-  ttl?: number;
-  /** Metadata to store with entry */
-  metadata?: Omit<CacheMetadata, "expiresAt">;
-}
-
-/**
- * Generic cache store interface for arbitrary value types.
- *
- * This interface is designed for future extensibility to support caching
- * responses, streams, and other values. Currently, segment caching uses
- * the SegmentCacheStore interface directly.
- *
- * Implementations must handle:
- * - Stream values (clone before storing, streams can only be read once)
- * - Promise values (await before storing)
- * - Expiration/TTL
- *
- * @internal Reserved for future extensibility
- */
-export interface CacheStore {
-  /**
-   * Retrieve a cached entry by key.
-   * @param key - Cache key
-   * @returns The cached entry or undefined if not found/expired
-   */
-  match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined>;
-
-  /**
-   * Store a value in the cache.
-   * @param key - Cache key
-   * @param value - Value to cache (stream, response, string, object, etc.)
-   * @param options - TTL, metadata, etc.
-   */
-  put<T extends CacheValue>(
-    key: string,
-    value: T,
-    options?: CachePutOptions
-  ): Promise<void>;
-
-  /**
-   * Delete a cached entry.
-   * @param key - Cache key
-   * @returns true if entry was deleted, false if not found
-   */
-  delete(key: string): Promise<boolean>;
-}

package/src/client.rsc.tsx

@@ -17,7 +17,6 @@ export {
   OutletProvider,
   useOutlet,
   useLoader,
-  useLoaderData,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
@@ -64,6 +63,8 @@ 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
@@ -71,6 +72,7 @@ export {
   createLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
 // Re-export useHref - it's a "use client" hook