Stokado: A Zero-Dependency Proxy Wrapper That Makes Browser Storage Feel Like a Plain Object

If you've shipped anything to the browser, you've used localStorage. And if you've used it for more than five minutes, you've also written this exact line more times than you'd like to admit:

const user = JSON.parse(localStorage.getItem('user') || 'null')

The Web Storage API has aged remarkably well for something so small, but it carries three persistent pain points that every frontend codebase ends up papering over by hand.

Pain point #1: everything is a string. localStorage.setItem('count', 0) doesn't store the number 0 — it stores the string "0". Read it back and typeof is "string". Booleans become "true"/"false", Date objects collapse into ISO strings (if you're lucky) or "[object Object]" (if you're not), and undefined becomes the literal string "undefined". So every project grows a thin serialization layer of JSON.parse/JSON.stringify wrappers, plus a pile of defensive try/catch blocks for the day a malformed value sneaks in.

Pain point #2: the API is verbose and stringly-typed. getItem, setItem, removeItem — three method calls and a string key for what is conceptually just reading and writing a property. It reads nothing like the rest of your code.

Pain point #3: reactivity is broken in the tab you actually care about. The native storage event only fires in other tabs of the same origin. The tab that performed the write never hears about it. So if you want to react to your own storage changes — the overwhelmingly common case — the platform gives you nothing.

Stokado is a small, zero-dependency library that addresses all three by wrapping any storage object in a Proxy. It's framework-agnostic, TypeScript-friendly, and works equally well with localStorage, sessionStorage, cookies, async backends like localForage, and a handful of mini-program runtimes. This article walks through what it actually does, feature by feature, with runnable code.

Quick start

npm install stokado

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)

// Write like a plain object
storage.token = 'abc'

// Read like a plain object
console.log(storage.token) // 'abc'

// Delete with the delete operator
delete storage.token

createProxyStorage takes any storage-like object and returns a proxy that behaves like a plain object on the surface, while doing serialization, change notification, expiration, and quota bookkeeping underneath. That's the whole mental model. Everything below is a refinement of it.

Type-safe serialization

The single most repetitive chore with native storage is converting values to and from strings. Stokado handles it transparently — and crucially, it preserves the type, not just the shape.

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)

storage.count = 0
storage.enabled = false
storage.missing = null
storage.createdAt = new Date('2024-01-01T00:00:00Z')
storage.pattern = /^\d+$/g
storage.profile = { name: 'Ada', roles: ['admin'] }

console.log(typeof storage.count) // 'number'  (not "0")
console.log(storage.enabled === false) // true     (not "false")
console.log(storage.missing) // null     (not "null")
console.log(storage.createdAt instanceof Date) // true
console.log(storage.pattern.test('42')) // true
console.log(storage.profile.roles[0]) // 'admin'

The trap that catches naive JSON.parse wrappers is the falsy-but-valid value: storage.count = 0 round-trips as the number 0, not the string "0" and not undefined. The same holds for false and null. Stokado records the original type tag at write time and reconstructs the matching JavaScript value at read time.

The supported type set is deliberately broad. In addition to the obvious string, number, boolean, null, undefined, object, and array, stokado round-trips BigInt, Date, RegExp, URL, Set, Map, and even Function:

storage.id = 9007199254740993n
storage.tags = new Set(['a', 'b', 'a'])
storage.lookup = new Map([['x', 1]])
storage.api = new URL('https://example.com/v1')
storage.greet = function (name) {
  return `hi ${name}`
}

console.log(typeof storage.id) // 'bigint'
console.log(storage.tags instanceof Set) // true
console.log(storage.lookup.get('x')) // 1
console.log(storage.api.host) // 'example.com'
console.log(storage.greet('Ada')) // 'hi Ada'

A note on Function: stokado serializes it via toString() and rebuilds it with the Function constructor on read. That's genuinely useful for storing small configuration callbacks, but be aware it relies on dynamic evaluation and loses closure scope — treat it as a convenience for trusted, self-contained functions rather than a general serialization mechanism.

If you ever need the raw conversion outside of a proxy, stokado exports the underlying encode and decode functions directly:

import { decode, encode } from 'stokado'

Same-tab reactive subscriptions

This is where stokado earns its keep. You can subscribe to changes on a specific key, and — unlike the native storage event — the callback fires in the same tab that made the change.

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)

storage.on('token', (newValue, oldValue) => {
  console.log(`token changed: ${oldValue} -> ${newValue}`)
})

storage.token = 'abc' // logs: token changed: undefined -> abc
storage.token = 'xyz' // logs: token changed: abc -> xyz

Every listener receives (newValue, oldValue), both already deserialized to their proper types. There are three methods:

