@preference-sl/pref-viewer 2.13.0-beta.2 → 2.13.0-beta.21

package/src/file-storage.js

@@ -36,12 +36,16 @@ import { openDB } from "idb";
  *  - getBlob(uri): Retrieves file blob from cache or server.
  *  - get(uri): Gets file from cache with automatic server sync and cache versioning.
  *  - put(uri): Stores file from server in IndexedDB cache.
+ *  - dispose(): Closes the active IndexedDB handle held by the instance.
  *
  * Features:
  *  - Automatic Cache Versioning: Compares server and cached timestamps to update cache.
  *  - Fallback Support: Uses direct server access when IndexedDB is unavailable.
  *  - Object URL Generation: Creates efficient object URLs for cached blobs.
  *  - HEAD Request Optimization: Uses HEAD requests to check metadata without downloading full files.
+ *  - TTL per entry: Expired records are removed automatically.
+ *  - Maximum entry limit: Old records are evicted with an LRU strategy when limit is exceeded.
+ *  - Quota-aware cleanup: Proactively frees space and retries writes on quota errors.
  *  - Promise-Based API: All operations return promises for async/await usage.
  *
  * Usage Example:
@@ -101,7 +105,8 @@ import { openDB } from "idb";
  *  - Uses XMLHttpRequest for file downloads and HEAD requests
  *  - Supports both HTTPS and HTTP (HTTP not recommended for production)
  *  - Object URLs should be revoked after use to free memory
- *  - IndexedDB quota management should be implemented for long-term storage
+ *  - IndexedDB cache is auto-maintained (TTL, max entries, quota cleanup)
+ *  - Call dispose() when the owner is torn down to release the DB connection proactively.
  *
  * Error Handling:
  *  - Network failures: Returns undefined (get) or false (other methods)
@@ -114,16 +119,329 @@ import { openDB } from "idb";
  *  - idb Library: https://github.com/jakearchibald/idb
  *  - npm idb: https://www.npmjs.com/package/idb
  */
