tiny-essentials 1.19.1 → 1.19.3

package/dist/v1/libs/TinyLocalStorage.cjs

@@ -9,6 +9,22 @@ const customEncoders = new Map();
 /** @type {Map<any, DecodeFn>} */
 const customDecoders = new Map();
 
+/** @type {Set<any>} */
+const customTypesFreezed = new Set([
+  'string',
+  'boolean',
+  'number',
+  'object',
+  'array',
+  String,
+  Boolean,
+  Number,
+  Object,
+  Array,
+  BigInt,
+  Symbol,
+]);
+
 /**
  * A function that encodes a value into a serializable JSON-compatible format.
  *
@@ -280,26 +296,49 @@ class TinyLocalStorage {
 
   ///////////////////////////////////////////////////
 
+  /**
+   * Checks whether a JSON-serializable type is already registered.
+   *
+   * @param {any} type - The type identifier, which can be a string (e.g., `"bigint"`, `"symbol"`)
+   *                     or a reference to a class/constructor function.
+   * @returns {boolean} True if the type has both an encoder and decoder registered.
+   */
+  static hasJsonType(type) {
+    return (customEncoders.has(type) && customDecoders.has(type)) || customTypesFreezed.has(type);
+  }
+
   /**
    * Registers a new JSON-serializable type with its encoder and decoder.
    *
-   * @param {any} type - The type or primitive type name (e.g. `"bigint"`, `"symbol"`, etc).
-   * @param {EncodeFn} encodeFn - The function that encodes the value.
-   * @param {DecodeFn} decodeFn - An object with `check` and `decode` methods for restoring the value.
+   * @param {any} type - The type identifier, which can be a string (e.g., `"bigint"`, `"symbol"`)
+   *                     or a reference to a class/constructor function.
+   * @param {EncodeFn} encodeFn - A function that receives a value of this type and returns a JSON-safe representation.
+   * @param {DecodeFn} decodeFn - An object with `check(value)` to identify this type and `decode(value)` to restore it.
+   * @param {boolean} [freezeType=false] - If true, prevents this type from being unregistered later.
+   * @throws {Error} Throws an error if the type is frozen and cannot be registered.
    */
-  static registerJsonType(type, encodeFn, decodeFn) {
+  static registerJsonType(type, encodeFn, decodeFn, freezeType = false) {
+    if (customTypesFreezed.has(type))
+      throw new Error(`Cannot register type "${type}" because it is frozen.`);
     customEncoders.set(type, encodeFn);
     customDecoders.set(type, decodeFn);
+    if (freezeType) customTypesFreezed.add(type);
   }
 
   /**
-   * Removes a previously registered custom type from the encoding/decoding system.
+   * Unregisters a previously registered custom type from the encoding/decoding system.
    *
-   * @param {string} type - The primitive name or constructor reference used in registration.
+   * @param {any} type - The primitive name or constructor reference used in the registration.
+   * @returns {boolean} Returns true if the type existed and was removed, or false if it wasn't found.
+   * @throws {Error} Throws an error if the type is frozen and cannot be unregistered.
    */
   static deleteJsonType(type) {
-    customEncoders.delete(type);
-    customDecoders.delete(type);
+    if (customTypesFreezed.has(type))
+      throw new Error(`Cannot remove type "${type}" because it is frozen.`);
+    let isDeleted = false;
+    if (customEncoders.delete(type)) isDeleted = true;
+    if (customDecoders.delete(type)) isDeleted = true;
+    return isDeleted;
   }
 
   //////////////////////////////////////////////////////
@@ -382,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);
 
