@skillsmith/core 0.5.5 → 0.5.6

package/dist/cache/CacheManager.js

@@ -0,0 +1,367 @@
+/**
+ * SMI-644: Unified Cache Manager
+ * Provides high-level cache operations with:
+ * - Popular query detection (dynamic TTL)
+ * - Background refresh for hot entries
+ * - Cache invalidation coordination
+ * - Statistics and monitoring
+ */
+import { TTLTier, POPULARITY_THRESHOLDS, calculateTTLTier, getTTLTierName } from './CacheEntry.js';
+import { EnhancedTieredCache, } from './TieredCache.js';
+/**
+ * Unified Cache Manager
+ * Coordinates L1/L2 caching with intelligent TTL management
+ */
+export class CacheManager {
+    cache;
+    config;
+    queryFrequencies = new Map();
+    refreshTimer = null;
+    /** SMI-683: Use Map<key, Promise> for proper deduplication of concurrent refreshes */
+    activeRefreshes = new Map();
+    refreshCallback = null;
+    // Track invalidation for coordination
+    lastInvalidation = 0;
+    invalidationCallbacks = [];
+    /**
+     * @deprecated Use CacheManager.create(config) — async factory with WASM fallback.
+     * This constructor always throws to prevent silent data loss.
+     */
+    constructor(_config) {
+        throw new Error('[CacheManager] Cannot construct synchronously. ' +
+            'Use await CacheManager.create(config) instead.');
+    }
+    /**
+     * Async factory — supports both native and WASM SQLite.
+     *
+     * @param config - Cache manager configuration
+     * @returns Fully initialised CacheManager instance
+     */
+    static async create(config = {}) {
+        const instance = Object.create(CacheManager.prototype);
+        instance.cache = await EnhancedTieredCache.create(config);
+        instance.config = {
+            enableBackgroundRefresh: config.enableBackgroundRefresh ?? true,
+            refreshIntervalMs: config.refreshIntervalMs ?? 30 * 1000,
+            maxConcurrentRefreshes: config.maxConcurrentRefreshes ?? 3,
+        };
+        instance.queryFrequencies = new Map();
+        instance.refreshTimer = null;
+        instance.activeRefreshes = new Map();
+        instance.refreshCallback = config.refreshCallback ?? null;
+        instance.lastInvalidation = 0;
+        instance.invalidationCallbacks = [];
+        // Start background refresh if enabled
+        if (instance.config.enableBackgroundRefresh && instance.refreshCallback) {
+            instance.startBackgroundRefresh();
+        }
+        return instance;
+    }
+    /**
+     * Generate cache key from search options
+     */
+    static generateKey(options) {
+        // Normalize query: lowercase, trim, collapse whitespace
+        const normalizedQuery = options.query.toLowerCase().trim().replace(/\s+/g, ' ');
+        // Sort and stringify filters for consistent keys
+        const sortedFilters = options.filters
+            ? JSON.stringify(Object.keys(options.filters)
+                .sort()
+                .reduce((acc, key) => {
+                acc[key] = options.filters[key];
+                return acc;
+            }, {}))
+            : '';
+        // Include pagination in key
+        const pagination = `${options.limit ?? 20}:${options.offset ?? 0}`;
+        return `search:${normalizedQuery}:${sortedFilters}:${pagination}`;
+    }
+    /**
+     * Parse search options from cache key
+     * SMI-683: Fixed regex to handle empty filters (was: .+? requires at least 1 char)
+     */
+    static parseKey(key) {
+        // Allow empty filters section with (.*?) instead of (.+?)
+        const match = key.match(/^search:(.+?):(.*?):(\d+):(\d+)$/);
+        if (!match)
+            return null;
+        const [, query, filtersJson, limit, offset] = match;
+        let filters;
+        try {
+            filters = filtersJson ? JSON.parse(filtersJson) : undefined;
+        }
+        catch {
+            filters = undefined;
+        }
+        return {
+            query,
+            filters,
+            limit: parseInt(limit, 10),
+            offset: parseInt(offset, 10),
+        };
+    }
+    /**
+     * Get cached results for search options
+     */
+    get(options) {
+        const key = CacheManager.generateKey(options);
+        const result = this.cache.get(key);
+        if (result) {
+            // Track query frequency for popularity detection
+            this.recordQueryHit(key);
+        }
+        return result;
+    }
+    /**
+     * Get or compute cached results
+     * @param options Search options
+     * @param compute Function to compute results if not cached
+     */
+    async getOrCompute(options, compute) {
+        const cached = this.get(options);
+        if (cached) {
+            return cached;
+        }
+        const result = await compute();
+        this.set(options, result.results, result.totalCount);
+        return result;
+    }
+    /**
+     * Store results in cache with automatic TTL detection
+     */
+    set(options, results, totalCount) {
+        const key = CacheManager.generateKey(options);
+        // Determine TTL tier based on query frequency
+        const ttlTier = this.determineTTLTier(key);
+        this.cache.set(key, results, totalCount, ttlTier);
+    }
+    /**
+     * Check if results are cached
+     */
+    has(options) {
+        const key = CacheManager.generateKey(options);
+        return this.cache.has(key);
+    }
+    /**
+     * Delete specific cached result
+     */
+    delete(options) {
+        const key = CacheManager.generateKey(options);
+        this.queryFrequencies.delete(key);
+        return this.cache.delete(key);
+    }
+    /**
+     * Invalidate all cached results
+     * Should be called when the skill index is updated
+     */
+    invalidateAll() {
+        this.cache.invalidateAll();
+        this.queryFrequencies.clear();
+        this.lastInvalidation = Date.now();
+        // Notify listeners
+        for (const callback of this.invalidationCallbacks) {
+            try {
+                callback();
+            }
+            catch {
+                // Ignore callback errors
+            }
+        }
+    }
+    /**
+     * Register callback for invalidation events
+     */
+    onInvalidate(callback) {
+        this.invalidationCallbacks.push(callback);
+        return () => {
+            const index = this.invalidationCallbacks.indexOf(callback);
+            if (index >= 0) {
+                this.invalidationCallbacks.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Get time since last invalidation
+     */
+    getTimeSinceInvalidation() {
+        return this.lastInvalidation > 0 ? Date.now() - this.lastInvalidation : -1;
+    }
+    /**
+     * Prune expired entries
+     */
+    prune() {
+        this.pruneQueryFrequencies();
+        return this.cache.prune();
+    }
+    /**
+     * Get comprehensive cache statistics
+     */
+    getStats() {
+        const cacheStats = this.cache.getStats();
+        // Count queries by frequency tier
+        const now = Date.now();
+        let popular = 0;
+        let standard = 0;
+        let rare = 0;
+        for (const [, freq] of this.queryFrequencies) {
+            const tier = calculateTTLTier(freq.firstSeen, freq.hits, now);
+            if (tier === TTLTier.POPULAR)
+                popular++;
+            else if (tier === TTLTier.RARE)
+                rare++;
+            else
+                standard++;
+        }
+        return {
+            ...cacheStats,
+            queryFrequencies: { popular, standard, rare },
+            backgroundRefresh: {
+                active: this.activeRefreshes.size, // Map.size works the same as Set.size
+                lastRun: this.refreshTimer ? Date.now() : 0,
+            },
+        };
+    }
+    /**
+     * Get detailed hit rate by TTL tier
+     */
+    getHitRateByTier() {
+        const stats = this.cache.getStats();
+        const total = stats.totalHits + stats.totalMisses;
+        return {
+            overall: total > 0 ? stats.totalHits / total : 0,
+            l1: stats.l1Hits + stats.l1Misses > 0 ? stats.l1Hits / (stats.l1Hits + stats.l1Misses) : 0,
+            l2: stats.l2Hits + stats.l2Misses > 0 ? stats.l2Hits / (stats.l2Hits + stats.l2Misses) : 0,
+        };
+    }
+    /**
+     * Set the refresh callback for background refresh
+     */
+    setRefreshCallback(callback) {
+        this.refreshCallback = callback;
+        // Start background refresh if not already running
+        if (this.config.enableBackgroundRefresh && !this.refreshTimer) {
+            this.startBackgroundRefresh();
+        }
+    }
+    /**
+     * Close cache manager and cleanup resources
+     */
+    close() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.cache.close();
+        this.queryFrequencies.clear();
+        this.invalidationCallbacks = [];
+    }
+    // Private methods
+    /**
+     * Record a hit for query frequency tracking
+     */
+    recordQueryHit(key) {
+        const now = Date.now();
+        const existing = this.queryFrequencies.get(key);
+        if (existing) {
+            existing.hits++;
+            existing.lastSeen = now;
+        }
+        else {
+            this.queryFrequencies.set(key, {
+                hits: 1,
+                firstSeen: now,
+                lastSeen: now,
+            });
+        }
+    }
+    /**
+     * Determine TTL tier based on query frequency
+     */
+    determineTTLTier(key) {
+        const freq = this.queryFrequencies.get(key);
+        if (!freq) {
+            return TTLTier.STANDARD;
+        }
+        return calculateTTLTier(freq.firstSeen, freq.hits);
+    }
+    /**
+     * Prune old query frequency entries
+     */
+    pruneQueryFrequencies() {
+        const now = Date.now();
+        const maxAge = 24 * 60 * 60 * 1000; // 24 hours
+        for (const [key, freq] of this.queryFrequencies) {
+            if (now - freq.lastSeen > maxAge) {
+                this.queryFrequencies.delete(key);
+            }
+        }
+    }
+    /**
+     * Start background refresh loop
+     */
+    startBackgroundRefresh() {
+        if (this.refreshTimer)
+            return;
+        this.refreshTimer = setInterval(() => {
+            this.performBackgroundRefresh().catch(() => {
+                // Ignore refresh errors - background task should not crash
+            });
+        }, this.config.refreshIntervalMs);
+        // Unref timer to not block process exit
+        this.refreshTimer.unref();
+    }
+    /**
+     * Perform background refresh for entries approaching expiration
+     */
+    async performBackgroundRefresh() {
+        if (!this.refreshCallback)
+            return;
+        const keysToRefresh = this.cache.getEntriesNeedingRefresh();
+        // Limit concurrent refreshes
+        const available = this.config.maxConcurrentRefreshes - this.activeRefreshes.size;
+        if (available <= 0)
+            return;
+        const toProcess = keysToRefresh
+            .filter((key) => !this.activeRefreshes.has(key))
+            .slice(0, available);
+        for (const key of toProcess) {
+            this.refreshEntry(key).catch(() => {
+                // Ignore individual refresh errors
+            });
+        }
+    }
+    /**
+     * Refresh a single cache entry
+     * SMI-683: Fixed race condition by using Map<string, Promise<void>> for proper deduplication.
+     * Concurrent calls for the same key now return the same promise instance.
+     */
+    refreshEntry(key) {
+        if (!this.refreshCallback)
+            return Promise.resolve();
+        // SMI-683: Check if already refreshing - return existing promise
+        const existing = this.activeRefreshes.get(key);
+        if (existing) {
+            return existing;
+        }
+        // Create new refresh promise
+        const refreshPromise = (async () => {
+            try {
+                const options = CacheManager.parseKey(key);
+                if (!options)
+                    return;
+                const result = await this.refreshCallback(options);
+                this.set(options, result.results, result.totalCount);
+            }
+            finally {
+                // SMI-683: Always cleanup on completion or error
+                this.activeRefreshes.delete(key);
+            }
+        })();
+        // Store promise for deduplication
+        this.activeRefreshes.set(key, refreshPromise);
+        return refreshPromise;
+    }
+}
+// Re-export types and utilities
+export { TTLTier, getTTLTierName, POPULARITY_THRESHOLDS };
+//# sourceMappingURL=CacheManager.js.map

package/dist/cache/CacheManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheManager.js","sourceRoot":"","sources":["../../src/cache/CacheManager.ts"],"names":[],"mappings":"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"}

package/dist/cache/TieredCache.d.ts

@@ -0,0 +1,110 @@
+/**
+ * SMI-644: Enhanced Tiered Cache with TTL Management
+ * L1 (memory) + L2 (SQLite) with automatic promotion/demotion
+ */
+import type { SearchResult } from './lru.js';
+import { TTLTier } from './CacheEntry.js';
+/** L1 cache configuration */
+export interface L1Config {
+    maxEntries?: number;
+    maxMemoryBytes?: number;
+}
+/** L2 cache configuration */
+export interface L2Config {
+    dbPath: string;
+    pruneIntervalMs?: number;
+}
+/** Combined tiered cache configuration */
+export interface TieredCacheConfig {
+    l1?: L1Config;
+    l2?: L2Config;
+    enablePromotion?: boolean;
+    enableDemotion?: boolean;
+}
+/** Cache statistics */
+export interface TieredCacheStats {
+    l1Hits: number;
+    l1Misses: number;
+    l2Hits: number;
+    l2Misses: number;
+    totalHits: number;
+    totalMisses: number;
+    hitRate: number;
+    l1Size: number;
+    l2Size: number;
+    promotions: number;
+    demotions: number;
+    evictions: number;
+    popularEntries: number;
+    rareEntries: number;
+}
+/**
+ * Enhanced two-tier cache with TTL management
+ */
+export declare class EnhancedTieredCache {
+    private l1;
+    private db;
+    private config;
+    private pruneTimer;
+    private stats;
+    private stmts;
+    /**
+     * @deprecated If l2.dbPath is passed, use EnhancedTieredCache.create(config) instead —
+     * the async factory supports both native and WASM SQLite. Passing l2.dbPath to this
+     * constructor throws to prevent silent data loss.
+     */
+    constructor(config?: TieredCacheConfig);
+    /**
+     * Async factory — supports both native and WASM SQLite.
+     *
+     * @param config - Cache configuration; l2.dbPath is opened via createDatabaseAsync
+     * @returns Fully initialised EnhancedTieredCache instance
+     */
+    static create(config?: TieredCacheConfig): Promise<EnhancedTieredCache>;
+    private initFromConfig;
+    private initL2Async;
+    /**
+     * Get entry from cache (L1 first, then L2)
+     */
+    get(key: string): {
+        results: SearchResult[];
+        totalCount: number;
+    } | undefined;
+    /**
+     * Store entry in cache
+     */
+    set(key: string, results: SearchResult[], totalCount: number, ttlTier?: TTLTier): void;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * Delete specific entry
+     */
+    delete(key: string): boolean;
+    /**
+     * Invalidate all entries (called on index update)
+     */
+    invalidateAll(): void;
+    /**
+     * Prune expired entries
+     */
+    prune(): number;
+    /**
+     * Get entries that need background refresh
+     */
+    getEntriesNeedingRefresh(): string[];
+    /**
+     * Get cache statistics
+     */
+    getStats(): TieredCacheStats;
+    /**
+     * Demote entry from L1 to L2
+     */
+    private demoteToL2;
+    /**
+     * Close cache and cleanup resources
+     */
+    close(): void;
+}
+//# sourceMappingURL=TieredCache.d.ts.map

package/dist/cache/TieredCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TieredCache.d.ts","sourceRoot":"","sources":["../../src/cache/TieredCache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAGL,OAAO,EAQR,MAAM,iBAAiB,CAAA;AAExB,6BAA6B;AAC7B,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,6BAA6B;AAC7B,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,uBAAuB;AACvB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;CACpB;AAuBD;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,EAAE,CAAwB;IAClC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAA8C;IAGhE,OAAO,CAAC,KAAK,CAQZ;IAGD,OAAO,CAAC,KAAK,CASE;IAEf;;;;OAIG;gBACS,MAAM,GAAE,iBAAsB;IAW1C;;;;;OAKG;WACU,MAAM,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAajF,OAAO,CAAC,cAAc;YA6BR,WAAW;IAmCzB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAuD7E;;OAEG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,EAAE,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,OAA0B,GAClC,IAAI;IA0BP;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAqBzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAkB5B;;OAEG;IACH,aAAa,IAAI,IAAI;IAOrB;;OAEG;IACH,KAAK,IAAI,MAAM;IAiBf;;OAEG;IACH,wBAAwB,IAAI,MAAM,EAAE;IAcpC;;OAEG;IACH,QAAQ,IAAI,gBAAgB;IA+C5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAoBlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAWd"}