@codejoo/storage

English | 简体中文

A tiny, type-safe wrapper over localStorage / sessionStorage / IndexedDB with one unified API: TTL & absolute expiry, sliding renewal, namespaces, pluggable serialization (incl. Date / Map / Set / bigint), an optional obfuscation codec, an opt-in in-memory cache, and a key-bound shortcut helper. Sync backends return values; the async IndexedDB backend returns Promises — decided by generics, one code path.

• Zero deps · ESM · sideEffects: false · ships a per-module tree-shakeable build (dist/esm/).
• Falls back to in-memory storage automatically when the native API is unavailable (privacy mode, sandboxed iframe, etc.).

Install

pnpm add @codejoo/storage

Quick start

import { factory } from "@codejoo/storage";

const { ls, ss } = factory();

ls.set("token", "abc"); // localStorage
ls.get("token"); // "abc"
ls.get("missing", "default"); // "default"
ls.set("session", 1, 60_000); // expires in 60s (ttl ms)
ls.remove("token");
ls.clear();
ls.length; // number of entries

With IndexedDB (async, large quota). Idb is not bundled by default — import it yourself:

import { factory, Idb } from "@codejoo/storage";

const { db } = factory({ db: new Idb() });

await db.set("user", { id: 1 }); // Promise<void>
await db.get("user"); // Promise<{ id: 1 }>

API

factory(options?)

Returns { ls, ss, db, destroy, setNamespace } over localStorage, sessionStorage, and the provided IndexedDB instance respectively. ls/ss are synchronous; db is asynchronous (returns Promises). All three share the same option behaviors. destroy() releases every layer at once (clears the memo caches and disconnects db's IndexedDB connection) and returns a Promise; it does not delete persisted data. setNamespace(username?) switches the prefix of all three layers in place (great for per-account isolation on login/logout) — handles you already hold keep working; it only isolates, it does not erase the previous namespace's persisted data.

BaseStorageOptions

Handler methods (ls / ss / db)

R<T> is T for sync backends (ls/ss) and Promise<T> for the async backend (db).

StorageOptions (per-call set options)

Only these three apply per call (everything else — codec, sliding, raw… — is instance-level, see BaseStorageOptions):

fast(target, key)

Binds a handler and a key, returning { get, set, remove } so you stop repeating the key. Sync/async return type follows target. Specify the value type once via fast<V>(...).

const token = fast<string>(ls, "token");
token.set("abc"); // value must be string
token.get(); // string | null
token.get("def"); // string
token.remove();

Accessor shape — SyncAccessor<V> (sync) / AsyncAccessor<V> (async):

lazy(target, key)

Like fast, but returns a getter that builds the accessor on first call and caches it. Combined with a /*#__PURE__*/ annotation, unused exports are tree-shaken — ideal for a central cache.ts registry of many keys.

export const token = /*#__PURE__*/ lazy<string>(ls, "token");
token().get(); // accessor created on first use, reused after

batchFast(target, keys)

Bind several keys at once; returns an object keyed by each key, with a fast accessor per key (key names preserved via const generic; value type V shared, defaults to unknown).

const { token, user } = batchFast(ls, ["token", "user"]);
token.set("abc");
user.get();

JSONX

JSON-compatible serializer that additionally round-trips bigint / Date / Map / Set. Methods don't use this, so they can be passed directly as serialize/deserialize.

const { ls } = factory({ serialize: JSONX.stringify, deserialize: JSONX.parse });
ls.set("x", { when: new Date(), ids: new Set([1n, 2n]) }); // round-trips exactly

Circular references are not supported (inherits JSON.stringify behavior — throws).

Codecs — codec / codecBase64 / codecAtob

Three lightweight obfuscation codecs (keep plaintext out of devtools — not strong encryption, the password ships in the bundle). All take an optional password (built-in default otherwise); changing it makes old data undecodable — decode returns null and the stale entry is cleared on read. Use with { codeable: true, codec: codec("pw") }.

Codec shape:

Idb(name?)

An asynchronous Storage-like backend over IndexedDB. No full in-memory mirror (constant memory; data is GC-friendly). Pass it to factory({ db }). Falls back to in-memory automatically if IndexedDB is unavailable or open() fails at runtime.

Methods (all return Promises): get(key), set(key, value), remove(key), clear(), key(index), keys(), length(), destroy() (close the connection; keeps data). Handler-level batch ops loop over these single-key methods (one transaction per key) — there is no bulk getMany/setMany/removeMany primitive.

crossTab(handler, channel?)

Standalone plugin (tree-shakes away when unused). Only activates in pure in-memory mode (native storage unavailable — privacy mode, sandboxed iframe): replays set/remove/clear to other same-origin tabs via BroadcastChannel so each tab's memory stays consistent. No-op when native storage works (already shared) or when mounted twice. Local writes apply before broadcasting; a failed broadcast (non-cloneable value) only warns. setNamespace is not synchronized — switch it per tab. Returns a stop function.

import { factory, crossTab } from "@codejoo/storage";
const { ls } = factory();
const stop = crossTab(ls);

debug(handler)

Standalone helper shipped as a separate subpath (@codejoo/storage/debug) — it is not part of the main entry, so the single-file bundles (dist/index.mjs / index.min.js) physically exclude it. Reads every entry of a handler decrypted and returns a { "namespace:key": value } snapshot (namespace preserved). It is a pure read with no side effects — it does not write the snapshot back to storage, so it never pollutes keys()/length. Use it to inspect data written with codeable/enckey.

import { factory, codec } from "@codejoo/storage";
import { debug } from "@codejoo/storage/debug";

const { ls, db } = factory({ codeable: true, codec: codec("pw"), enckey: true });
debug(ls); // sync → { "key": value, ... }
await debug(db); // async backend → Promise

Notes

• Sync vs async is driven by the backend type via generics: ls.get(k) returns a value, db.get(k) returns a Promise. One proxy implementation serves both.
• db features: ttl / expireAt / codec / namespace / sliding / memoized all apply to db too (just await it). force quota-purge currently applies to sync backends only.
• Memo is isolated per factory() instance: each factory() call gets its own in-memory read cache; separate instances do not share memo (no cross-instance reads).
• Tree-shaking: the package points import at dist/esm/ (one file per module). With sideEffects: false, unused modules/exports are dropped by the bundler.

Differences from native localStorage

• Values are wrapped in an entity envelope ({ value, createdAt, ... }) by default, not stored as bare strings. Reading a key with the native localStorage.getItem (bypassing this library) yields the JSON envelope, not your raw value (except in raw mode).
• set does not throw on quota (native throws QuotaExceededError). When storage is full it only logs / invokes onError and gives up the write — use onError if you need to observe write failures.
• length and clear() are namespace-scoped: with namespace/enckey they cover only the keys this instance owns, unlike native's global semantics.
• Expiry is lazy: expired entries are not read and not eagerly deleted; they are reclaimed by purge() or under quota pressure.

Build outputs

Testing

pnpm test

runs the full integration suite (test/*.browser.test.ts) in a real Chromium via Playwright (vitest browser mode), against real localStorage / sessionStorage / IndexedDB / BroadcastChannel — not a jsdom simulation. This covers sync backends, async IDB transactions, and cross-tab sync as they behave in an actual browser.

An interactive playground remains at test/manual.html: run pnpm dev and open /test/manual.html.

License

MIT