tiny-essentials 1.19.1 → 1.19.3

package/dist/v1/libs/TinyLocalStorage.mjs

@@ -4,6 +4,21 @@ import TinyEvents from './TinyEvents.mjs';
 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.
  *
@@ -243,25 +258,50 @@ class TinyLocalStorage {
         return this.#events.getMaxListeners();
     }
     ///////////////////////////////////////////////////
+    /**
+     * 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;
     }
     //////////////////////////////////////////////////////
     /**
@@ -335,16 +375,83 @@ 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);
     /**
      * 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`).
      *
@@ -352,7 +459,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;
     }
     /**
@@ -372,7 +479,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);
     }
     /**
@@ -384,11 +491,12 @@ class TinyLocalStorage {
      * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
      */
     setJson(name, data) {
+        this.#isProtectedDbKey(name);
         if (!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);
@@ -405,7 +513,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 = {
             obj: () => ({}),
@@ -451,8 +559,9 @@ class TinyLocalStorage {
      * @param {Date} data
      */
     setDate(name, data) {
+        this.#isProtectedDbKey(name);
         if (!(data instanceof Date))
-            throw new Error('Value must be a 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));
@@ -472,8 +581,9 @@ class TinyLocalStorage {
      * @param {RegExp} data
      */
     setRegExp(name, data) {
+        this.#isProtectedDbKey(name);
         if (!(data instanceof RegExp))
-            throw new Error('Value must be a 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));
@@ -493,8 +603,9 @@ class TinyLocalStorage {
      * @param {bigint} data
      */
     setBigInt(name, data) {
+        this.#isProtectedDbKey(name);
         if (typeof data !== 'bigint')
-            throw new Error('Value must be a 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));
@@ -515,8 +626,9 @@ class TinyLocalStorage {
      * @param {symbol} data
      */
     setSymbol(name, data) {
+        this.#isProtectedDbKey(name);
         if (typeof data !== 'symbol')
-            throw new Error('Value must be a 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));
@@ -546,8 +658,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);
     }
@@ -559,7 +672,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);
     }
     /**
@@ -569,12 +682,16 @@ 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.');
+            throw new TypeError('Key must be a non-empty string.');
         if (typeof data !== 'string')
-            throw new Error('Value must be a 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,
+        }));
     }
     /**
      * Retrieves a string value from `localStorage`.
@@ -584,8 +701,19 @@ 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 (!isJsonObject(value) || !value.__string__ || typeof value.value !== 'string')
+                return null;
+            value = value.value;
+        }
+        catch {
+            value = null;
+        }
         if (typeof value === 'string')
             return value;
         return null;
@@ -597,10 +725,11 @@ 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.');
+            throw new TypeError('Key must be a non-empty string.');
         if (typeof data !== 'number')
-            throw new Error('Value must be a number.');
+            throw new TypeError('Value must be a number.');
         this.emit('setNumber', name, data);
         return this.#localStorage.setItem(name, String(data));
     }
@@ -612,7 +741,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);
         if (typeof number === 'number')
@@ -631,10 +760,11 @@ 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.');
+            throw new TypeError('Key must be a non-empty string.');
         if (typeof data !== 'boolean')
-            throw new Error('Value must be a boolean.');
+            throw new TypeError('Value must be a boolean.');
         this.emit('setBool', name, data);
         return this.#localStorage.setItem(name, String(data));
     }
@@ -646,7 +776,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;
@@ -665,7 +795,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);
     }
@@ -692,7 +822,7 @@ TinyLocalStorage.registerJsonType(Map, (value, encodeSpecialJson) => ({
     check: (value) => value.__map__,
     /** @param {{ data: any[] }} value */
     decode: (value, decodeSpecialJson) => new Map(value.data.map(([k, v]) => [k, decodeSpecialJson(v)])),
-});
+}, true);
 // Set
 TinyLocalStorage.registerJsonType(Set, (value, encodeSpecialJson) => ({
     __set__: true,
@@ -700,7 +830,7 @@ TinyLocalStorage.registerJsonType(Set, (value, encodeSpecialJson) => ({
 }), {
     check: (value) => value.__set__,
     decode: (value, decodeSpecialJson) => new Set(value.data.map(decodeSpecialJson)),
-});
+}, true);
 // Date
 TinyLocalStorage.registerJsonType(Date, (value) => ({
     __date__: true,
@@ -708,7 +838,7 @@ TinyLocalStorage.registerJsonType(Date, (value) => ({
 }), {
     check: (value) => value.__date__,
     decode: (value) => new Date(value.value),
-});
+}, true);
 // Regex
 TinyLocalStorage.registerJsonType(RegExp, (value) => ({
     __regexp__: true,
@@ -717,7 +847,7 @@ TinyLocalStorage.registerJsonType(RegExp, (value) => ({
 }), {
     check: (value) => value.__regexp__,
     decode: (value) => new RegExp(value.source, value.flags),
-});
+}, true);
 // Big Int
 TinyLocalStorage.registerJsonType('bigint', (value) => ({
     __bigint__: true,
@@ -725,7 +855,7 @@ TinyLocalStorage.registerJsonType('bigint', (value) => ({
 }), {
     check: (value) => value.__bigint__,
     decode: (value) => BigInt(value.value),
-});
+}, true);
 // Symbol
 TinyLocalStorage.registerJsonType('symbol', (value) => ({
     __symbol__: true,
@@ -736,5 +866,5 @@ TinyLocalStorage.registerJsonType('symbol', (value) => ({
         const key = value.key;
         return key != null ? Symbol.for(key) : Symbol();
     },
-});
+}, true);
 export default TinyLocalStorage;

package/docs/v1/libs/TinyLocalStorage.md

@@ -32,6 +32,59 @@ console.log(storage.getDate('today') instanceof Date); // true
 
 ---
 
+## 🏁 `constructor(dbName?: string)`
+
+Initializes the `TinyLocalStorage` instance and sets up cross-tab synchronization.
+
+### 🔧 Parameters
+
+* `dbName` (optional, `string`) – A unique name for the database. It becomes the base key used internally in `localStorage`.
+
+### 📡 Behavior
+
+* Automatically adds a `storage` event listener to support syncing across browser tabs.
+
+---
+
+## 🔁 `updateStorageVersion(version: number, onUpgrade: (oldVersion: number, newVersion: number) => void)`
+
+Updates the version of the database. If the new version is higher than the current one, it triggers the provided migration callback.
+
+### 🔧 Parameters
+
+* `version` (`number`) – The desired new version of the database. Must be a positive integer.
+* `onUpgrade` (`function`) – A callback function executed during upgrade. Receives `oldVersion` and `newVersion` as arguments.
+
+### ⚠️ Throws
+
+* `Error` – If the database key hasn't been initialized via the constructor.
+* `TypeError` – If `version` is invalid (not a number, NaN, or < 1).
+* `TypeError` – If `onUpgrade` is not a function.
+* `TypeError` – If the saved version in `localStorage` is invalid.
+* `Error` – If the provided `version` is lower than the stored version (downgrade is not supported).
+
+---
+
+## 🔑 `getDbKey(): string | null`
+
+Returns the current internal database key used in `localStorage`.
+
+### 🔙 Returns
+
+* `string | null` – The full storage key prefix (e.g. `LSDB::yourDbName`), or `null` if uninitialized.
+
+---
+
+## 🧮 `getVersion(): number`
+
+Returns the current active version of the storage system.
+
+### 🔙 Returns
+
+* `number` – The version number currently in use.
+
+---
+
 ## 📦 Storage Methods
 
 ### `setJson(key, data)`
@@ -243,7 +296,7 @@ Returns `true` if the browser supports the configured storage backend.
 
 ## 🧩 Custom Type Registration
 
-### `registerJsonType(type, encodeFn, decodeFn)`
+### `registerJsonType(type, encodeFn, decodeFn, freezeType?)`
 
 Registers support for custom types with encoder/decoder logic.
 
@@ -254,10 +307,15 @@ registerJsonType(
   decodeFn: {
     check: (value: any) => boolean,
     decode: (value: any, decodeSpecialJson: DecodeFn) => any
-  }
+  },
+  freezeType?: boolean // default: false
 ): void
 ```
 
+Registers a custom type by associating it with encoder and decoder logic. If `freezeType` is set to `true`, the type becomes immutable and cannot be unregistered or overwritten later.
+
+> ⚠️ Throws an error if trying to register a type that is already frozen.
+
 ---
 
 ### `deleteJsonType(type)`
@@ -265,10 +323,24 @@ registerJsonType(
 Unregisters a previously registered custom type.
 
 ```ts
-deleteJsonType(type: any): void
+deleteJsonType(type: any): boolean
+```
+
+Removes the encoder and decoder associated with the given type. Returns `true` if the type was found and removed, or `false` if it was not registered.
+
+> ❌ Throws an error if the type was marked as frozen via `freezeType`.
+
+---
+
+### `hasJsonType(type)`
+
+Checks whether a type is currently registered for custom encoding/decoding.
+
+```ts
+hasJsonType(type: any): boolean
 ```
 
-Removes the encoder and decoder associated with the given type. Useful for cleanup or reconfiguration.
+Returns `true` if the type has both encoder and decoder registered, otherwise `false`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.19.1",
+  "version": "1.19.3",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",