@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

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

@@ -15,24 +15,35 @@ import type {
   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_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__";
 
 /**
- * Returns the globalThis-backed registry of named cache Maps.
- * The registry itself survives HMR; individual stores are keyed by name.
+ * Get or create a named Map from a globalThis-backed registry.
+ * The registry survives HMR; individual stores are keyed by name.
  */
-function getGlobalRegistry(): Map<string, Map<string, CachedEntryData>> {
-  let registry = (globalThis as any)[CACHE_REGISTRY_KEY] as
-    | Map<string, Map<string, CachedEntryData>>
+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)[CACHE_REGISTRY_KEY] = registry;
+    (globalThis as any)[registryKey] = registry;
   }
-  return registry;
+  let map = registry.get(name);
+  if (!map) {
+    map = new Map<string, V>();
+    registry.set(name, map);
+  }
+  return map;
 }
 
 interface CachedResponseEntry {
@@ -47,37 +58,7 @@ interface CachedItemEntry {
   value: string;
   handles?: Record<string, SegmentHandleData>;
   expiresAt: number;
-}
-
-/**
- * Returns the globalThis-backed registry of named item cache Maps (for "use cache").
- */
-function getItemCacheRegistry(): Map<string, Map<string, CachedItemEntry>> {
-  let registry = (globalThis as any)[ITEM_CACHE_REGISTRY_KEY] as
-    | Map<string, Map<string, CachedItemEntry>>
-    | undefined;
-  if (!registry) {
-    registry = new Map();
-    (globalThis as any)[ITEM_CACHE_REGISTRY_KEY] = registry;
-  }
-  return registry;
-}
-
-/**
- * Returns the globalThis-backed registry of named response cache Maps.
- */
-function getResponseCacheRegistry(): Map<
-  string,
-  Map<string, CachedResponseEntry>
-> {
-  let registry = (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY] as
-    | Map<string, Map<string, CachedResponseEntry>>
-    | undefined;
-  if (!registry) {
-    registry = new Map();
-    (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY] = registry;
-  }
-  return registry;
+  staleAt: number;
 }
 
 /**
@@ -122,7 +103,7 @@ 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}`;
    * }
    * ```
@@ -172,29 +153,18 @@ export class MemorySegmentCacheStore<
     if (options?.name != null) {
       // Named stores use the globalThis registry so data survives HMR.
       // Each name gets its own isolated Map.
-      const registry = getGlobalRegistry();
-      let map = registry.get(options.name);
-      if (!map) {
-        map = new Map<string, CachedEntryData>();
-        registry.set(options.name, map);
-      }
-      this.cache = map;
-
-      const responseRegistry = getResponseCacheRegistry();
-      let responseMap = responseRegistry.get(options.name);
-      if (!responseMap) {
-        responseMap = new Map<string, CachedResponseEntry>();
-        responseRegistry.set(options.name, responseMap);
-      }
-      this.responseCache = responseMap;
-
-      const itemRegistry = getItemCacheRegistry();
-      let itemMap = itemRegistry.get(options.name);
-      if (!itemMap) {
-        itemMap = new Map<string, CachedItemEntry>();
-        itemRegistry.set(options.name, itemMap);
-      }
-      this.itemCache = itemMap;
+      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>();
@@ -281,9 +251,8 @@ export class MemorySegmentCacheStore<
       headers.push([name, value]);
     });
 
-    const swrWindow = swr ?? this.defaults?.swr ?? 0;
-    const staleAt = Date.now() + ttl * 1000;
-    const expiresAt = staleAt + swrWindow * 1000;
+    const swrWindow = resolveSwrWindow(swr, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
     this.responseCache.set(key, {
       body,
@@ -298,15 +267,17 @@ export class MemorySegmentCacheStore<
     const cached = this.itemCache.get(key);
     if (!cached) return null;
 
-    if (Date.now() > cached.expiresAt) {
+    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: false,
+      shouldRevalidate: isStale,
     };
   }
 
@@ -315,11 +286,14 @@ export class MemorySegmentCacheStore<
     value: string,
     options?: CacheItemOptions,
   ): Promise<void> {
-    const ttl = options?.ttl ?? this.defaults?.ttl ?? 900;
+    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: Date.now() + ttl * 1000,
+      expiresAt,
+      staleAt,
     });
   }
 

package/src/cache/profile-registry.ts

@@ -15,23 +15,58 @@ export interface CacheProfile {
   tags?: string[];
 }
 
+const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
+
 let _profiles: Record<string, CacheProfile> = {
-  default: { ttl: 900, swr: 1800 },
+  default: DEFAULT_PROFILE,
 };
 
+const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
 /**
- * Set all cache profiles. Called by createRouter() at startup.
+ * 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 setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = { ...profiles };
-  // Ensure a default profile always exists
-  if (!_profiles.default) {
-    _profiles.default = { ttl: 900, swr: 1800 };
+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. Returns undefined for unknown 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;
+}

package/src/cache/segment-codec.ts

@@ -62,6 +62,10 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
 /**
  * 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,
@@ -87,19 +91,49 @@ export async function rscDeserialize<T>(
 }
 
 // ============================================================================
-// Public API
+// Null-Preserving RSC Serialization (for caching)
 // ============================================================================
 
 /**
- * RSC-deserialize a single encoded component string back to a React element.
- * Used by the static handler runtime to revive pre-rendered components.
+ * 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 deserializeComponent(encoded: string): Promise<unknown> {
+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(stream, { temporaryReferences });
+  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.
@@ -108,79 +142,76 @@ export async function deserializeComponent(encoded: string): Promise<unknown> {
 export async function serializeSegments(
   segments: ResolvedSegment[],
 ): Promise<SerializedSegmentData[]> {
-  const serialized: SerializedSegmentData[] = [];
-
-  for (const segment of segments) {
-    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,
-    });
-
-    // Convert stream to string
-    const encoded = await streamToString(stream);
-
-    // RSC-serialize layout if present (ReactNode)
-    const encodedLayout = segment.layout
-      ? await rscSerialize(segment.layout)
-      : undefined;
-
-    // RSC-serialize loading if present (ReactNode) - preserves tree structure
-    // Use "null" string to distinguish explicit null from undefined
-    const encodedLoading =
-      segment.loading !== undefined
-        ? segment.loading === null
-          ? "null"
-          : await rscSerialize(segment.loading)
-        : undefined;
-
-    // Await and RSC-serialize loaderData if present
-    const loaderDataResolved =
-      segment.loaderData instanceof Promise
-        ? await segment.loaderData
-        : segment.loaderData;
-    const encodedLoaderData = await rscSerialize(loaderDataResolved);
-
-    // Await and RSC-serialize loaderDataPromise if present
-    const loaderDataPromiseResolved =
-      segment.loaderDataPromise instanceof Promise
-        ? await segment.loaderDataPromise
-        : segment.loaderDataPromise;
-    const encodedLoaderDataPromise = await rscSerialize(
-      loaderDataPromiseResolved,
-    );
-
-    serialized.push({
-      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,
-      },
-    });
-  }
+  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 serialized;
+      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,
+        },
+      };
+    }),
+  );
 }
 
 /**
@@ -190,44 +221,36 @@ export async function serializeSegments(
 export async function deserializeSegments(
   data: SerializedSegmentData[],
 ): Promise<ResolvedSegment[]> {
-  const segments: ResolvedSegment[] = [];
-
-  for (const item of data) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Revive the component from cached string
-    const stream = stringToStream(item.encoded);
-    const component = await createFromReadableStream(stream, {
-      temporaryReferences,
-    });
-
-    // RSC-deserialize layout, loaderData, loaderDataPromise in parallel.
-    // Handle the "null" sentinel for loading before RSC deserialization.
-    // During serialization, loading: null is stored as the string "null" to
-    // distinguish it from undefined. This sentinel must be intercepted here
-    // rather than passed to rscDeserialize, which would try to decode it as
-    // an RSC Flight payload.
-    const loadingIsNullSentinel = item.encodedLoading === "null";
-
-    const [layout, loaderData, loaderDataPromise, loadingData] =
-      await Promise.all([
-        rscDeserialize(item.encodedLayout),
-        rscDeserialize(item.encodedLoaderData),
-        rscDeserialize(item.encodedLoaderDataPromise),
-        loadingIsNullSentinel
-          ? (null as any)
-          : rscDeserialize(item.encodedLoading),
-      ]);
-
-    segments.push({
-      ...item.metadata,
-      component,
-      layout,
-      loading: loadingData,
-      loaderData,
-      loaderDataPromise,
-    } as ResolvedSegment);
-  }
-
-  return segments;
+  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;
+    }),
+  );
 }