@memberjunction/core 2.127.0 → 2.129.0

package/dist/generic/localCacheManager.js

@@ -0,0 +1,856 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalCacheManager = exports.CacheCategory = void 0;
+const global_1 = require("@memberjunction/global");
+const logging_1 = require("./logging");
+// ============================================================================
+// DEFAULT CONFIGURATION
+// ============================================================================
+const DEFAULT_CONFIG = {
+    enabled: true,
+    maxSizeBytes: 50 * 1024 * 1024, // 50MB
+    maxEntries: 1000,
+    defaultTTLMs: 5 * 60 * 1000, // 5 minutes
+    evictionPolicy: 'lru'
+};
+// ============================================================================
+// STORAGE CATEGORIES
+// ============================================================================
+/**
+ * Storage categories for organizing cache data.
+ * These map to IndexedDB object stores or localStorage key prefixes.
+ */
+exports.CacheCategory = {
+    /** Cache for RunView results */
+    RunViewCache: 'RunViewCache',
+    /** Cache for RunQuery results */
+    RunQueryCache: 'RunQueryCache',
+    /** Cache for Dataset results */
+    DatasetCache: 'DatasetCache',
+    /** Cache for metadata */
+    Metadata: 'Metadata',
+    /** Default category for uncategorized data */
+    Default: 'default'
+};
+// ============================================================================
+// LOCAL CACHE MANAGER
+// ============================================================================
+/**
+ * LocalCacheManager is a singleton that provides a unified caching abstraction
+ * for datasets, RunView results, and RunQuery results. It wraps ILocalStorageProvider
+ * for actual storage and maintains an internal registry of all cached items.
+ *
+ * Key features:
+ * - Typed methods for datasets, RunViews, and RunQueries
+ * - Automatic cache metadata tracking (timestamps, access counts, sizes)
+ * - Hit/miss statistics for performance monitoring
+ * - Eviction policies (LRU, LFU, FIFO) for memory management
+ * - Dashboard-friendly registry queries
+ *
+ * Usage:
+ * ```typescript
+ * // Initialize during app startup
+ * await LocalCacheManager.Instance.Initialize(storageProvider);
+ *
+ * // Cache a dataset
+ * await LocalCacheManager.Instance.SetDataset('MyDataset', filters, dataset, keyPrefix);
+ *
+ * // Retrieve cached data
+ * const cached = await LocalCacheManager.Instance.GetDataset('MyDataset', filters, keyPrefix);
+ * ```
+ */
+class LocalCacheManager extends global_1.BaseSingleton {
+    /**
+     * Returns the singleton instance of LocalCacheManager
+     */
+    static get Instance() {
+        return super.getInstance();
+    }
+    constructor() {
+        super();
+        this._storageProvider = null;
+        this._registry = new Map();
+        this._initialized = false;
+        this._initializePromise = null;
+        this._stats = { hits: 0, misses: 0 };
+        this._config = { ...DEFAULT_CONFIG };
+        this.REGISTRY_KEY = '__MJ_CACHE_REGISTRY__';
+        this._persistTimeout = null;
+    }
+    // ========================================================================
+    // INITIALIZATION
+    // ========================================================================
+    /**
+     * Initialize the cache manager with a storage provider.
+     * This should be called during app startup after the storage provider is available.
+     *
+     * This method is safe to call multiple times - subsequent calls will return the same
+     * promise as the first caller, ensuring initialization only happens once.
+     *
+     * @param storageProvider - The local storage provider to use for persistence
+     * @param config - Optional configuration overrides
+     * @returns A promise that resolves when initialization is complete
+     */
+    Initialize(storageProvider, config) {
+        // If already initialized, return immediately
+        if (this._initialized) {
+            return Promise.resolve();
+        }
+        // If initialization is in progress, return the existing promise
+        // so all callers await the same initialization
+        if (this._initializePromise) {
+            return this._initializePromise;
+        }
+        // First caller - start initialization and store the promise
+        this._initializePromise = this.doInitialize(storageProvider, config);
+        return this._initializePromise;
+    }
+    /**
+     * Internal initialization logic - only called once by the first caller
+     */
+    async doInitialize(storageProvider, config) {
+        this._storageProvider = storageProvider;
+        if (config) {
+            this._config = { ...this._config, ...config };
+        }
+        await this.loadRegistry();
+        this._initialized = true;
+    }
+    /**
+     * Returns whether the cache manager has been initialized
+     */
+    get IsInitialized() {
+        return this._initialized;
+    }
+    /**
+     * Returns the current configuration
+     */
+    get Config() {
+        return { ...this._config };
+    }
+    /**
+     * Updates the configuration at runtime
+     */
+    UpdateConfig(config) {
+        this._config = { ...this._config, ...config };
+    }
+    // ========================================================================
+    // DATASET CACHING
+    // ========================================================================
+    /**
+     * Stores a dataset in the local cache.
+     *
+     * @param name - The dataset name
+     * @param itemFilters - Optional filters applied to the dataset
+     * @param dataset - The dataset result to cache
+     * @param keyPrefix - Prefix for the cache key (typically includes connection info)
+     */
+    async SetDataset(name, itemFilters, dataset, keyPrefix) {
+        if (!this._storageProvider || !this._config.enabled)
+            return;
+        const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
+        const value = JSON.stringify(dataset);
+        const sizeBytes = this.estimateSize(value);
+        // Check if we need to evict entries
+        await this.evictIfNeeded(sizeBytes);
+        try {
+            await this._storageProvider.SetItem(key, value, exports.CacheCategory.DatasetCache);
+            await this._storageProvider.SetItem(key + '_date', dataset.LatestUpdateDate.toISOString(), exports.CacheCategory.DatasetCache);
+            this.registerEntry({
+                key,
+                type: 'dataset',
+                name,
+                params: itemFilters ? { itemFilters } : undefined,
+                cachedAt: Date.now(),
+                lastAccessedAt: Date.now(),
+                accessCount: 1,
+                sizeBytes,
+                maxUpdatedAt: dataset.LatestUpdateDate.toISOString()
+            });
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.SetDataset failed: ${e}`);
+        }
+    }
+    /**
+     * Retrieves a cached dataset.
+     *
+     * @param name - The dataset name
+     * @param itemFilters - Optional filters applied to the dataset
+     * @param keyPrefix - Prefix for the cache key
+     * @returns The cached dataset or null if not found
+     */
+    async GetDataset(name, itemFilters, keyPrefix) {
+        if (!this._storageProvider || !this._config.enabled)
+            return null;
+        const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
+        try {
+            const value = await this._storageProvider.GetItem(key, exports.CacheCategory.DatasetCache);
+            if (value) {
+                this.recordAccess(key);
+                this._stats.hits++;
+                return JSON.parse(value);
+            }
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.GetDataset failed: ${e}`);
+        }
+        this._stats.misses++;
+        return null;
+    }
+    /**
+     * Gets the timestamp of a cached dataset.
+     *
+     * @param name - The dataset name
+     * @param itemFilters - Optional filters applied to the dataset
+     * @param keyPrefix - Prefix for the cache key
+     * @returns The cache timestamp or null if not found
+     */
+    async GetDatasetTimestamp(name, itemFilters, keyPrefix) {
+        if (!this._storageProvider)
+            return null;
+        const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
+        try {
+            const dateStr = await this._storageProvider.GetItem(key + '_date', exports.CacheCategory.DatasetCache);
+            return dateStr ? new Date(dateStr) : null;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    /**
+     * Clears a cached dataset.
+     *
+     * @param name - The dataset name
+     * @param itemFilters - Optional filters applied to the dataset
+     * @param keyPrefix - Prefix for the cache key
+     */
+    async ClearDataset(name, itemFilters, keyPrefix) {
+        if (!this._storageProvider)
+            return;
+        const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
+        try {
+            await this._storageProvider.Remove(key, exports.CacheCategory.DatasetCache);
+            await this._storageProvider.Remove(key + '_date', exports.CacheCategory.DatasetCache);
+            this.unregisterEntry(key);
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.ClearDataset failed: ${e}`);
+        }
+    }
+    /**
+     * Checks if a dataset is cached.
+     *
+     * @param name - The dataset name
+     * @param itemFilters - Optional filters applied to the dataset
+     * @param keyPrefix - Prefix for the cache key
+     * @returns True if the dataset is cached
+     */
+    async IsDatasetCached(name, itemFilters, keyPrefix) {
+        if (!this._storageProvider)
+            return false;
+        const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
+        try {
+            const val = await this._storageProvider.GetItem(key, exports.CacheCategory.DatasetCache);
+            return val != null;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    // ========================================================================
+    // RUNVIEW CACHING
+    // ========================================================================
+    /**
+     * Generates a human-readable cache fingerprint for a RunView request.
+     * This fingerprint uniquely identifies the query based on its parameters and connection.
+     *
+     * Format: EntityName|filter|orderBy|resultType|maxRows|startRow|connection
+     * Example: Users|Active=1|Name ASC|simple|100|0|localhost
+     *
+     * @param params - The RunView parameters
+     * @param connectionPrefix - Prefix identifying the connection (e.g., server URL) to differentiate caches across connections
+     * @returns A unique, human-readable fingerprint string
+     */
+    GenerateRunViewFingerprint(params, connectionPrefix) {
+        const entity = params.EntityName?.trim() || 'Unknown';
+        const filter = (params.ExtraFilter || '').trim();
+        const orderBy = (params.OrderBy || '').trim();
+        const resultType = params.ResultType || 'simple';
+        const maxRows = params.MaxRows ?? -1;
+        const startRow = params.StartRow ?? 0;
+        const connection = connectionPrefix || '';
+        // Build human-readable fingerprint with pipe separators
+        // Format: Entity|Filter|OrderBy|ResultType|MaxRows|StartRow|Connection
+        const parts = [
+            entity,
+            filter || '_', // Use underscore for empty filter
+            orderBy || '_', // Use underscore for empty orderBy
+            resultType,
+            maxRows.toString(),
+            startRow.toString()
+        ];
+        // Only include connection if provided
+        if (connection) {
+            parts.push(connection);
+        }
+        return parts.join('|');
+    }
+    /**
+     * Stores a RunView result in the cache.
+     *
+     * @param fingerprint - The cache fingerprint (from GenerateRunViewFingerprint)
+     * @param params - The original RunView parameters
+     * @param results - The results to cache
+     * @param maxUpdatedAt - The latest __mj_UpdatedAt from the results
+     * @param rowCount - Optional row count (defaults to results.length if not provided)
+     */
+    async SetRunViewResult(fingerprint, params, results, maxUpdatedAt, rowCount) {
+        if (!this._storageProvider || !this._config.enabled)
+            return;
+        const actualRowCount = rowCount ?? results.length;
+        const value = JSON.stringify({ results, maxUpdatedAt, rowCount: actualRowCount });
+        const sizeBytes = this.estimateSize(value);
+        // Check if we need to evict entries
+        await this.evictIfNeeded(sizeBytes);
+        try {
+            await this._storageProvider.SetItem(fingerprint, value, exports.CacheCategory.RunViewCache);
+            this.registerEntry({
+                key: fingerprint,
+                type: 'runview',
+                name: params.EntityName || 'Unknown',
+                fingerprint,
+                params: {
+                    EntityName: params.EntityName,
+                    ExtraFilter: params.ExtraFilter,
+                    OrderBy: params.OrderBy,
+                    ResultType: params.ResultType,
+                    MaxRows: params.MaxRows
+                },
+                cachedAt: Date.now(),
+                lastAccessedAt: Date.now(),
+                accessCount: 1,
+                sizeBytes,
+                maxUpdatedAt,
+                rowCount: actualRowCount
+            });
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.SetRunViewResult failed: ${e}`);
+        }
+    }
+    /**
+     * Retrieves a cached RunView result.
+     *
+     * @param fingerprint - The cache fingerprint
+     * @returns The cached results, maxUpdatedAt, and rowCount, or null if not found
+     */
+    async GetRunViewResult(fingerprint) {
+        if (!this._storageProvider || !this._config.enabled)
+            return null;
+        try {
+            const value = await this._storageProvider.GetItem(fingerprint, exports.CacheCategory.RunViewCache);
+            if (value) {
+                this.recordAccess(fingerprint);
+                this._stats.hits++;
+                const parsed = JSON.parse(value);
+                // Handle legacy entries that may not have rowCount
+                return {
+                    results: parsed.results,
+                    maxUpdatedAt: parsed.maxUpdatedAt,
+                    rowCount: parsed.rowCount ?? parsed.results?.length ?? 0
+                };
+            }
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.GetRunViewResult failed: ${e}`);
+        }
+        this._stats.misses++;
+        return null;
+    }
+    /**
+     * Invalidates a cached RunView result.
+     *
+     * @param fingerprint - The cache fingerprint to invalidate
+     */
+    async InvalidateRunViewResult(fingerprint) {
+        if (!this._storageProvider)
+            return;
+        try {
+            await this._storageProvider.Remove(fingerprint, exports.CacheCategory.RunViewCache);
+            this.unregisterEntry(fingerprint);
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.InvalidateRunViewResult failed: ${e}`);
+        }
+    }
+    /**
+     * Invalidates all cached RunView results for a specific entity.
+     * Useful when an entity's data changes and all related caches should be cleared.
+     *
+     * @param entityName - The entity name to invalidate
+     */
+    async InvalidateEntityCaches(entityName) {
+        if (!this._storageProvider)
+            return;
+        const normalizedName = entityName.toLowerCase().trim();
+        const toRemove = [];
+        for (const [key, entry] of this._registry.entries()) {
+            if (entry.type === 'runview' && entry.name.toLowerCase().trim() === normalizedName) {
+                toRemove.push(key);
+            }
+        }
+        for (const key of toRemove) {
+            try {
+                await this._storageProvider.Remove(key, exports.CacheCategory.RunViewCache);
+                this._registry.delete(key);
+            }
+            catch (e) {
+                (0, logging_1.LogError)(`LocalCacheManager.InvalidateEntityCaches failed for key ${key}: ${e}`);
+            }
+        }
+        await this.persistRegistry();
+    }
+    // ========================================================================
+    // RUNQUERY CACHING
+    // ========================================================================
+    /**
+     * Generates a human-readable cache fingerprint for a RunQuery request.
+     *
+     * Format: QueryName|QueryID|params|connection
+     * Example: GetActiveUsers|abc123|{"status":"active"}|localhost
+     *
+     * @param queryId - The query ID
+     * @param queryName - The query name
+     * @param parameters - Optional query parameters
+     * @param connectionPrefix - Prefix identifying the connection (e.g., server URL) to differentiate caches across connections
+     * @returns A unique, human-readable fingerprint string
+     */
+    GenerateRunQueryFingerprint(queryId, queryName, parameters, connectionPrefix) {
+        const name = queryName?.trim() || 'Unknown';
+        const id = queryId || '_';
+        const params = parameters ? JSON.stringify(parameters) : '_';
+        const connection = connectionPrefix || '';
+        // Build human-readable fingerprint with pipe separators
+        // Format: QueryName|QueryID|Params|Connection
+        const parts = [name, id, params];
+        // Only include connection if provided
+        if (connection) {
+            parts.push(connection);
+        }
+        return parts.join('|');
+    }
+    /**
+     * Stores a RunQuery result in the cache.
+     *
+     * @param fingerprint - The cache fingerprint
+     * @param queryName - The query name for display
+     * @param results - The results to cache
+     * @param maxUpdatedAt - The latest update timestamp (for smart cache validation)
+     * @param rowCount - Optional row count (defaults to results.length if not provided)
+     * @param queryId - Optional query ID for reference
+     * @param ttlMs - Optional TTL in milliseconds (for cache expiry tracking)
+     */
+    async SetRunQueryResult(fingerprint, queryName, results, maxUpdatedAt, rowCount, queryId, ttlMs) {
+        if (!this._storageProvider || !this._config.enabled)
+            return;
+        const actualRowCount = rowCount ?? results.length;
+        const value = JSON.stringify({ results, maxUpdatedAt, rowCount: actualRowCount, queryId });
+        const sizeBytes = this.estimateSize(value);
+        // Check if we need to evict entries
+        await this.evictIfNeeded(sizeBytes);
+        const now = Date.now();
+        const expiresAt = ttlMs ? now + ttlMs : undefined;
+        try {
+            await this._storageProvider.SetItem(fingerprint, value, exports.CacheCategory.RunQueryCache);
+            this.registerEntry({
+                key: fingerprint,
+                type: 'runquery',
+                name: queryName,
+                fingerprint,
+                cachedAt: now,
+                lastAccessedAt: now,
+                accessCount: 1,
+                sizeBytes,
+                maxUpdatedAt,
+                rowCount: actualRowCount,
+                expiresAt
+            });
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.SetRunQueryResult failed: ${e}`);
+        }
+    }
+    /**
+     * Retrieves a cached RunQuery result.
+     *
+     * @param fingerprint - The cache fingerprint
+     * @returns The cached results, maxUpdatedAt, rowCount, and queryId, or null if not found
+     */
+    async GetRunQueryResult(fingerprint) {
+        if (!this._storageProvider || !this._config.enabled)
+            return null;
+        // Check if entry has expired
+        const entry = this._registry.get(fingerprint);
+        if (entry?.expiresAt && Date.now() > entry.expiresAt) {
+            // Entry has expired, invalidate it
+            await this.InvalidateRunQueryResult(fingerprint);
+            this._stats.misses++;
+            return null;
+        }
+        try {
+            const value = await this._storageProvider.GetItem(fingerprint, exports.CacheCategory.RunQueryCache);
+            if (value) {
+                this.recordAccess(fingerprint);
+                this._stats.hits++;
+                const parsed = JSON.parse(value);
+                // Handle legacy entries that may not have rowCount
+                return {
+                    results: parsed.results,
+                    maxUpdatedAt: parsed.maxUpdatedAt,
+                    rowCount: parsed.rowCount ?? parsed.results?.length ?? 0,
+                    queryId: parsed.queryId
+                };
+            }
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.GetRunQueryResult failed: ${e}`);
+        }
+        this._stats.misses++;
+        return null;
+    }
+    /**
+     * Invalidates a cached RunQuery result.
+     *
+     * @param fingerprint - The cache fingerprint to invalidate
+     */
+    async InvalidateRunQueryResult(fingerprint) {
+        if (!this._storageProvider)
+            return;
+        try {
+            await this._storageProvider.Remove(fingerprint, exports.CacheCategory.RunQueryCache);
+            this.unregisterEntry(fingerprint);
+        }
+        catch (e) {
+            (0, logging_1.LogError)(`LocalCacheManager.InvalidateRunQueryResult failed: ${e}`);
+        }
+    }
+    /**
+     * Invalidates all cached RunQuery results for a specific query.
+     * Useful when a query's underlying data changes and all related caches should be cleared.
+     *
+     * @param queryName - The query name to invalidate
+     */
+    async InvalidateQueryCaches(queryName) {
+        if (!this._storageProvider)
+            return;
+        const normalizedName = queryName.toLowerCase().trim();
+        const toRemove = [];
+        for (const [key, entry] of this._registry.entries()) {
+            if (entry.type === 'runquery' && entry.name.toLowerCase().trim() === normalizedName) {
+                toRemove.push(key);
+            }
+        }
+        for (const key of toRemove) {
+            try {
+                await this._storageProvider.Remove(key, exports.CacheCategory.RunQueryCache);
+                this._registry.delete(key);
+            }
+            catch (e) {
+                (0, logging_1.LogError)(`LocalCacheManager.InvalidateQueryCaches failed for key ${key}: ${e}`);
+            }
+        }
+        await this.persistRegistry();
+    }
+    /**
+     * Gets the cache status (fingerprint data) for a RunQuery result.
+     * Used for smart cache validation with the server.
+     *
+     * @param fingerprint - The cache fingerprint
+     * @returns The cache status with maxUpdatedAt and rowCount, or null if not found/expired
+     */
+    async GetRunQueryCacheStatus(fingerprint) {
+        const cached = await this.GetRunQueryResult(fingerprint);
+        if (!cached)
+            return null;
+        return {
+            maxUpdatedAt: cached.maxUpdatedAt,
+            rowCount: cached.rowCount
+        };
+    }
+    // ========================================================================
+    // REGISTRY QUERIES (FOR DASHBOARD)
+    // ========================================================================
+    /**
+     * Returns all cache entries for dashboard display.
+     */
+    GetAllEntries() {
+        return [...this._registry.values()];
+    }
+    /**
+     * Returns cache entries filtered by type.
+     *
+     * @param type - The cache entry type to filter by
+     */
+    GetEntriesByType(type) {
+        return this.GetAllEntries().filter(e => e.type === type);
+    }
+    /**
+     * Returns comprehensive cache statistics.
+     */
+    GetStats() {
+        const entries = this.GetAllEntries();
+        const byType = {
+            dataset: { count: 0, sizeBytes: 0 },
+            runview: { count: 0, sizeBytes: 0 },
+            runquery: { count: 0, sizeBytes: 0 }
+        };
+        for (const entry of entries) {
+            byType[entry.type].count++;
+            byType[entry.type].sizeBytes += entry.sizeBytes;
+        }
+        const timestamps = entries.map(e => e.cachedAt);
+        return {
+            totalEntries: entries.length,
+            totalSizeBytes: entries.reduce((sum, e) => sum + e.sizeBytes, 0),
+            byType,
+            oldestEntry: timestamps.length ? Math.min(...timestamps) : 0,
+            newestEntry: timestamps.length ? Math.max(...timestamps) : 0,
+            hits: this._stats.hits,
+            misses: this._stats.misses
+        };
+    }
+    /**
+     * Calculates the cache hit rate as a percentage.
+     */
+    GetHitRate() {
+        const total = this._stats.hits + this._stats.misses;
+        return total > 0 ? (this._stats.hits / total) * 100 : 0;
+    }
+    // ========================================================================
+    // BULK OPERATIONS
+    // ========================================================================
+    /**
+     * Clears all cache entries of a specific type.
+     *
+     * @param type - The cache entry type to clear
+     * @returns The number of entries cleared
+     */
+    async ClearByType(type) {
+        if (!this._storageProvider)
+            return 0;
+        const entries = this.GetEntriesByType(type);
+        const category = this.getCategoryForType(type);
+        for (const entry of entries) {
+            try {
+                await this._storageProvider.Remove(entry.key, category);
+                if (entry.type === 'dataset') {
+                    await this._storageProvider.Remove(entry.key + '_date', category);
+                }
+                this._registry.delete(entry.key);
+            }
+            catch (e) {
+                (0, logging_1.LogError)(`LocalCacheManager.ClearByType failed for key ${entry.key}: ${e}`);
+            }
+        }
+        await this.persistRegistry();
+        return entries.length;
+    }
+    /**
+     * Clears all cache entries.
+     *
+     * @returns The number of entries cleared
+     */
+    async ClearAll() {
+        if (!this._storageProvider)
+            return 0;
+        const count = this._registry.size;
+        for (const entry of this._registry.values()) {
+            try {
+                const category = this.getCategoryForType(entry.type);
+                await this._storageProvider.Remove(entry.key, category);
+                if (entry.type === 'dataset') {
+                    await this._storageProvider.Remove(entry.key + '_date', category);
+                }
+            }
+            catch (e) {
+                (0, logging_1.LogError)(`LocalCacheManager.ClearAll failed for key ${entry.key}: ${e}`);
+            }
+        }
+        this._registry.clear();
+        this._stats = { hits: 0, misses: 0 };
+        await this.persistRegistry();
+        return count;
+    }
+    /**
+     * Resets the hit/miss statistics.
+     */
+    ResetStats() {
+        this._stats = { hits: 0, misses: 0 };
+    }
+    // ========================================================================
+    // INTERNAL HELPERS
+    // ========================================================================
+    /**
+     * Maps a cache entry type to its storage category.
+     */
+    getCategoryForType(type) {
+        switch (type) {
+            case 'runview':
+                return exports.CacheCategory.RunViewCache;
+            case 'runquery':
+                return exports.CacheCategory.RunQueryCache;
+            case 'dataset':
+                return exports.CacheCategory.DatasetCache;
+            default:
+                return exports.CacheCategory.Default;
+        }
+    }
+    /**
+     * Builds a cache key for a dataset.
+     */
+    buildDatasetKey(name, itemFilters, keyPrefix) {
+        const filterKey = itemFilters
+            ? '{' + itemFilters.map(f => `"${f.ItemCode}":"${f.Filter}"`).join(',') + '}'
+            : '';
+        return keyPrefix + '__DATASET__' + name + filterKey;
+    }
+    /**
+     * Registers a cache entry in the registry.
+     */
+    registerEntry(entry) {
+        this._registry.set(entry.key, entry);
+        // Debounce registry persistence to avoid too many writes
+        this.debouncedPersistRegistry();
+    }
+    /**
+     * Unregisters a cache entry from the registry.
+     */
+    unregisterEntry(key) {
+        this._registry.delete(key);
+        this.debouncedPersistRegistry();
+    }
+    /**
+     * Records an access to a cache entry (updates lastAccessedAt and accessCount).
+     */
+    recordAccess(key) {
+        const entry = this._registry.get(key);
+        if (entry) {
+            entry.lastAccessedAt = Date.now();
+            entry.accessCount++;
+            // Don't persist on every access - too expensive
+        }
+    }
+    /**
+     * Loads the registry from storage.
+     */
+    async loadRegistry() {
+        if (!this._storageProvider)
+            return;
+        try {
+            const stored = await this._storageProvider.GetItem(this.REGISTRY_KEY, exports.CacheCategory.Metadata);
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                this._registry = new Map(parsed.map(e => [e.key, e]));
+            }
+        }
+        catch (e) {
+            this._registry.clear();
+        }
+    }
+    /**
+     * Debounced registry persistence to avoid too many writes.
+     */
+    debouncedPersistRegistry() {
+        if (this._persistTimeout) {
+            clearTimeout(this._persistTimeout);
+        }
+        this._persistTimeout = setTimeout(() => {
+            this.persistRegistry();
+        }, 1000); // 1 second debounce
+    }
+    /**
+     * Persists the registry to storage.
+     */
+    async persistRegistry() {
+        if (!this._storageProvider)
+            return;
+        try {
+            const data = JSON.stringify(this.GetAllEntries());
+            await this._storageProvider.SetItem(this.REGISTRY_KEY, data, exports.CacheCategory.Metadata);
+        }
+        catch (e) {
+            // Ignore persistence errors - cache is still functional
+        }
+    }
+    /**
+     * Estimates the size of a string in bytes.
+     */
+    estimateSize(value) {
+        // Approximate size: UTF-16 strings are ~2 bytes per character
+        return value.length * 2;
+    }
+    /**
+     * Evicts entries if needed to make room for new data.
+     */
+    async evictIfNeeded(neededBytes) {
+        if (!this._storageProvider)
+            return;
+        const stats = this.GetStats();
+        const wouldExceedSize = (stats.totalSizeBytes + neededBytes) > this._config.maxSizeBytes;
+        const wouldExceedCount = stats.totalEntries >= this._config.maxEntries;
+        if (!wouldExceedSize && !wouldExceedCount)
+            return;
+        // Calculate how much to free
+        const targetFreeBytes = Math.max(neededBytes, this._config.maxSizeBytes * 0.1); // At least 10% of max
+        const targetFreeCount = Math.max(1, Math.floor(this._config.maxEntries * 0.1)); // At least 10% of max
+        await this.evict(targetFreeBytes, targetFreeCount);
+    }
+    /**
+     * Evicts entries based on the configured eviction policy.
+     */
+    async evict(targetBytes, targetCount) {
+        if (!this._storageProvider)
+            return;
+        const entries = this.GetAllEntries();
+        // Sort by eviction policy
+        switch (this._config.evictionPolicy) {
+            case 'lru':
+                entries.sort((a, b) => a.lastAccessedAt - b.lastAccessedAt);
+                break;
+            case 'lfu':
+                entries.sort((a, b) => a.accessCount - b.accessCount);
+                break;
+            case 'fifo':
+                entries.sort((a, b) => a.cachedAt - b.cachedAt);
+                break;
+        }
+        let freedBytes = 0;
+        let freedCount = 0;
+        const toDelete = [];
+        for (const entry of entries) {
+            if (freedBytes >= targetBytes && freedCount >= targetCount)
+                break;
+            toDelete.push(entry.key);
+            freedBytes += entry.sizeBytes;
+            freedCount++;
+        }
+        for (const key of toDelete) {
+            try {
+                const entry = this._registry.get(key);
+                const category = this.getCategoryForType(entry?.type);
+                await this._storageProvider.Remove(key, category);
+                if (entry?.type === 'dataset') {
+                    await this._storageProvider.Remove(key + '_date', category);
+                }
+                this._registry.delete(key);
+            }
+            catch (e) {
+                // Continue evicting other entries
+            }
+        }
+        await this.persistRegistry();
+    }
+}
+exports.LocalCacheManager = LocalCacheManager;
+//# sourceMappingURL=localCacheManager.js.map