@preference-sl/pref-viewer 2.10.0-beta.9 → 2.11.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preference-sl/pref-viewer",
-  "version": "2.10.0-beta.9",
+  "version": "2.11.0-beta.0",
   "description": "Web Component to preview GLTF models with Babylon.js",
   "author": "Alex Moreno Palacio <amoreno@preference.es>",
   "scripts": {
@@ -34,10 +34,11 @@
     "index.d.ts"
   ],
   "dependencies": {
-    "@babylonjs/core": "^8.28.2",
-    "@babylonjs/loaders": "^8.28.2",
-    "@babylonjs/serializers": "^8.28.2",
-    "babylonjs-gltf2interface": "^8.28.2"
+    "@babylonjs/core": "^8.31.3",
+    "@babylonjs/loaders": "^8.31.3",
+    "@babylonjs/serializers": "^8.31.3",
+    "babylonjs-gltf2interface": "^8.31.3",
+    "idb": "^8.0.3"
   },
   "devDependencies": {
     "esbuild": "^0.25.10",

package/src/file-storage.js

@@ -0,0 +1,288 @@
+/**
+ * FileStore class to manage file storage in IndexedDB using a promise-based wrapper around the IndexedDB API.
+ * @see {@link https://github.com/jakearchibald/idb|GitHub - jakearchibald/idb: IndexedDB, but with promises}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API|IndexedDB API - MDN}
+ * @see {@link https://www.npmjs.com/package/idb|idb - npm}
+ */
+
+import { openDB } from "idb";
+
+export 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
+
+    constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
+        this.dbName = dbName; // database name
+        this.osName = osName; // object store name used for file cache
+    }
+
+    /**
+     * Create the object store if it does not exist.
+     * @param {IDBDatabase} db IndexedDB database instance
+     */
+    #createObjectStore = (db, osName) => {
+        if (!db.objectStoreNames.contains(osName)) {
+            db.createObjectStore(osName);
+        }
+    };
+
+    /**
+     * Open the IndexedDB database (creating it if needed) and ensure the object store for files exists.
+     * @returns {Promise<IDBDatabase|null>} Resolves with the opened database or null if IndexedDB is not supported or opening fails.
+     */
+    #openDB = async () => {
+        if (!this.#supported) {
+            return null;
+        }
+        const self = this;
+        try {
+            return await openDB(this.dbName, this.#dbVersion, {
+                upgrade(db) {
+                    self.#createObjectStore(db, self.osName);
+                },
+            });
+        } catch (error) {
+            return null;
+        }
+    };
+
+    /**
+     * Download the file from the server (forced download).
+     * @param {String} uri File URI
+     * @returns {Promise<{blob: Blob, timeStamp: string}|undefined>} Resolves with:
+     *   - { blob, timeStamp }: object with the downloaded Blob and the Last-Modified timestamp (ISO string) on success
+     *   - undefined: if the download fails (non-200 status or network error)
+     */
+    #getServerFile = async (uri) => {
+        let file = undefined;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("GET", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    const blob = xhr.response;
+                    const timeStamp = new Date(xhr.getResponseHeader("Last-Modified")).toISOString();
+                    file = { blob: blob, timeStamp: timeStamp };
+                    resolve(file);
+                } else {
+                    resolve(file);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(file);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Get the Last-Modified timestamp of the file on the server without downloading its content.
+     * @param {String} uri File URI
+     * @returns {Promise<string|null>} Resolves with:
+     *   - ISO 8601 string from the Last-Modified header if available
+     *   - null if the header is not present or on error
+     */
+    #getServerFileTimeStamp = async (uri) => {
+        let timeStamp = null;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("HEAD", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    timeStamp = new Date(xhr.getResponseHeader("Last-Modified")).toISOString();
+                    resolve(timeStamp);
+                } else {
+                    resolve(timeStamp);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(timeStamp);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Get the size of the file on the server without downloading its content.
+     * @param {String} uri File URI
+     * @returns {Promise<number>} Promise that resolves with:
+     *   - number: Content-Length in bytes when the HEAD request succeeds and the header is present
+     *   - 0: when the header is missing or the request fails
+     */
+    #getServerFileSize = async (uri) => {
+        let size = 0;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("HEAD", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    size = parseInt(xhr.getResponseHeader("Content-Length"));
+                    resolve(size);
+                } else {
+                    resolve(size);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(size);
+            };
+            xhr.send();
+        });
+    };
+
+    /**
+     * Stores a file record in IndexedDB under the provided key (uri).
+     * @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
+     */
+    #putFile = async (file, uri) => {
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        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);
+    };
+
+    /**
+     * Retrieve a file record from IndexedDB.
+     * @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
+     *   - undefined: if there is no stored entry for that URI
+     *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
+     */
+    #getFile = async (uri) => {
+        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);
+    };
+
+    /**
+     * Get a URL to the file: either an object URL for the cached Blob, or the original URI if the server copy is available and IndexedDB isn't supported.
+     * @param {String} uri File URI
+     * @returns {Promise<string|boolean>} Resolves with:
+     *   - object URL string for the cached Blob
+     *   - original URI string if IndexedDB unsupported but server file exists
+     *   - false if the file is not available on the server
+     */
+    getURL = async (uri) => {
+        if (!this.#supported) {
+            return (await this.#getServerFileTimeStamp(uri)) ? uri : false;
+        }
+        const storedFile = await this.get(uri);
+        return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
+    };
+
+    /**
+     * Get the cached or server Last-Modified timestamp for a file.
+     * @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
+     *   - null: when no timestamp is available or on error
+     */
+    getTimeStamp = async (uri) => {
+        if (!this.#supported) {
+            const serverFileTimeStamp = await this.#getServerFileTimeStamp(uri);
+            return serverFileTimeStamp ? serverFileTimeStamp : null;
+        }
+        const storedFile = await this.get(uri);
+        return storedFile ? storedFile.timeStamp : null;
+    };
+
+    /**
+     * Get the cached or server size of a file in bytes.
+     * @param {String} uri File URI
+     * @returns {Promise<number|null>} Resolves with:
+     *   - number: size in bytes when available (from cache or server)
+     *   - null: when size is not available or on error
+     */
+    getSize = async (uri) => {
+        if (!this.#supported) {
+            const serverFileSize = await this.#getServerFileSize(uri);
+            return serverFileSize ? serverFileSize : null;
+        }
+        const storedFile = await this.get(uri);
+        return storedFile ? storedFile.blob.size : null;
+    };
+
+    /**
+     * Retrieve the Blob for a file from cache or server.
+     * @param {String} uri File URI
+     * @returns {Promise<Blob|false>} Resolves with:
+     *   - Blob: the file blob when available (from cache or server)
+     *   - false: when the file cannot be retrieved
+     */
+    getBlob = async (uri) => {
+        if (!this.#supported) {
+            const serverFile = await this.#getServerFile(uri);
+            return serverFile ? serverFile.blob : false;
+        }
+        const storedFile = await this.get(uri);
+        return storedFile ? storedFile.blob : false;
+    };
+
+    /**
+     * Get the file Blob from IndexedDB if stored; otherwise download and store it, then return the Blob.
+     * @param {String} uri File URI
+     * @returns {Promise<Blob|undefined|false>} Resolves with:
+     *   - Blob of the stored file
+     *   - undefined if the download fails
+     *   - false if uri is falsy
+     * @description
+     * The method controls the cache version of the file. If the server copy has a different timestamp than the stored one,
+     * the file is re-downloaded from the server and stored again in IndexedDB.
+     * If the server file is not available at that time to check its age but is stored, the stored file is returned.
+     */
+    get = async (uri) => {
+        if (!uri) {
+            return false;
+        }
+        if (!this.#supported) {
+            return await this.#getServerFile(uri);
+        }
+        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)) {
+            const fileToStore = await this.#getServerFile(uri);
+            if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
+                storedFile = await this.#getFile(uri);
+            } else {
+                storedFile = fileToStore;
+            }
+        }
+        return storedFile;
+    };
+
+    /**
+     * Store the file in IndexedDB.
+     * @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
+     */
+    put = async (uri) => {
+        if (!this.#supported) {
+            return false;
+        }
+        const fileToStore = await this.#getServerFile(uri);
+        return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
+    };
+}