@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1c0bdfad

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).
@@ -136,20 +126,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param response - Response to cache (will be cloned)
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation
    */
   putResponse?(
     key: string,
     response: Response,
     ttl: number,
     swr?: number,
+    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.
@@ -167,6 +153,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
     value: string,
     options?: CacheItemOptions,
   ): Promise<void>;
+
+  /**
+   * Invalidate every cache entry (segment, response, item) tagged with any of
+   * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+   * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+   * stores can batch their work (e.g. a single CDN purge request rather than
+   * one per tag). Stores that do not support tags simply omit this method.
+   * @param tags - The cache tags to invalidate
+   */
+  invalidateTags?(tags: string[]): Promise<void>;
 }
 
 /**
@@ -175,18 +171,27 @@ 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;
+  /**
+   * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+   * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+   * set used by document-level caching. On a hit the cached function is not
+   * re-run, so its runtime tags are only available here, not from re-execution.
+   */
+  tags?: string[];
 }
 
 /**
  * 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,16 +232,18 @@ 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;
+  /** Cache tags for invalidation */
+  tags?: string[];
+  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  taggedAt?: number;
 }
 
-// ============================================================================
-// Cache Configuration
-// ============================================================================
-
 /**
  * Default cache options applied to all cache() boundaries.
  * Individual cache() calls can override any of these values.
@@ -252,91 +259,21 @@ export interface CacheDefaults {
   /**
    * Default time-to-live in seconds.
    * After TTL expires, cached entry is considered stale.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   ttl?: number;
   /**
    * Default stale-while-revalidate window in seconds.
    * During SWR window, stale content is served while revalidating in background.
+   * Must be a finite, non-negative number; an invalid value (NaN/Infinity/
+   * negative) falls back to the default at read time.
    */
   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,59 +14,81 @@
 export {
   Outlet,
   ParallelOutlet,
-  OutletProvider,
   useOutlet,
   useLoader,
-  useLoaderData,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
 
-// Re-export the server's createLoader for RSC context
-// This version includes the actual loader function
+export {
+  useFetchLoader,
+  useRefreshLoaders,
+  type LoadFunction,
+  type UseLoaderResult,
+  type UseFetchLoaderResult,
+  type UseLoaderOptions,
+} from "./use-loader.js";
+
 export { createLoader } from "./route-definition.js";
 
-// Re-export Link component (can be used in server components)
+// "use client" hooks the default ./client entry exports. They are client
+// references in the RSC graph, identical in kind to useHref/useReverse/
+// useHandle already forwarded below; forward them so the RSC client entry's
+// hook surface matches the default entry. useNavigation/useAction stay omitted
+// (they drive client-only navigation/action state — see note below).
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+// CSP nonce for userland head-script components (analytics/GTM/inline init);
+// forwarded so the RSC client entry's hook surface matches the default entry.
+export { useNonce } from "./browser/react/nonce-context.js";
+export { useMount } from "./browser/react/use-mount.js";
+export {
+  useSegments,
+  type SegmentsState,
+} from "./browser/react/use-segments.js";
+export {
+  useLinkStatus,
+  type LinkStatus,
+} from "./browser/react/use-link-status.js";
+export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+
 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, useAction, useClientCache 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";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
+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,
@@ -74,11 +96,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 useHandle - it's a "use client" hook
+export { useReverse } from "./browser/react/use-reverse.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";
 
-// Re-export useLocationState - it's a "use client" hook
 export { useLocationState } from "./browser/react/location-state.js";