@hkdigital/lib-sveltekit 0.1.70 → 0.1.72

package/dist/classes/cache/IndexedDbCache.js

@@ -0,0 +1,673 @@
+/**
+ * @fileoverview IndexedDbCache provides efficient persistent caching with 
+ * automatic, non-blocking background cleanup.
+ * 
+ * This cache automatically manages storage limits and entry expiration
+ * in the background using requestIdleCallback to avoid impacting application
+ * performance. It supports incremental cleanup, storage monitoring, and
+ * graceful degradation on older browsers.
+ * 
+ * @example
+ * // Create a cache instance
+ * const cache = new IndexedDbCache({
+ *   dbName: 'app-cache',
+ *   storeName: 'http-responses',
+ *   maxSize: 100 * 1024 * 1024, // 100MB
+ *   maxAge: 30 * 24 * 60 * 60 * 1000 // 30 days
+ * });
+ * 
+ * // Store a response
+ * const response = await fetch('https://api.example.com/data');
+ * await cache.set('api-data', response, { 
+ *   expiresIn: 3600000 // 1 hour
+ * });
+ * 
+ * // Retrieve cached response
+ * const cached = await cache.get('api-data');
+ * if (cached) {
+ *   console.log('Cache hit', cached.response);
+ * } else {
+ *   console.log('Cache miss');
+ * }
+ */
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response - Cached Response object
+ * @property {Object} metadata - Cache entry metadata
+ * @property {string} url - Original URL
+ * @property {number} timestamp - When the entry was cached
+ * @property {number|null} expires - Expiration timestamp (null if no expiration)
+ * @property {string|null} etag - ETag header if present
+ * @property {string|null} lastModified - Last-Modified header if present
+ */
+
+/**
+ * IndexedDbCache with automatic background cleanup
+ */
+export default class IndexedDbCache {
+  /**
+   * Create a new IndexedDB cache storage
+   * 
+   * @param {Object} [options] - Cache options
+   * @param {string} [options.dbName='http-cache'] - Database name
+   * @param {string} [options.storeName='responses'] - Store name
+   * @param {number} [options.maxSize=50000000] - Max cache size in bytes (50MB)
+   * @param {number} [options.maxAge=604800000] - Max age in ms (7 days)
+   * @param {number} [options.cleanupBatchSize=100] - Items per cleanup batch
+   * @param {number} [options.cleanupInterval=300000] - Time between cleanup attempts (5min)
+   */
+  constructor(options = {}) {
+    this.dbName = options.dbName || 'http-cache';
+    this.storeName = options.storeName || 'responses';
+    this.maxSize = options.maxSize || 50 * 1024 * 1024; // 50MB
+    this.maxAge = options.maxAge || 7 * 24 * 60 * 60 * 1000; // 7 days
+    this.cleanupBatchSize = options.cleanupBatchSize || 100;
+    this.cleanupInterval = options.cleanupInterval || 5 * 60 * 1000; // 5 minutes
+    
+    /**
+     * Database connection promise
+     * @type {Promise<IDBDatabase>}
+     * @private
+     */
+    this.dbPromise = this._openDatabase();
+    
+    /**
+     * Cleanup state tracker
+     * @type {Object}
+     * @private
+     */
+    this.cleanupState = {
+      inProgress: false,
+      lastRun: 0,
+      lastCursor: null,
+      totalRemoved: 0,
+      nextScheduled: false
+    };
+    
+    // Schedule initial cleanup
+    this._scheduleCleanup();
+  }
+  
+  /**
+   * Open the IndexedDB database
+   * 
+   * @private
+   * @returns {Promise<IDBDatabase>}
+   */
+  async _openDatabase() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+      
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          // Create object store with indexes to help with cleanup
+          const store = db.createObjectStore(this.storeName, { keyPath: 'key' });
+          
+          // Index for expiration-based cleanup
+          store.createIndex('expires', 'expires', { unique: false });
+          
+          // Index for age-based cleanup
+          store.createIndex('timestamp', 'timestamp', { unique: false });
+          
+          // Index for size-based estimate (rough approximation)
+          store.createIndex('size', 'size', { unique: false });
+        }
+      };
+    });
+  }
+  
+  /**
+   * Get a cached response
+   * 
+   * @param {string} key - Cache key
+   * @returns {Promise<CacheEntry|null>} Cache entry or null if not found/expired
+   */
+  async get(key) {
+    try {
+      const db = await this.dbPromise;
+      
+      return new Promise((resolve, reject) => {
+        const transaction = db.transaction(this.storeName, 'readonly');
+        const store = transaction.objectStore(this.storeName);
+        const request = store.get(key);
+        
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => {
+          const entry = request.result;
+          
+          if (!entry) {
+            resolve(null);
+            return;
+          }
+          
+          // Check if expired
+          if (entry.expires && Date.now() > entry.expires) {
+            // Delete expired entry
+            this._deleteEntry(key).catch(console.error);
+            resolve(null);
+            return;
+          }
+          
+          // Update access timestamp (but don't block)
+          this._updateAccessTime(key).catch(console.error);
+          
+          // Deserialize the response
+          try {
+            // Create headers safely
+            let responseHeaders;
+            try {
+              responseHeaders = new Headers(entry.headers);
+            } catch (err) {
+              // Fallback for environments without Headers support
+              responseHeaders = {
+                get: (name) => {
+                  const header = entry.headers?.find(h => h[0].toLowerCase() === name.toLowerCase());
+                  return header ? header[1] : null;
+                }
+              };
+            }
+
+            // Create Response safely
+            let response;
+            try {
+              response = new Response(entry.body, {
+                status: entry.status,
+                statusText: entry.statusText,
+                headers: responseHeaders
+              });
+            } catch (err) {
+              // Simplified mock response for test environments
+              response = {
+                status: entry.status,
+                statusText: entry.statusText,
+                headers: responseHeaders,
+                body: entry.body,
+                url: entry.url,
+                clone() { return this; }
+              };
+            }
+
+            resolve({
+              response,
+              metadata: entry.metadata,
+              url: entry.url,
+              timestamp: entry.timestamp,
+              expires: entry.expires,
+              etag: entry.etag,
+              lastModified: entry.lastModified
+            });
+          } catch (err) {
+            console.error('Failed to deserialize cached response:', err);
+
+            // Delete corrupted entry
+            this._deleteEntry(key).catch(console.error);
+            resolve(null);
+          }
+        };
+      });
+    } catch (err) {
+      console.error('Cache get error:', err);
+      return null;
+    }
+  }
+
+  /**
+   * Store a response in the cache
+   *
+   * @param {string} key - Cache key
+   * @param {Response} response - Response to cache
+   * @param {Object} [metadata={}] - Cache metadata
+   * @returns {Promise<void>}
+   */
+  async set(key, response, metadata = {}) {
+    try {
+      const db = await this.dbPromise;
+
+      // Clone the response to avoid consuming it
+      const clonedResponse = response.clone();
+
+      // Extract response data - handle both browser Response and test mocks
+      let body;
+      try {
+        // Try standard Response.blob() first (browser environment)
+        body = await clonedResponse.blob();
+      } catch (err) {
+        // Fallback for test environment
+        if (typeof clonedResponse.body === 'string' ||
+            clonedResponse.body instanceof ArrayBuffer ||
+            clonedResponse.body instanceof Uint8Array) {
+          body = new Blob([clonedResponse.body]);
+        } else {
+          // Last resort - store as-is and hope it's serializable
+          body = clonedResponse.body || new Blob([]);
+        }
+      }
+
+      // Extract headers safely
+      let headers = [];
+      try {
+        headers = Array.from(clonedResponse.headers.entries());
+      } catch (err) {
+        // Fallback for test environment - extract headers if available
+        if (clonedResponse._headers && typeof clonedResponse._headers.entries === 'function') {
+          headers = Array.from(clonedResponse._headers.entries());
+        }
+      }
+
+      // Calculate rough size estimate
+      const headerSize = JSON.stringify(headers).length * 2;
+      const size = (body.size || 0) + headerSize + key.length * 2;
+
+      const entry = {
+        key,
+        url: clonedResponse.url || '',
+        status: clonedResponse.status || 200,
+        statusText: clonedResponse.statusText || '',
+        headers,
+        body,
+        metadata,
+        timestamp: Date.now(),
+        lastAccessed: Date.now(),
+        expires: metadata.expires || (metadata.expiresIn ? Date.now() + metadata.expiresIn : null),
+        etag: clonedResponse.headers?.get?.('ETag') || null,
+        lastModified: clonedResponse.headers?.get?.('Last-Modified') || null,
+        size // Store estimated size for cleanup
+      };
+
+      return new Promise((resolve, reject) => {
+        const transaction = db.transaction(this.storeName, 'readwrite');
+        const store = transaction.objectStore(this.storeName);
+        const request = store.put(entry);
+
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => {
+          resolve();
+
+          // Check if we need cleanup after adding new entries
+          this._checkAndScheduleCleanup();
+        };
+      });
+    } catch (err) {
+      console.error('Cache set error:', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Update last accessed timestamp (without blocking)
+   *
+   * @private
+   * @param {string} key - Cache key
+   * @returns {Promise<void>}
+   */
+  async _updateAccessTime(key) {
+    const db = await this.dbPromise;
+
+    return new Promise((resolve) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.get(key);
+
+      request.onerror = () => resolve(); // Don't block on errors
+
+      request.onsuccess = () => {
+        const entry = request.result;
+        if (!entry) return resolve();
+
+        entry.lastAccessed = Date.now();
+
+        const updateRequest = store.put(entry);
+        updateRequest.onerror = () => resolve(); // Don't block
+        updateRequest.onsuccess = () => resolve();
+      };
+    });
+  }
+
+  /**
+   * Delete a cached entry
+   *
+   * @param {string} key - Cache key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    return this._deleteEntry(key);
+  }
+
+  /**
+   * Delete a cached entry (internal implementation)
+   *
+   * @private
+   * @param {string} key - Cache key
+   * @returns {Promise<boolean>}
+   */
+  async _deleteEntry(key) {
+    try {
+      const db = await this.dbPromise;
+
+      return new Promise((resolve, reject) => {
+        const transaction = db.transaction(this.storeName, 'readwrite');
+        const store = transaction.objectStore(this.storeName);
+        const request = store.delete(key);
+
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(true);
+      });
+    } catch (err) {
+      console.error('Cache delete error:', err);
+      return false;
+    }
+  }
+
+  /**
+   * Clear all cached responses
+   *
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    try {
+      const db = await this.dbPromise;
+
+      return new Promise((resolve, reject) => {
+        const transaction = db.transaction(this.storeName, 'readwrite');
+        const store = transaction.objectStore(this.storeName);
+        const request = store.clear();
+
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => {
+          this.cleanupState.lastCursor = null;
+          this.cleanupState.totalRemoved = 0;
+          resolve();
+        };
+      });
+    } catch (err) {
+      console.error('Cache clear error:', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Check storage usage and schedule cleanup if needed
+   *
+   * @private
+   */
+  async _checkAndScheduleCleanup() {
+    // Avoid multiple concurrent checks
+    if (this.cleanupState.inProgress || this.cleanupState.nextScheduled) {
+      return;
+    }
+
+    // Only check periodically
+    const now = Date.now();
+    if (now - this.cleanupState.lastRun < this.cleanupInterval) {
+      return;
+    }
+
+    // Use storage estimate API if available in browser environment
+    if (typeof navigator !== 'undefined' &&
+        navigator.storage &&
+        typeof navigator.storage.estimate === 'function') {
+      try {
+        const estimate = await navigator.storage.estimate();
+        const usageRatio = estimate.usage / estimate.quota;
+
+        // If using more than 80% of quota, schedule urgent cleanup
+        if (usageRatio > 0.8) {
+          this._scheduleCleanup(true);
+          return;
+        }
+      } catch (err) {
+        // Fall back to regular scheduling if estimate fails
+        console.error('Storage estimate error:', err);
+      }
+    }
+
+    // Schedule normal cleanup
+    this._scheduleCleanup();
+  }
+
+  /**
+   * Schedule a cleanup to run during idle time
+   *
+   * @private
+   * @param {boolean} [urgent=false] - If true, clean up sooner
+   */
+  _scheduleCleanup(urgent = false) {
+    if (this.cleanupState.nextScheduled) {
+      return;
+    }
+
+    this.cleanupState.nextScheduled = true;
+
+    // Check if we're in a browser environment with requestIdleCallback
+    if (typeof window !== 'undefined' &&
+        typeof window.requestIdleCallback === 'function') {
+      window.requestIdleCallback(
+        () => {
+          this.cleanupState.nextScheduled = false;
+          this._performCleanupStep();
+        },
+        { timeout: urgent ? 1000 : 10000 }
+      );
+    } else {
+      // Fallback for Node.js or browsers without requestIdleCallback
+      setTimeout(() => {
+        this.cleanupState.nextScheduled = false;
+        this._performCleanupStep();
+      }, urgent ? 100 : 1000);
+    }
+  }
+
+  /**
+   * Perform a single cleanup step
+   *
+   * @private
+   */
+  async _performCleanupStep() {
+    if (this.cleanupState.inProgress) {
+      return;
+    }
+
+    this.cleanupState.inProgress = true;
+
+    try {
+      const now = Date.now();
+      const db = await this.dbPromise;
+      let removedCount = 0;
+
+      // Step 1: Remove expired entries first
+      const expiredRemoved = await this._removeExpiredEntries(
+        this.cleanupBatchSize / 2
+      );
+      removedCount += expiredRemoved;
+
+      // If we have a lot of expired entries, focus on those first
+      if (expiredRemoved >= this.cleanupBatchSize / 2) {
+        this.cleanupState.inProgress = false;
+        this.cleanupState.lastRun = now;
+        this.cleanupState.totalRemoved += removedCount;
+
+        // Schedule next cleanup step immediately
+        this._scheduleCleanup();
+        return;
+      }
+
+      // Step 2: Remove old entries if we're over size/age limits
+      const remainingBatch = this.cleanupBatchSize - expiredRemoved;
+      if (remainingBatch > 0) {
+        const oldRemoved = await this._removeOldEntries(remainingBatch);
+        removedCount += oldRemoved;
+      }
+
+      // Update cleanup state
+      this.cleanupState.lastRun = now;
+      this.cleanupState.totalRemoved += removedCount;
+
+      // If we removed entries in this batch, schedule another cleanup
+      if (removedCount > 0) {
+        this._scheduleCleanup();
+      } else {
+        // Reset cursor if we didn't find anything to clean
+        this.cleanupState.lastCursor = null;
+
+        // Schedule a check later
+        setTimeout(() => {
+          this._checkAndScheduleCleanup();
+        }, this.cleanupInterval);
+      }
+    } catch (err) {
+      console.error('Cache cleanup error:', err);
+    } finally {
+      this.cleanupState.inProgress = false;
+    }
+  }
+
+  /**
+   * Remove expired entries
+   *
+   * @private
+   * @param {number} limit - Maximum number of entries to remove
+   * @returns {Promise<number>} Number of entries removed
+   */
+  async _removeExpiredEntries(limit) {
+    const now = Date.now();
+    const db = await this.dbPromise;
+    let removed = 0;
+
+    return new Promise((resolve) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const index = store.index('expires');
+
+      // Create range for all entries with expiration before now
+      const range = IDBKeyRange.upperBound(now);
+
+      // Skip non-expiring entries (null expiration)
+      const request = index.openCursor(range);
+
+      request.onerror = () => resolve(removed);
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result;
+
+        if (!cursor || removed >= limit) {
+          resolve(removed);
+          return;
+        }
+
+        // Delete the expired entry
+        const deleteRequest = cursor.delete();
+        deleteRequest.onsuccess = () => {
+          removed++;
+        };
+
+        // Move to next entry
+        cursor.continue();
+      };
+    });
+  }
+
+  /**
+   * Remove old entries based on age and size constraints
+   *
+   * @private
+   * @param {number} limit - Maximum number of entries to remove
+   * @returns {Promise<number>} Number of entries removed
+   */
+  async _removeOldEntries(limit) {
+    const db = await this.dbPromise;
+    let removed = 0;
+
+    // Get total cache size estimate (rough)
+    const sizeEstimate = await this._getCacheSizeEstimate();
+
+    // If we're under limits, don't remove anything
+    if (sizeEstimate < this.maxSize) {
+      return 0;
+    }
+
+    return new Promise((resolve) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const index = store.index('timestamp');
+
+      // Start from the oldest entries
+      const request = index.openCursor();
+
+      request.onerror = () => resolve(removed);
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result;
+
+        if (!cursor || removed >= limit) {
+          resolve(removed);
+          return;
+        }
+
+        const entry = cursor.value;
+        const now = Date.now();
+        const age = now - entry.timestamp;
+
+        // Delete if older than max age
+        if (age > this.maxAge) {
+          const deleteRequest = cursor.delete();
+          deleteRequest.onsuccess = () => {
+            removed++;
+          };
+        }
+
+        // Move to next entry
+        cursor.continue();
+      };
+    });
+  }
+
+  /**
+   * Get an estimate of the total cache size
+   *
+   * @private
+   * @returns {Promise<number>} Size estimate in bytes
+   */
+  async _getCacheSizeEstimate() {
+    const db = await this.dbPromise;
+
+    return new Promise((resolve) => {
+      const transaction = db.transaction(this.storeName, 'readonly');
+      const store = transaction.objectStore(this.storeName);
+      const index = store.index('size');
+
+      // Get the sum of all entry sizes
+      const request = index.openCursor();
+      let totalSize = 0;
+
+      request.onerror = () => resolve(totalSize);
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result;
+
+        if (!cursor) {
+          resolve(totalSize);
+          return;
+        }
+
+        const entry = cursor.value;
+        totalSize += entry.size || 0;
+
+        cursor.continue();
+      };
+    });
+  }
+
+  /**
+   * Close the database connection
+   */
+  close() {
+    this.dbPromise.then(db => {
+      db.close();
+    }).catch(console.error);
+  }
+}