@ivogt/rsc-router 0.0.0-experimental.1

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

@@ -0,0 +1,150 @@
+/**
+ * In-Memory Segment Cache Store
+ *
+ * Simple in-memory implementation of SegmentCacheStore.
+ * Uses globalThis to survive HMR in development.
+ */
+
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+
+const CACHE_GLOBAL_KEY = "__rsc_router_segment_cache_store__";
+
+/**
+ * Options for MemorySegmentCacheStore
+ */
+export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Default cache options for cache() boundaries.
+   * When cache() is called without explicit ttl/swr,
+   * these defaults are used.
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({
+   *   defaults: { ttl: 60, swr: 300 }
+   * });
+   * ```
+   */
+  defaults?: CacheDefaults;
+
+  /**
+   * Custom key generator applied to all cache operations.
+   * Receives the full RequestContext and the default-generated key.
+   *
+   * @example
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const locale = ctx.cookie('locale') || 'en';
+   *   return `${locale}:${defaultKey}`;
+   * }
+   * ```
+   */
+  keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    defaultKey: string
+  ) => string | Promise<string>;
+}
+
+/**
+ * In-memory segment cache store.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production with multiple instances, use a distributed store
+ * like Cloudflare KV or Redis.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = new MemorySegmentCacheStore();
+ *
+ * // With defaults for cache() boundaries
+ * const store = new MemorySegmentCacheStore({
+ *   defaults: { ttl: 60 }
+ * });
+ *
+ * createRSCHandler({
+ *   router,
+ *   cache: { store }
+ * })
+ * ```
+ */
+export class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+  private cache: Map<string, CachedEntryData>;
+  readonly defaults?: CacheDefaults;
+  readonly keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    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>());
+    this.defaults = options?.defaults;
+    this.keyGenerator = options?.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    const cached = this.cache.get(key);
+
+    if (!cached) {
+      return null;
+    }
+
+    // Check expiration
+    if (Date.now() > cached.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Memory store doesn't support SWR - never triggers revalidation
+    return { data: cached, shouldRevalidate: false };
+  }
+
+  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 = {
+      ...data,
+      expiresAt: Date.now() + ttl * 1000,
+    };
+    this.cache.set(key, entry);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.cache.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics for debugging purposes.
+   * @internal
+   */
+  getStats(): { size: number; keys: string[] } {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+    };
+  }
+
+  /**
+   * Reset the global cache state.
+   * Useful for test isolation - call this in beforeEach to ensure
+   * tests don't share cache state via globalThis.
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   MemorySegmentCacheStore.resetGlobalCache();
+   * });
+   * ```
+   */
+  static resetGlobalCache(): void {
+    delete (globalThis as any)[CACHE_GLOBAL_KEY];
+  }
+}

package/src/cache/memory-store.ts

