hyperstorage-js 5.0.6 → 5.1.0

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`, ...)
@@ -38,7 +39,7 @@ yarn add hyperstorage-js
 ## Constructor Syntax
 
 ```ts
-class StorageManager<T> {
+class HyperStorage<T> {
   constructor(
     itemName: string,
     defaultValue: T,
@@ -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}
+// Present in localStorage
+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()`
@@ -168,14 +168,19 @@ userStore.value = { theme: 'light' }
 Safe usage of `sync()` requires explicit runtime validation before accessing any properties. It quickly becomes clear how type-unsafe `sync()` is and why it should be avoided.
 
 ```ts
-const current = userStore.sync() // (method): unknown
+const result = userStore.sync() // (method): unknown
+// Right now, 'result' equals 'userStore.value' exactly
 
-// 'current' is of type 'unknown'. ts(18046)
-console.log(current.theme) // { theme: 'light' }
+// 'result' is of type 'unknown'. ts(18046)
+console.log(result.theme) // 'dark'
 
-// Must narrow down
-if (current && typeof current === 'object' && 'theme' in current) {
-  console.log(current.theme)
+// No error, but unsafe
+console.log(userStore.value.theme) // 'dark'
+
+// Must narrow down to be safe
+if (result && typeof result === 'object' && 'theme' in result) {
+  // No error, safe
+  console.log(result.theme) // 'dark'
 }
 ```
 
@@ -245,13 +250,66 @@ 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}
+```
+
+#### Why `sync()` is unsafe
+
+1. The item in `Storage` is undecodable by the `decodeFn` passed to `sync()`.
+
+```js
+localStorage.setItem('userSettings', 'not an object')
+
+// SyntaxError: Unexpected token 'o', "not an object" is not valid JSON
+const result = userStore.sync((value) => JSON.parse(value))
+// Execution continues because sync() uses a try-catch
+
+console.log(result) // instance of SyntaxError
+
+// Reset to default value
+console.log(userStore.value) // {theme: 'system', language: 'en'}
+```
+
+2. The item in `Storage`, after being decoded, is not of type `T`.
+
+```js
+localStorage.setItem('userSettings', '{"not":"valid"}')
+
+const result = userStore.sync((value) => JSON.parse(value))
+console.log(result) // {not: 'valid'}
+console.log(userStore.value) // {not: 'valid'}
+```
+
+No errors, but `result` and `userStore.value` are both not of type `T`.
+
+This **must** be manually checked and `userStore.reset()` should be called if the check fails.
+
+```js
+// This example is specifically for type 'Settings'
+if (
+  result &&
+  typeof result === 'object' &&
+  'theme' in result &&
+  'language' in result &&
+  (result.theme === 'system' ||
+    result.theme === 'light' ||
+    result.theme === 'dark') &&
+  typeof result.language === 'string'
+) {
+  // 'result' is of type 'T'
+} else {
+  // 'result' is not of type 'T'
+  userStore.reset()
+  console.log(userStore.value) // {theme: 'system', language: 'en'}
+}
+
+// 'userStore.value' is of type 'T'
 ```
 
 <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.1.0";
     /** 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
+            stringValue = '\0' + String(value);
+        }
+        else {
             stringValue = '\0' + JSON.stringify(value);
+        }
         this.storage.setItem(this.itemName, this.encodeFn(stringValue));
     }
     /**
@@ -104,8 +107,9 @@ class HyperStorage {
             value = decodeFn(value);
         }
         catch (err) {
+            this.reset();
             console.error(err);
-            return this.reset();
+            return err;
         }
         if (value[0] !== '\0')
             return (this.value = value); // Raw string value

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.1.0";
     /** 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
+            stringValue = '\0' + String(value);
+        }
+        else {
             stringValue = '\0' + JSON.stringify(value);
+        }
         this.storage.setItem(this.itemName, this.encodeFn(stringValue));
     }
     /**
@@ -102,8 +105,9 @@ class HyperStorage {
             value = decodeFn(value);
         }
         catch (err) {
+            this.reset();
             console.error(err);
-            return this.reset();
+            return err;
         }
         if (value[0] !== '\0')
             return (this.value = value); // Raw string value

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).HyperStorage=t()}(this,function(){"use strict";return class{static version="5.1.0";itemName;defaultValue;encodeFn;decodeFn;storage;#e;constructor(e,t,i={}){const{encodeFn:s,decodeFn:n,storage:o=window.localStorage}=i;if("string"!=typeof e)throw new TypeError("itemName is not a string");if(this.itemName=e,this.defaultValue=t,s&&"function"!=typeof s)throw new TypeError("encodeFn is defined but is not a function");if(this.encodeFn=s||(e=>e),n&&"function"!=typeof n)throw new TypeError("decodeFn is defined but is not a function");if(this.decodeFn=n||(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)?"\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 this.reset(),console.error(e),e}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.1.0",
   "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)
+      stringValue = '\0' + String(value)
+    } else {
+      stringValue = '\0' + JSON.stringify(value)
+    }
+
     this.storage.setItem(this.itemName, this.encodeFn(stringValue))
   }
 
@@ -125,8 +133,9 @@ class HyperStorage<T> {
     try {
       value = decodeFn(value)
     } catch (err) {
+      this.reset()
       console.error(err)
-      return this.reset()
+      return err
     }
 
     if (value[0] !== '\0') return (this.value = value as T) // Raw string value