• on(key, fn) — subscribe to all future changes for key.
• once(key, fn) — fire exactly once, then auto-unsubscribe.
• off(key?, fn?) — unsubscribe. Pass a key and function to remove one listener, pass just a key to remove all listeners for that key, or pass nothing to clear everything.

function handler(n, o) {
  console.log('once:', n, o)
}

storage.once('session', handler)
storage.session = 'first' // fires once
storage.session = 'second' // silent — already unsubscribed

storage.on('cart', updateBadge)
storage.off('cart', updateBadge) // remove a single listener

Subscriptions even reach into nested properties using dot paths, which is handy when you store structured objects:

storage.on('profile.name', (n, o) => console.log(`name: ${o} -> ${n}`))

storage.profile = { name: 'Ada' }
storage.profile.name = 'Grace' // logs: name: Ada -> Grace

Because this works in the same tab, you can use storage as a lightweight intra-app event bus — for example, keeping a header avatar in sync with a settings page without reaching for a global store.

Expiration and disposable values

Native storage has no concept of a TTL. Stokado adds two complementary lifetime controls through the third argument of setItem.

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)

// Expires at a specific time (timestamp or Date)
storage.setItem('session', 'token-123', {
  expires: Date.now() + 60_000, // gone in 60 seconds
})

// Disposable: self-destructs after the first read
storage.setItem('flash', 'You just signed in!', {
  disposable: true,
})

console.log(storage.flash) // 'You just signed in!'
console.log(storage.flash) // undefined — consumed on first read

expires accepts a timestamp, a date string, or a Date instance. Once the moment passes, the value is treated as gone — reading it returns undefined and the entry is cleaned up. disposable is a one-shot read: perfect for flash messages, single-use tokens, or any "show this exactly once" value.

The two can be combined, and there's a small family of helpers for managing lifetimes after the fact:

// Set / inspect / clear an expiry on an existing key
storage.setExpires('session', new Date('2030-01-01'))
console.log(storage.getExpires('session')) // Date instance
storage.removeExpires('session')

// Mark an existing key as disposable
storage.setDisposable('flash')

// Inspect the full option set for a key
console.log(storage.getOptions('session'))
// e.g. { expires: <Date>, disposable: true } — or null if no options set

getOptions returns whatever lifetime metadata is attached to a key (expires, disposable, or both), or null if the key is a plain value. It's a clean way to introspect state without guessing.

Cross-tab synchronization

Same-tab reactivity is great, but sometimes you genuinely want every open tab to agree. Stokado can broadcast changes across tabs of the same origin using the BroadcastChannel API.

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage, {
  broadcast: true,
  channel: 'app-storage',
})

// In any tab:
storage.on('theme', (next) => {
  document.documentElement.dataset.theme = next
})

// In another tab:
storage.theme = 'dark' // every tab's listener fires

With broadcast enabled, a write in one tab propagates over the named channel and triggers your subscriptions in the others — so your same-tab on/once handlers and your cross-tab handlers share one unified API. The channel option lets you scope the broadcast so unrelated proxies don't talk over each other.

Quota alerts

Web Storage throws a QuotaExceededError when you exceed the (browser-dependent, typically ~5 MB) limit, and by then it's too late. Stokado lets you set a soft quota and get a callback before a write lands.

import { createProxyStorage, MB } from 'stokado'

const storage = createProxyStorage(localStorage, {
  quota: 4 * MB,
  onQuotaExceeded(info) {
    console.warn(
      `Quota hit on "${info.key}": ${info.current}/${info.limit} bytes`,
    )
    // Return false to block this write entirely
    return false
  },
})

The callback receives a QuotaInfo object with { current, limit, key, value } — the projected total size, your configured limit, and the key/value being written. The return value controls the write:

• Return false to reject the write (the value is not stored).
• Return anything else (or nothing) to allow it.

The handler may also be async, which is useful when you want to evict old entries or ask the user before deciding:

const storage = createProxyStorage(localStorage, {
  quota: 4 * MB,
  async onQuotaExceeded(info) {
    const proceed = await confirmWithUser(info)
    return proceed // false blocks, true allows
  },
})

For proactive monitoring, getUsage() reports current consumption against the limit at any time:

const { current, limit } = storage.getUsage()
console.log(`Using ${current} of ${limit} bytes`)

Stokado measures byte size accurately (via Blob), so the numbers reflect real UTF-8 encoded sizes rather than naive string lengths. The exported KB and MB constants are just 1024 and 1024 * 1024 to keep your quota declarations readable.

Async backends

localStorage caps out around 5 MB and is synchronous. For larger or non-blocking storage, localForage is the go-to — it transparently uses IndexedDB and exposes a Promise-based API. Stokado proxies it just as happily, returning an AsyncProxyStorage whose methods return Promises.

