tiny-essentials 1.19.0 → 1.19.2

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;
   }
 
   //////////////////////////////////////////////////////
@@ -446,7 +485,7 @@ class TinyLocalStorage {
     }
     const encoded = this.#setJson(name, data);
     this.emit('setJson', name, data);
-    this.#localStorage.setItem(name, JSON.stringify(encoded));
+    return this.#localStorage.setItem(name, JSON.stringify(encoded));
   }
 
   /**
@@ -516,8 +555,8 @@ class TinyLocalStorage {
   setDate(name, data) {
     if (!(data instanceof Date)) throw new Error('Value must be a Date.');
     const encoded = this.#setJson(name, data);
-    this.#localStorage.setItem(name, JSON.stringify(encoded));
     this.emit('setDate', name, data);
+    return this.#localStorage.setItem(name, JSON.stringify(encoded));
   }
 
   /**
@@ -538,8 +577,8 @@ class TinyLocalStorage {
   setRegExp(name, data) {
     if (!(data instanceof RegExp)) throw new Error('Value must be a RegExp.');
     const encoded = this.#setJson(name, data);
-    this.#localStorage.setItem(name, JSON.stringify(encoded));
     this.emit('setRegExp', name, data);
+    return this.#localStorage.setItem(name, JSON.stringify(encoded));
   }
 
   /**
@@ -560,8 +599,8 @@ class TinyLocalStorage {
   setBigInt(name, data) {
     if (typeof data !== 'bigint') throw new Error('Value must be a BigInt.');
     const encoded = this.#setJson(name, data);
-    this.#localStorage.setItem(name, JSON.stringify(encoded));
     this.emit('setBigInt', name, data);
+    return this.#localStorage.setItem(name, JSON.stringify(encoded));
   }
 
   /**
@@ -583,8 +622,8 @@ class TinyLocalStorage {
   setSymbol(name, data) {
     if (typeof data !== 'symbol') throw new Error('Value must be a Symbol.');
     const encoded = this.#setJson(name, data);
-    this.#localStorage.setItem(name, JSON.stringify(encoded));
     this.emit('setSymbol', name, data);
+    return this.#localStorage.setItem(name, JSON.stringify(encoded));
   }
 
   /**
@@ -644,7 +683,13 @@ class TinyLocalStorage {
     if (typeof data !== 'string') throw new Error('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,
+      }),
+    );
   }
 
   /**
@@ -657,6 +702,15 @@ class TinyLocalStorage {
     if (typeof name !== 'string' || !name.length)
       throw new Error('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;
   }
@@ -746,7 +800,7 @@ class TinyLocalStorage {
    * Clears all data from `localStorage`.
    */
   clearLocalStorage() {
-    this.#localStorage.clear();
+    return this.#localStorage.clear();
   }
 
   /**
@@ -773,6 +827,7 @@ TinyLocalStorage.registerJsonType(
     decode: (value, decodeSpecialJson) =>
       new Map(value.data.map(([k, v]) => [k, decodeSpecialJson(v)])),
   },
+  true,
 );
 
 // Set
@@ -786,6 +841,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__set__,
     decode: (value, decodeSpecialJson) => new Set(value.data.map(decodeSpecialJson)),
   },
+  true,
 );
 
 // Date
@@ -799,6 +855,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__date__,
     decode: (value) => new Date(value.value),
   },
+  true,
 );
 
 // Regex
@@ -813,6 +870,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__regexp__,
     decode: (value) => new RegExp(value.source, value.flags),
   },
+  true,
 );
 
 // Big Int
@@ -826,6 +884,7 @@ TinyLocalStorage.registerJsonType(
     check: (value) => value.__bigint__,
     decode: (value) => BigInt(value.value),
   },
+  true,
 );
 
 // Symbol
@@ -842,6 +901,7 @@ TinyLocalStorage.registerJsonType(
       return key != null ? Symbol.for(key) : Symbol();
     },
   },
+  true,
 );
 
 module.exports = TinyLocalStorage;

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

@@ -101,20 +101,33 @@ 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;
     /**

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;
     }
     //////////////////////////////////////////////////////
     /**
@@ -392,7 +432,7 @@ class TinyLocalStorage {
         }
         const encoded = this.#setJson(name, data);
         this.emit('setJson', name, data);
-        this.#localStorage.setItem(name, JSON.stringify(encoded));
+        return this.#localStorage.setItem(name, JSON.stringify(encoded));
     }
     /**
      * Retrieves a value from `localStorage`.
@@ -454,8 +494,8 @@ class TinyLocalStorage {
         if (!(data instanceof Date))
             throw new Error('Value must be a Date.');
         const encoded = this.#setJson(name, data);
-        this.#localStorage.setItem(name, JSON.stringify(encoded));
         this.emit('setDate', name, data);
+        return this.#localStorage.setItem(name, JSON.stringify(encoded));
     }
     /**
      * Retrieves a Date from localStorage.
@@ -475,8 +515,8 @@ class TinyLocalStorage {
         if (!(data instanceof RegExp))
             throw new Error('Value must be a RegExp.');
         const encoded = this.#setJson(name, data);
-        this.#localStorage.setItem(name, JSON.stringify(encoded));
         this.emit('setRegExp', name, data);
+        return this.#localStorage.setItem(name, JSON.stringify(encoded));
     }
     /**
      * Retrieves a RegExp from localStorage.
@@ -496,8 +536,8 @@ class TinyLocalStorage {
         if (typeof data !== 'bigint')
             throw new Error('Value must be a BigInt.');
         const encoded = this.#setJson(name, data);
-        this.#localStorage.setItem(name, JSON.stringify(encoded));
         this.emit('setBigInt', name, data);
+        return this.#localStorage.setItem(name, JSON.stringify(encoded));
     }
     /**
      * Retrieves a BigInt from localStorage.
@@ -518,8 +558,8 @@ class TinyLocalStorage {
         if (typeof data !== 'symbol')
             throw new Error('Value must be a Symbol.');
         const encoded = this.#setJson(name, data);
-        this.#localStorage.setItem(name, JSON.stringify(encoded));
         this.emit('setSymbol', name, data);
+        return this.#localStorage.setItem(name, JSON.stringify(encoded));
     }
     /**
      * Retrieves a Symbol from localStorage.
@@ -574,7 +614,10 @@ class TinyLocalStorage {
         if (typeof data !== 'string')
             throw new Error('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`.
@@ -586,6 +629,17 @@ class TinyLocalStorage {
         if (typeof name !== 'string' || !name.length)
             throw new Error('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;
@@ -673,7 +727,7 @@ class TinyLocalStorage {
      * Clears all data from `localStorage`.
      */
     clearLocalStorage() {
-        this.#localStorage.clear();
+        return this.#localStorage.clear();
     }
     /**
      * Destroys the storage instance by removing the storage event listener.
@@ -692,7 +746,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 +754,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 +762,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 +771,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 +779,7 @@ TinyLocalStorage.registerJsonType('bigint', (value) => ({
 }), {
     check: (value) => value.__bigint__,
     decode: (value) => BigInt(value.value),
-});
+}, true);
 // Symbol
 TinyLocalStorage.registerJsonType('symbol', (value) => ({
     __symbol__: true,
@@ -736,5 +790,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

@@ -243,7 +243,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 +254,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 +270,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.0",
+  "version": "1.19.2",
   "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",