hyperstorage-js 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kyle Hoeckman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# HyperStorage: Storage Manager for JavaScript/TypeScript
+
+A lightweight wrapper for Storage interfaces (e.g., `localStorage` or `sessionStorage`) with **efficient caching** and **type-preserving serialization**. Perfect for easy, fast and type-safe client-side data management.
+
+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/@khoeckman/hyperstorage.svg)](https://www.npmjs.com/package/@khoeckman/hyperstorage)
+[![npm downloads](https://img.shields.io/npm/dt/@khoeckman/hyperstorage.svg)](https://www.npmjs.com/package/@khoeckman/hyperstorage)
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@khoeckman/hyperstorage/badge)](https://www.jsdelivr.com/package/npm/@khoeckman/hyperstorage)
+[![License](https://img.shields.io/npm/l/@khoeckman/hyperstorage.svg)](LICENSE)
+
+---
+
+## 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`, ...)
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install hyperstorage-js
+
+# pnpm
+pnpm add hyperstorage-js
+
+# yarn
+yarn add hyperstorage-js
+```
+
+---
+
+## Constructor Syntax
+
+```ts
+class StorageManager<T> {
+  constructor(
+    itemName: string,
+    defaultValue: T,
+    options: {
+      encodeFn?: (value: string) => string
+      decodeFn?: (value: string) => string
+      storage?: Storage
+    } = {}
+  )
+}
+```
+
+---
+
+## 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.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}
+```
+
+---
+
+## 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' }
+```
+
+---
+
+## 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}
+```
+
+---
+
+## Source
+
+[GitHub Repository](https://github.com/Khoeckman/HyperStorage)
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * @class HyperStorage
+ * @classdesc A lightweight wrapper for localStorage/sessionStorage
+ * with efficient caching and type-preserving serialization.
+ *
+ * @source https://github.com/Khoeckman/HyperStorage
+ */
+class HyperStorage {
+    /** Version of the library, injected via Rollup replace plugin. */
+    static version = "5.0.0";
+    /** Key name under which the data is stored. */
+    itemName;
+    /** Default value used when the key does not exist in storage. */
+    defaultValue;
+    /** Function to encode values before storing. */
+    encodeFn;
+    /** Function to decode values when reading. */
+    decodeFn;
+    /** The underlying storage backend (defaults to `window.localStorage`). */
+    storage;
+    /** Internal cached value to improve access speed. */
+    #value;
+    /**
+     * 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 {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.
+     * @param {Storage} [options.storage=window.localStorage] - Optional custom storage backend.
+     *
+     * @throws {TypeError} If `itemName` is not a string.
+     * @throws {TypeError} If `encodeFn` or `decodeFn` are defined but not functions.
+     * @throws {TypeError} If `storage` does not implement the standard Storage API.
+     */
+    constructor(itemName, defaultValue, options = {}) {
+        const { encodeFn, decodeFn, storage = window.localStorage } = options;
+        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');
+        this.encodeFn = encodeFn || ((v) => v);
+        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');
+        this.storage = storage;
+        this.sync();
+    }
+    /**
+     * Sets the current value in storage.
+     * Automatically caches, stringifies and encodes the value.
+     */
+    set value(value) {
+        // Cache real value
+        this.#value = value;
+        // Store stringified value with prefix to distinguish from raw strings
+        let stringValue;
+        if (typeof value === 'string') {
+            if (value[0] === '\0')
+                stringValue = '\0' + value;
+            else
+                stringValue = value;
+        }
+        else if (value === undefined ||
+            (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity)))
+            // Manually stringify non-JSON values
+            stringValue = String(value);
+        else
+            stringValue = '\0' + JSON.stringify(value);
+        this.storage.setItem(this.itemName, this.encodeFn(stringValue));
+    }
+    /**
+     * Gets the current cached value.
+     */
+    get value() {
+        return this.#value ?? this.defaultValue;
+    }
+    /**
+     * Allows using the setter with a callback.
+     */
+    set(callback) {
+        return (this.value = callback(this.value));
+    }
+    /**
+     * Synchronizes the internal cache (`#value`) with the actual value in storage.
+     *
+     * This is only necessary if the stored value may have been modified externally.
+     * Using this function should be avoided when possible and is not type safe.
+     */
+    sync(decodeFn = this.decodeFn) {
+        let value = this.storage.getItem(this.itemName);
+        // Reset value to defaultValue if it does not exist in storage
+        if (typeof value !== 'string')
+            return this.reset();
+        // Reset value to defaultValue if the incoming value is not properly encoded
+        try {
+            value = decodeFn(value);
+        }
+        catch (err) {
+            console.error(err);
+            return this.reset();
+        }
+        if (value[0] !== '\0')
+            return (this.value = value); // Raw string value
+        // Slice off '\0' prefix
+        value = value.slice(1);
+        if (value[0] === '\0')
+            return (this.value = value); // Raw string value that started with '\0'
+        // Parse non JSON
+        if (value === 'undefined')
+            return (this.value = undefined);
+        if (value === 'NaN')
+            return (this.value = NaN);
+        if (value === 'Infinity')
+            return (this.value = Infinity);
+        if (value === '-Infinity')
+            return (this.value = -Infinity);
+        return (this.value = JSON.parse(value));
+    }
+    /**
+     * Resets the stored value to its configured default.
+     *
+     * Updates both the underlying storage and the internal cache.
+     */
+    reset() {
+        return (this.value = this.defaultValue);
+    }
+    /**
+     * Removes this specific key and its value from storage.
+     *
+     * Also clears the internal cache to prevent stale data access.
+     */
+    remove() {
+        this.#value = undefined;
+        this.storage.removeItem(this.itemName);
+    }
+    /**
+     * Clears **all** data fromstorage.
+     *
+     * This affects every key in the storage.
+     * Also clears the internal cache to prevent stale data access.
+     */
+    clear() {
+        this.#value = undefined;
+        this.storage.clear();
+    }
+    /**
+     * Checks whether the current cached value matches the configured default value.
+     *
+     * Uses reference comparison for objects and strict equality for primitives.
+     */
+    isDefault() {
+        return this.#value === this.defaultValue;
+    }
+}
+
+module.exports = HyperStorage;

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @class HyperStorage
+ * @classdesc A lightweight wrapper for localStorage/sessionStorage
+ * with efficient caching and type-preserving serialization.
+ *
+ * @source https://github.com/Khoeckman/HyperStorage
+ */
+declare class HyperStorage<T> {
+    #private;
+    /** Version of the library, injected via Rollup replace plugin. */
+    static readonly version: string;
+    /** Key name under which the data is stored. */
+    readonly itemName: string;
+    /** Default value used when the key does not exist in storage. */
+    private readonly defaultValue;
+    /** Function to encode values before storing. */
+    private readonly encodeFn;
+    /** Function to decode values when reading. */
+    private readonly decodeFn;
+    /** The underlying storage backend (defaults to `window.localStorage`). */
+    readonly storage: Storage;
+    /**
+     * 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 {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.
+     * @param {Storage} [options.storage=window.localStorage] - Optional custom storage backend.
+     *
+     * @throws {TypeError} If `itemName` is not a string.
+     * @throws {TypeError} If `encodeFn` or `decodeFn` are defined but not functions.
+     * @throws {TypeError} If `storage` does not implement the standard Storage API.
+     */
+    constructor(itemName: string, defaultValue: T, options?: {
+        encodeFn?: (value: string) => string;
+        decodeFn?: (value: string) => string;
+        storage?: Storage;
+    });
+    /**
+     * Sets the current value in storage.
+     * Automatically caches, stringifies and encodes the value.
+     */
+    set value(value: T);
+    /**
+     * Gets the current cached value.
+     */
+    get value(): T;
+    /**
+     * Allows using the setter with a callback.
+     */
+    set(callback: (value: T) => T): T;
+    /**
+     * Synchronizes the internal cache (`#value`) with the actual value in storage.
+     *
+     * This is only necessary if the stored value may have been modified externally.
+     * Using this function should be avoided when possible and is not type safe.
+     */
+    sync(decodeFn?: (value: string) => string): unknown;
+    /**
+     * Resets the stored value to its configured default.
+     *
+     * Updates both the underlying storage and the internal cache.
+     */
+    reset(): T;
+    /**
+     * Removes this specific key and its value from storage.
+     *
+     * Also clears the internal cache to prevent stale data access.
+     */
+    remove(): void;
+    /**
+     * Clears **all** data fromstorage.
+     *
+     * This affects every key in the storage.
+     * Also clears the internal cache to prevent stale data access.
+     */
+    clear(): void;
+    /**
+     * Checks whether the current cached value matches the configured default value.
+     *
+     * Uses reference comparison for objects and strict equality for primitives.
+     */
+    isDefault(): boolean;
+}
+export default HyperStorage;

package/dist/index.mjs

@@ -0,0 +1,162 @@
+/**
+ * @class HyperStorage
+ * @classdesc A lightweight wrapper for localStorage/sessionStorage
+ * with efficient caching and type-preserving serialization.
+ *
+ * @source https://github.com/Khoeckman/HyperStorage
+ */
+class HyperStorage {
+    /** Version of the library, injected via Rollup replace plugin. */
+    static version = "5.0.0";
+    /** Key name under which the data is stored. */
+    itemName;
+    /** Default value used when the key does not exist in storage. */
+    defaultValue;
+    /** Function to encode values before storing. */
+    encodeFn;
+    /** Function to decode values when reading. */
+    decodeFn;
+    /** The underlying storage backend (defaults to `window.localStorage`). */
+    storage;
+    /** Internal cached value to improve access speed. */
+    #value;
+    /**
+     * 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 {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.
+     * @param {Storage} [options.storage=window.localStorage] - Optional custom storage backend.
+     *
+     * @throws {TypeError} If `itemName` is not a string.
+     * @throws {TypeError} If `encodeFn` or `decodeFn` are defined but not functions.
+     * @throws {TypeError} If `storage` does not implement the standard Storage API.
+     */
+    constructor(itemName, defaultValue, options = {}) {
+        const { encodeFn, decodeFn, storage = window.localStorage } = options;
+        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');
+        this.encodeFn = encodeFn || ((v) => v);
+        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');
+        this.storage = storage;
+        this.sync();
+    }
+    /**
+     * Sets the current value in storage.
+     * Automatically caches, stringifies and encodes the value.
+     */
+    set value(value) {
+        // Cache real value
+        this.#value = value;
+        // Store stringified value with prefix to distinguish from raw strings
+        let stringValue;
+        if (typeof value === 'string') {
+            if (value[0] === '\0')
+                stringValue = '\0' + value;
+            else
+                stringValue = value;
+        }
+        else if (value === undefined ||
+            (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity)))
+            // Manually stringify non-JSON values
+            stringValue = String(value);
+        else
+            stringValue = '\0' + JSON.stringify(value);
+        this.storage.setItem(this.itemName, this.encodeFn(stringValue));
+    }
+    /**
+     * Gets the current cached value.
+     */
+    get value() {
+        return this.#value ?? this.defaultValue;
+    }
+    /**
+     * Allows using the setter with a callback.
+     */
+    set(callback) {
+        return (this.value = callback(this.value));
+    }
+    /**
+     * Synchronizes the internal cache (`#value`) with the actual value in storage.
+     *
+     * This is only necessary if the stored value may have been modified externally.
+     * Using this function should be avoided when possible and is not type safe.
+     */
+    sync(decodeFn = this.decodeFn) {
+        let value = this.storage.getItem(this.itemName);
+        // Reset value to defaultValue if it does not exist in storage
+        if (typeof value !== 'string')
+            return this.reset();
+        // Reset value to defaultValue if the incoming value is not properly encoded
+        try {
+            value = decodeFn(value);
+        }
+        catch (err) {
+            console.error(err);
+            return this.reset();
+        }
+        if (value[0] !== '\0')
+            return (this.value = value); // Raw string value
+        // Slice off '\0' prefix
+        value = value.slice(1);
+        if (value[0] === '\0')
+            return (this.value = value); // Raw string value that started with '\0'
+        // Parse non JSON
+        if (value === 'undefined')
+            return (this.value = undefined);
+        if (value === 'NaN')
+            return (this.value = NaN);
+        if (value === 'Infinity')
+            return (this.value = Infinity);
+        if (value === '-Infinity')
+            return (this.value = -Infinity);
+        return (this.value = JSON.parse(value));
+    }
+    /**
+     * Resets the stored value to its configured default.
+     *
+     * Updates both the underlying storage and the internal cache.
+     */
+    reset() {
+        return (this.value = this.defaultValue);
+    }
+    /**
+     * Removes this specific key and its value from storage.
+     *
+     * Also clears the internal cache to prevent stale data access.
+     */
+    remove() {
+        this.#value = undefined;
+        this.storage.removeItem(this.itemName);
+    }
+    /**
+     * Clears **all** data fromstorage.
+     *
+     * This affects every key in the storage.
+     * Also clears the internal cache to prevent stale data access.
+     */
+    clear() {
+        this.#value = undefined;
+        this.storage.clear();
+    }
+    /**
+     * Checks whether the current cached value matches the configured default value.
+     *
+     * Uses reference comparison for objects and strict equality for primitives.
+     */
+    isDefault() {
+        return this.#value === this.defaultValue;
+    }
+}
+
+export { HyperStorage as default };

package/dist/index.umd.js

@@ -0,0 +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.0";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

@@ -0,0 +1,71 @@
+{
+  "name": "hyperstorage-js",
+  "version": "5.0.0",
+  "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.4",
+    "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"
+  ],
+  "dependencies": {
+    "pnpm": "^10.27.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,188 @@
+// Injected by Rollup
+declare const __VERSION__: string
+
+/**
+ * @class HyperStorage
+ * @classdesc A lightweight wrapper for localStorage/sessionStorage
+ * with efficient caching and type-preserving serialization.
+ *
+ * @source https://github.com/Khoeckman/HyperStorage
+ */
+class HyperStorage<T> {
+  /** Version of the library, injected via Rollup replace plugin. */
+  static readonly version: string = __VERSION__
+
+  /** Key name under which the data is stored. */
+  readonly itemName: string
+
+  /** Default value used when the key does not exist in storage. */
+  private readonly defaultValue: T
+
+  /** Function to encode values before storing. */
+  private readonly encodeFn: (value: string) => string
+
+  /** Function to decode values when reading. */
+  private readonly decodeFn: (value: string) => string
+
+  /** The underlying storage backend (defaults to `window.localStorage`). */
+  readonly storage: Storage
+
+  /** Internal cached value to improve access speed. */
+  #value?: 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 {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.
+   * @param {Storage} [options.storage=window.localStorage] - Optional custom storage backend.
+   *
+   * @throws {TypeError} If `itemName` is not a string.
+   * @throws {TypeError} If `encodeFn` or `decodeFn` are defined but not functions.
+   * @throws {TypeError} If `storage` does not implement the standard Storage API.
+   */
+  constructor(
+    itemName: string,
+    defaultValue: T,
+    options: {
+      encodeFn?: (value: string) => string
+      decodeFn?: (value: string) => string
+      storage?: Storage
+    } = {}
+  ) {
+    const { encodeFn, decodeFn, storage = window.localStorage } = options
+
+    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')
+    this.encodeFn = encodeFn || ((v) => v)
+
+    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')
+    this.storage = storage
+
+    this.sync()
+  }
+
+  /**
+   * Sets the current value in storage.
+   * Automatically caches, stringifies and encodes the value.
+   */
+  set value(value: T) {
+    // Cache real value
+    this.#value = value
+
+    // Store stringified value with prefix to distinguish from raw strings
+    let stringValue: string
+
+    if (typeof value === 'string') {
+      if (value[0] === '\0') stringValue = '\0' + value
+      else stringValue = value
+    } else if (
+      value === undefined ||
+      (typeof value === 'number' && (isNaN(value) || value === Infinity || value === -Infinity))
+    )
+      // Manually stringify non-JSON values
+      stringValue = String(value)
+    else stringValue = '\0' + JSON.stringify(value)
+    this.storage.setItem(this.itemName, this.encodeFn(stringValue))
+  }
+
+  /**
+   * Gets the current cached value.
+   */
+  get value(): T {
+    return this.#value ?? this.defaultValue
+  }
+
+  /**
+   * Allows using the setter with a callback.
+   */
+  set(callback: (value: T) => T): T {
+    return (this.value = callback(this.value))
+  }
+
+  /**
+   * Synchronizes the internal cache (`#value`) with the actual value in storage.
+   *
+   * This is only necessary if the stored value may have been modified externally.
+   * Using this function should be avoided when possible and is not type safe.
+   */
+  sync(decodeFn = this.decodeFn): unknown {
+    let value = this.storage.getItem(this.itemName)
+
+    // Reset value to defaultValue if it does not exist in storage
+    if (typeof value !== 'string') return this.reset()
+
+    // Reset value to defaultValue if the incoming value is not properly encoded
+    try {
+      value = decodeFn(value)
+    } catch (err) {
+      console.error(err)
+      return this.reset()
+    }
+
+    if (value[0] !== '\0') return (this.value = value as T) // Raw string value
+
+    // Slice off '\0' prefix
+    value = value.slice(1)
+
+    if (value[0] === '\0') return (this.value = value as T) // Raw string value that started with '\0'
+
+    // Parse non JSON
+    if (value === 'undefined') return (this.value = undefined as any)
+    if (value === 'NaN') return (this.value = NaN as any)
+    if (value === 'Infinity') return (this.value = Infinity as any)
+    if (value === '-Infinity') return (this.value = -Infinity as any)
+
+    return (this.value = JSON.parse(value) as any)
+  }
+
+  /**
+   * Resets the stored value to its configured default.
+   *
+   * Updates both the underlying storage and the internal cache.
+   */
+  reset(): T {
+    return (this.value = this.defaultValue)
+  }
+
+  /**
+   * Removes this specific key and its value from storage.
+   *
+   * Also clears the internal cache to prevent stale data access.
+   */
+  remove(): void {
+    this.#value = undefined
+    this.storage.removeItem(this.itemName)
+  }
+
+  /**
+   * Clears **all** data fromstorage.
+   *
+   * This affects every key in the storage.
+   * Also clears the internal cache to prevent stale data access.
+   */
+  clear(): void {
+    this.#value = undefined
+    this.storage.clear()
+  }
+
+  /**
+   * Checks whether the current cached value matches the configured default value.
+   *
+   * Uses reference comparison for objects and strict equality for primitives.
+   */
+  isDefault(): boolean {
+    return this.#value === this.defaultValue
+  }
+}
+
+export default HyperStorage