hyperstorage-js 5.0.5 → 5.0.7

package/README.md

@@ -1,255 +1,267 @@
-# HyperStorage: Storage Manager for JavaScript/TypeScript
-
-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.
-
-[![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)
-[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/hyperstorage-js/badge)](https://www.jsdelivr.com/package/npm/hyperstorage-js)
-
-<br>
-
-## 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.
-- ⚡ **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`, ...)
-
-<br>
-
-## Installation
-
-```bash
-# npm
-npm install hyperstorage-js
-
-# pnpm
-pnpm add hyperstorage-js
-
-# yarn
-yarn add hyperstorage-js
-```
-
-<br>
-
-## Constructor Syntax
-
-```ts
-class StorageManager<T> {
-  constructor(
-    itemName: string,
-    defaultValue: T,
-    options: {
-      encodeFn?: (value: string) => string
-      decodeFn?: (value: string) => string
-      storage?: Storage
-    } = {}
-  )
-}
-```
-
-<br>
-
-## Usage
-
-```js
-import HyperStorage from 'hyperstorage-js'
-```
-
-```js
-const defaultValue = { theme: 'dark', 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' }
-
-// Change theme to light:
-userStore.value = { theme: 'light', language: 'en' }
-
-console.log(userStore.value) // { theme: 'light' }
-console.log(userStore.value.theme) // 'light'
-
-// Present in localStorage:
-console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"light"}', 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' }
-
-// Overwrite all using callback
-userStore.set((v) => (v = { theme: 'light', language: 'en' }))
-
-// Overwrite specific using callback
-userStore.set((v) => (v.theme = 'light'))
-
-// Overwrite and store result
-const result = userStore.set((v) => (v.theme = 'light'))
-```
-
-### Using Another Storage API
-
-Use `sessionStorage` to only remember data for the duration of a session.
-
-```js
-const sessionStore = new HyperStorage('sessionData', 'none', {
-  storage: window.sessionStorage,
-})
-
-sessionStore.value = 'temporary'
-console.log(sessionStore.value) // 'temporary'
-console.log(sessionStore.storage) // Storage {sessionData: 'temporary', length: 1}
-```
-
-### Using Encoding and Decoding Functions
-
-If you want to make stored data significantly harder to reverse-engineer, you should use the `encodeFn` and `decodeFn` options.
-
-Apply Base64 encoding using JavaScript's `btoa` (String to Base64) and `atob` (Base64 to String).
-
-```js
-const sessionStore = new HyperStorage('sessionData', 'none', {
-  encodeFn: (value) => btoa(value),
-  decodeFn: (value) => atob(value),
-})
-
-sessionStore.value = 'temporary'
-console.log(sessionStore.value) // 'temporary'
-console.log(sessionStore.storage) // Storage {sessionData: 'hN0IEUdoqmJ/', length: 1}
-```
-
-### Resetting Values
-
-```js
-sessionStore.reset()
-console.log(sessionStore.defaultValue) // 'none'
-console.log(sessionStore.value) // 'none'
-```
-
-### Removing Values
-
-Internally uses `Storage.removeItem()` to remove the item from storage and sets the cached value to `undefined`.
-
-```js
-sessionStore.remove()
-console.log(sessionStore.value) // undefined
-console.log(sessionStore.storage) // Storage {length: 0}
-```
-
-<br>
-
-## TypeScript Usage
-
-### Using Type Parameter `T`
-
-```ts
-interface Settings {
-  theme: 'dark' | 'light'
-  language: string
-}
-
-const defaultValue: Settings = { theme: 'dark', 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' }
-
-const current = userStore.sync() // (method): Settings | undefined
-// 'current' is possibly 'undefined'. ts(18048)
-console.log(current.theme) // { theme: 'light' }
-```
-
-<br>
-
-## API
-
-### `constructor<T>(itemName: string, defaultValue: T, options = {})`
-
-- **itemName**: `string` — key under which the data is stored.
-- **defaultValue**: default value to be stored if none exists.
-- **options** _(optional)_:
-  - `encodeFn` — function to encode values before writing to the `Storage`.
-  - `decodeFn` — function to decode values when reading from the `Storage`.
-  - `storage` — a `Storage` instance (e.g., `localStorage` or `sessionStorage`).
-
-### `value`
-
-- **Getter** — returns the cached value (very fast, does not use `JSON.parse`).
-- **Setter** — sets and caches the value, serializing and encoding it into `Storage`.
-
-### `set(callback: (value: T) => T): T`
-
-- Updates the stored value using a callback function.
-- The callback receives the current value and must return the new value.
-- Returns the newly stored value.
-
-### `reset(): T`
-
-- Resets the stored value to `defaultValue`.
-- Updates both `Storage` and internal cache.
-- Returns the restored default value.
-
-### `remove(): void`
-
-- Removes the key and its value from `Storage`.
-- Sets the internal cache to `undefined`.
-- Returns nothing.
-
-### `clear(): void`
-
-- Clears **all keys** in `Storage`.
-- Affects all stored data, not just this key.
-- Returns nothing.
-
-### `isDefault(): boolean`
-
-- Checks whether the cached value equals the configured default.
-- Uses reference comparison for objects and strict equality for primitives.
-- Returns `true` if the current value matches the default, otherwise `false`.
-
-```js
-if (userStore.isDefault()) {
-  console.log('value equals the default value.')
-}
-```
-
-### `sync(decodeFn = this.decodeFn): unknown`
-
-If the underlying `Storage` is not modified through the value setter, the internal cache will **not automatically update**. Use `sync()` to synchronize the internal cache with the actual value stored in `Storage`.
-
-- **decodeFn** _(optional)_ — a function to decode values when reading (defaults to `this.decodeFn`).
-- Reads the value from storage.
-- Decodes it using `decodeFn`.
-- Updates the internal cache.
-- Returns the synchronized value. The return type is `unknown` because data read from `Storage` cannot be type-checked or trusted at compile time, especially when it may have been modified externally.
-
-```js
-// External change to storage (to be avoided)
-localStorage.setItem('userSettings', '{"theme":"blue"}')
-
-// 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}
-```
-
-<br>
-
-## Source
-
-[GitHub Repository](https://github.com/Khoeckman/HyperStorage)
-
-<br>
-
-## License
-
-MIT
+# HyperStorage: Storage Manager for JavaScript/TypeScript
+
+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 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)
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/hyperstorage-js/badge)](https://www.jsdelivr.com/package/npm/hyperstorage-js)
+
+<br>
+
+## Features
+
+- 📝 **Default values**: are automatically set when the key is not in Storage.
+- 🧩 **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`, ...)
+
+<br>
+
+## Installation
+
+```bash
+# npm
+npm install hyperstorage-js
+
+# pnpm
+pnpm add hyperstorage-js
+
+# yarn
+yarn add hyperstorage-js
+```
+
+<br>
+
+## Constructor Syntax
+
+```ts
+class StorageManager<T> {
+  constructor(
+    itemName: string,
+    defaultValue: T,
+    options: {
+      encodeFn?: (value: string) => string
+      decodeFn?: (value: string) => string
+      storage?: Storage
+    } = {}
+  )
+}
+```
+
+<br>
+
+## Usage
+
+```js
+import HyperStorage from 'hyperstorage-js'
+```
+
+```js
+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: '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: 'dark', language: 'en' }
+console.log(userStore.value.theme) // 'dark'
+
+// Present in localStorage:
+console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"dark","language":"en"}', length: 1}
+```
+
+### Different Ways to Assign a New Value
+
+```js
+// Using setter
+userStore.value = { theme: 'dark', language: 'en' }
+
+// Change single property using the setter
+userStore.value = { ...userStore.value, theme: 'dark' }
+
+// Change single property using a callback
+userStore.set((v) => (v.theme = 'dark'))
+
+// Change single property using a property setter
+userStore.set('theme', 'dark')
+```
+
+### Using Another Storage API
+
+Use `sessionStorage` to only remember data for the duration of a session.
+
+```js
+const sessionStore = new HyperStorage('sessionData', 'none', {
+  storage: window.sessionStorage,
+})
+
+sessionStore.value = 'temporary'
+console.log(sessionStore.value) // 'temporary'
+console.log(sessionStore.storage) // Storage {sessionData: 'temporary', length: 1}
+```
+
+### Using Encoding and Decoding Functions
+
+If you want to make stored data significantly harder to reverse-engineer, you should use the `encodeFn` and `decodeFn` options.
+
+Apply Base64 encoding using JavaScript's `btoa` (String to Base64) and `atob` (Base64 to String).
+
+```js
+const sessionStore = new HyperStorage('sessionData', 'none', {
+  encodeFn: (value) => btoa(value),
+  decodeFn: (value) => atob(value),
+})
+
+sessionStore.value = 'temporary'
+console.log(sessionStore.value) // 'temporary'
+console.log(sessionStore.storage) // Storage {sessionData: 'hN0IEUdoqmJ/', length: 1}
+```
+
+### Resetting Values
+
+```js
+sessionStore.reset()
+console.log(sessionStore.defaultValue) // 'none'
+console.log(sessionStore.value) // 'none'
+```
+
+### Removing Values
+
+Internally uses `Storage.removeItem()` to remove the item from storage and sets the cached value to `undefined`.
+
+```js
+sessionStore.remove()
+console.log(sessionStore.value) // undefined
+console.log(sessionStore.storage) // Storage {length: 0}
+```
+
+<br>
+
+## TypeScript Usage
+
+### Using Type Parameter `T`
+
+```ts
+interface Settings {
+  theme: 'system' | 'light' | 'dark'
+  language: string
+}
+
+const defaultValue: Settings = { theme: 'system', language: 'en' }
+const userStore = new HyperStorage<Settings>('userSettings', defaultValue)
+
+// Property 'language' is missing in type '{ theme: "dark"; }' but required in type 'Settings'. ts(2741)
+userStore.value = { theme: 'dark' }
+```
+
+### Using `sync()`
+
+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
+
+// 'current' is of type 'unknown'. ts(18046)
+console.log(current.theme) // { theme: 'dark' }
+
+// Must narrow down
+if (current && typeof current === 'object' && 'theme' in current) {
+  console.log(current.theme)
+}
+```
+
+<br>
+
+## API
+
+### `constructor<T>(itemName: string, defaultValue: T, options = {})`
+
+- **itemName**: `string` — key under which the data is stored.
+- **defaultValue**: default value to be stored if none exists.
+- **options** _(optional)_:
+  - `encodeFn` — function to encode values before writing to the `Storage`.
+  - `decodeFn` — function to decode values when reading from the `Storage`.
+  - `storage` — a `Storage` instance (e.g., `localStorage` or `sessionStorage`).
+
+### `value`
+
+- **Getter** — returns the cached value (very fast, does not use `JSON.parse`).
+- **Setter** — sets and caches the value, serializing and encoding it into `Storage`.
+
+### `set(callback: (value: T) => T): T`
+
+- Updates the stored value using a callback function.
+- The callback receives the current value and must return the new value.
+- Returns the newly stored value.
+
+### `reset(): T`
+
+- Resets the stored value to `defaultValue`.
+- Updates both `Storage` and internal cache.
+- Returns the restored default value.
+
+### `remove(): void`
+
+- Removes the key and its value from `Storage`.
+- Sets the internal cache to `undefined`.
+- Returns nothing.
+
+### `clear(): void`
+
+- Clears **all keys** in `Storage`.
+- Affects all stored data, not just this key.
+- Returns nothing.
+
+### `isDefault(): boolean`
+
+- Checks whether the cached value equals the configured default.
+- Uses reference comparison for objects and strict equality for primitives.
+- Returns `true` if the current value matches the default, otherwise `false`.
+
+```js
+if (userStore.isDefault()) {
+  console.log('value equals the default value.')
+}
+```
+
+### `sync(decodeFn = this.decodeFn): unknown`
+
+If the underlying `Storage` is not modified through the value setter, the internal cache will **not automatically update**. Use `sync()` to synchronize the internal cache with the actual value stored in `Storage`.
+
+- **decodeFn** _(optional)_ — a function to decode values when reading (defaults to `this.decodeFn`).
+- Reads the value from storage.
+- Decodes it using `decodeFn`.
+- Updates the internal cache.
+- Returns the synchronized value. The return type is `unknown` because data read from `Storage` cannot be type-checked or trusted at compile time, especially when it may have been modified externally.
+
+```js
+// External change to storage (to be avoided)
+localStorage.setItem('userSettings', '{"theme":"dark"}')
+
+// Resynchronize the cache, optionally with a custom decoder
+userStore.sync((value) => JSON.parse(value))
+
+console.log(userStore.value) // { theme: 'dark' }
+console.log(userStore.storage) // Storage {userSettings: '\x00{"theme":"dark"}', length: 1}
+```
+
+<br>
+
+## Source
+
+[GitHub Repository](https://github.com/Khoeckman/HyperStorage)
+
+<br>
+
+## License
+
+MIT

package/dist/index.cjs

@@ -9,7 +9,7 @@
  */
 class HyperStorage {
     /** Version of the library, injected via Rollup replace plugin. */
-    static version = "5.0.5";
+    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.5";
+    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.5";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,69 +1,69 @@
-{
-  "name": "hyperstorage-js",
-  "version": "5.0.5",
-  "description": "A lightweight wrapper for localStorage/sessionStorage with efficient caching and type-preserving serialization.",
-  "license": "MIT",
-  "author": "Khoeckman",
-  "type": "module",
-  "main": "dist/index.umd.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "default": "./dist/index.umd.js"
-    }
-  },
-  "files": [
-    "src/",
-    "dist/"
-  ],
-  "scripts": {
-    "test": "exit 0",
-    "build": "rollup -c rollup.config.js",
-    "prepack": "npm run build"
-  },
-  "devDependencies": {
-    "@rollup/plugin-replace": "^6.0.3",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^24.10.7",
-    "pnpm": "^10.28.0",
-    "prettier": "^3.7.4",
-    "rollup": "^4.55.1",
-    "rollup-plugin-delete": "^3.0.2",
-    "rollup-plugin-prettier": "^4.1.2",
-    "tslib": "^2.8.1",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://github.com/Khoeckman/HyperStorage#readme",
-  "bugs": {
-    "url": "https://github.com/Khoeckman/HyperStorage/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Khoeckman/HyperStorage.git"
-  },
-  "keywords": [
-    "localStorage",
-    "sessionStorage",
-    "storage",
-    "utility",
-    "javascript",
-    "js",
-    "typescript",
-    "ts",
-    "ecmascript",
-    "es",
-    "umd",
-    "browser",
-    "client",
-    "module",
-    "commonjs"
-  ]
-}
+{
+  "name": "hyperstorage-js",
+  "version": "5.0.7",
+  "description": "A lightweight wrapper for localStorage/sessionStorage with efficient caching and type-preserving serialization.",
+  "license": "MIT",
+  "author": "Khoeckman",
+  "type": "module",
+  "main": "dist/index.umd.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.umd.js"
+    }
+  },
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "scripts": {
+    "test": "exit 0",
+    "build": "rollup -c rollup.config.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^24.10.7",
+    "pnpm": "^10.28.0",
+    "prettier": "^3.7.4",
+    "rollup": "^4.55.1",
+    "rollup-plugin-delete": "^3.0.2",
+    "rollup-plugin-prettier": "^4.1.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/Khoeckman/HyperStorage#readme",
+  "bugs": {
+    "url": "https://github.com/Khoeckman/HyperStorage/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Khoeckman/HyperStorage.git"
+  },
+  "keywords": [
+    "localStorage",
+    "sessionStorage",
+    "storage",
+    "utility",
+    "javascript",
+    "js",
+    "typescript",
+    "ts",
+    "ecmascript",
+    "es",
+    "umd",
+    "browser",
+    "client",
+    "module",
+    "commonjs"
+  ]
+}

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))
   }