@@ -389,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`).
    *
@@ -401,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;
   }
 
@@ -423,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);
   }
 
@@ -436,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);
@@ -460,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 = {
@@ -514,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));
@@ -536,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));
@@ -558,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));
@@ -581,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));
@@ -614,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);
   }
@@ -628,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);
   }
 
@@ -639,12 +763,19 @@ 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(name, data);
+    return this.#localStorage.setItem(
+      name,
+      JSON.stringify({
+        __string__: true,
+        value: data,
+      }),
+    );
   }
 
   /**
@@ -655,8 +786,17 @@ 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 }} */
+      // @ts-ignore
+      value = JSON.parse(value);
+      if (!objChecker.isJsonObject(value) || !value.__string__ || typeof value.value !== 'string') return null;
+      value = value.value;
+    } catch {
+      value = null;
+    }
     if (typeof value === 'string') return value;
     return null;
   }
@@ -668,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));
   }
@@ -683,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);
@@ -702,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));
   }
@@ -717,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;
@@ -736,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);
@@ -773,6 +915,7 @@ TinyLocalStorage.registerJsonType(
     decode: (value, decodeSpecialJson) =>
       new Map(value.data.map(([k, v]) => [k, decodeSpecialJson(v)])),
   },
+  true,
 );
 
 // Set
@@ -786,6 +929,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__set__,
     decode: (value, decodeSpecialJson) => new Set(value.data.map(decodeSpecialJson)),
   },
+  true,
 );
 
 // Date
@@ -799,6 +943,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__date__,
     decode: (value) => new Date(value.value),
   },
+  true,
 );
 
 // Regex
@@ -813,6 +958,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__regexp__,
     decode: (value) => new RegExp(value.source, value.flags),
   },
+  true,
 );
 
 // Big Int
@@ -826,6 +972,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__bigint__,
     decode: (value) => BigInt(value.value),
   },
+  true,
 );
 
 // Symbol
@@ -842,6 +989,7 @@ TinyLocalStorage.registerJsonType(
       return key != null ? Symbol.for(key) : Symbol();
     },
   },
+  true,
 );
 
 module.exports = TinyLocalStorage;

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

@@ -101,22 +101,42 @@ 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 {
+    /**
+     * Checks whether a JSON-serializable type is already registered.
+     *
+     * @param {any} type - The type identifier, which can be a string (e.g., `"bigint"`, `"symbol"`)
+     *                     or a reference to a class/constructor function.
+     * @returns {boolean} True if the type has both an encoder and decoder registered.
+     */
+    static hasJsonType(type: any): boolean;
     /**
      * Registers a new JSON-serializable type with its encoder and decoder.
      *
-     * @param {any} type - The type or primitive type name (e.g. `"bigint"`, `"symbol"`, etc).
-     * @param {EncodeFn} encodeFn - The function that encodes the value.
-     * @param {DecodeFn} decodeFn - An object with `check` and `decode` methods for restoring the value.
+     * @param {any} type - The type identifier, which can be a string (e.g., `"bigint"`, `"symbol"`)
+     *                     or a reference to a class/constructor function.
+     * @param {EncodeFn} encodeFn - A function that receives a value of this type and returns a JSON-safe representation.
+     * @param {DecodeFn} decodeFn - An object with `check(value)` to identify this type and `decode(value)` to restore it.
+     * @param {boolean} [freezeType=false] - If true, prevents this type from being unregistered later.
+     * @throws {Error} Throws an error if the type is frozen and cannot be registered.
      */
-    static registerJsonType(type: any, encodeFn: EncodeFn, decodeFn: DecodeFn): void;
+    static registerJsonType(type: any, encodeFn: EncodeFn, decodeFn: DecodeFn, freezeType?: boolean): void;
     /**
-     * Removes a previously registered custom type from the encoding/decoding system.
+     * Unregisters a previously registered custom type from the encoding/decoding system.
      *
-     * @param {string} type - The primitive name or constructor reference used in registration.
+     * @param {any} type - The primitive name or constructor reference used in the registration.
+     * @returns {boolean} Returns true if the type existed and was removed, or false if it wasn't found.
+     * @throws {Error} Throws an error if the type is frozen and cannot be unregistered.
      */
-    static deleteJsonType(type: string): void;
+    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.
      *
@@ -245,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`).
      *