createStorage

Create a multi-key, typed storage instance with reactive subscriptions and automatic serialization.

Usage

import {
  createStorage,
  localStorageProvider,
} from '@studiometa/js-toolkit/utils';

const storage = createStorage({
  provider: localStorageProvider,
  prefix: 'myapp:',
});

// Set and get values
storage.set('theme', 'dark');
storage.get('theme'); // 'dark'

// Get with default value
storage.get('lang', 'en'); // 'en' (key not set yet)

// Subscribe to changes
const unsubscribe = storage.subscribe('theme', (value) => {
  console.log('Theme changed:', value);
});

// Clean up
unsubscribe();
storage.destroy();

TypeScript

Use generics to type your storage keys and values:

import { createStorage } from '@studiometa/js-toolkit/utils';

type AppStorage = {
  theme: 'light' | 'dark';
  user: { name: string; id: number };
  lang: string;
};

const storage = createStorage<AppStorage>();

storage.set('theme', 'dark'); // ✅ typed
storage.set('theme', 'blue'); // ❌ type error
Argument of type '"blue"' is not assignable to parameter of type '"light" | "dark"'.
storage.get('user'); // { name: string; id: number } | undefined
storage.delete('user');

Parameters

• options (StorageOptions): Configuration options.
  • options.provider (StorageProvider): The storage provider to use. Defaults to localStorageProvider.
  • options.serializer (StorageSerializer): Custom serializer with serialize and deserialize methods. Defaults to JSON.
  • options.prefix (string): Key prefix for namespacing. All keys will be stored with this prefix (e.g. 'myapp:' stores key 'theme' as 'myapp:theme').

Return value

A StorageInstance<T> with the following methods:

• get(key) — Get the value for a key. Returns undefined if not set or if the stored value is corrupted.
• get(key, defaultValue) — Get the value for a key, returning defaultValue if not set.
• set(key, value) — Set a value. null is stored as a real value when your type allows it.
• delete(key) — Remove a key from storage. Subscribers are notified with undefined.
• has(key) — Check if a key exists in storage.
• keys() — List all keys managed by this instance. When a prefix is set, only prefixed keys are returned (with the prefix stripped).
• clear() — Remove all entries. When a prefix is set, only prefixed keys are cleared — other keys in the same provider are left untouched. Subscribers are notified with undefined.
• subscribe(key, callback) — Subscribe to changes on a key. Returns an unsubscribe function. Listeners are notified on both local changes and external sync events (cross-tab, navigation). undefined means the key is absent.
• destroy() — Clean up all listeners and event handlers.

Cleanup

Each createStorage() call registers a global event listener (when the provider has a syncEvent). Always call destroy() when the storage instance is no longer needed to avoid memory leaks — for example in a component's unmount/destroy lifecycle hook.