hyperstorage-js 5.0.6 → 5.0.7

package/README.md

@@ -2,7 +2,7 @@
 
 A lightweight wrapper for Storage interfaces (e.g., `localStorage` or `sessionStorage`) with **efficient caching** and **type-preserving serialization**.
 
-The biggest burdens of working with the **Storage API** is verifying values on every read, providing proper default values and only being able to store strings, having to `JSON.stringify()` and `JSON.parse()` manually everytime. This package eliminates all of this by providing a safe and automatic wrapper that handles everything at once. You can read/store numbers and objects without any extra steps and lose no performance.
+The biggest burdens of working with the **Storage API** is verifying values on every read, providing proper default values and only being able to store strings, having to `JSON.stringify()` and `JSON.parse()` manually everytime. This package eliminates this all by providing a safe, automatic and efficient wrapper that handles everything for you. You can read/store numbers and objects without any extra steps, lose no performance and improve code readability.
 
 [![npm version](https://img.shields.io/npm/v/hyperstorage-js.svg)](https://www.npmjs.com/package/hyperstorage-js)
 [![npm downloads](https://img.shields.io/npm/dt/hyperstorage-js.svg)](https://www.npmjs.com/package/hyperstorage-js)
@@ -13,7 +13,8 @@ The biggest burdens of working with the **Storage API** is verifying values on e
 ## Features
 
 - 📝 **Default values**: are automatically set when the key is not in Storage.
-- 🧩 **JSON support**: automatically serializes and parses objects or non-string primitives (`undefined`, `NaN`, `Infinity`) which the Storage API does not support by default.
+- 🧩 **JSON support**: automatically serializes and parses objects or non-string primitives (numbers, `undefined`, `NaN`, etc.) which the Storage API does not support by default.
+- 🛠️ **Utility helpers**: built-in helper methods (like `.set()` and `.isDefault()`) to simplify storage operations.
 - ⚡ **Fast caching**: memory cache avoids repeated JSON convertions.
 - 🔒 **Optional encoding/decoding** hooks to obfuscate data.
 - 🌐 **Custom storage**: works with any object implementing the standard Storage API. (`localStorage`, `sessionStorage`, ...)
@@ -60,39 +61,38 @@ import HyperStorage from 'hyperstorage-js'
 ```
 
 ```js
-const defaultValue = { theme: 'dark', language: 'en' }
+const defaultValue = { theme: 'light', language: 'en' }
 const userStore = new HyperStorage('userSettings', defaultValue)
 
 // If 'userSettings' is not present in the Storage, the defaultValue is set:
-console.log(userStore.value) // { theme: 'dark', language: 'en' }
+console.log(userStore.value) // { theme: 'light', language: 'en' }
 
-// Change theme to light:
-userStore.value = { theme: 'light', language: 'en' }
+// Change theme to dark:
+userStore.value = { theme: 'dark', language: 'en' }
+// or
+userStore.set((v) => (v.theme = 'dark'))
 
-console.log(userStore.value) // { theme: 'light' }
-console.log(userStore.value.theme) // 'light'
+console.log(userStore.value) // { theme: 'dark', language: 'en' }
+console.log(userStore.value.theme) // 'dark'
 
 // Present in localStorage:
-console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"light"}', length: 1}
+console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"dark","language":"en"}', length: 1}
 ```
 
 ### Different Ways to Assign a New Value
 
 ```js
-// Overwrite all
-userStore.value = { theme: 'light', language: 'en' }
-
-// Overwrite specific
-userStore.value = { ...userStore.value, theme: 'light' }
+// Using setter
+userStore.value = { theme: 'dark', language: 'en' }
 
-// Overwrite all using callback
-userStore.set((v) => (v = { theme: 'light', language: 'en' }))
+// Change single property using the setter
+userStore.value = { ...userStore.value, theme: 'dark' }
 
-// Overwrite specific using callback
-userStore.set((v) => (v.theme = 'light'))
+// Change single property using a callback
+userStore.set((v) => (v.theme = 'dark'))
 
-// Overwrite and store result
-const result = userStore.set((v) => (v.theme = 'light'))
+// Change single property using a property setter
+userStore.set('theme', 'dark')
 ```
 
 ### Using Another Storage API
@@ -152,15 +152,15 @@ console.log(sessionStore.storage) // Storage {length: 0}
 
 ```ts
 interface Settings {
-  theme: 'dark' | 'light'
+  theme: 'system' | 'light' | 'dark'
   language: string
 }
 
-const defaultValue: Settings = { theme: 'dark', language: 'en' }
+const defaultValue: Settings = { theme: 'system', language: 'en' }
 const userStore = new HyperStorage<Settings>('userSettings', defaultValue)
 
-// Property 'language' is missing in type '{ theme: "light"; }' but required in type 'Settings'. ts(2741)
-userStore.value = { theme: 'light' }
+// Property 'language' is missing in type '{ theme: "dark"; }' but required in type 'Settings'. ts(2741)
+userStore.value = { theme: 'dark' }
 ```
 
 ### Using `sync()`
@@ -171,7 +171,7 @@ Safe usage of `sync()` requires explicit runtime validation before accessing any
 const current = userStore.sync() // (method): unknown
 
 // 'current' is of type 'unknown'. ts(18046)
-console.log(current.theme) // { theme: 'light' }
+console.log(current.theme) // { theme: 'dark' }
 
 // Must narrow down
 if (current && typeof current === 'object' && 'theme' in current) {
@@ -245,13 +245,13 @@ If the underlying `Storage` is not modified through the value setter, the intern
 
 ```js
 // External change to storage (to be avoided)
-localStorage.setItem('userSettings', '{"theme":"blue"}')
+localStorage.setItem('userSettings', '{"theme":"dark"}')
 
 // Resynchronize the cache, optionally with a custom decoder
 userStore.sync((value) => JSON.parse(value))
 
-console.log(userStore.value) // { theme: 'blue' }
-console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"blue"}', length: 1}
+console.log(userStore.value) // { theme: 'dark' }
+console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"dark"}', length: 1}
 ```
 
 <br>

package/dist/index.cjs

@@ -9,7 +9,7 @@
  */
 class HyperStorage {
     /** Version of the library, injected via Rollup replace plugin. */
-    static version = "5.0.6";
+    static version = "5.0.7";
     /** Key name under which the data is stored. */
     itemName;
     /** Default value used when the key does not exist in storage. */
@@ -26,7 +26,7 @@ class HyperStorage {
      * Creates a new HyperStorage instance.
      *
      * @param {string} itemName - The key name under which the data will be stored.
-     * @param {T} [defaultValue] - Default value if the key does not exist.
+     * @param {T} [defaultValue] - Default value assigned to the key if it does not exist yet.
      * @param {Object} [options={}] - Optional configuration parameters.
      * @param {(value: string) => string} [options.encodeFn] - Optional function to encode stored values.
      * @param {(value: string) => string} [options.decodeFn] - Optional function to decode stored values.
@@ -69,11 +69,14 @@ class HyperStorage {
                 stringValue = value;
         }
         else if (value === undefined ||
-            (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity)))
+            (typeof value === 'number' &&
+                (isNaN(value) || value === Infinity || value === -Infinity))) {
             // Manually stringify non-JSON values
             stringValue = String(value);
-        else
+        }
+        else {
             stringValue = '\0' + JSON.stringify(value);
+        }
         this.storage.setItem(this.itemName, this.encodeFn(stringValue));
     }
     /**

package/dist/index.d.ts

@@ -23,7 +23,7 @@ declare class HyperStorage<T> {
      * Creates a new HyperStorage instance.
      *
      * @param {string} itemName - The key name under which the data will be stored.
-     * @param {T} [defaultValue] - Default value if the key does not exist.
+     * @param {T} [defaultValue] - Default value assigned to the key if it does not exist yet.
      * @param {Object} [options={}] - Optional configuration parameters.
      * @param {(value: string) => string} [options.encodeFn] - Optional function to encode stored values.
      * @param {(value: string) => string} [options.decodeFn] - Optional function to decode stored values.

package/dist/index.mjs

@@ -7,7 +7,7 @@
  */
 class HyperStorage {
     /** Version of the library, injected via Rollup replace plugin. */
-    static version = "5.0.6";
+    static version = "5.0.7";
     /** Key name under which the data is stored. */
     itemName;
     /** Default value used when the key does not exist in storage. */
@@ -24,7 +24,7 @@ class HyperStorage {
      * Creates a new HyperStorage instance.
      *
      * @param {string} itemName - The key name under which the data will be stored.
-     * @param {T} [defaultValue] - Default value if the key does not exist.
+     * @param {T} [defaultValue] - Default value assigned to the key if it does not exist yet.
      * @param {Object} [options={}] - Optional configuration parameters.
      * @param {(value: string) => string} [options.encodeFn] - Optional function to encode stored values.
      * @param {(value: string) => string} [options.decodeFn] - Optional function to decode stored values.
@@ -67,11 +67,14 @@ class HyperStorage {
                 stringValue = value;
         }
         else if (value === undefined ||
-            (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity)))
+            (typeof value === 'number' &&
+                (isNaN(value) || value === Infinity || value === -Infinity))) {
             // Manually stringify non-JSON values
             stringValue = String(value);
-        else
+        }
+        else {
             stringValue = '\0' + JSON.stringify(value);
+        }
         this.storage.setItem(this.itemName, this.encodeFn(stringValue));
     }
     /**

package/dist/index.umd.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).StorageManager=t()}(this,function(){"use strict";return class{static version="5.0.6";itemName;defaultValue;encodeFn;decodeFn;storage;#e;constructor(e,t,i={}){const{encodeFn:n,decodeFn:s,storage:o=window.localStorage}=i;if("string"!=typeof e)throw new TypeError("itemName is not a string");if(this.itemName=e,this.defaultValue=t,n&&"function"!=typeof n)throw new TypeError("encodeFn is defined but is not a function");if(this.encodeFn=n||(e=>e),s&&"function"!=typeof s)throw new TypeError("decodeFn is defined but is not a function");if(this.decodeFn=s||(e=>e),!(o instanceof Storage))throw new TypeError("storage must be an instance of Storage");this.storage=o,this.sync()}set value(e){let t;this.#e=e,t="string"==typeof e?"\0"===e[0]?"\0"+e:e:void 0===e||"number"==typeof e&&(isNaN(e)||e===1/0||e===-1/0)?String(e):"\0"+JSON.stringify(e),this.storage.setItem(this.itemName,this.encodeFn(t))}get value(){return this.#e??this.defaultValue}set(e){return this.value=e(this.value)}sync(e=this.decodeFn){let t=this.storage.getItem(this.itemName);if("string"!=typeof t)return this.reset();try{t=e(t)}catch(e){return console.error(e),this.reset()}return"\0"!==t[0]?this.value=t:(t=t.slice(1),"\0"===t[0]?this.value=t:this.value="undefined"===t?void 0:"NaN"===t?NaN:"Infinity"===t?1/0:"-Infinity"===t?-1/0:JSON.parse(t))}reset(){return this.value=this.defaultValue}remove(){this.#e=void 0,this.storage.removeItem(this.itemName)}clear(){this.#e=void 0,this.storage.clear()}isDefault(){return this.#e===this.defaultValue}}});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).StorageManager=t()}(this,function(){"use strict";return class{static version="5.0.7";itemName;defaultValue;encodeFn;decodeFn;storage;#e;constructor(e,t,i={}){const{encodeFn:n,decodeFn:s,storage:o=window.localStorage}=i;if("string"!=typeof e)throw new TypeError("itemName is not a string");if(this.itemName=e,this.defaultValue=t,n&&"function"!=typeof n)throw new TypeError("encodeFn is defined but is not a function");if(this.encodeFn=n||(e=>e),s&&"function"!=typeof s)throw new TypeError("decodeFn is defined but is not a function");if(this.decodeFn=s||(e=>e),!(o instanceof Storage))throw new TypeError("storage must be an instance of Storage");this.storage=o,this.sync()}set value(e){let t;this.#e=e,t="string"==typeof e?"\0"===e[0]?"\0"+e:e:void 0===e||"number"==typeof e&&(isNaN(e)||e===1/0||e===-1/0)?String(e):"\0"+JSON.stringify(e),this.storage.setItem(this.itemName,this.encodeFn(t))}get value(){return this.#e??this.defaultValue}set(e){return this.value=e(this.value)}sync(e=this.decodeFn){let t=this.storage.getItem(this.itemName);if("string"!=typeof t)return this.reset();try{t=e(t)}catch(e){return console.error(e),this.reset()}return"\0"!==t[0]?this.value=t:(t=t.slice(1),"\0"===t[0]?this.value=t:this.value="undefined"===t?void 0:"NaN"===t?NaN:"Infinity"===t?1/0:"-Infinity"===t?-1/0:JSON.parse(t))}reset(){return this.value=this.defaultValue}remove(){this.#e=void 0,this.storage.removeItem(this.itemName)}clear(){this.#e=void 0,this.storage.clear()}isDefault(){return this.#e===this.defaultValue}}});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperstorage-js",
-  "version": "5.0.6",
+  "version": "5.0.7",
   "description": "A lightweight wrapper for localStorage/sessionStorage with efficient caching and type-preserving serialization.",
   "license": "MIT",
   "author": "Khoeckman",
@@ -34,7 +34,7 @@
     "prettier": "^3.7.4",
     "rollup": "^4.55.1",
     "rollup-plugin-delete": "^3.0.2",
-    "rollup-plugin-prettier": "^4.1.2",
+    "rollup-plugin-prettier": "^4.1.1",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3"
   },

package/src/index.ts

@@ -34,7 +34,7 @@ class HyperStorage<T> {
    * Creates a new HyperStorage instance.
    *
    * @param {string} itemName - The key name under which the data will be stored.
-   * @param {T} [defaultValue] - Default value if the key does not exist.
+   * @param {T} [defaultValue] - Default value assigned to the key if it does not exist yet.
    * @param {Object} [options={}] - Optional configuration parameters.
    * @param {(value: string) => string} [options.encodeFn] - Optional function to encode stored values.
    * @param {(value: string) => string} [options.decodeFn] - Optional function to decode stored values.
@@ -55,17 +55,21 @@ class HyperStorage<T> {
   ) {
     const { encodeFn, decodeFn, storage = window.localStorage } = options
 
-    if (typeof itemName !== 'string') throw new TypeError('itemName is not a string')
+    if (typeof itemName !== 'string')
+      throw new TypeError('itemName is not a string')
     this.itemName = itemName
     this.defaultValue = defaultValue
 
-    if (encodeFn && typeof encodeFn !== 'function') throw new TypeError('encodeFn is defined but is not a function')
+    if (encodeFn && typeof encodeFn !== 'function')
+      throw new TypeError('encodeFn is defined but is not a function')
     this.encodeFn = encodeFn || ((v) => v)
 
-    if (decodeFn && typeof decodeFn !== 'function') throw new TypeError('decodeFn is defined but is not a function')
+    if (decodeFn && typeof decodeFn !== 'function')
+      throw new TypeError('decodeFn is defined but is not a function')
     this.decodeFn = decodeFn || ((v) => v)
 
-    if (!(storage instanceof Storage)) throw new TypeError('storage must be an instance of Storage')
+    if (!(storage instanceof Storage))
+      throw new TypeError('storage must be an instance of Storage')
     this.storage = storage
 
     this.sync()
@@ -87,11 +91,15 @@ class HyperStorage<T> {
       else stringValue = value
     } else if (
       value === undefined ||
-      (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity))
-    )
+      (typeof value === 'number' &&
+        (isNaN(value) || value === Infinity || value === -Infinity))
+    ) {
       // Manually stringify non-JSON values
       stringValue = String(value)
-    else stringValue = '\0' + JSON.stringify(value)
+    } else {
+      stringValue = '\0' + JSON.stringify(value)
+    }
+
     this.storage.setItem(this.itemName, this.encodeFn(stringValue))
   }