@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.21

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

@@ -5,15 +5,83 @@
  * Uses globalThis to survive HMR in development.
  */
 
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult } from "./types.js";
+import type {
+  SegmentCacheStore,
+  CachedEntryData,
+  CacheDefaults,
+  CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
+  SegmentHandleData,
+} from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  computeExpiration,
+  DEFAULT_FUNCTION_TTL,
+} from "./cache-policy.js";
 
-const CACHE_GLOBAL_KEY = "__rsc_router_segment_cache_store__";
+const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
+const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
+const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
+
+/**
+ * Get or create a named Map from a globalThis-backed registry.
+ * The registry survives HMR; individual stores are keyed by name.
+ */
+function getNamedMap<V>(registryKey: string, name: string): Map<string, V> {
+  let registry = (globalThis as any)[registryKey] as
+    | Map<string, Map<string, V>>
+    | undefined;
+  if (!registry) {
+    registry = new Map();
+    (globalThis as any)[registryKey] = registry;
+  }
+  let map = registry.get(name);
+  if (!map) {
+    map = new Map<string, V>();
+    registry.set(name, map);
+  }
+  return map;
+}
+
+interface CachedResponseEntry {
+  body: ArrayBuffer;
+  status: number;
+  headers: [string, string][];
+  expiresAt: number;
+  staleAt: number;
+}
+
+interface CachedItemEntry {
+  value: string;
+  handles?: Record<string, SegmentHandleData>;
+  expiresAt: number;
+  staleAt: number;
+}
 
 /**
  * Options for MemorySegmentCacheStore
  */
 export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Optional name for this store instance. Named stores persist their
+   * backing Map on globalThis so data survives Vite HMR module reloads.
+   * Stores with different names get separate Maps.
+   *
+   * When omitted, the store uses a plain instance-level Map with no
+   * globalThis sharing, which is the safest default for isolation.
+   *
+   * @example
+   * ```typescript
+   * // Two named stores are isolated from each other
+   * const fast = new MemorySegmentCacheStore({ name: "fast", defaults: { ttl: 10 } });
+   * const slow = new MemorySegmentCacheStore({ name: "slow", defaults: { ttl: 300 } });
+   * ```
+   */
+  name?: string;
+
   /**
    * Default cache options for cache() boundaries.
    * When cache() is called without explicit ttl/swr,
@@ -35,14 +103,14 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * @example
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = ctx.cookie('locale') || 'en';
+   *   const locale = cookies().get('locale')?.value || 'en';
    *   return `${locale}:${defaultKey}`;
    * }
    * ```
    */
   keyGenerator?: (
     ctx: RequestContext<TEnv>,
-    defaultKey: string
+    defaultKey: string,
   ) => string | Promise<string>;
 }
 