@@ -0,0 +1,253 @@
+/**
+ * In-Memory Cache Store
+ *
+ * Simple implementation for development and testing.
+ * Not suitable for production (no persistence, single-instance only).
+ *
+ * @internal This is reserved for future extensibility.
+ * For segment caching, use MemorySegmentCacheStore instead.
+ */
+
+import type {
+  CacheStore,
+  CacheEntry,
+  CacheValue,
+  CachePutOptions,
+  CacheMetadata,
+  CacheValueType,
+} from "./types.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default TTL when no explicit value is provided */
+const DEFAULT_TTL_SECONDS = 60;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface StoredEntry {
+  /** Stored value (streams/responses converted to ArrayBuffer) */
+  value: ArrayBuffer | string | object;
+  metadata: CacheMetadata;
+}
+
+/**
+ * In-memory cache store implementation
+ */
+export class MemoryCacheStore implements CacheStore {
+  private cache = new Map<string, StoredEntry>();
+
+  async match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined> {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    // Check expiration
+    if (entry.metadata.expiresAt && Date.now() > entry.metadata.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    // Reconstruct value based on original type
+    const value = this.reconstructValue(entry);
+
+    return {
+      value: value as T,
+      metadata: entry.metadata,
+    };
+  }
+
+  async put<T extends CacheValue>(
+    key: string,
+    value: T,
+    options?: CachePutOptions
+  ): Promise<void> {
+    const ttl = options?.ttl ?? DEFAULT_TTL_SECONDS;
+    const expiresAt = Date.now() + ttl * 1000;
+
+    // Detect value type and convert for storage
+    const { storedValue, valueType, responseHeaders, responseStatus } =
+      await this.prepareForStorage(value);
+
+    const metadata: CacheMetadata = {
+      ...options?.metadata,
+      expiresAt,
+      valueType,
+      responseHeaders,
+      responseStatus,
+    };
+
+    this.cache.set(key, {
+      value: storedValue,
+      metadata,
+    });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries (useful for testing)
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get current cache size (useful for testing/debugging)
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Manually purge expired entries
+   */
+  purgeExpired(): number {
+    const now = Date.now();
+    let purged = 0;
+
+    for (const [key, entry] of this.cache) {
+      if (entry.metadata.expiresAt && now > entry.metadata.expiresAt) {
+        this.cache.delete(key);
+        purged++;
+      }
+    }
+
+    return purged;
+  }
+
+  /**
+   * Prepare a value for storage
+   * Converts streams and responses to ArrayBuffer, detects type
+   */
+  private async prepareForStorage(value: CacheValue): Promise<{
+    storedValue: ArrayBuffer | string | object;
+    valueType: CacheValueType;
+    responseHeaders?: Record<string, string>;
+    responseStatus?: number;
+  }> {
+    // ReadableStream -> ArrayBuffer
+    if (value instanceof ReadableStream) {
+      return {
+        storedValue: await streamToArrayBuffer(value),
+        valueType: "stream",
+      };
+    }
+
+    // Response -> ArrayBuffer + headers/status
+    if (value instanceof Response) {
+      const headers: Record<string, string> = {};
+      value.headers.forEach((v, k) => {
+        headers[k] = v;
+      });
+
+      return {
+        storedValue: await value.clone().arrayBuffer(),
+        valueType: "response",
+        responseHeaders: headers,
+        responseStatus: value.status,
+      };
+    }
+
+    // ArrayBuffer -> store as-is
+    if (value instanceof ArrayBuffer) {
+      return {
+        storedValue: value,
+        valueType: "arraybuffer",
+      };
+    }
+
+    // String -> store as-is
+    if (typeof value === "string") {
+      return {
+        storedValue: value,
+        valueType: "string",
+      };
+    }
+
+    // Object -> store as-is (JSON-serializable)
+    return {
+      storedValue: value,
+      valueType: "object",
+    };
+  }
+
+  /**
+   * Reconstruct original value type from stored entry
+   */
+  private reconstructValue(entry: StoredEntry): CacheValue {
+    const { value, metadata } = entry;
+
+    switch (metadata.valueType) {
+      case "stream":
+        return arrayBufferToStream(value as ArrayBuffer);
+
+      case "response": {
+        const status = metadata.responseStatus ?? 200;
+        // Status codes 204 (No Content) and 304 (Not Modified) cannot have a body
+        const isNullBodyStatus = status === 204 || status === 304;
+        return new Response(isNullBodyStatus ? null : (value as ArrayBuffer), {
+          status,
+          headers: metadata.responseHeaders,
+        });
+      }
+
+      case "arraybuffer":
+      case "string":
+      case "object":
+      default:
+        return value as CacheValue;
+    }
+  }
+}
+
+/**
+ * Convert a ReadableStream to ArrayBuffer.
+ * @internal
+ */
+async function streamToArrayBuffer(
+  stream: ReadableStream<Uint8Array>
+): Promise<ArrayBuffer> {
+  const chunks: Uint8Array[] = [];
+  const reader = stream.getReader();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+
+  // Concatenate chunks
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  return result.buffer;
+}
+
+/**
+ * Convert an ArrayBuffer to a ReadableStream.
+ * @internal
+ */
+function arrayBufferToStream(buffer: ArrayBuffer): ReadableStream<Uint8Array> {
+  const uint8 = new Uint8Array(buffer);
+
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(uint8);
+      controller.close();
+    },
+  });
+}