StorageManager

Isomorphic key-value storage with automatic prefix namespacing and custom serialization.

Import

import { StorageManager } from "bytekit/storage-utils";

What it does

StorageManager provides a unified key-value storage API that works in the browser (localStorage / sessionStorage) and falls back to an in-memory store in Node.js or environments where the Web Storage API is unavailable. Keys are automatically namespaced with a configurable prefix.

In Node.js the in-memory fallback behaves identically to the browser API, so your code can run isomorphically without conditional imports.

Constructor

const storage = new StorageManager(config?: StorageManagerConfig);

StorageManagerConfig

Property	Type	Default	Description
prefix	string	""	Prefix prepended to every key to avoid collisions.
storage	'local' | 'session'	'local'	Which browser storage backend to use.
serializer	(value: unknown) => string	JSON.stringify	Custom serialization function.
deserializer	(raw: string) => unknown	JSON.parse	Custom deserialization function.

Methods

get<T>(key)

const user = storage.get<User>("current-user");

Returns the deserialized value for key, or null if the key does not exist.

Parameter	Type	Description
key	string	Storage key (prefix is applied automatically).

set<T>(key, value)

storage.set("current-user", { id: 1, name: "Ada" });

Serializes and stores value under key.

Parameter	Type	Description
key	string	Storage key.
value	T	Value to store.

remove(key)

storage.remove("current-user");

Deletes the entry for key.

clear()

storage.clear();

Removes all entries managed by this StorageManager instance (scoped by prefix).

has(key)

if (storage.has("token")) {
  // ...
}

Returns true if key exists in storage.

keys()

const allKeys = storage.keys();

Returns an array of all keys (without the prefix) stored by this instance.

getAll()

const snapshot = storage.getAll();
// { "current-user": { id: 1, name: "Ada" }, "token": "abc" }

Returns a record of every key-value pair managed by this instance.

size()

console.log(`Stored items: ${storage.size()}`);

Returns the number of entries.

Examples

Basic session storage

import { StorageManager } from "bytekit/storage-utils";

const session = new StorageManager({
  prefix: "app:",
  storage: "session",
});

session.set("lang", "en");
console.log(session.get<string>("lang")); // "en"
console.log(session.has("lang"));          // true
console.log(session.keys());               // ["lang"]
session.remove("lang");

Custom serializer for dates

import { StorageManager } from "bytekit/storage-utils";
import superjson from "superjson";

const storage = new StorageManager({
  prefix: "v2:",
  serializer: (v) => superjson.stringify(v),
  deserializer: (s) => superjson.parse(s),
});

storage.set("createdAt", new Date());
const date = storage.get<Date>("createdAt"); // Date instance, not a string

Node.js in-memory usage

import { StorageManager } from "bytekit/storage-utils";

const cache = new StorageManager({ prefix: "cache:" });

cache.set("config", { debug: true });
console.log(cache.size());    // 1
console.log(cache.getAll());  // { config: { debug: true } }
cache.clear();

Use a unique prefix per feature or module to avoid key collisions when multiple parts of your application share the same storage backend.

Browser storage is limited to roughly 5 MB per origin. For larger datasets consider CacheManager or IndexedDB.