typed-local-storage

Getting started

Install#

npm i @dmytromykhailiuk/typed-local-storage

Quick start#

Create a storage once at module scope. The value type is inferred from initialValue.

import { createLocalStorage } from "@dmytromykhailiuk/typed-local-storage";

const settings = createLocalStorage("app:settings", {
  initialValue: { theme: "dark", fontSize: 14 },
});

settings.get();                       // { theme: "dark", fontSize: 14 } — typed
settings.set({ theme: "light", fontSize: 16 });
settings.update((s) => ({ ...s, fontSize: s.fontSize + 1 }));
settings.clear();                     // back to the initial value

const unsubscribe = settings.subscribe((value) => {
  // fires on every write through this instance —
  // and when another tab writes the same key
  document.body.dataset.theme = value.theme;
});

Because an initialValue was given, get() returns T — never undefined. Without one it returns T | undefined, and the callbacks of update and subscribe follow. See TypeScript.

One key, one owner#

The library's one opinion: a localStorage key should have exactly one owner. You declare that owner — the storage object — in one place, give it the type, and import it everywhere else.

import { createLocalStorage } from "@dmytromykhailiuk/typed-local-storage";

export const session = createLocalStorage<Session>("app:session");
export const drafts = createLocalStorage("app:drafts", {
  initialValue: [] as Draft[],
});

// anywhere else in the app
import { drafts } from "./storage";
drafts.update((list) => [...list, draft]);

Creating a second storage with a name that is already registered throws — two storages writing one key with different types is a bug worth failing loudly on:

createLocalStorage("app:session");
createLocalStorage("app:session"); // Error: Storage "app:session" already exists

The returned object is frozen (Object.freeze), so its methods cannot be monkey-patched or reassigned — what you export from storage.ts is exactly what every consumer gets.

Reference

createLocalStorage#

function createLocalStorage<T>(
  key: string,
  options?: {
    initialValue?: T;
    isString?: boolean;
    groups?: LocalStoragesGroup[];
    onParseError?: (error: unknown, raw: string) => void;
  },
): LocalStorage<T>;

Options#

The storage object#

Everything below is a stable reference on a frozen object. V stands for what get() returns — T when the storage has an initialValue, T | undefined otherwise.

Serialization#

Values go through JSON.stringify / JSON.parse — objects, arrays, numbers, booleans and null round-trip as you would expect:

const cart = createLocalStorage("cart", { initialValue: [] as CartItem[] });
cart.set([{ id: 1, qty: 2 }]);
// localStorage["cart"] === '[{"id":1,"qty":2}]'

String mode#

A JSON-encoded string is stored with quotes — "\"dark\"" — which is noisy in devtools and breaks interop with code that wrote the key before this library. String mode stores the value raw. It turns on automatically when initialValue is a string, or explicitly with isString: true:

const theme = createLocalStorage("app:theme", { initialValue: "dark" });
// localStorage["app:theme"] === "dark"        (not "\"dark\"")

const token = createLocalStorage<string>("app:token", { isString: true });
token.set("eyJhbGciOi…");
// localStorage["app:token"] === "eyJhbGciOi…" — readable by anything

In string mode nothing is parsed on read either, so a value written by other code — whatever it contains — comes back verbatim and can never trigger onParseError.

Initial values#

An initialValue does three things:

1. Seeds the key at creation — written to storage immediately, but only when the key is absent.
2. Defines what clear() means — reset to it, rather than remove the key.
3. Backs get() — a missing or unparseable value falls back to it, which is why get() can promise a plain T.

const counter = createLocalStorage("counter", { initialValue: 0 });

// key absent           → "0" is written; get() === 0
// a session stored 7   → seeding skipped; get() === 7
// a session stored 0   → kept as 0 — falsy is a value, not an absence

What emptying a storage means, in both configurations:

Error handling#

Storage is shared, hand-editable state — a browser extension, an old app version or a stray devtools session can leave anything in it. get() therefore never throws: unparseable JSON is reported through onParseError and the call falls back to initialValue (or undefined).

const cart = createLocalStorage("cart", {
  initialValue: [] as CartItem[],
  onParseError: (error, raw) => report(error, { raw }),
});

