fscr 6.2.6 → 7.3.0

package/dist/lib/cache/file-watcher.js

@@ -0,0 +1,193 @@
+/**
+ * File watcher for automatic cache invalidation
+ * @module cache/file-watcher
+ */
+
+import { watch } from 'fs';
+import { resolve } from 'path';
+import EventEmitter from 'events';
+
+/**
+ * FileWatcher - Monitors files and triggers cache invalidation
+ * @class
+ * @extends EventEmitter
+ */
+class FileWatcher extends EventEmitter {
+    /**
+     * Create a file watcher
+     * @param {CacheManager} cacheManager - Cache manager instance
+     * @param {Object} options - Configuration options
+     * @param {number} [options.debounceMs=100] - Debounce time in milliseconds
+     */
+    constructor(cacheManager, options = {}) {
+        super();
+
+        this.cacheManager = cacheManager;
+        this.debounceMs = options.debounceMs || 100;
+        this.watchers = new Map();
+        this.debounceTimers = new Map();
+
+        // Statistics
+        this.stats = {
+            filesWatched: 0,
+            changeEvents: 0,
+            invalidations: 0
+        };
+    }
+
+    /**
+     * Watch a file for changes
+     * @param {string} filePath - Path to file
+     * @returns {void}
+     */
+    watch(filePath) {
+        const absolutePath = resolve(filePath);
+
+        // Don't watch if already watching
+        if (this.watchers.has(absolutePath)) {
+            return;
+        }
+
+        try {
+            const watcher = watch(absolutePath, (eventType) => {
+                this._handleChange(absolutePath, eventType);
+            });
+
+            // unref() so watching a file never keeps a one-shot CLI process alive.
+            if (typeof watcher.unref === 'function') {
+                watcher.unref();
+            }
+
+            watcher.on('error', (error) => {
+                console.warn(`File watcher error for ${absolutePath}:`, error.message);
+                this.unwatch(absolutePath);
+            });
+
+            this.watchers.set(absolutePath, watcher);
+            this.stats.filesWatched++;
+
+            this.emit('watch', { filePath: absolutePath });
+        } catch (error) {
+            console.warn(`Failed to watch file ${absolutePath}:`, error.message);
+        }
+    }
+
+    /**
+     * Stop watching a file
+     * @param {string} filePath - Path to file
+     * @returns {boolean} True if file was being watched
+     */
+    unwatch(filePath) {
+        const absolutePath = resolve(filePath);
+        const watcher = this.watchers.get(absolutePath);
+
+        if (watcher) {
+            watcher.close();
+            this.watchers.delete(absolutePath);
+            this.stats.filesWatched--;
+            this.emit('unwatch', { filePath: absolutePath });
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Handle file change event
+     * @private
+     * @param {string} filePath - Path to changed file
+     * @param {string} eventType - Type of change event
+     */
+    _handleChange(filePath, eventType) {
+        // Clear existing debounce timer
+        if (this.debounceTimers.has(filePath)) {
+            clearTimeout(this.debounceTimers.get(filePath));
+        }
+
+        // Debounce the invalidation
+        const timer = setTimeout(() => {
+            this._invalidateFile(filePath, eventType);
+            this.debounceTimers.delete(filePath);
+        }, this.debounceMs);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+
+        this.debounceTimers.set(filePath, timer);
+    }
+
+    /**
+     * Invalidate cache entries for a file
+     * @private
+     * @param {string} filePath - Path to file
+     * @param {string} eventType - Type of change event
+     */
+    _invalidateFile(filePath, eventType) {
+        this.stats.changeEvents++;
+
+        const invalidated = this.cacheManager.invalidateFile(filePath);
+
+        if (invalidated > 0) {
+            this.stats.invalidations += invalidated;
+            this.emit('invalidate', {
+                filePath,
+                eventType,
+                count: invalidated
+            });
+        }
+    }
+
+    /**
+     * Stop watching all files
+     * @returns {void}
+     */
+    unwatchAll() {
+        for (const [filePath, watcher] of this.watchers.entries()) {
+            watcher.close();
+        }
+        this.watchers.clear();
+        this.stats.filesWatched = 0;
+
+        // Clear all debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+
+        this.emit('unwatchAll');
+    }
+
+    /**
+     * Get watcher statistics
+     * @returns {Object} Statistics object
+     */
+    getStats() {
+        return {
+            filesWatched: this.stats.filesWatched,
+            changeEvents: this.stats.changeEvents,
+            invalidations: this.stats.invalidations,
+            watchedFiles: Array.from(this.watchers.keys())
+        };
+    }
+
+    /**
+     * Check if a file is being watched
+     * @param {string} filePath - Path to file
+     * @returns {boolean} True if being watched
+     */
+    isWatching(filePath) {
+        const absolutePath = resolve(filePath);
+        return this.watchers.has(absolutePath);
+    }
+
+    /**
+     * Destroy the file watcher and cleanup resources
+     * @returns {void}
+     */
+    destroy() {
+        this.unwatchAll();
+        this.removeAllListeners();
+    }
+}
+
+export default FileWatcher;

package/dist/lib/cache/index.js

@@ -0,0 +1,422 @@
+/**
+ * Cache Manager with TTL support
+ * Provides in-memory caching with automatic invalidation
+ * @module cache
+ */
+
+import { createHash } from 'crypto';
+import { statSync } from 'fs';
+import EventEmitter from 'events';
+
+/**
+ * Cache entry structure
+ * @typedef {Object} CacheEntry
+ * @property {*} data - Cached data
+ * @property {number} timestamp - Creation timestamp
+ * @property {number} ttl - Time to live in milliseconds
+ * @property {string} key - Cache key
+ * @property {string} [filePath] - Associated file path for file-based caching
+ * @property {number} [mtime] - File modification time
+ */
+
+/**
+ * Cache statistics
+ * @typedef {Object} CacheStats
+ * @property {number} hits - Cache hit count
+ * @property {number} misses - Cache miss count
+ * @property {number} invalidations - Cache invalidation count
+ * @property {number} size - Current cache size
+ * @property {number} hitRate - Cache hit rate percentage
+ */
+
+/**
+ * CacheManager - In-memory cache with TTL and file watching
+ * @class
+ * @extends EventEmitter
+ */
+class CacheManager extends EventEmitter {
+    /**
+     * Create a cache manager
+     * @param {Object} options - Configuration options
+     * @param {number} [options.defaultTTL=300000] - Default TTL in milliseconds (5 minutes)
+     * @param {number} [options.maxSize=100] - Maximum number of cache entries
+     * @param {boolean} [options.enableStats=true] - Enable statistics tracking
+     */
+    constructor(options = {}) {
+        super();
+
+        this.cache = new Map();
+        this.defaultTTL = options.defaultTTL || 300000; // 5 minutes
+        this.maxSize = options.maxSize || 100;
+        this.enableStats = options.enableStats !== false;
+
+        // Statistics
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            invalidations: 0,
+            evictions: 0,
+            startTime: Date.now()
+        };
+
+        // Cleanup interval - run every minute.
+        // unref() so this background timer never keeps a one-shot CLI process alive.
+        this.cleanupInterval = setInterval(() => this._cleanup(), 60000);
+        if (this.cleanupInterval && typeof this.cleanupInterval.unref === "function") {
+            this.cleanupInterval.unref();
+        }
+
+        // Ensure cleanup on exit
+        process.on('exit', () => this.destroy());
+    }
+
+    /**
+     * Generate a cache key from file path and modification time
+     * @param {string} filePath - File path
+     * @returns {string} Cache key
+     */
+    generateFileKey(filePath) {
+        try {
+            const stats = statSync(filePath);
+            const mtime = stats.mtimeMs;
+            return this._hash(`${filePath}:${mtime}`);
+        } catch (error) {
+            throw new Error(`Failed to generate cache key for ${filePath}: ${error.message}`);
+        }
+    }
+
+    /**
+     * Generate a hash-based cache key
+     * @private
+     * @param {string} input - Input string
+     * @returns {string} Hash
+     */
+    _hash(input) {
+        return createHash('sha256').update(input).digest('hex').substring(0, 16);
+    }
+
+    /**
+     * Get value from cache
+     * @template T
+     * @param {string} key - Cache key
+     * @returns {T|null} Cached value or null
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            this._recordMiss();
+            return null;
+        }
+
+        // Check if entry is expired
+        if (this._isExpired(entry)) {
+            this.invalidate(key);
+            this._recordMiss();
+            return null;
+        }
+
+        // Check if file-based cache is still valid
+        if (entry.filePath) {
+            try {
+                const stats = statSync(entry.filePath);
+                if (stats.mtimeMs !== entry.mtime) {
+                    this.invalidate(key);
+                    this._recordMiss();
+                    return null;
+                }
+            } catch (error) {
+                // File might have been deleted
+                this.invalidate(key);
+                this._recordMiss();
+                return null;
+            }
+        }
+
+        this._recordHit();
+        this.emit('hit', { key, data: entry.data });
+        return entry.data;
+    }
+
+    /**
+     * Set value in cache
+     * @template T
+     * @param {string} key - Cache key
+     * @param {T} data - Data to cache
+     * @param {Object} [options] - Cache options
+     * @param {number} [options.ttl] - Custom TTL in milliseconds
+     * @param {string} [options.filePath] - Associated file path
+     * @returns {void}
+     */
+    set(key, data, options = {}) {
+        // Evict oldest entry if cache is full
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            this._evictOldest();
+        }
+
+        const ttl = options.ttl !== undefined ? options.ttl : this.defaultTTL;
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl,
+            key
+        };
+
+        // Add file tracking if provided
+        if (options.filePath) {
+            try {
+                const stats = statSync(options.filePath);
+                entry.filePath = options.filePath;
+                entry.mtime = stats.mtimeMs;
+            } catch (error) {
+                console.warn(`Warning: Could not stat file ${options.filePath}`);
+            }
+        }
+
+        this.cache.set(key, entry);
+        this.emit('set', { key, data, ttl });
+    }
+
+    /**
+     * Invalidate a cache entry
+     * @param {string} key - Cache key
+     * @returns {boolean} True if entry was deleted
+     */
+    invalidate(key) {
+        const deleted = this.cache.delete(key);
+        if (deleted) {
+            this.stats.invalidations++;
+            this.emit('invalidate', { key });
+        }
+        return deleted;
+    }
+
+    /**
+     * Invalidate all entries for a specific file path
+     * @param {string} filePath - File path
+     * @returns {number} Number of invalidated entries
+     */
+    invalidateFile(filePath) {
+        let count = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.filePath === filePath) {
+                this.invalidate(key);
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Clear all cache entries
+     * @returns {void}
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.stats.invalidations += size;
+        this.emit('clear');
+    }
+
+    /**
+     * Check if a cache entry is valid
+     * @param {string} key - Cache key
+     * @returns {boolean} True if valid
+     */
+    isValid(key) {
+        const entry = this.cache.get(key);
+        if (!entry) return false;
+
+        if (this._isExpired(entry)) return false;
+
+        // Check file modification time if applicable
+        if (entry.filePath) {
+            try {
+                const stats = statSync(entry.filePath);
+                return stats.mtimeMs === entry.mtime;
+            } catch {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Check if an entry is expired
+     * @private
+     * @param {CacheEntry} entry - Cache entry
+     * @returns {boolean} True if expired
+     */
+    _isExpired(entry) {
+        if (entry.ttl === 0) return false; // TTL of 0 means never expire
+        return Date.now() - entry.timestamp > entry.ttl;
+    }
+
+    /**
+     * Get cache statistics
+     * @returns {CacheStats} Statistics object
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? (this.stats.hits / total) * 100 : 0;
+        const uptime = Date.now() - this.stats.startTime;
+
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            invalidations: this.stats.invalidations,
+            evictions: this.stats.evictions,
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hitRate: hitRate.toFixed(2),
+            uptime,
+            totalRequests: total
+        };
+    }
+
+    /**
+     * Reset statistics
+     * @returns {void}
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            invalidations: 0,
+            evictions: 0,
+            startTime: Date.now()
+        };
+    }
+
+    /**
+     * Cleanup expired entries
+     * @private
+     * @returns {number} Number of cleaned entries
+     */
+    _cleanup() {
+        let cleaned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (this._isExpired(entry)) {
+                this.cache.delete(key);
+                cleaned++;
+            }
+        }
+
+        if (cleaned > 0) {
+            this.emit('cleanup', { count: cleaned });
+        }
+
+        return cleaned;
+    }
+
+    /**
+     * Evict the oldest cache entry
+     * @private
+     * @returns {void}
+     */
+    _evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            this.emit('evict', { key: oldestKey });
+        }
+    }
+
+    /**
+     * Record a cache hit
+     * @private
+     */
+    _recordHit() {
+        if (this.enableStats) {
+            this.stats.hits++;
+        }
+    }
+
+    /**
+     * Record a cache miss
+     * @private
+     */
+    _recordMiss() {
+        if (this.enableStats) {
+            this.stats.misses++;
+        }
+    }
+
+    /**
+     * Destroy the cache manager and cleanup resources
+     * @returns {void}
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.clear();
+        this.removeAllListeners();
+    }
+
+    /**
+     * Get all cache keys
+     * @returns {string[]} Array of cache keys
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+
+    /**
+     * Get cache size
+     * @returns {number} Number of entries
+     */
+    size() {
+        return this.cache.size;
+    }
+
+    /**
+     * Check if cache has a key
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists
+     */
+    has(key) {
+        return this.cache.has(key) && this.isValid(key);
+    }
+}
+
+// Singleton instance
+let globalCache = null;
+
+/**
+ * Get the global cache instance
+ * @param {Object} [options] - Configuration options
+ * @returns {CacheManager} Cache manager instance
+ */
+export function getCache(options) {
+    if (!globalCache) {
+        globalCache = new CacheManager(options);
+    }
+    return globalCache;
+}
+
+/**
+ * Reset the global cache instance
+ * @returns {void}
+ */
+export function resetCache() {
+    if (globalCache) {
+        globalCache.destroy();
+        globalCache = null;
+    }
+}
+
+export { CacheManager };
+export default CacheManager;