@hkdigital/lib-sveltekit 0.1.73 → 0.1.74

package/dist/classes/cache/IndexedDbCache.d.ts

@@ -1,45 +1,3 @@
-/**
- * @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
  */
@@ -54,6 +12,8 @@ export default class IndexedDbCache {
      * @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)
+     * @param {number} [options.cleanupPostponeTimeout=5000] - Time to postpone cleanup after store (5sec)
+     * @param {string} [options.cacheVersion='1.0.0'] - Cache version, used for cache invalidation
      */
     constructor(options?: {
         dbName?: string;
@@ -62,6 +22,8 @@ export default class IndexedDbCache {
         maxAge?: number;
         cleanupBatchSize?: number;
         cleanupInterval?: number;
+        cleanupPostponeTimeout?: number;
+        cacheVersion?: string;
     });
     dbName: string;
     storeName: string;
@@ -69,6 +31,13 @@ export default class IndexedDbCache {
     maxAge: number;
     cleanupBatchSize: number;
     cleanupInterval: number;
+    cleanupPostponeTimeout: number;
+    cacheVersion: string;
+    EXPIRES_INDEX: string;
+    TIMESTAMP_INDEX: string;
+    SIZE_INDEX: string;
+    CACHE_VERSION_INDEX: string;
+    SCHEMA_VERSION: number;
     /**
      * Database connection promise
      * @type {Promise<IDBDatabase>}
@@ -81,15 +50,54 @@ export default class IndexedDbCache {
      * @private
      */
     private cleanupState;
+    postponeCleanupTimer: number;
     /**
-     * Open the IndexedDB database
+     * Initialize the database connection
+     *
+     * @private
+     */
+    private _initDatabase;
+    /**
+     * Open the IndexedDB database with proper schema versioning
      *
      * @private
      * @returns {Promise<IDBDatabase>}
      */
     private _openDatabase;
+    /**
+     * Ensure an index exists in a store, create if missing
+     *
+     * @private
+     * @param {IDBObjectStore} store - The object store
+     * @param {string} indexName - Name of the index
+     * @param {string} keyPath - Key path for the index
+     * @param {Object} options - Index options (e.g. unique)
+     */
+    private _ensureIndexExists;
+    /**
+     * Check if all required indexes exist in the database
+     *
+     * @private
+     * @returns {Promise<boolean>}
+     */
+    private _validateSchema;
+    /**
+     * Postpone cleanup for the specified duration
+     * Resets the postpone timer if called again before timeout
+     *
+     * @private
+     */
+    private _postponeCleanup;
+    /**
+     * Check if cleanup is postponed
+     *
+     * @private
+     * @returns {boolean}
+     */
+    private _isCleanupPostponed;
     /**
      * Get a cached response
+     * Supports retrieving older cache versions and migrating them
      *
      * @param {string} key - Cache key
      * @returns {Promise<CacheEntry|null>} Cache entry or null if not found/expired
@@ -104,6 +112,14 @@ export default class IndexedDbCache {
      * @returns {Promise<void>}
      */
     set(key: string, response: Response, metadata?: any): Promise<void>;
+    /**
+     * Update an existing entry in the cache
+     *
+     * @private
+     * @param {Object} entry - The entry to update
+     * @returns {Promise<boolean>}
+     */
+    private _updateEntry;
     /**
      * Update last accessed timestamp (without blocking)
      *
@@ -146,6 +162,13 @@ export default class IndexedDbCache {
      * @param {boolean} [urgent=false] - If true, clean up sooner
      */
     private _scheduleCleanup;
+    /**
+     * Get a random expiration time between 30 minutes and 90 minutes
+     *
+     * @private
+     * @returns {number} Expiration time in milliseconds
+     */
+    private _getRandomExpiration;
     /**
      * Perform a single cleanup step
      *
@@ -160,6 +183,14 @@ export default class IndexedDbCache {
      * @returns {Promise<number>} Number of entries removed
      */
     private _removeExpiredEntries;
+    /**
+     * Mark entries from old cache versions for gradual expiration
+     *
+     * @private
+     * @param {number} limit - Maximum number of entries to mark
+     * @returns {Promise<number>} Number of entries marked
+     */
+    private _markOldCacheVersionsForExpiration;
     /**
      * Remove old entries based on age and size constraints
      *
@@ -178,35 +209,8 @@ export default class IndexedDbCache {
     /**
      * Close the database connection
      */
-    close(): void;
+    close(): Promise<void>;
 }
-export type CacheEntry = {
-    /**
-     * - Cached Response object
-     */
-    response: Response;
-    /**
-     * - Cache entry metadata
-     */
-    metadata: any;
-    /**
-     * - Original URL
-     */
-    url: string;
-    /**
-     * - When the entry was cached
-     */
-    timestamp: number;
-    /**
-     * - Expiration timestamp (null if no expiration)
-     */
-    expires: number | null;
-    /**
-     * - ETag header if present
-     */
-    etag: string | null;
-    /**
-     * - Last-Modified header if present
-     */
-    lastModified: string | null;
-};
+export type CacheEntry = import("./typedef").CacheEntry;
+export type IDBRequestEvent = import("./typedef").IDBRequestEvent;
+export type IDBVersionChangeEvent = import("./typedef").IDBVersionChangeEvent;