@@ -69,19 +137,40 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * })
  * ```
  */
-export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+export class MemorySegmentCacheStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
   private cache: Map<string, CachedEntryData>;
+  private responseCache: Map<string, CachedResponseEntry>;
+  private itemCache: Map<string, CachedItemEntry>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
-    defaultKey: string
+    defaultKey: string,
   ) => string | Promise<string>;
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
-    // Use globalThis to survive HMR in development
-    this.cache =
-      (globalThis as any)[CACHE_GLOBAL_KEY] ??
-      ((globalThis as any)[CACHE_GLOBAL_KEY] = new Map<string, CachedEntryData>());
+    if (options?.name != null) {
+      // Named stores use the globalThis registry so data survives HMR.
+      // Each name gets its own isolated Map.
+      this.cache = getNamedMap<CachedEntryData>(
+        CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.responseCache = getNamedMap<CachedResponseEntry>(
+        RESPONSE_CACHE_REGISTRY_KEY,
+        options.name,
+      );
+      this.itemCache = getNamedMap<CachedItemEntry>(
+        ITEM_CACHE_REGISTRY_KEY,
+        options.name,
+      );
+    } else {
+      // Unnamed stores get a plain instance-level Map (no globalThis sharing).
+      this.cache = new Map<string, CachedEntryData>();
+      this.responseCache = new Map<string, CachedResponseEntry>();
+      this.itemCache = new Map<string, CachedItemEntry>();
+    }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
   }
@@ -103,7 +192,12 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
     return { data: cached, shouldRevalidate: false };
   }
 
-  async set(key: string, data: CachedEntryData, ttl: number, _swr?: number): Promise<void> {
+  async set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    _swr?: number,
+  ): Promise<void> {
     // Note: Memory store doesn't implement SWR - entries just expire at TTL
     // For SWR support, use CFCacheStore or similar distributed cache
     const entry: CachedEntryData = {
@@ -119,6 +213,88 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
 
   async clear(): Promise<void> {
     this.cache.clear();
+    this.responseCache.clear();
+    this.itemCache.clear();
+  }
+
+  async getResponse(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
+    const cached = this.responseCache.get(key);
+    if (!cached) return null;
+
+    if (Date.now() > cached.expiresAt) {
+      this.responseCache.delete(key);
+      return null;
+    }
+
+    const isStale = cached.staleAt > 0 && Date.now() > cached.staleAt;
+    const headers = new Headers(cached.headers);
+    return {
+      response: new Response(cached.body, {
+        status: cached.status,
+        headers,
+      }),
+      shouldRevalidate: isStale,
+    };
+  }
+
+  async putResponse(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+  ): Promise<void> {
+    const body = await response.clone().arrayBuffer();
+    const headers: [string, string][] = [];
+    response.headers.forEach((value, name) => {
+      headers.push([name, value]);
+    });
+
+    const swrWindow = resolveSwrWindow(swr, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+
+    this.responseCache.set(key, {
+      body,
+      status: response.status,
+      headers,
+      expiresAt,
+      staleAt,
+    });
+  }
+
+  async getItem(key: string): Promise<CacheItemResult | null> {
+    const cached = this.itemCache.get(key);
+    if (!cached) return null;
+
+    const now = Date.now();
+    if (now > cached.expiresAt) {
+      this.itemCache.delete(key);
+      return null;
+    }
+
+    const isStale = now > cached.staleAt;
+    return {
+      value: cached.value,
+      handles: cached.handles,
+      shouldRevalidate: isStale,
+    };
+  }
+
+  async setItem(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void> {
+    const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
+    const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+    this.itemCache.set(key, {
+      value,
+      handles: options?.handles,
+      expiresAt,
+      staleAt,
+    });
   }
 
   /**
@@ -133,7 +309,7 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
   }
 
   /**
-   * Reset the global cache state.
+   * Reset the global cache registry.
    * Useful for test isolation - call this in beforeEach to ensure
    * tests don't share cache state via globalThis.
    *
@@ -145,6 +321,8 @@ export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStor
    * ```
    */
   static resetGlobalCache(): void {
-    delete (globalThis as any)[CACHE_GLOBAL_KEY];
+    delete (globalThis as any)[CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[ITEM_CACHE_REGISTRY_KEY];
   }
 }

package/src/cache/profile-registry.ts

@@ -0,0 +1,73 @@
+/**
+ * Cache Profile Registry
+ *
+ * Named cache profiles for "use cache" directive.
+ * Profiles define TTL, SWR, and optional default tags.
+ * Set by createRouter() at startup, read by registerCachedFunction() at runtime.
+ */
+
+export interface CacheProfile {
+  /** Time-to-live in seconds */
+  ttl: number;
+  /** Stale-while-revalidate window in seconds */
+  swr?: number;
+  /** Default cache tags for invalidation */
+  tags?: string[];
+}
+
+const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
+
+let _profiles: Record<string, CacheProfile> = {
+  default: DEFAULT_PROFILE,
+};
+
+const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate and merge user profiles with the default profile.
+ * Returns a new object suitable for both DSL-time and request-scoped use.
+ *
+ * Used by createRouter() to compute the resolved profile map once,
+ * stored on the router instance and passed to every request context.
+ */
+export function resolveCacheProfiles(
+  profiles?: Record<string, CacheProfile>,
+): Record<string, CacheProfile> {
+  const merged: Record<string, CacheProfile> = {
+    default: DEFAULT_PROFILE,
+  };
+  if (profiles) {
+    for (const name of Object.keys(profiles)) {
+      if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(
+          `Invalid cache profile name "${name}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+.`,
+        );
+      }
+      merged[name] = profiles[name];
+    }
+  }
+  return merged;
+}
+
+/**
+ * Set all cache profiles in the global registry.
+ * Called by createRouter() at startup for DSL-time resolution
+ * (cache("profileName") reads from this during route definition).
+ *
+ * WARNING: This is global mutable state. It exists only for DSL-time
+ * reads. Runtime resolution (registerCachedFunction) uses request-scoped
+ * profiles and does NOT read from this registry.
+ */
+export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
+  _profiles = resolveCacheProfiles(profiles);
+}
+
+/**
+ * Get a cache profile by name from the global registry.
+ * Used only at DSL-time (cache("profileName") inside urls() evaluation).
+ * Runtime code uses request-scoped profiles instead.
+ */
+export function getCacheProfile(name: string): CacheProfile | undefined {
+  return _profiles[name];
+}

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

