tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinyLocalStorage.mjs

@@ -1,5 +1,7 @@
+import { EventEmitter } from 'events';
 import { isJsonObject } from '../basics/objChecker.mjs';
-import TinyEvents from './TinyEvents.mjs';
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyLocalStorage');
 /** @type {Map<any, EncodeFn>} */
 const customEncoders = new Map();
 /** @type {Map<any, DecodeFn>} */
@@ -73,7 +75,7 @@ const customTypesFreezed = new Set([
  * - Type-specific `set` and `get` methods (`setDate`, `getBool`, etc.)
  * - `getValue()` to retrieve any structure regardless of type
  * - Auto-encoding/decoding with support for custom types via `registerJsonType`
- * - Built-in event system (`TinyEvents`) to listen for changes
+ * - Built-in event system to listen for changes
  * - Optional fallback values on decoding errors
  *
  * Supports registering and unregistering custom types via:
@@ -82,181 +84,7 @@ const customTypesFreezed = new Set([
  *
  * This class is suitable for applications that require structured persistence in the browser.
  */
-class TinyLocalStorage {
-    /** @typedef {import('./TinyEvents.mjs').handler} handler */
-    #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|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|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|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|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|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|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|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|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();
-    }
-    //////////////////////////////////////////////////////
-    /**
-     * Emits an event, triggering all registered handlers for that event.
-     *
-     * @param {string} event - The event name to emit.
-     * @param {...any} payload - Optional data to pass to each handler.
-     * @returns {boolean[]} True if any listeners were called, false otherwise.
-     */
-    emit(event, ...payload) {
-        return this.#events.emit(event, ...payload);
-    }
-    /**
-     * 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();
-    }
-    ///////////////////////////////////////////////////
+class TinyLocalStorage extends EventEmitter {
     /**
      * Checks whether a JSON-serializable type is already registered.
      *
@@ -372,6 +200,19 @@ class TinyLocalStorage {
         return value;
     }
     //////////////////////////////////////////////////////
+    /**
+     * Tracks whether the instance has been destroyed.
+     * @type {boolean}
+     */
+    #destroyed = false;
+    /**
+     * Gets the current destruction status of the instance.
+     *
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
+     */
+    get destroyed() {
+        return this.#destroyed;
+    }
     /** @type {Storage} */
     #localStorage = window.localStorage;
     /** @type {string|null} */
@@ -387,6 +228,7 @@ class TinyLocalStorage {
      * @param {string} [dbName] - Unique database name.
      */
     constructor(dbName) {
+        super();
         if (typeof dbName !== 'undefined' && typeof dbName !== 'string')
             throw new TypeError('TinyLocalStorage: dbName must be a string if provided.');
         if (typeof dbName === 'string')
@@ -417,6 +259,7 @@ class TinyLocalStorage {
      * @throws {TypeError} If `onUpgrade` is not a function.
      */
     updateStorageVersion(version, onUpgrade) {
+        checkDestroy(this.#destroyed);
         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)
@@ -441,6 +284,7 @@ class TinyLocalStorage {
      * @returns {string|null} The database key, or null if not set.
      */
     getDbKey() {
+        checkDestroy(this.#destroyed);
         return this.#dbKey;
     }
     /**
@@ -449,6 +293,7 @@ class TinyLocalStorage {
      * @returns {number} The current version number.
      */
     getVersion() {
+        checkDestroy(this.#destroyed);
         return this.#version;
     }
     /**
@@ -457,6 +302,7 @@ class TinyLocalStorage {
      * @param {Storage} localstorage - A valid Storage object (localStorage or sessionStorage).
      */
     setLocalStorage(localstorage) {
+        checkDestroy(this.#destroyed);
         if (!(localstorage instanceof Storage))
             throw new TypeError('Argument must be a valid instance of Storage.');
         this.#localStorage = localstorage;
@@ -467,6 +313,7 @@ class TinyLocalStorage {
      * @returns {boolean} True if `localStorage` exists, false otherwise.
      */
     localStorageExists() {
+        checkDestroy(this.#destroyed);
         return this.#localStorage instanceof Storage;
     }
     /**
@@ -490,6 +337,7 @@ class TinyLocalStorage {
      * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
      */
     setJson(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (!isJsonObject(data) &&
             !Array.isArray(data) &&
@@ -544,6 +392,7 @@ class TinyLocalStorage {
      * @returns {LocalStorageJsonValue|null} The parsed object or fallback.
      */
     getJson(name, defaultData) {
+        checkDestroy(this.#destroyed);
         const { decoded, fallback } = this.#getJson(name, defaultData);
         if (decoded instanceof Map ||
             decoded instanceof Set ||
@@ -558,6 +407,7 @@ class TinyLocalStorage {
      * @param {Date} data
      */
     setDate(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (!(data instanceof Date))
             throw new TypeError('Value must be a Date.');
@@ -571,6 +421,7 @@ class TinyLocalStorage {
      * @returns {Date|null}
      */
     getDate(name) {
+        checkDestroy(this.#destroyed);
         const value = this.#getJson(name).decoded;
         return value instanceof Date ? value : null;
     }
@@ -580,6 +431,7 @@ class TinyLocalStorage {
      * @param {RegExp} data
      */
     setRegExp(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (!(data instanceof RegExp))
             throw new TypeError('Value must be a RegExp.');
@@ -593,6 +445,7 @@ class TinyLocalStorage {
      * @returns {RegExp|null}
      */
     getRegExp(name) {
+        checkDestroy(this.#destroyed);
         const value = this.#getJson(name).decoded;
         return value instanceof RegExp ? value : null;
     }
@@ -602,6 +455,7 @@ class TinyLocalStorage {
      * @param {bigint} data
      */
     setBigInt(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof data !== 'bigint')
             throw new TypeError('Value must be a BigInt.');
@@ -615,6 +469,7 @@ class TinyLocalStorage {
      * @returns {bigint|null}
      */
     getBigInt(name) {
+        checkDestroy(this.#destroyed);
         const value = this.#getJson(name).decoded;
         return typeof value === 'bigint' ? value : null;
     }
@@ -625,6 +480,7 @@ class TinyLocalStorage {
      * @param {symbol} data
      */
     setSymbol(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof data !== 'symbol')
             throw new TypeError('Value must be a Symbol.');
@@ -638,6 +494,7 @@ class TinyLocalStorage {
      * @returns {symbol|null}
      */
     getSymbol(name) {
+        checkDestroy(this.#destroyed);
         const value = this.#getJson(name).decoded;
         return typeof value === 'symbol' ? value : null;
     }
@@ -648,6 +505,7 @@ class TinyLocalStorage {
      * @returns {any} The stored value or null if not found.
      */
     getValue(name) {
+        checkDestroy(this.#destroyed);
         return this.#getJson(name).decoded ?? null;
     }
     /**
@@ -657,6 +515,7 @@ class TinyLocalStorage {
      * @param {any} data - The data to store.
      */
     setItem(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
@@ -670,6 +529,7 @@ class TinyLocalStorage {
      * @returns {string|null} The stored value or null if not found.
      */
     getItem(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
         return this.#localStorage.getItem(name);
@@ -681,6 +541,7 @@ class TinyLocalStorage {
      * @param {string} data - The string to store.
      */
     setString(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
@@ -699,6 +560,7 @@ class TinyLocalStorage {
      * @returns {string|null} The string if valid, or null.
      */
     getString(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
         let value = this.#localStorage.getItem(name);
@@ -724,6 +586,7 @@ class TinyLocalStorage {
      * @param {number} data - The number to store.
      */
     setNumber(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
@@ -739,6 +602,7 @@ class TinyLocalStorage {
      * @returns {number|null} The number or null if invalid.
      */
     getNumber(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
         /** @type {number|string|null} */
@@ -759,6 +623,7 @@ class TinyLocalStorage {
      * @param {boolean} data - The boolean value to store.
      */
     setBool(name, data) {
+        checkDestroy(this.#destroyed);
         this.#isProtectedDbKey(name);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
@@ -774,6 +639,7 @@ class TinyLocalStorage {
      * @returns {boolean|null} The boolean or null if invalid.
      */
     getBool(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
         const value = this.#localStorage.getItem(name);
@@ -793,6 +659,7 @@ class TinyLocalStorage {
      * @param {string} name - The key to remove.
      */
     removeItem(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name.length)
             throw new TypeError('Key must be a non-empty string.');
         this.emit('removeItem', name);
@@ -802,14 +669,19 @@ class TinyLocalStorage {
      * Clears all data from `localStorage`.
      */
     clearLocalStorage() {
+        checkDestroy(this.#destroyed);
         return this.#localStorage.clear();
     }
     /**
      * Destroys the storage instance by removing the storage event listener.
      */
     destroy() {
+        if (this.#destroyed)
+            return;
         window.removeEventListener('storage', this.#storageEvent);
-        this.#events.offAllTypes();
+        this.removeAllListeners();
+        // Lock the instance
+        this.#destroyed = true;
     }
 }
 // First registers