tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinyLocalStorage.cjs

@@ -1,7 +1,10 @@
 'use strict';
 
+var events = require('events');
 var objChecker = require('../basics/objChecker.cjs');
-var TinyEvents = require('./TinyEvents.cjs');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyLocalStorage');
 
 /** @type {Map<any, EncodeFn>} */
 const customEncoders = new Map();
@@ -84,7 +87,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:
@@ -93,208 +96,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 events.EventEmitter {
   /**
    * Checks whether a JSON-serializable type is already registered.
    *
@@ -417,6 +219,21 @@ class TinyLocalStorage {
 
   //////////////////////////////////////////////////////
 
+  /**
+   * 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;
 
@@ -436,6 +253,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') this.#dbKey = `LSDB::${dbName}`;
@@ -467,6 +285,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.',
@@ -499,6 +318,7 @@ class TinyLocalStorage {
    * @returns {string|null} The database key, or null if not set.
    */
   getDbKey() {
+    checkDestroy(this.#destroyed);
     return this.#dbKey;
   }
 
@@ -508,6 +328,7 @@ class TinyLocalStorage {
    * @returns {number} The current version number.
    */
   getVersion() {
+    checkDestroy(this.#destroyed);
     return this.#version;
   }
 
@@ -517,6 +338,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;
@@ -528,6 +350,7 @@ class TinyLocalStorage {
    * @returns {boolean} True if `localStorage` exists, false otherwise.
    */
   localStorageExists() {
+    checkDestroy(this.#destroyed);
     return this.#localStorage instanceof Storage;
   }
 
@@ -553,6 +376,7 @@ class TinyLocalStorage {
    * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
    */
   setJson(name, data) {
+    checkDestroy(this.#destroyed);
     this.#isProtectedDbKey(name);
     if (
       !objChecker.isJsonObject(data) &&
@@ -615,6 +439,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 ||
@@ -632,6 +457,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.');
     const encoded = this.#setJson(name, data);
@@ -645,6 +471,7 @@ class TinyLocalStorage {
    * @returns {Date|null}
    */
   getDate(name) {
+    checkDestroy(this.#destroyed);
     const value = this.#getJson(name).decoded;
     return value instanceof Date ? value : null;
   }
@@ -655,6 +482,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.');
     const encoded = this.#setJson(name, data);
@@ -668,6 +496,7 @@ class TinyLocalStorage {
    * @returns {RegExp|null}
    */
   getRegExp(name) {
+    checkDestroy(this.#destroyed);
     const value = this.#getJson(name).decoded;
     return value instanceof RegExp ? value : null;
   }
@@ -678,6 +507,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.');
     const encoded = this.#setJson(name, data);
@@ -691,6 +521,7 @@ class TinyLocalStorage {
    * @returns {bigint|null}
    */
   getBigInt(name) {
+    checkDestroy(this.#destroyed);
     const value = this.#getJson(name).decoded;
     return typeof value === 'bigint' ? value : null;
   }
@@ -702,6 +533,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.');
     const encoded = this.#setJson(name, data);
@@ -715,6 +547,7 @@ class TinyLocalStorage {
    * @returns {symbol|null}
    */
   getSymbol(name) {
+    checkDestroy(this.#destroyed);
     const value = this.#getJson(name).decoded;
     return typeof value === 'symbol' ? value : null;
   }
@@ -726,6 +559,7 @@ class TinyLocalStorage {
    * @returns {any} The stored value or null if not found.
    */
   getValue(name) {
+    checkDestroy(this.#destroyed);
     return this.#getJson(name).decoded ?? null;
   }
 
@@ -736,6 +570,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.');
@@ -750,6 +585,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);
@@ -762,6 +598,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.');
@@ -784,6 +621,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);
@@ -807,6 +645,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.');
@@ -822,6 +661,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.');
 
@@ -842,6 +682,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.');
@@ -857,6 +698,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.');
 
@@ -876,6 +718,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.');
 
@@ -887,6 +730,7 @@ class TinyLocalStorage {
    * Clears all data from `localStorage`.
    */
   clearLocalStorage() {
+    checkDestroy(this.#destroyed);
     return this.#localStorage.clear();
   }
 
@@ -894,8 +738,12 @@ class TinyLocalStorage {
    * 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;
   }
 }
 

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

@@ -91,7 +91,7 @@ export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any
  * - 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:
@@ -100,7 +100,7 @@ export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any
  *
  * This class is suitable for applications that require structured persistence in the browser.
  */
-declare class TinyLocalStorage {
+declare class TinyLocalStorage extends EventEmitter<any> {
     /**
      * Checks whether a JSON-serializable type is already registered.
      *
@@ -138,133 +138,11 @@ declare class TinyLocalStorage {
      */
     constructor(dbName?: string);
     /**
-     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     * Gets the current destruction status of the instance.
      *
-     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
      */
-    setThrowOnMaxListeners(shouldThrow: boolean): void;
-    /**
-     * 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(): boolean;
-    /**
-     * 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: string | string[], handler: import("./TinyEvents.mjs").handler): void;
-    /**
-     * 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: string | string[], handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").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: string | string[], handler: import("./TinyEvents.mjs").handler): void;
-    /**
-     * 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: string | string[], handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").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: string | string[], handler: import("./TinyEvents.mjs").handler): void;
-    /**
-     * 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: string | string[], handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").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: string | string[], handler: import("./TinyEvents.mjs").handler): void;
-    /**
-     * 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: string | string[]): void;
-    /**
-     * Removes all event listeners of all types from the element.
-     */
-    offAllTypes(): void;
-    /**
-     * 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: string): number;
-    /**
-     * 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: string): import("./TinyEvents.mjs").handler[];
-    /**
-     * 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: string): import("./TinyEvents.mjs").handler[];
-    /**
-     * 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: string | symbol): import("./TinyEvents.mjs").handler[];
-    /**
-     * Returns an array of event names for which there are registered listeners.
-     *
-     * @returns {string[]} Array of registered event names.
-     */
-    eventNames(): string[];
-    /**
-     * 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: string, ...payload: any[]): boolean[];
-    /**
-     * Sets the maximum number of listeners per event before a warning is shown.
-     *
-     * @param {number} n - The maximum number of listeners.
-     */
-    setMaxListeners(n: number): void;
-    /**
-     * Gets the maximum number of listeners allowed per event.
-     *
-     * @returns {number} The maximum number of listeners.
-     */
-    getMaxListeners(): number;
+    get destroyed(): boolean;
     /**
      * Updates the version of the storage and triggers migration if needed.
      *
@@ -446,4 +324,5 @@ declare class TinyLocalStorage {
     destroy(): void;
     #private;
 }
+import { EventEmitter } from 'events';
 //# sourceMappingURL=TinyLocalStorage.d.mts.map