veryfront 0.0.81 → 0.0.82

package/esm/src/cache/module-cache.js

@@ -0,0 +1,214 @@
+/**
+ * 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 = null;
+/**
+ * Pod-level ESM cache singleton.
+ *
+ * Maps ESM specifiers to resolved URLs or file paths.
+ * Key format varies by usage.
+ */
+let esmCache = null;
+/**
+ * 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() {
+    if (!moduleCache) {
+        moduleCache = new LRUCache({
+            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() {
+    if (!esmCache) {
+        esmCache = new LRUCache({
+            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() {
+    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() {
+    const cache = getEsmCache();
+    return createMapInterface(cache);
+}
+/**
+ * Create a Map-compatible interface backed by an LRU cache.
+ */
+function createMapInterface(cache) {
+    // Create a proxy that delegates to the LRU cache
+    // This allows existing code expecting Map to work unchanged
+    return {
+        get(key) {
+            return cache.get(key);
+        },
+        set(key, value) {
+            cache.set(key, value);
+            return this;
+        },
+        has(key) {
+            return cache.has(key);
+        },
+        delete(key) {
+            return cache.delete(key);
+        },
+        clear() {
+            cache.clear();
+        },
+        get size() {
+            return cache.size;
+        },
+        // Required Map methods that iterate - these work but may be expensive
+        *keys() {
+            yield* cache.keys();
+        },
+        *values() {
+            for (const key of cache.keys()) {
+                const value = cache.get(key);
+                if (value !== undefined)
+                    yield value;
+            }
+        },
+        *entries() {
+            for (const key of cache.keys()) {
+                const value = cache.get(key);
+                if (value !== undefined)
+                    yield [key, value];
+            }
+        },
+        forEach(callback) {
+            for (const key of cache.keys()) {
+                const value = cache.get(key);
+                if (value !== undefined)
+                    callback(value, key, this);
+            }
+        },
+        [Symbol.iterator]() {
+            return this.entries();
+        },
+        [Symbol.toStringTag]: "Map",
+    };
+}
+/**
+ * Get statistics about the module caches.
+ */
+export function getModuleCacheStats() {
+    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() {
+    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) {
+    if (!moduleCache)
+        return 0;
+    let cleared = 0;
+    const keysToDelete = [];
+    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() {
+    moduleCache?.destroy();
+    esmCache?.destroy();
+    moduleCache = null;
+    esmCache = null;
+    logger.info("[ModuleCache] Module caches destroyed");
+}

package/esm/src/cache/multi-tier.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Multi-Tier Cache Abstraction
+ *
+ * Generic implementation for L1 → L2 → L3 cache flows with automatic backfill.
+ * This provides consistent caching behavior across the codebase:
+ *
+ * - L1: In-memory (fastest, per-pod, lost on restart)
+ * - L2: Local disk (fast, per-pod, survives restart)
+ * - L3: Distributed (Redis/API, cross-pod, shared state)
+ *
+ * When a cache hit occurs at a lower tier (e.g., L3), the value is automatically
+ * backfilled to higher tiers (L1, L2) for faster subsequent access.
+ *
+ * @module cache/multi-tier
+ */
+/**
+ * Generic cache tier interface.
+ * Each tier implements async get/set operations.
+ */
+export interface CacheTier<T = string> {
+    /** Tier name for logging/debugging */
+    readonly name: string;
+    /** Get a value from this tier */
+    get(key: string): Promise<T | null>;
+    /** Set a value in this tier */
+    set(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /** Delete a value from this tier */
+    delete?(key: string): Promise<void>;
+    /** Check if key exists (optional, uses get if not implemented) */
+    has?(key: string): Promise<boolean>;
+    /** Get multiple values (optional batch operation) */
+    getBatch?(keys: string[]): Promise<Map<string, T | null>>;
+    /** Set multiple values (optional batch operation) */
+    setBatch?(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>): Promise<void>;
+}
+/**
+ * Configuration for multi-tier cache.
+ */
+export interface MultiTierCacheConfig<T = string> {
+    /** Cache name for logging */
+    name: string;
+    /** L1: Memory tier (optional) */
+    l1?: CacheTier<T>;
+    /** L2: Disk tier (optional) */
+    l2?: CacheTier<T>;
+    /** L3: Distributed tier (optional) */
+    l3?: CacheTier<T>;
+    /** Default TTL in seconds for set operations */
+    defaultTtlSeconds?: number;
+    /** Whether to backfill higher tiers on lower-tier hits (default: true) */
+    backfillOnHit?: boolean;
+    /** Whether to use fire-and-forget for backfill operations (default: true) */
+    asyncBackfill?: boolean;
+}
+/**
+ * Cache hit statistics.
+ */
+export interface CacheStats {
+    /** Total get operations */
+    gets: number;
+    /** Hits at each tier */
+    l1Hits: number;
+    l2Hits: number;
+    l3Hits: number;
+    /** Total misses (no tier had the value) */
+    misses: number;
+    /** Set operations */
+    sets: number;
+    /** Backfill operations triggered */
+    backfills: number;
+}
+/**
+ * Multi-tier cache implementation.
+ *
+ * Provides automatic fallthrough from L1 → L2 → L3 with backfill on hits.
+ *
+ * @example
+ * ```typescript
+ * const cache = new MultiTierCache({
+ *   name: "http-module",
+ *   l1: new MemoryTier(),
+ *   l3: await CacheBackends.httpModule(),
+ *   defaultTtlSeconds: 86400,
+ * });
+ *
+ * const value = await cache.get("my-key");
+ * // If found in L3, automatically backfills L1
+ * ```
+ */
+export declare class MultiTierCache<T = string> {
+    private readonly config;
+    private stats;
+    constructor(config: MultiTierCacheConfig<T>);
+    /**
+     * Get a value from the cache.
+     *
+     * Checks tiers in order: L1 → L2 → L3.
+     * On hit at a lower tier, backfills higher tiers.
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in all tiers.
+     *
+     * Writes to all configured tiers in parallel (or sequentially if asyncBackfill=false).
+     */
+    set(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a value from all tiers.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get or compute a value.
+     *
+     * If the key exists in any tier, returns it.
+     * Otherwise, calls the compute function and stores the result in all tiers.
+     */
+    getOrCompute(key: string, computeFn: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+    /**
+     * Batch get multiple values.
+     *
+     * Uses batch operations where available for efficiency.
+     * Returns a map of key → value (null if not found).
+     */
+    getBatch(keys: string[]): Promise<Map<string, T | null>>;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats & {
+        hitRate: number;
+    };
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Backfill higher tiers with a value found at a lower tier.
+     */
+    private backfill;
+    /**
+     * Helper for individual gets when batch operation is not available.
+     */
+    private individualGets;
+}
+/**
+ * Create a memory-backed cache tier from a CacheBackend.
+ */
+export declare function createMemoryTier(backend: {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    del?(key: string): Promise<void>;
+    getBatch?(keys: string[]): Promise<Map<string, string | null>>;
+    setBatch?(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<void>;
+}): CacheTier<string>;
+/**
+ * Create a distributed cache tier from a CacheBackend.
+ */
+export declare function createDistributedTier(backend: {
+    readonly type: string;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    del?(key: string): Promise<void>;
+    getBatch?(keys: string[]): Promise<Map<string, string | null>>;
+    setBatch?(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<void>;
+}): CacheTier<string>;
+//# sourceMappingURL=multi-tier.d.ts.map

package/esm/src/cache/multi-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-tier.d.ts","sourceRoot":"","sources":["../../../src/src/cache/multi-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,MAAM;IACnC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,iCAAiC;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpC,+BAA+B;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D,oCAAoC;IACpC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,kEAAkE;IAClE,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpC,qDAAqD;IACrD,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAE1D,qDAAqD;IACrD,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,MAAM;IAC9C,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb,iCAAiC;IACjC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAElB,+BAA+B;IAC/B,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAElB,sCAAsC;IACtC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAElB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,MAAM;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAI+B;IAEtD,OAAO,CAAC,KAAK,CAQX;gBAEU,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAS3C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAyEnC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC9D;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;OAKG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;IASb;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAiG9D;;OAEG;IACH,QAAQ,IAAI,UAAU,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;IAM5C;;OAEG;IACH,UAAU,IAAI,IAAI;IAYlB;;OAEG;IACH,OAAO,CAAC,QAAQ;IA0BhB;;OAEG;YACW,cAAc;CAS7B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxF,GAAG,SAAS,CAAC,MAAM,CAAC,CASpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxF,GAAG,SAAS,CAAC,MAAM,CAAC,CASpB"}