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

package/src/cache/cf/__tests__/cf-cache-store.test.ts

@@ -1,428 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import {
-  CFCacheStore,
-  CACHE_STALE_AT_HEADER,
-  CACHE_STATUS_HEADER,
-} from "../cf-cache-store";
-import type { CachedEntryData } from "../../types";
-
-// ============================================================================
-// Mock Cloudflare Cache API
-// ============================================================================
-
-class MockCache {
-  private store = new Map<string, Response>();
-
-  async match(request: Request): Promise<Response | undefined> {
-    return this.store.get(request.url)?.clone();
-  }
-
-  async put(request: Request, response: Response): Promise<void> {
-    this.store.set(request.url, response.clone());
-  }
-
-  async delete(request: Request): Promise<boolean> {
-    return this.store.delete(request.url);
-  }
-
-  clear(): void {
-    this.store.clear();
-  }
-}
-
-class MockCaches {
-  private caches = new Map<string, MockCache>();
-  private _default = new MockCache();
-
-  async open(name: string): Promise<MockCache> {
-    if (!this.caches.has(name)) {
-      this.caches.set(name, new MockCache());
-    }
-    return this.caches.get(name)!;
-  }
-
-  get default(): MockCache {
-    return this._default;
-  }
-
-  clear(): void {
-    this._default.clear();
-    this.caches.forEach((cache) => cache.clear());
-    this.caches.clear();
-  }
-}
-
-// Install mock globally
-const mockCaches = new MockCaches();
-(globalThis as any).caches = mockCaches;
-
-// ============================================================================
-// Mock ExecutionContext
-// ============================================================================
-
-const createMockCtx = () => ({
-  waitUntil: vi.fn((p: Promise<any>) => p),
-  passThroughOnException: vi.fn(),
-});
-
-// ============================================================================
-// Test Data
-// ============================================================================
-
-const createTestData = (): CachedEntryData => ({
-  segments: [
-    {
-      encoded: "test-component",
-      metadata: {
-        id: "test-segment",
-        type: "route",
-        namespace: "test",
-        index: 0,
-        params: {},
-      },
-    },
-  ],
-  handles: {},
-  expiresAt: Date.now() + 60000,
-});
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe("CFCacheStore", () => {
-  beforeEach(() => {
-    mockCaches.clear();
-    vi.useFakeTimers();
-  });
-
-  describe("constructor", () => {
-    it("should require ctx", () => {
-      expect(() => new CFCacheStore({} as any)).toThrow(
-        "[CFCacheStore] ExecutionContext (ctx) is required"
-      );
-    });
-
-    it("should accept ctx and custom options", () => {
-      const store = new CFCacheStore({
-        ctx: createMockCtx(),
-        namespace: "custom-cache",
-        baseUrl: "https://custom.internal/",
-        defaults: { ttl: 120, swr: 600 },
-      });
-      expect(store.defaults).toEqual({ ttl: 120, swr: 600 });
-    });
-  });
-
-  describe("get/set", () => {
-    it("should return null for missing key", async () => {
-      const store = new CFCacheStore({ ctx: createMockCtx() });
-      const result = await store.get("missing-key");
-      expect(result).toBeNull();
-    });
-
-    it("should store and retrieve data", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      // Execute waitUntil callback
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const result = await store.get("test-key");
-
-      expect(result).not.toBeNull();
-      expect(result!.data).toEqual(data);
-      expect(result!.shouldRevalidate).toBe(false);
-    });
-
-    it("should set Cache-Control header with TTL", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Uses caches.default by default
-      const cache = mockCaches.default;
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=60");
-    });
-
-    it("should extend TTL with SWR window", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60, 300);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const cache = mockCaches.default;
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=360");
-    });
-
-    it("should use store defaults for SWR if not provided", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx, defaults: { swr: 120 } });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const cache = mockCaches.default;
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=180");
-    });
-
-    it("should use named cache when namespace is provided", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx, namespace: "custom-cache" });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const cache = await mockCaches.open("custom-cache");
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=60");
-    });
-
-    it("should use waitUntil for non-blocking writes", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-
-      expect(mockCtx.waitUntil).toHaveBeenCalledTimes(1);
-      expect(mockCtx.waitUntil).toHaveBeenCalledWith(expect.any(Promise));
-
-      // Wait for the write to complete
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Now the entry should be in cache
-      const result = await store.get("test-key");
-      expect(result).not.toBeNull();
-    });
-  });
-
-  describe("staleness headers", () => {
-    it("should set stale-at header based on TTL", async () => {
-      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
-
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const cache = mockCaches.default;
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      const staleAt = Number(response?.headers.get(CACHE_STALE_AT_HEADER));
-      const expectedStaleAt = Date.now() + 60 * 1000;
-
-      expect(staleAt).toBe(expectedStaleAt);
-    });
-
-    it("should set status header to HIT", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const cache = mockCaches.default;
-      const request = new Request("https://rsc-cache.internal.com/test-key");
-      const response = await cache.match(request);
-
-      expect(response?.headers.get(CACHE_STATUS_HEADER)).toBe("HIT");
-    });
-  });
-
-  describe("staleness detection and atomic revalidation", () => {
-    it("should return shouldRevalidate=false for fresh entries", async () => {
-      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
-
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Still fresh
-      vi.advanceTimersByTime(30 * 1000);
-
-      const result = await store.get("test-key");
-      expect(result?.shouldRevalidate).toBe(false);
-    });
-
-    it("should return shouldRevalidate=true and atomically mark REVALIDATING for stale entries", async () => {
-      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
-
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60, 300);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Past TTL but within SWR window
-      vi.advanceTimersByTime(120 * 1000);
-
-      // First get should return shouldRevalidate=true and mark as REVALIDATING
-      const result = await store.get("test-key");
-      expect(result?.shouldRevalidate).toBe(true);
-
-      // Verify the entry is now marked as REVALIDATING
-      const cache = mockCaches.default;
-      const request = new Request(
-        "https://rsc-cache.internal.com/" + encodeURIComponent("test-key")
-      );
-      const response = await cache.match(request);
-      expect(response?.headers.get(CACHE_STATUS_HEADER)).toBe("REVALIDATING");
-    });
-
-    it("should return shouldRevalidate=false when already REVALIDATING", async () => {
-      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
-
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60, 300);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Make it stale
-      vi.advanceTimersByTime(120 * 1000);
-
-      // First get - atomically marks as REVALIDATING
-      const result1 = await store.get("test-key");
-      expect(result1?.shouldRevalidate).toBe(true);
-
-      // Second get - already REVALIDATING, should not trigger again
-      const result2 = await store.get("test-key");
-      expect(result2?.shouldRevalidate).toBe(false);
-    });
-
-    it("should prevent thundering herd with sequential requests", async () => {
-      // Note: Real thundering herd prevention relies on CF Cache API's atomic semantics.
-      // This test verifies sequential requests work correctly - first triggers revalidation,
-      // subsequent ones see REVALIDATING status and don't trigger again.
-      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
-
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60, 300);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Make it stale
-      vi.advanceTimersByTime(120 * 1000);
-
-      // Sequential requests - first triggers revalidation
-      const result1 = await store.get("test-key");
-      expect(result1?.shouldRevalidate).toBe(true);
-      expect(result1?.data).toBeDefined();
-
-      // Subsequent requests see REVALIDATING status
-      const result2 = await store.get("test-key");
-      expect(result2?.shouldRevalidate).toBe(false);
-      expect(result2?.data).toBeDefined();
-
-      const result3 = await store.get("test-key");
-      expect(result3?.shouldRevalidate).toBe(false);
-      expect(result3?.data).toBeDefined();
-    });
-  });
-
-  describe("delete", () => {
-    it("should delete existing entry", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("test-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const deleted = await store.delete("test-key");
-
-      expect(deleted).toBe(true);
-
-      const result = await store.get("test-key");
-      expect(result).toBeNull();
-    });
-
-    it("should return false for non-existent entry", async () => {
-      const store = new CFCacheStore({ ctx: createMockCtx() });
-      const deleted = await store.delete("missing-key");
-      expect(deleted).toBe(false);
-    });
-  });
-
-  describe("key encoding", () => {
-    it("should handle special characters in keys", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      const key = "route:products/category=electronics&page=1";
-      await store.set(key, data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      const result = await store.get(key);
-      expect(result).not.toBeNull();
-      expect(result!.data).toEqual(data);
-    });
-  });
-
-  describe("baseUrl configuration", () => {
-    it("should use explicit baseUrl when provided", async () => {
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({
-        ctx: mockCtx,
-        baseUrl: "https://custom.example.com/",
-      });
-      const data = createTestData();
-
-      await store.set("custom-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Verify round-trip works with custom baseUrl
-      const result = await store.get("custom-key");
-      expect(result).not.toBeNull();
-      expect(result!.data).toEqual(data);
-    });
-
-    it("should use fallback when no requestContext available", async () => {
-      // Default behavior when getRequestContext returns null
-      const mockCtx = createMockCtx();
-      const store = new CFCacheStore({ ctx: mockCtx });
-      const data = createTestData();
-
-      await store.set("fallback-key", data, 60);
-      await mockCtx.waitUntil.mock.results[0].value;
-
-      // Verify round-trip works with fallback baseUrl
-      const result = await store.get("fallback-key");
-      expect(result).not.toBeNull();
-      expect(result!.data).toEqual(data);
-    });
-  });
-});

package/src/cache/memory-store.ts

@@ -1,253 +0,0 @@
-/**
- * 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();
-    },
-  });
-}