tiny-essentials 1.19.2 → 1.20.0

package/dist/v1/libs/TinyIframeEvents.mjs

@@ -0,0 +1,348 @@
+import { isJsonObject } from '../basics/objChecker.mjs';
+import TinyEvents from './TinyEvents.mjs';
+/** @type {WeakMap<Window, TinyIframeEvents>} */
+const instances = new WeakMap();
+/**
+ * @callback handler
+ * A function to handle incoming event payloads.
+ * @param {any} payload - The data sent by the emitter.
+ * @param {MessageEvent<any>} event - Metadata about the message.
+ */
+/**
+ * A flexible event routing system for structured communication
+ * between a parent window and its iframe using `postMessage`.
+ *
+ * This class abstracts the complexity of cross-origin and window-type handling,
+ * allowing both the iframe and parent to:
+ * - Send events with arbitrary payloads
+ * - Listen to specific event names
+ * - Filter events by origin and source
+ * - Work symmetrically from both sides with automatic direction handling
+ *
+ * Use this class when building applications that require modular, event-driven
+ * communication across embedded frames.
+ */
+class TinyIframeEvents {
+    #events = new TinyEvents();
+    /**
+     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     *
+     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     */
+    setThrowOnMaxListeners(shouldThrow) {
+        return this.#events.setThrowOnMaxListeners(shouldThrow);
+    }
+    /**
+     * Checks whether an error will be thrown when the max listener limit is exceeded.
+     *
+     * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+     */
+    getThrowOnMaxListeners() {
+        return this.#events.getThrowOnMaxListeners();
+    }
+    /////////////////////////////////////////////////////////////
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     */
+    prependListener(event, handler) {
+        return this.#events.prependListener(event, handler);
+    }
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     * @returns {handler} - The wrapped handler used internally.
+     */
+    prependListenerOnce(event, handler) {
+        return this.#events.prependListenerOnce(event, handler);
+    }
+    //////////////////////////////////////////////////////////////////////
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    appendListener(event, handler) {
+        return this.#events.appendListener(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    appendListenerOnce(event, handler) {
+        return this.#events.appendListenerOnce(event, handler);
+    }
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    on(event, handler) {
+        return this.#events.on(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    once(event, handler) {
+        return this.#events.once(event, handler);
+    }
+    ////////////////////////////////////////////////////////////////////
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {string} event - The name of the event to remove the handler from.
+     * @param {handler} handler - The specific callback function to remove.
+     */
+    off(event, handler) {
+        return this.#events.off(event, handler);
+    }
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event) {
+        return this.#events.offAll(event);
+    }
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes() {
+        return this.#events.offAllTypes();
+    }
+    ////////////////////////////////////////////////////////////
+    /**
+     * Returns the number of listeners for a given event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {number} Number of listeners for the event.
+     */
+    listenerCount(event) {
+        return this.#events.listenerCount(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    listeners(event) {
+        return this.#events.listeners(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    onceListeners(event) {
+        return this.#events.onceListeners(event);
+    }
+    /**
+     * Returns a copy of the internal listeners array for the specified event,
+     * including wrapper functions like those used by `.once()`.
+     * @param {string | symbol} event - The event name.
+     * @returns {handler[]} An array of raw listener functions.
+     */
+    allListeners(event) {
+        return this.#events.allListeners(event);
+    }
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames() {
+        return this.#events.eventNames();
+    }
+    //////////////////////////////////////////////////////
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n) {
+        return this.#events.setMaxListeners(n);
+    }
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners() {
+        return this.#events.getMaxListeners();
+    }
+    ///////////////////////////////////////////////////
+    /** @type {Window} */
+    #targetWindow;
+    /** @type {string} */
+    #targetOrigin;
+    /** @type {string} */
+    #selfType;
+    /** @type {boolean} */
+    #isDestroyed = false;
+    /** @type {boolean} */
+    #ready = false;
+    /**
+     * @typedef {object} IframeEventBase
+     * @property {string} eventName - The name of the custom event route.
+     * @property {any} payload - The data being sent (can be any type).
+     * @property {'iframe' | 'parent'} direction - Indicates the sender: 'iframe' or 'parent'.
+     */
+    /**
+     * Queue of messages emitted before connection is ready
+     * @type {IframeEventBase[]}
+     */
+    #pendingQueue = [];
+    /** @type {string} Internal message type for routed communication */
+    #secretEventName = '__tinyIframeEvent__';
+    /**
+     * Gets the internal secret iframe event name.
+     * @returns {string}
+     */
+    get secretEventName() {
+        return this.#secretEventName;
+    }
+    /**
+     * Sets the internal secret iframe event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set secretEventName(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyIframeEvents: secretEventName must be a string.');
+        this.#secretEventName = name;
+    }
+    /**
+     * Creates a new TinyIframeEvents instance to manage communication between iframe and parent.
+     * Automatically determines the current context (`iframe` or `parent`) based on the `targetWindow`.
+     *
+     * @param {Object} config - Configuration object.
+     * @param {HTMLIFrameElement} [config.targetIframe] - The target window to post messages to. Defaults to `window.parent` (assumes this is inside an iframe).
+     * @param {string} [config.targetOrigin] - The target origin to restrict messages to. Defaults to `window.location.origin`.
+     */
+    constructor({ targetIframe, targetOrigin } = {}) {
+        if (typeof targetIframe !== 'undefined' &&
+            (!(targetIframe instanceof HTMLIFrameElement) || !targetIframe.contentWindow))
+            throw new TypeError(`[TinyIframeEvents] Invalid "targetIframe" provided: expected a HTML Iframe Element, received ${typeof targetIframe}`);
+        if (typeof targetOrigin !== 'undefined' && typeof targetOrigin !== 'string')
+            throw new TypeError(`[TinyIframeEvents] Invalid "targetOrigin" provided: expected a string, received ${typeof targetOrigin}`);
+        this.#targetWindow = targetIframe?.contentWindow ?? window.parent;
+        this.#targetOrigin = targetOrigin ?? window.location.origin;
+        this.#selfType = !targetIframe ? 'iframe' : 'parent';
+        if (instances.has(this.#targetWindow))
+            throw new Error('Duplicate window reference.');
+        this._boundOnMessage = this.#onMessage.bind(this);
+        this._boundOnceMessage = this.#onceMessage.bind(this);
+        if (this.#targetWindow.document.readyState === 'complete' ||
+            this.#targetWindow.document.readyState === 'interactive')
+            this.#onceMessage();
+        else {
+            this.#targetWindow.addEventListener('load', this._boundOnceMessage, false);
+            this.#targetWindow.addEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+        }
+        window.addEventListener('message', this._boundOnMessage, false);
+        instances.set(this.#targetWindow, this);
+    }
+    /**
+     * Marks the communication as ready and flushes any queued messages.
+     */
+    #onceMessage() {
+        if (this.#ready)
+            return;
+        this.#ready = true;
+        this.#flushQueue();
+    }
+    /**
+     * Internal handler for the message event. Filters and dispatches incoming messages.
+     *
+     * @param {MessageEvent<any>} event - The message event received via `postMessage`.
+     */
+    #onMessage(event) {
+        const { data, source } = event;
+        // Reject non-object or unrelated messages
+        if (!isJsonObject(data) || !data[this.#secretEventName])
+            return;
+        const { eventName, payload, direction } = data;
+        // Reject if not from the expected window (for security)
+        if (source !== this.#targetWindow)
+            return;
+        // Reject if direction is not meant for this side
+        if ((this.#selfType === 'iframe' && direction !== 'iframe') ||
+            (this.#selfType === 'parent' && direction !== 'parent'))
+            return;
+        this.#events.emit(/** @type {string} */ (eventName), payload, event);
+    }
+    /**
+     * Sends an event to the target window.
+     *
+     * @param {string} eventName - A unique name identifying the event.
+     * @param {*} payload - The data to send with the event. Can be any serializable value.
+     * @throws {Error} If `eventName` is not a string.
+     */
+    emit(eventName, payload) {
+        if (typeof eventName !== 'string')
+            throw new TypeError('Event name must be a string.');
+        if (this.#isDestroyed)
+            throw new Error('Cannot emit: instance has been destroyed.');
+        /** @type {IframeEventBase} */
+        const message = {
+            [this.#secretEventName]: true,
+            eventName,
+            payload,
+            direction: this.#selfType === 'parent' ? 'iframe' : 'parent',
+        };
+        if (!this.#ready) {
+            this.#pendingQueue.push(message);
+            return;
+        }
+        this.#targetWindow.postMessage(message, this.#targetOrigin);
+    }
+    /**
+     * Sends all pending messages queued before handshake completion.
+     *
+     * @returns {void}
+     */
+    #flushQueue() {
+        while (this.#pendingQueue.length) {
+            const data = this.#pendingQueue.shift();
+            if (data)
+                this.#targetWindow.postMessage(data, this.#targetOrigin);
+        }
+    }
+    /**
+     * Checks if the communication instance has been destroyed.
+     *
+     * @returns {boolean}
+     */
+    isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /**
+     * Unsubscribes all registered event listeners and removes the message handler.
+     * Call this when the instance is no longer needed to prevent memory leaks.
+     */
+    destroy() {
+        this.#isDestroyed = true;
+        window.removeEventListener('message', this._boundOnMessage);
+        this.#targetWindow.removeEventListener('load', this._boundOnceMessage, false);
+        this.#targetWindow.removeEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+        this.#events.offAllTypes();
+        this.#pendingQueue = [];
+        instances.delete(this.#targetWindow);
+    }
+}
+export default TinyIframeEvents;

package/dist/v1/libs/TinyLocalStorage.cjs

@@ -421,6 +421,12 @@ class TinyLocalStorage {
   /** @type {Storage} */
   #localStorage = window.localStorage;
 
+  /** @type {string|null} */
+  #dbKey = null;
+
+  /** @type {number} */
+  #version = 0;
+
   /** @type {(ev: StorageEvent) => any} */
   #storageEvent = (ev) => this.emit('storage', ev);
 
@@ -428,11 +434,84 @@ class TinyLocalStorage {
    * Initializes the TinyLocalStorage instance and sets up cross-tab sync.
    *
    * Adds listener for the native `storage` event to support tab synchronization.
+   * @param {string} [dbName] - Unique database name.
    */
-  constructor() {
+  constructor(dbName) {
+    if (typeof dbName !== 'undefined' && typeof dbName !== 'string')
+      throw new TypeError('TinyLocalStorage: dbName must be a string if provided.');
+    if (typeof dbName === 'string') this.#dbKey = `LSDB::${dbName}`;
     window.addEventListener('storage', this.#storageEvent);
   }
 
+  /**
+   * Validates that a given key does not conflict with internal database keys.
+   *
+   * This method is used to prevent accidental overwriting of reserved `LSDB::` keys
+   * in `localStorage`, which are used internally by TinyLocalStorage for versioning
+   * and data management.
+   *
+   * @param {string} name - The key to validate before writing to localStorage.
+   * @throws {Error} If the key starts with `LSDB::`.
+   */
+  #isProtectedDbKey(name) {
+    if (typeof name === 'string' && name.startsWith('LSDB::'))
+      throw new Error(`TinyLocalStorage: Key "${name}" may conflict with reserved dbKeys.`);
+  }
+
+  /**
+   * Updates the version of the storage and triggers migration if needed.
+   *
+   * @param {number} version - Desired version of the database.
+   * @param {(oldVersion: number, newVersion: number) => void} onUpgrade - Callback to perform migration logic.
+   * @throws {Error} If the database key has not been initialized.
+   * @throws {TypeError} If `version` is not a valid positive number.
+   * @throws {TypeError} If `onUpgrade` is not a function.
+   */
+  updateStorageVersion(version, onUpgrade) {
+    if (typeof this.#dbKey !== 'string')
+      throw new Error(
+        'TinyLocalStorage: Database key is not initialized. Set a valid dbName in the constructor.',
+      );
+    if (typeof version !== 'number' || Number.isNaN(version) || version < 1)
+      throw new TypeError('TinyLocalStorage: version must be a positive number.');
+    if (typeof onUpgrade !== 'function')
+      throw new TypeError('TinyLocalStorage: onUpgrade must be a function.');
+
+    // @ts-ignore
+    const savedVersion = parseInt(localStorage.getItem(this.#dbKey), 10) || 0;
+    if (typeof savedVersion !== 'number' || Number.isNaN(savedVersion) || savedVersion < 0)
+      throw new TypeError('TinyLocalStorage: saved version in localStorage is not a valid number.');
+
+    if (version < savedVersion)
+      throw new Error(
+        `TinyLocalStorage: Cannot downgrade database version from ${savedVersion} to ${version}.`,
+      );
+
+    if (version > savedVersion) {
+      onUpgrade(savedVersion, version);
+      localStorage.setItem(this.#dbKey, String(version));
+      this.#version = version;
+    }
+  }
+
+  /**
+   * Gets the current database key used in localStorage.
+   *
+   * @returns {string|null} The database key, or null if not set.
+   */
+  getDbKey() {
+    return this.#dbKey;
+  }
+
+  /**
+   * Gets the current version of the database.
+   *
+   * @returns {number} The current version number.
+   */
+  getVersion() {
+    return this.#version;
+  }
+
   /**
    * Defines a custom storage interface (e.g. `sessionStorage`).
    *
@@ -440,7 +519,7 @@ class TinyLocalStorage {
    */
   setLocalStorage(localstorage) {
     if (!(localstorage instanceof Storage))
-      throw new Error('Argument must be a valid instance of Storage.');
+      throw new TypeError('Argument must be a valid instance of Storage.');
     this.#localStorage = localstorage;
   }
 
@@ -462,7 +541,7 @@ class TinyLocalStorage {
    */
   #setJson(name, data) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     return TinyLocalStorage.encodeSpecialJson(data);
   }
 
@@ -475,13 +554,14 @@ class TinyLocalStorage {
    * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
    */
   setJson(name, data) {
+    this.#isProtectedDbKey(name);
     if (
       !objChecker.isJsonObject(data) &&
       !Array.isArray(data) &&
       !(data instanceof Map) &&
       !(data instanceof Set)
     ) {
-      throw new Error('The storage value is not a valid JSON-compatible structure.');
+      throw new TypeError('The storage value is not a valid JSON-compatible structure.');
     }
     const encoded = this.#setJson(name, data);
     this.emit('setJson', name, data);
@@ -499,7 +579,7 @@ class TinyLocalStorage {
    */
   #getJson(name, defaultData) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     const raw = this.#localStorage.getItem(name);
     const fallbackTypes = {
@@ -553,7 +633,8 @@ class TinyLocalStorage {
    * @param {Date} data
    */
   setDate(name, data) {
-    if (!(data instanceof Date)) throw new Error('Value must be a Date.');
+    this.#isProtectedDbKey(name);
+    if (!(data instanceof Date)) throw new TypeError('Value must be a Date.');
     const encoded = this.#setJson(name, data);
     this.emit('setDate', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -575,7 +656,8 @@ class TinyLocalStorage {
    * @param {RegExp} data
    */
   setRegExp(name, data) {
-    if (!(data instanceof RegExp)) throw new Error('Value must be a RegExp.');
+    this.#isProtectedDbKey(name);
+    if (!(data instanceof RegExp)) throw new TypeError('Value must be a RegExp.');
     const encoded = this.#setJson(name, data);
     this.emit('setRegExp', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -597,7 +679,8 @@ class TinyLocalStorage {
    * @param {bigint} data
    */
   setBigInt(name, data) {
-    if (typeof data !== 'bigint') throw new Error('Value must be a BigInt.');
+    this.#isProtectedDbKey(name);
+    if (typeof data !== 'bigint') throw new TypeError('Value must be a BigInt.');
     const encoded = this.#setJson(name, data);
     this.emit('setBigInt', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -620,7 +703,8 @@ class TinyLocalStorage {
    * @param {symbol} data
    */
   setSymbol(name, data) {
-    if (typeof data !== 'symbol') throw new Error('Value must be a Symbol.');
+    this.#isProtectedDbKey(name);
+    if (typeof data !== 'symbol') throw new TypeError('Value must be a Symbol.');
     const encoded = this.#setJson(name, data);
     this.emit('setSymbol', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -653,8 +737,9 @@ class TinyLocalStorage {
    * @param {any} data - The data to store.
    */
   setItem(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     this.emit('setItem', name, data);
     return this.#localStorage.setItem(name, data);
   }
@@ -667,7 +752,7 @@ class TinyLocalStorage {
    */
   getItem(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     return this.#localStorage.getItem(name);
   }
 
@@ -678,9 +763,10 @@ class TinyLocalStorage {
    * @param {string} data - The string to store.
    */
   setString(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'string') throw new Error('Value must be a string.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'string') throw new TypeError('Value must be a string.');
 
     this.emit('setString', name, data);
     return this.#localStorage.setItem(
@@ -700,7 +786,7 @@ class TinyLocalStorage {
    */
   getString(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     let value = this.#localStorage.getItem(name);
     try {
       /** @type {{ value: string; __string__: boolean }} */
@@ -722,9 +808,10 @@ class TinyLocalStorage {
    * @param {number} data - The number to store.
    */
   setNumber(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'number') throw new Error('Value must be a number.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'number') throw new TypeError('Value must be a number.');
     this.emit('setNumber', name, data);
     return this.#localStorage.setItem(name, String(data));
   }
@@ -737,7 +824,7 @@ class TinyLocalStorage {
    */
   getNumber(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     /** @type {number|string|null} */
     let number = this.#localStorage.getItem(name);
@@ -756,9 +843,10 @@ class TinyLocalStorage {
    * @param {boolean} data - The boolean value to store.
    */
   setBool(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'boolean') throw new Error('Value must be a boolean.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'boolean') throw new TypeError('Value must be a boolean.');
     this.emit('setBool', name, data);
     return this.#localStorage.setItem(name, String(data));
   }
@@ -771,7 +859,7 @@ class TinyLocalStorage {
    */
   getBool(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     const value = this.#localStorage.getItem(name);
     if (typeof value === 'boolean') return value;
@@ -790,7 +878,7 @@ class TinyLocalStorage {
    */
   removeItem(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     this.emit('removeItem', name);
     return this.#localStorage.removeItem(name);

package/dist/v1/libs/TinyLocalStorage.d.mts

@@ -130,6 +130,13 @@ declare class TinyLocalStorage {
     static deleteJsonType(type: any): boolean;
     static encodeSpecialJson(value: any): any;
     static decodeSpecialJson(value: any): any;
+    /**
+     * Initializes the TinyLocalStorage instance and sets up cross-tab sync.
+     *
+     * Adds listener for the native `storage` event to support tab synchronization.
+     * @param {string} [dbName] - Unique database name.
+     */
+    constructor(dbName?: string);
     /**
      * Enables or disables throwing an error when the maximum number of listeners is exceeded.
      *
@@ -258,6 +265,28 @@ declare class TinyLocalStorage {
      * @returns {number} The maximum number of listeners.
      */
     getMaxListeners(): number;
+    /**
+     * Updates the version of the storage and triggers migration if needed.
+     *
+     * @param {number} version - Desired version of the database.
+     * @param {(oldVersion: number, newVersion: number) => void} onUpgrade - Callback to perform migration logic.
+     * @throws {Error} If the database key has not been initialized.
+     * @throws {TypeError} If `version` is not a valid positive number.
+     * @throws {TypeError} If `onUpgrade` is not a function.
+     */
+    updateStorageVersion(version: number, onUpgrade: (oldVersion: number, newVersion: number) => void): void;
+    /**
+     * Gets the current database key used in localStorage.
+     *
+     * @returns {string|null} The database key, or null if not set.
+     */
+    getDbKey(): string | null;
+    /**
+     * Gets the current version of the database.
+     *
+     * @returns {number} The current version number.
+     */
+    getVersion(): number;
     /**
      * Defines a custom storage interface (e.g. `sessionStorage`).
      *