hyperstorage-js 5.0.7 → 5.1.0

package/README.md

@@ -39,7 +39,7 @@ yarn add hyperstorage-js
 ## Constructor Syntax
 
 ```ts
-class StorageManager<T> {
+class HyperStorage<T> {
   constructor(
     itemName: string,
     defaultValue: T,
@@ -67,7 +67,7 @@ const userStore = new HyperStorage('userSettings', defaultValue)
 // If 'userSettings' is not present in the Storage, the defaultValue is set:
 console.log(userStore.value) // { theme: 'light', language: 'en' }
 
-// Change theme to dark:
+// Change theme to dark
 userStore.value = { theme: 'dark', language: 'en' }
 // or
 userStore.set((v) => (v.theme = 'dark'))
@@ -75,7 +75,7 @@ userStore.set((v) => (v.theme = 'dark'))
 console.log(userStore.value) // { theme: 'dark', language: 'en' }
 console.log(userStore.value.theme) // 'dark'
 
-// Present in localStorage:
+// Present in localStorage
 console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"dark","language":"en"}', length: 1}
 ```
 
@@ -168,14 +168,19 @@ userStore.value = { theme: 'dark' }
 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: 'dark' }
+// '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'
 }
 ```
 
@@ -254,6 +259,59 @@ 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>
 
 ## Source

package/dist/index.cjs

@@ -9,7 +9,7 @@
  */
 class HyperStorage {
     /** Version of the library, injected via Rollup replace plugin. */
-    static version = "5.0.7";
+    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. */
@@ -72,7 +72,7 @@ class HyperStorage {
             (typeof value === 'number' &&
                 (isNaN(value) || value === Infinity || value === -Infinity))) {
             // Manually stringify non-JSON values
-            stringValue = String(value);
+            stringValue = '\0' + String(value);
         }
         else {
             stringValue = '\0' + JSON.stringify(value);
@@ -107,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.mjs

@@ -7,7 +7,7 @@
  */
 class HyperStorage {
     /** Version of the library, injected via Rollup replace plugin. */
-    static version = "5.0.7";
+    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. */
@@ -70,7 +70,7 @@ class HyperStorage {
             (typeof value === 'number' &&
                 (isNaN(value) || value === Infinity || value === -Infinity))) {
             // Manually stringify non-JSON values
-            stringValue = String(value);
+            stringValue = '\0' + String(value);
         }
         else {
             stringValue = '\0' + JSON.stringify(value);
@@ -105,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.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}}});
+!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.7",
+  "version": "5.1.0",
   "description": "A lightweight wrapper for localStorage/sessionStorage with efficient caching and type-preserving serialization.",
   "license": "MIT",
   "author": "Khoeckman",

package/src/index.ts

@@ -95,7 +95,7 @@ class HyperStorage<T> {
         (isNaN(value) || value === Infinity || value === -Infinity))
     ) {
       // Manually stringify non-JSON values
-      stringValue = String(value)
+      stringValue = '\0' + String(value)
     } else {
       stringValue = '\0' + JSON.stringify(value)
     }
@@ -133,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