localStorage.setItem("cart", "{oops"); // someone corrupted it
cart.get(); // [] — the initial value; onParseError was called with "{oops"

The default handler is a console.warn naming the library and the raw value — corruption is visible in development even when you configure nothing.

Subscriptions#

subscribe delivers every change of the key to one callback, wherever the change came from:

• This instance — set, update and clear notify synchronously after writing.
• Other tabs — the browser's storage event is translated into the same callback. The event only fires in other documents, so a write is delivered exactly once everywhere — no double notifications.

const theme = createLocalStorage("app:theme", { initialValue: "dark" });

const unsubscribe = theme.subscribe((value) => {
  document.body.dataset.theme = value; // value: string — typed like get()
});

theme.set("light");
// …and when another tab calls theme.set("dark"), this tab's callback
// fires with "dark" via the storage event.

unsubscribe();

The window-level storage listener is attached lazily on the first subscribe and detached when the last subscriber leaves — a storage nobody listens to costs nothing. A listener that throws is isolated (reported via console.error) and never blocks the other listeners.

Groups#

When an app stores many keys, "clear the user's data" has two bad answers: localStorage.clear(), which levels the whole origin — theme, language, consent flags, everything that should have survived — and clearing keys one by one, a list that silently drifts out of date every time a feature adds a key.

A group is the middle ground: storages that belong together are declared together, and reset together with one call — nothing outside the group is touched. The classic case — "clear everything user-scoped on logout":

import {
  createLocalStorage,
  createLocalStoragesGroup,
} from "@dmytromykhailiuk/typed-local-storage";

const userScoped = createLocalStoragesGroup("app:user-scoped");

const session = createLocalStorage<Session>("app:session", {
  groups: [userScoped],
});
const drafts = createLocalStorage("app:drafts", {
  initialValue: [] as Draft[],
  groups: [userScoped],
});

// on logout
userScoped.clear(); // session removed, drafts reset to []

clear() applies each member's own semantics: a member with an initialValue is reset to it, a member without one is removed. Members are cleared through their instances, so their subscribers are notified.

Registrations survive reloads#

The group persists its member list — key and initial value — in storage under its own name. On the next session, clear() also covers keys whose createLocalStorage call didn't run this time (a lazy route, an unvisited feature) — code paths that didn't execute can't leak stale data past a logout.

One storage can belong to any number of groups — pass several in groups, or call group.add(storage) after creation; both do the same thing.

SSR & fallbacks#

Where localStorage is missing or throws on access — Node during SSR, sandboxed iframes, browsers with cookies disabled — every storage transparently runs against a shared in-memory fallback. The entire API keeps working; values simply live for the lifetime of the process.

const session = createLocalStorage<Session>("app:session", {
  initialValue: guest,
});

session.get(); // guest — served from the in-memory fallback, no crash
session.set(user);
session.get(); // user — persists for the lifetime of the process

The fallback is shared across all storages in the process, so groups and cross-storage flows behave the same as in a browser. Subscriptions still deliver local writes; there are simply no other tabs to hear from.

TypeScript#

Whether the storage can be empty is part of its type. createLocalStorage has two overloads: with an initialValue the storage can never observe an absent value, so get() returns T; without one it returns T | undefined. The callbacks of update and subscribe follow the same rule.

const counter = createLocalStorage("counter", { initialValue: 0 });
counter.get();                // number — no undefined to handle
counter.update((v) => v + 1); // v: number

const session = createLocalStorage<Session>("app:session");
session.get();                // Session | undefined
session.update((v) => v ?? emptySession); // v: Session | undefined
session.subscribe((v) => {    // v: Session | undefined
  if (v) render(v);
});

The value type comes from inference off initialValue — including literal widening, so initialValue: "dark" infers string… or from the explicit parameter (createLocalStorage<Session>(…)) when there is nothing to infer from. To keep a union type with an inferred initial value, annotate it:

type Theme = "dark" | "light";

const theme = createLocalStorage<Theme>("app:theme", { initialValue: "dark" });
theme.set("light"); // ✓ typed
theme.set("blue");  // ✗ Type '"blue"' is not assignable to type 'Theme'

Exports#

Values

createLocalStorage · createLocalStoragesGroup

Types

LocalStorage · LocalStorageOptions · LocalStoragesGroup