import localforage from 'localforage'
import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localforage)

// Wait for the backend to be ready before first use
await storage.ready

await storage.setItem('test', 'hello stokado')
console.log(await storage.test) // 'hello stokado'

await storage.removeItem('test')
console.log(await storage.test) // undefined

Stokado auto-detects that the backend is asynchronous and adapts its surface accordingly. A few differences from the sync case to keep in mind:

• Reads and writes resolve to Promises, so you await them (await storage.test, await storage.setItem(...)).
• ready is a Promise you can await to ensure the backend has finished initializing.
• length() is a method that returns a Promise, not a synchronous property.
• getUsage() returns a Promise.

Everything else — type preservation, subscriptions, expiration, disposable values — works identically. The same setItem('key', value, { expires, disposable }), the same on/once/off, just with await where the platform forces it.

Multi-platform presets

Browser localStorage is only one of many key-value stores in the JavaScript world. Stokado ships seven ready-made presets as sub-path imports, each adapting a foreign storage API to the shape createProxyStorage expects. Import only the one you need — they're tree-shakeable.

Cookies — a Storage-like view over document.cookie:

import { createProxyStorage } from 'stokado'
import { cookieStorage } from 'stokado/presets/cookie'

const cookies = createProxyStorage(cookieStorage)
cookies.consent = true

WeChat / Douyin / Alipay mini-programs — each exposes both a sync and an async variant mapping to that platform's storage SDK:

import { createProxyStorage } from 'stokado'
import { wechatStorage, wechatStorageAsync } from 'stokado/presets/wechat'
import { douyinStorage, douyinStorageAsync } from 'stokado/presets/douyin'
import { alipayStorage, alipayStorageAsync } from 'stokado/presets/alipay'

const wx = createProxyStorage(wechatStorage)

uni-app — the cross-platform mini-program framework, again sync and async:

import { createProxyStorage } from 'stokado'
import { uniStorage, uniStorageAsync } from 'stokado/presets/uni-app'

const uni = createProxyStorage(uniStorage)

React Native — wrap @react-native-async-storage/async-storage (or any compatible AsyncStorage) into an async storage-like object:

import AsyncStorage from '@react-native-async-storage/async-storage'
import { createProxyStorage } from 'stokado'
import { createReactNativeStorage } from 'stokado/presets/react-native'

const storage = createProxyStorage(createReactNativeStorage(AsyncStorage))
await storage.ready
await storage.setItem('token', 'abc')

Node — an in-memory store, ideal for tests, SSR, and CLI tools where no browser storage exists:

import { createProxyStorage } from 'stokado'
import { memoryStorage } from 'stokado/presets/node'

const storage = createProxyStorage(memoryStorage)
storage.cached = { ok: true }

Because the presets normalize everything to the same storage-like interface, the entire stokado feature set — serialization, subscriptions, expiration — works the same across all of them. Write your data layer once, run it on the web, in a mini-program, in React Native, or on the server.

How it compares

Stokado is not trying to be the only storage tool you'll ever need, and it's worth being honest about where other libraries are the better pick.

• If your priority is squeezing data into a smaller footprint, reach for lz-string. It's purpose-built for compressing strings before they hit storage. Stokado focuses on faithful type round-tripping, not compression.
• If you live entirely in Vue and want storage wired into the reactivity system, useStorage from @vueuse/core gives you a ref that syncs to storage with deep Vue integration. Stokado is framework-agnostic by design and won't give you a Vue ref out of the box.
• If you need a large IndexedDB-backed key-value store and nothing else, idb-keyval is a tiny, focused option. (And if you want stokado's features on top of IndexedDB, recall that it proxies localForage, which sits on IndexedDB.)

Where stokado's edge shows is the combination: faithful type preservation and same-tab reactivity and expiration/disposable values and quota awareness, all behind one plain-object interface, with zero dependencies and the same API across browsers, mini-programs, React Native, and Node. No single feature is unique; having all of them composed together, with nothing to install but the package itself, is.

Wrap-up

The Web Storage API gives you a synchronous string-to-string map and not much else. Stokado keeps that simplicity at the surface — storage.token = 'abc' — while quietly handling the parts every team reimplements: type-correct serialization, same-tab change subscriptions, TTLs and one-shot values, cross-tab sync, and quota guards. And it does it without dragging in a single dependency, across every JavaScript runtime that has a key-value store.

If you've been hand-rolling JSON.parse wrappers and storage event workarounds, give it a try:

npm install stokado

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)
storage.user = { name: 'Ada', lastSeen: new Date() }

The full source, tests, and API reference live at github.com/KID-joker/stokado.