veryfront 0.0.81 → 0.0.82

package/src/src/cache/hash.ts

@@ -0,0 +1,205 @@
+/**
+ * Standardized Cache Hashing Utilities
+ *
+ * Provides consistent hashing for cache keys across the codebase.
+ * All cache keys should use these utilities to ensure:
+ * - Consistent format with type prefixes
+ * - Collision resistance between different cache types
+ * - Easy debugging and key parsing
+ *
+ * Key format: `{type}:{hash}` or `{type}:{version}:{hash}`
+ *
+ * @module cache/hash
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { simpleHash } from "../utils/hash-utils.js";
+
+/**
+ * Cache key types for different cache domains.
+ * Using type prefixes prevents collisions between different caches.
+ */
+export type CacheKeyType =
+  | "http" // HTTP module cache (esm.sh bundles)
+  | "mod" // Module transform cache
+  | "esm" // ESM resolution cache
+  | "render" // Render result cache
+  | "mdx" // MDX bundle cache
+  | "css" // CSS/Tailwind cache
+  | "file" // File content cache
+  | "config"; // Configuration cache
+
+/**
+ * Fast, synchronous hash function for cache keys.
+ *
+ * Uses DJB2 algorithm - good distribution, very fast.
+ * Returns a positive number suitable for string conversion.
+ *
+ * @param input - String to hash
+ * @returns Positive integer hash
+ */
+export function fastHash(input: string): number {
+  let hash = 5381;
+
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) + hash) ^ input.charCodeAt(i);
+  }
+
+  return hash >>> 0; // Convert to unsigned 32-bit
+}
+
+/**
+ * Convert a hash number to a compact string representation.
+ *
+ * Uses base36 for compact output (0-9, a-z).
+ */
+export function hashToString(hash: number): string {
+  return hash.toString(36);
+}
+
+/**
+ * Fast synchronous hash that returns a string.
+ *
+ * Combines fastHash + hashToString for convenience.
+ */
+export function hashString(input: string): string {
+  return hashToString(fastHash(input));
+}
+
+/**
+ * Generate a cache key with type prefix.
+ *
+ * Format: `{type}:{hash}`
+ *
+ * @example
+ * ```typescript
+ * getCacheKey("http", "https://esm.sh/react@18.3.1")
+ * // Returns: "http:1abc2def"
+ *
+ * getCacheKey("mod", "pages/index.tsx")
+ * // Returns: "mod:xyz789"
+ * ```
+ */
+export function getCacheKey(type: CacheKeyType, input: string): string {
+  const hash = hashString(input);
+  return `${type}:${hash}`;
+}
+
+/**
+ * Generate a versioned cache key with type prefix.
+ *
+ * Format: `{type}:v{version}:{hash}`
+ *
+ * @example
+ * ```typescript
+ * getVersionedCacheKey("mod", 12, "pages/index.tsx:abc123")
+ * // Returns: "mod:v12:xyz789"
+ * ```
+ */
+export function getVersionedCacheKey(
+  type: CacheKeyType,
+  version: number | string,
+  input: string,
+): string {
+  const hash = hashString(input);
+  return `${type}:v${version}:${hash}`;
+}
+
+/**
+ * Generate a cache key with multiple components.
+ *
+ * Useful for keys that depend on multiple inputs.
+ * Components are joined with colons before hashing.
+ *
+ * @example
+ * ```typescript
+ * getCompoundCacheKey("mod", ["projectId", "filePath", "contentHash"])
+ * // Returns: "mod:abc123"
+ * ```
+ */
+export function getCompoundCacheKey(type: CacheKeyType, components: string[]): string {
+  const combined = components.join(":");
+  return getCacheKey(type, combined);
+}
+
+/**
+ * Parse a cache key into its components.
+ *
+ * @returns The type prefix and hash, or null if invalid format
+ */
+export function parseCacheKey(
+  key: string,
+): { type: string; hash: string; version?: string } | null {
+  const parts = key.split(":");
+
+  if (parts.length < 2) return null;
+
+  const type = parts[0]!;
+  const rest = parts.slice(1);
+
+  // Check for version: type:vN:hash
+  if (rest[0]?.startsWith("v") && /^v\d+$/.test(rest[0])) {
+    return {
+      type,
+      version: rest[0].slice(1),
+      hash: rest.slice(1).join(":"),
+    };
+  }
+
+  return {
+    type,
+    hash: rest.join(":"),
+  };
+}
+
+/**
+ * SHA-256 async hash for content-addressed keys.
+ *
+ * Use this when you need cryptographic strength (e.g., content hashes).
+ * For cache keys where speed matters more, use hashString().
+ */
+export async function sha256Hash(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await dntShim.crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Short SHA-256 hash (8 characters).
+ *
+ * Good balance between collision resistance and key length.
+ */
+export async function sha256Short(input: string): Promise<string> {
+  const full = await sha256Hash(input);
+  return full.slice(0, 8);
+}
+
+/**
+ * Generate HTTP bundle filename from URL.
+ *
+ * Consistent with existing http-cache.ts format: `http-{hash}.mjs`
+ */
+export function getHttpBundleFilename(normalizedUrl: string): string {
+  const hash = simpleHash(normalizedUrl);
+  return `http-${hash}.mjs`;
+}
+
+/**
+ * Extract hash from HTTP bundle filename.
+ *
+ * @returns The hash string, or null if not a valid bundle filename
+ */
+export function parseHttpBundleFilename(filename: string): string | null {
+  const match = filename.match(/^http-(\d+)\.mjs$/);
+  return match?.[1] ?? null;
+}
+
+/**
+ * Check if a value looks like a cache key.
+ */
+export function isCacheKey(value: string): boolean {
+  return /^[a-z]+:[a-z0-9]+/.test(value);
+}

package/src/src/cache/index.ts

@@ -1,4 +1,7 @@
 export * from "./backend.js";
+export * from "./multi-tier.js";
+export * from "./module-cache.js";
+export * from "./hash.js";
 
 export {
   type CacheKeyContext,

package/src/src/cache/module-cache.ts

@@ -0,0 +1,252 @@
+/**
+ * Pod-Level Module Cache Singleton
+ *
+ * Provides shared module caches that persist across all RenderPipeline instances
+ * within a pod. This dramatically improves cache hit rates for unchanged modules
+ * compared to per-request caches.
+ *
+ * Features:
+ * - LRU eviction to bound memory usage
+ * - TTL-based expiration to pick up source changes
+ * - Automatic registration with cache registry for debugging
+ * - Project-scoped invalidation support
+ *
+ * @module cache/module-cache
+ */
+
+import { LRUCache } from "../utils/lru-wrapper.js";
+import { rendererLogger as logger } from "../utils/index.js";
+import { registerLRUCache } from "./registry.js";
+import {
+  ESM_CACHE_MAX_ENTRIES,
+  ESM_CACHE_TTL_MS,
+  MODULE_CACHE_MAX_ENTRIES,
+  MODULE_CACHE_TTL_MS,
+} from "../utils/constants/cache.js";
+
+/**
+ * Pod-level module cache singleton.
+ *
+ * Maps module cache keys to transformed temp file paths.
+ * Key format: `{projectId}:{filePath}`
+ */
+let moduleCache: LRUCache<string, string> | null = null;
+
+/**
+ * Pod-level ESM cache singleton.
+ *
+ * Maps ESM specifiers to resolved URLs or file paths.
+ * Key format varies by usage.
+ */
+let esmCache: LRUCache<string, string> | null = null;
+
+/**
+ * Cache statistics for monitoring.
+ */
+interface ModuleCacheStats {
+  moduleCache: {
+    size: number;
+    maxEntries: number;
+    ttlMs: number;
+  };
+  esmCache: {
+    size: number;
+    maxEntries: number;
+    ttlMs: number;
+  };
+}
+
+/**
+ * Get or create the pod-level module cache.
+ *
+ * The cache is created lazily on first access and persists for the pod's lifetime.
+ * Uses LRU eviction and TTL-based expiration.
+ */
+export function getModuleCache(): LRUCache<string, string> {
+  if (!moduleCache) {
+    moduleCache = new LRUCache<string, string>({
+      maxEntries: MODULE_CACHE_MAX_ENTRIES,
+      ttlMs: MODULE_CACHE_TTL_MS,
+    });
+
+    // Register with cache registry for debugging and invalidation
+    registerLRUCache("pod-module-cache", moduleCache);
+
+    logger.info("[ModuleCache] Pod-level module cache initialized", {
+      maxEntries: MODULE_CACHE_MAX_ENTRIES,
+      ttlMs: MODULE_CACHE_TTL_MS,
+    });
+  }
+  return moduleCache;
+}
+
+/**
+ * Get or create the pod-level ESM cache.
+ *
+ * Used for caching ESM resolution results (specifier → URL mappings).
+ */
+export function getEsmCache(): LRUCache<string, string> {
+  if (!esmCache) {
+    esmCache = new LRUCache<string, string>({
+      maxEntries: ESM_CACHE_MAX_ENTRIES,
+      ttlMs: ESM_CACHE_TTL_MS,
+    });
+
+    // Register with cache registry for debugging and invalidation
+    registerLRUCache("pod-esm-cache", esmCache);
+
+    logger.info("[ModuleCache] Pod-level ESM cache initialized", {
+      maxEntries: ESM_CACHE_MAX_ENTRIES,
+      ttlMs: ESM_CACHE_TTL_MS,
+    });
+  }
+  return esmCache;
+}
+
+/**
+ * Create a Map-compatible interface for the module cache.
+ *
+ * This provides backward compatibility with code expecting Map<string, string>.
+ * The underlying storage is the pod-level LRU cache singleton.
+ */
+export function createModuleCache(): Map<string, string> {
+  const cache = getModuleCache();
+  return createMapInterface(cache);
+}
+
+/**
+ * Create a Map-compatible interface for the ESM cache.
+ *
+ * This provides backward compatibility with code expecting Map<string, string>.
+ */
+export function createEsmCache(): Map<string, string> {
+  const cache = getEsmCache();
+  return createMapInterface(cache);
+}
+
+/**
+ * Create a Map-compatible interface backed by an LRU cache.
+ */
+function createMapInterface(cache: LRUCache<string, string>): Map<string, string> {
+  // Create a proxy that delegates to the LRU cache
+  // This allows existing code expecting Map to work unchanged
+  return {
+    get(key: string): string | undefined {
+      return cache.get(key);
+    },
+    set(key: string, value: string): Map<string, string> {
+      cache.set(key, value);
+      return this;
+    },
+    has(key: string): boolean {
+      return cache.has(key);
+    },
+    delete(key: string): boolean {
+      return cache.delete(key);
+    },
+    clear(): void {
+      cache.clear();
+    },
+    get size(): number {
+      return cache.size;
+    },
+    // Required Map methods that iterate - these work but may be expensive
+    *keys(): IterableIterator<string> {
+      yield* cache.keys();
+    },
+    *values(): IterableIterator<string> {
+      for (const key of cache.keys()) {
+        const value = cache.get(key);
+        if (value !== undefined) yield value;
+      }
+    },
+    *entries(): IterableIterator<[string, string]> {
+      for (const key of cache.keys()) {
+        const value = cache.get(key);
+        if (value !== undefined) yield [key, value];
+      }
+    },
+    forEach(callback: (value: string, key: string, map: Map<string, string>) => void): void {
+      for (const key of cache.keys()) {
+        const value = cache.get(key);
+        if (value !== undefined) callback(value, key, this);
+      }
+    },
+    [Symbol.iterator](): IterableIterator<[string, string]> {
+      return this.entries();
+    },
+    [Symbol.toStringTag]: "Map",
+  } as Map<string, string>;
+}
+
+/**
+ * Get statistics about the module caches.
+ */
+export function getModuleCacheStats(): ModuleCacheStats {
+  return {
+    moduleCache: {
+      size: moduleCache?.size ?? 0,
+      maxEntries: MODULE_CACHE_MAX_ENTRIES,
+      ttlMs: MODULE_CACHE_TTL_MS,
+    },
+    esmCache: {
+      size: esmCache?.size ?? 0,
+      maxEntries: ESM_CACHE_MAX_ENTRIES,
+      ttlMs: ESM_CACHE_TTL_MS,
+    },
+  };
+}
+
+/**
+ * Clear all module caches.
+ *
+ * Used for invalidation when project content changes.
+ */
+export function clearModuleCaches(): void {
+  moduleCache?.clear();
+  esmCache?.clear();
+  logger.info("[ModuleCache] All module caches cleared");
+}
+
+/**
+ * Clear module cache entries for a specific project.
+ *
+ * @param projectId - The project ID to clear entries for
+ * @returns Number of entries cleared
+ */
+export function clearModuleCacheForProject(projectId: string): number {
+  if (!moduleCache) return 0;
+
+  let cleared = 0;
+  const keysToDelete: string[] = [];
+
+  for (const key of moduleCache.keys()) {
+    if (key.startsWith(`${projectId}:`)) {
+      keysToDelete.push(key);
+    }
+  }
+
+  for (const key of keysToDelete) {
+    moduleCache.delete(key);
+    cleared++;
+  }
+
+  if (cleared > 0) {
+    logger.info("[ModuleCache] Cleared module cache for project", { projectId, cleared });
+  }
+
+  return cleared;
+}
+
+/**
+ * Destroy the module caches and cleanup resources.
+ *
+ * Should be called on server shutdown.
+ */
+export function destroyModuleCaches(): void {
+  moduleCache?.destroy();
+  esmCache?.destroy();
+  moduleCache = null;
+  esmCache = null;
+  logger.info("[ModuleCache] Module caches destroyed");
+}