@hkdigital/lib-sveltekit 0.1.70 → 0.1.72

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

@@ -0,0 +1,212 @@
+/**
+ * @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?: {
+        dbName?: string;
+        storeName?: string;
+        maxSize?: number;
+        maxAge?: number;
+        cleanupBatchSize?: number;
+        cleanupInterval?: number;
+    });
+    dbName: string;
+    storeName: string;
+    maxSize: number;
+    maxAge: number;
+    cleanupBatchSize: number;
+    cleanupInterval: number;
+    /**
+     * Database connection promise
+     * @type {Promise<IDBDatabase>}
+     * @private
+     */
+    private dbPromise;
+    /**
+     * Cleanup state tracker
+     * @type {Object}
+     * @private
+     */
+    private cleanupState;
+    /**
+     * Open the IndexedDB database
+     *
+     * @private
+     * @returns {Promise<IDBDatabase>}
+     */
+    private _openDatabase;
+    /**
+     * Get a cached response
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<CacheEntry|null>} Cache entry or null if not found/expired
+     */
+    get(key: string): Promise<CacheEntry | 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>}
+     */
+    set(key: string, response: Response, metadata?: any): Promise<void>;
+    /**
+     * Update last accessed timestamp (without blocking)
+     *
+     * @private
+     * @param {string} key - Cache key
+     * @returns {Promise<void>}
+     */
+    private _updateAccessTime;
+    /**
+     * Delete a cached entry
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<boolean>}
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete a cached entry (internal implementation)
+     *
+     * @private
+     * @param {string} key - Cache key
+     * @returns {Promise<boolean>}
+     */
+    private _deleteEntry;
+    /**
+     * Clear all cached responses
+     *
+     * @returns {Promise<void>}
+     */
+    clear(): Promise<void>;
+    /**
+     * Check storage usage and schedule cleanup if needed
+     *
+     * @private
+     */
+    private _checkAndScheduleCleanup;
+    /**
+     * Schedule a cleanup to run during idle time
+     *
+     * @private
+     * @param {boolean} [urgent=false] - If true, clean up sooner
+     */
+    private _scheduleCleanup;
+    /**
+     * Perform a single cleanup step
+     *
+     * @private
+     */
+    private _performCleanupStep;
+    /**
+     * Remove expired entries
+     *
+     * @private
+     * @param {number} limit - Maximum number of entries to remove
+     * @returns {Promise<number>} Number of entries removed
+     */
+    private _removeExpiredEntries;
+    /**
+     * 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
+     */
+    private _removeOldEntries;
+    /**
+     * Get an estimate of the total cache size
+     *
+     * @private
+     * @returns {Promise<number>} Size estimate in bytes
+     */
+    private _getCacheSizeEstimate;
+    /**
+     * Close the database connection
+     */
+    close(): 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;
+};