-export class FileStorage {
+export default class FileStorage {
     #supported = "indexedDB" in window && openDB; // true if IndexedDB is available in the browser and the idb helper is loaded
     #dbVersion = 1; // single DB version; cache is managed per-file
     #db = undefined; // IndexedDB database handle
+    #maxEntries = 300; // hard cap for cache records; oldest entries are evicted first
+    #entryTTLms = 7 * 24 * 60 * 60 * 1000; // 7 days
+    #cleanupIntervalMs = 5 * 60 * 1000; // run background cleanup at most every 5 minutes
+    #minimumFreeSpaceRatio = 0.05; // try to keep at least 5% of quota free
+    #maxQuotaEvictionRetries = 5; // max retries after quota error
+    #lastCleanupAt = 0; // timestamp of last automatic cleanup run
 
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
         this.osName = osName; // object store name used for file cache
     }
 
+    /**
+     * Returns the current timestamp in milliseconds.
+     * @private
+     * @returns {number} Epoch time in milliseconds.
+     */
+    #now() {
+        return Date.now();
+    }
+
+    /**
+     * Determines whether a cached record is expired.
+     * @private
+     * @param {Object|null|undefined} record Cached record with `expiresAt`.
+     * @param {number} [now=this.#now()] Current timestamp used for comparison.
+     * @returns {boolean} True when the record has expired; false otherwise.
+     */
+    #isExpired(record, now = this.#now()) {
+        return !!record && typeof record.expiresAt === "number" && record.expiresAt <= now;
+    }
+
+    /**
+     * Normalizes a raw cache record into the internal shape expected by the storage layer.
+     * Fills missing metadata (`size`, `createdAt`, `lastAccess`, `expiresAt`) using defaults.
+     * @private
+     * @param {Object|null|undefined} record Raw record from IndexedDB or network conversion.
+     * @returns {{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|null}
+     * Normalized record, or null if the input is invalid.
+     */
+    #normalizeRecord(record) {
+        if (!record || !record.blob) {
+            return null;
+        }
+        const now = this.#now();
+        const createdAt = typeof record.createdAt === "number" ? record.createdAt : now;
+        const expiresAt = typeof record.expiresAt === "number" ? record.expiresAt : createdAt + this.#entryTTLms;
+        return {
+            blob: record.blob,
+            timeStamp: record.timeStamp ?? null,
+            size: typeof record.size === "number" ? record.size : record.blob.size,
+            createdAt: createdAt,
+            lastAccess: typeof record.lastAccess === "number" ? record.lastAccess : now,
+            expiresAt: expiresAt,
+        };
+    }
+
+    /**
+     * Converts an incoming file payload into a normalized cache record.
+     * @private
+     * @param {Object|Blob} file Incoming payload ({ blob, timeStamp } or raw Blob).
+     * @returns {{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|null}
+     * Normalized record ready to persist, or null when payload is invalid.
+     */
+    #createRecordFromFile(file) {
+        if (!file) {
+            return null;
+        }
+        const now = this.#now();
+        const record = file instanceof Blob ? { blob: file, timeStamp: null } : file;
+        if (!record?.blob) {
+            return null;
+        }
+        return this.#normalizeRecord({
+            ...record,
+            createdAt: now,
+            lastAccess: now,
+            expiresAt: now + this.#entryTTLms,
+            size: record.blob.size,
+        });
+    }
+
+    /**
+     * Checks whether an IndexedDB error corresponds to quota exhaustion.
+     * @private
+     * @param {any} error Error thrown by IndexedDB operations.
+     * @returns {boolean} True when the error indicates storage quota was exceeded.
+     */
+    #isQuotaExceededError(error) {
+        if (!error) {
+            return false;
+        }
+        return error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED" || error.code === 22 || error.code === 1014;
+    }
+
+    /**
+     * Loads all records from the object store with their keys.
+     * Invalid rows are ignored.
+     * @private
+     * @returns {Promise<Array<{key: IDBValidKey, record: {blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}}>>}
+     * Array of key-record pairs.
+     */
+    async #getAllRecords() {
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return [];
+        }
+        const transaction = this.#db.transaction(this.osName, "readonly");
+        const store = transaction.objectStore(this.osName);
+        const [keys, values] = await Promise.all([store.getAllKeys(), store.getAll()]);
+        return keys.map((key, index) => ({ key: key, record: this.#normalizeRecord(values[index]) })).filter((entry) => entry.record !== null);
+    }
+
+    /**
+     * Deletes a list of keys from the object store.
+     * @private
+     * @param {IDBValidKey[]} [keys=[]] Keys to delete.
+     * @returns {Promise<number>} Number of requested deletions.
+     */
+    async #deleteKeys(keys = []) {
+        if (!keys.length) {
+            return 0;
+        }
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return 0;
+        }
+        const transaction = this.#db.transaction(this.osName, "readwrite");
+        const store = transaction.objectStore(this.osName);
+        keys.forEach((key) => {
+            store.delete(key);
+        });
+        await transaction.done;
+        return keys.length;
+    }
+
+    /**
+     * Removes expired entries based on their `expiresAt` field.
+     * @private
+     * @returns {Promise<number>} Number of deleted expired entries.
+     */
+    async #deleteExpiredEntries() {
+        const now = this.#now();
+        const records = await this.#getAllRecords();
+        const expiredKeys = records.filter((entry) => this.#isExpired(entry.record, now)).map((entry) => entry.key);
+        return this.#deleteKeys(expiredKeys);
+    }
+
+    /**
+     * Evicts least-recently-used records, excluding protected keys.
+     * @private
+     * @param {number} [maxToDelete=1] Maximum number of entries to delete.
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys that must not be evicted.
+     * @returns {Promise<number>} Number of deleted entries.
+     */
+    async #evictLeastRecentlyUsed(maxToDelete = 1, protectedKeys = []) {
+        if (maxToDelete <= 0) {
+            return 0;
+        }
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            })
+            .slice(0, maxToDelete);
+        const keys = candidates.map((entry) => entry.key);
+        return this.#deleteKeys(keys);
+    }
+
+    /**
+     * Enforces the maximum number of cache entries by evicting LRU records.
+     * @private
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<number>} Number of removed entries.
+     */
+    async #enforceMaxEntries(protectedKeys = []) {
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const count = records.length;
+        if (count <= this.#maxEntries) {
+            return 0;
+        }
+        const overflow = count - this.#maxEntries;
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            })
+            .slice(0, overflow)
+            .map((entry) => entry.key);
+        return this.#deleteKeys(candidates);
+    }
+
+    /**
+     * Frees cache space when estimated free quota is below threshold.
+     * Uses LRU eviction and can reserve bytes for an upcoming write.
+     * @private
+     * @param {number} [requiredBytes=0] Extra free bytes desired for the next write.
+     * @param {IDBValidKey[]} [protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<number>} Number of removed entries.
+     */
+    async #freeSpaceForQuota(requiredBytes = 0, protectedKeys = []) {
+        if (typeof navigator === "undefined" || !navigator.storage?.estimate) {
+            return 0;
+        }
+        let estimate = null;
+        try {
+            estimate = await navigator.storage.estimate();
+        } catch (error) {
+            return 0;
+        }
+        const quota = Number(estimate?.quota || 0);
+        const usage = Number(estimate?.usage || 0);
+        if (quota <= 0) {
+            return 0;
+        }
+        const minimumFreeBytes = Math.max(requiredBytes, Math.floor(quota * this.#minimumFreeSpaceRatio));
+        const freeBytes = Math.max(0, quota - usage);
+        if (freeBytes >= minimumFreeBytes) {
+            return 0;
+        }
+        const bytesToFree = minimumFreeBytes - freeBytes;
+
+        const protectedSet = new Set(protectedKeys);
+        const records = await this.#getAllRecords();
+        const candidates = records
+            .filter((entry) => !protectedSet.has(entry.key))
+            .sort((a, b) => {
+                const aAccess = typeof a.record.lastAccess === "number" ? a.record.lastAccess : 0;
+                const bAccess = typeof b.record.lastAccess === "number" ? b.record.lastAccess : 0;
+                if (aAccess !== bAccess) {
+                    return aAccess - bAccess;
+                }
+                return a.record.createdAt - b.record.createdAt;
+            });
+
+        let accumulated = 0;
+        const keysToDelete = [];
+        for (const candidate of candidates) {
+            keysToDelete.push(candidate.key);
+            accumulated += Number(candidate.record.size || 0);
+            if (accumulated >= bytesToFree) {
+                break;
+            }
+        }
+        return this.#deleteKeys(keysToDelete);
+    }
+
+    /**
+     * Runs full maintenance: delete expired entries, enforce max entries, and free quota.
+     * @private
+     * @param {Object} [options={}] Cleanup options.
+     * @param {number} [options.requiredBytes=0] Extra bytes to reserve for a pending write.
+     * @param {IDBValidKey[]} [options.protectedKeys=[]] Keys excluded from eviction.
+     * @returns {Promise<void>}
+     */
+    async #runCleanup({ requiredBytes = 0, protectedKeys = [] } = {}) {
+        await this.#deleteExpiredEntries();
+        await this.#enforceMaxEntries(protectedKeys);
+        await this.#freeSpaceForQuota(requiredBytes, protectedKeys);
+    }
+
+    /**
+     * Runs maintenance only when the cleanup interval has elapsed.
+     * @private
+     * @returns {Promise<void>}
+     */
+    async #runCleanupIfDue() {
+        const now = this.#now();
+        if (now - this.#lastCleanupAt < this.#cleanupIntervalMs) {
+            return;
+        }
+        this.#lastCleanupAt = now;
+        await this.#runCleanup();
+    }
+
+    /**
+     * Updates `lastAccess` for a record to keep LRU ordering current.
+     * @private
+     * @param {String} uri Record key.
+     * @param {Object} record Existing normalized record.
+     * @returns {Promise<void>}
+     */
+    async #touchFile(uri, record) {
+        const normalized = this.#normalizeRecord(record);
+        if (!normalized) {
+            return;
+        }
+        normalized.lastAccess = this.#now();
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) {
+            return;
+        }
+        try {
+            const transaction = this.#db.transaction(this.osName, "readwrite");
+            const store = transaction.objectStore(this.osName);
+            store.put(normalized, uri);
+            await transaction.done;
+        } catch (error) {}
+    }
+
     /**
      * Create the object store if it does not exist.
      * @private
@@ -260,10 +578,11 @@ export class FileStorage {
      * @private
      * @param {Object|Blob} file The value to store (for example an object {blob, timeStamp} or a Blob).
      * @param {String} uri Key to use for storage (the original URI).
-     * @returns {Promise<any|undefined>} Resolves with the value returned by the underlying idb store.put (usually the record key — string or number)
-     *   - resolves to the put result on success
-     *   - resolves to undefined if the database could not be opened
-     *   - rejects if the underlying put operation throws
+     * @returns {Promise<any|undefined>} Resolves with idb store.put result on success,
+     * or undefined when the database is unavailable, input is invalid, or write fails after quota retries.
+     * @description
+     * Runs maintenance before write (TTL, max entries, and quota-aware cleanup), then retries quota errors
+     * by evicting least-recently-used entries.
      */
     async #putFile(file, uri) {
         if (this.#db === undefined) {
@@ -272,30 +591,71 @@ export class FileStorage {
         if (this.#db === null) {
             return undefined;
         }
-        const transation = this.#db.transaction(this.osName, "readwrite");
-        const store = transation.objectStore(this.osName);
-        return store.put(file, uri);
+        const record = this.#createRecordFromFile(file);
+        if (!record) {
+            return undefined;
+        }
+
+        const currentRecord = await this.#getFile(uri, { touch: false, allowExpired: true });
+        const currentSize = currentRecord ? Number(currentRecord.size || currentRecord.blob?.size || 0) : 0;
+        const requiredBytes = Math.max(0, record.size - currentSize);
+
+        await this.#runCleanup({ requiredBytes: requiredBytes, protectedKeys: [uri] });
+
+        for (let attempt = 0; attempt <= this.#maxQuotaEvictionRetries; attempt++) {
+            try {
+                const transaction = this.#db.transaction(this.osName, "readwrite");
+                const store = transaction.objectStore(this.osName);
+                const result = await store.put(record, uri);
+                await transaction.done;
+                return result;
+            } catch (error) {
+                if (!this.#isQuotaExceededError(error) || attempt === this.#maxQuotaEvictionRetries) {
+                    return undefined;
+                }
+                const deleted = await this.#evictLeastRecentlyUsed(1, [uri]);
+                if (!deleted) {
+                    return undefined;
+                }
+            }
+        }
+        return undefined;
     }
 
     /**
      * Retrieve a file record from IndexedDB.
      * @private
      * @param {String} uri File URI
-     * @returns {Promise<{blob: Blob, timeStamp: string}|undefined|false>} Resolves with:
-     *   - {blob, timeStamp}: object with the Blob and ISO timestamp if the entry exists in IndexedDB
+     * @param {{touch?: boolean, allowExpired?: boolean}} [options] Read options.
+     * @param {boolean} [options.touch=true] Update lastAccess when the record is found.
+     * @param {boolean} [options.allowExpired=false] Return expired records instead of deleting them.
+     * @returns {Promise<{blob: Blob, timeStamp: string|null, size: number, createdAt: number, lastAccess: number, expiresAt: number}|undefined|false>} Resolves with:
+     *   - normalized cache record when found
      *   - undefined: if there is no stored entry for that URI
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
-    async #getFile(uri) {
+    async #getFile(uri, { touch = true, allowExpired = false } = {}) {
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
         if (this.#db === null) {
             return false;
         }
-        const transation = this.#db.transaction(this.osName, "readonly");
-        const store = transation.objectStore(this.osName);
-        return store.get(uri);
+        const transaction = this.#db.transaction(this.osName, "readonly");
+        const store = transaction.objectStore(this.osName);
+        const record = this.#normalizeRecord(await store.get(uri));
+        if (!record) {
+            return undefined;
+        }
+        if (!allowExpired && this.#isExpired(record)) {
+            await this.#deleteKeys([uri]);
+            return undefined;
+        }
+        if (touch) {
+            await this.#touchFile(uri, record);
+            record.lastAccess = this.#now();
+        }
+        return record;
     }
 
     /**
@@ -309,7 +669,7 @@ export class FileStorage {
      * @public
      * @param {String} uri - File URI
      * @returns {Promise<string|boolean>} Resolves with:
-     *   - object URL string for the cached Blob
+     *   - object URL string for the cached Blob (caller must revoke it when done)
      *   - original URI string if IndexedDB unsupported but server file exists
      *   - false if the file is not available on the server
      */
@@ -317,6 +677,7 @@ export class FileStorage {
         if (!this.#supported) {
             return (await this.#getServerFileTimeStamp(uri)) ? uri : false;
         }
+        await this.#runCleanupIfDue();
         const storedFile = await this.get(uri);
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
     }
@@ -326,7 +687,7 @@ export class FileStorage {
      * @public
      * @param {String} uri - File URI
      * @returns {Promise<string|null>} Resolves with:
-     *   - ISO 8601 string: Last-Modified timestamp from the cached record (when using IndexedDB) or from the server HEAD response
+     *   - ISO 8601 string from the cached record (when using IndexedDB) or from the server HEAD response
      *   - null: when no timestamp is available or on error
      */
     async getTimeStamp(uri) {
@@ -343,7 +704,7 @@ export class FileStorage {
      * @public
      * @param {String} uri - File URI
      * @returns {Promise<number|null>} Resolves with:
-     *   - number: size in bytes when available (from cache or server)
+     *   - number: size in bytes when available (from cache metadata/blob or server HEAD)
      *   - null: when size is not available or on error
      */
     async getSize(uri) {
@@ -376,8 +737,8 @@ export class FileStorage {
      * Get the file Blob from IndexedDB if stored; otherwise download and store it, then return the Blob.
      * @public
      * @param {String} uri - File URI
-     * @returns {Promise<Blob|undefined|false>} Resolves with:
-     *   - Blob of the stored file
+     * @returns {Promise<{blob: Blob, timeStamp: string|null, size?: number, createdAt?: number, lastAccess?: number, expiresAt?: number}|undefined|false>} Resolves with:
+     *   - cached/server record containing at least `{ blob, timeStamp }`
      *   - undefined if the download fails
      *   - false if uri is falsy
      * @description
@@ -392,10 +753,14 @@ export class FileStorage {
         if (!this.#supported) {
             return await this.#getServerFile(uri);
         }
+        await this.#runCleanupIfDue();
         let storedFile = await this.#getFile(uri);
-        const serverFileTimeStamp = storedFile ? await this.#getServerFileTimeStamp(uri) : 0;
-        const storedFileTimeStamp = storedFile ? storedFile.timeStamp : 0;
-        if (!storedFile || (storedFile && serverFileTimeStamp !== null && serverFileTimeStamp !== storedFileTimeStamp)) {
+        // If there is already a cached file, return it without HEAD revalidation.
+        // In ecommerce flow, new IDs/URLs from WASM drive real resource updates.
+        if (storedFile) {
+            return storedFile;
+        }
+        if (!storedFile) {
             const fileToStore = await this.#getServerFile(uri);
             if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
                 storedFile = await this.#getFile(uri);
@@ -412,13 +777,29 @@ export class FileStorage {
      * @param {String} uri - File URI
      * @returns {Promise<boolean>} Resolves with:
      *   - true if the file was stored successfully
-     *   - false if IndexedDB is not supported or storing failed
+     *   - false if IndexedDB is not supported, download failed, or storing failed after cleanup/retries
      */
     async put(uri) {
         if (!this.#supported) {
             return false;
         }
+        await this.#runCleanupIfDue();
         const fileToStore = await this.#getServerFile(uri);
         return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
     }
+
+    /**
+     * Closes the IndexedDB handle held by this storage instance.
+     * Safe to call multiple times; next storage operation will lazily reopen the DB.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#db) {
+            try {
+                this.#db.close();
+            } catch {}
+        }
+        this.#db = undefined;
+    }
 }