@@ -0,0 +1,134 @@
+/**
+ * SWR Read-Through Engine
+ *
+ * Generic read-through cache with stale-while-revalidate support
+ * for item-level caching (getItem/setItem).
+ *
+ * Flow:
+ * 1. Lookup cached item by key
+ * 2. Fresh hit → deserialize, return
+ * 3. Stale hit → deserialize, return, revalidate in background
+ * 4. Miss → execute, cache write (blocking when no waitUntil), return
+ */
+
+import type { CacheItemResult, CacheItemOptions } from "./types.js";
+import { runBackground } from "./background-task.js";
+
+interface WaitUntilHost {
+  waitUntil?: (fn: () => Promise<void>) => void;
+}
+
+export interface ReadThroughItemConfig<T> {
+  /** Retrieve a cached item by key */
+  getItem: (key: string) => Promise<CacheItemResult | null>;
+  /** Store a serialized item by key */
+  setItem: (
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ) => Promise<void>;
+  /** Cache key */
+  key: string;
+  /** Execute the underlying function/loader on miss or revalidation */
+  execute: () => Promise<T>;
+  /** Serialize result for storage. Return null to skip caching. */
+  serialize: (data: T) => Promise<string | null>;
+  /** Deserialize cached value back to the original type */
+  deserialize: (value: string) => Promise<T>;
+  /** Options passed to setItem on cache write */
+  storeOptions: CacheItemOptions;
+  /** Called on fresh cache hit (before returning data) */
+  onHit?: (cached: CacheItemResult) => void;
+  /** Called on stale cache hit (before scheduling background revalidation) */
+  onStale?: (cached: CacheItemResult) => void;
+  /** Called on cache miss (before executing) */
+  onMiss?: () => void;
+  /** Called after successful cache write */
+  onCached?: () => void;
+  /** Host with optional waitUntil for background tasks */
+  host?: WaitUntilHost | null;
+}
+
+/**
+ * Read-through cache with SWR support for item-level caching.
+ *
+ * On fresh hit: returns deserialized cached data.
+ * On stale hit: returns stale data, schedules background revalidation.
+ * On miss: executes, writes to cache (blocking when no waitUntil), returns.
+ */
+export async function readThroughItem<T>(
+  config: ReadThroughItemConfig<T>,
+): Promise<T> {
+  const {
+    getItem,
+    setItem,
+    key,
+    execute,
+    serialize,
+    deserialize,
+    storeOptions,
+    onHit,
+    onStale,
+    onMiss,
+    onCached,
+    host,
+  } = config;
+
+  // Cache lookup
+  try {
+    const cached = await getItem(key);
+
+    if (cached) {
+      const data = await deserialize(cached.value);
+
+      if (!cached.shouldRevalidate) {
+        onHit?.(cached);
+        return data;
+      }
+
+      // Stale hit — return stale data, revalidate in background
+      onStale?.(cached);
+      runBackground(
+        host,
+        async () => {
+          try {
+            const fresh = await execute();
+            const serialized = await serialize(fresh);
+            if (serialized !== null) {
+              await setItem(key, serialized, storeOptions);
+            }
+          } catch {
+            // Background revalidation failed silently
+          }
+        },
+        true,
+      );
+      return data;
+    }
+  } catch {
+    // Cache lookup failed, fall through to fresh execution
+  }
+
+  // Cache miss
+  onMiss?.();
+  const data = await execute();
+
+  // Non-blocking cache write (blocks when no waitUntil)
+  await runBackground(
+    host,
+    async () => {
+      try {
+        const serialized = await serialize(data);
+        if (serialized !== null) {
+          await setItem(key, serialized, storeOptions);
+          onCached?.();
+        }
+      } catch {
+        // Cache write failed silently
+      }
+    },
+    true,
+  );
+
+  return data;
+}