DEV Community: KID-joker

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

KID-joker — Wed, 24 Jun 2026 15:30:39 +0000

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.

I finally shipped the plugin I'd been putting off for years. Then I started questioning why I built it.

KID-joker — Thu, 21 May 2026 14:13:05 +0000

A few days ago I checked off something that had been sitting in my todo list for a long time.

It's a small develop plugin called unplugin-drop-committed. It removes method calls like console.log from your code during development — but only the ones that have been committed to Git. Your uncommitted lines are safe.

The idea came from a real frustration: a colleague had left console.log calls inside polling loops. The browser console was unusable. I didn't want to ban console.log globally — I just wanted the committed noise gone.

Simple enough concept. I had the idea. I never built it.

Why it sat there so long

I care deeply about DX tooling. Probably more than is professionally sensible. I've filtered job opportunities based on whether I'd be working on developer experience. I think it's underrated craft — the invisible layer that makes other developers' days slightly less painful.

But DX is almost always low priority at work. There's always a feature to ship, a bug to fix, a deadline to hit. The DX improvements I want to make get pushed to "later". Later becomes the weekend. The weekend fills up. The todo list grows.

unplugin-drop-committed sat there for a long time. Not because it was hard. Because I never had the uninterrupted time to start.

How AI changed that

I used Claude to help me build it. I want to be clear about what that means: the ideas, the design, the four removal modes — those were mine. What AI gave me was momentum. It handled the boilerplate, suggested approaches I hadn't considered, and kept me from getting stuck on implementation details that would have cost me a whole evening.

It took a fraction of the time I expected. I finally crossed something off the list.

For someone like me — someone with a backlog of DX ideas and a shortage of free hours — AI is genuinely liberating. It's not replacing my thinking. It's removing the friction that was keeping my thinking from becoming real things.

The question that followed

The satisfaction lasted maybe ten minutes.

Then I started thinking about who would actually use this.

AI-assisted development is changing how code gets written. AI agents don't forget to delete their console.log calls the way humans do — or if they produce noise, it's a different kind. The problem this plugin solves is a human problem, shaped by human habits.

I asked Claude how I should position the plugin. It suggested: "unplugin-drop-committed helps AI coding agents stay focused — keeping debug output isolated to the module being worked on."

That's… not wrong. It's actually an interesting reframe. But it also felt like I was watching my motivation quietly shift from "making developers' lives better" to "making AI agents' workflows cleaner."

DX. AX. Developer Experience. Agent Experience.

I'm not sure when the transition happened, or if it already has.

What I actually believe

I don't think DX is dead. I think the audience is changing, and the best DX tools will be the ones that serve both humans and the agents working alongside them.

I also think there's something worth preserving about caring whether the developer console is readable. Whether the hot reload feels instant. Whether configuration is intuitive. These things still matter, even if fewer people are writing the code by hand.

And I'm going to keep building these tools. AI gave me back the time to do it. I'd rather use that time on the things I actually care about than spend it wondering whether caring still counts.

If you want to try it:

https://github.com/KID-joker/unplugin-drop-committed

Four modes: strict (committed lines), file (committed files), user (other authors), time (older than N days/months). Vite, Webpack, Rollup, Rspack. Vue and Svelte script blocks included.

I'd genuinely like to know: do you think DX tooling still matters the same way it did two years ago?

How to keep the type of storage value unchanged?

KID-joker — Sun, 15 Jan 2023 13:24:03 +0000

Hello, everyone! In September last year, I created a new repository called proxy-web-storage which has over 200 stars now. It can helps some developers manage storage more easily, so I want to share it with you. If you think this repository is useful and deserves more attention, please click a star to support it. I'll introduce it below, so let's get started.

What can proxy-web-storage do?

proxy-web-storage reflects every change of the storage through the Proxy.

The Proxy object enables you to create a proxy for another object, which can intercept and redefine fundamental operations for that object.

1. Keep the type of storage value unchanged.

import { local } from 'proxy-web-storage';

local.test = 'Hello proxy-web-storage'; // works
delete local.test; // works

// number
local.test = 0;
local.test === 0; // true

// boolean
local.test = false;
local.test === false; // true

// undefined
local.test = undefined;
local.test === undefined; // true

// null
local.test = null;
local.test === null; // true

// object
local.test = { hello: 'world' };
local.test.hello = 'proxy-web-storage'; // works

// array
local.test = ['hello'];
local.test.push('proxy-web-storage'); // works
local.test.length // 2

// Date
local.test = new Date('2000-01-01T00:00:00.000Z');
local.test.getTime() === 946684800000; // true

// RegExp
local.test = /d(b+)d/g;
local.test.test("cdbbdbsbz"); // true

// function
local.test = function() {
  return 'Hello proxy-web-storage!';
};
local.test() === 'Hello proxy-web-storage!'; // true

The local corresponds to localStorage, and the same is true for session. They have the same methods and properties: key(), getItem(), setItem(), removeItem(), clear() and length.

2. Listen to the changes.

import { local } from 'proxy-web-storage';

local.on('test', function(newVal, oldVal) {
  console.log('test', newVal, oldVal);
});
local.on('test.a', function(newVal, oldVal) {
  console.log('test.a', newVal, oldVal);
});

local.test = {};
// test {} undefined

local.test.a = 1;
// test.a 1 undefined

It can also listens to changes triggered by other tabs.

on

Subscribe to an item.

key: the name of the item to subscribe to. Support obj.a for Object and list[0] for Array, and also Array length.
callback: the function to call when the item is changed. Includes newValue and oldValue.

once

Subscribe to an item only once.

key: the name of the item to subscribe to. Support obj.a for Object and list[0] for Array.
callback: the function to call when the item is changed. Includes newValue and oldValue.

off

Unsubscribe from an item or all items.

key(optional): the name of the item to unsubscribe from. If no key is provided, it unsubscribes you from all items.
callback(optional): the function used when binding to the item. If no callback is provided, it unsubscribes you from all functions binding to the item.

3. Set expires for items.

import { local } from 'proxy-web-storage';

local.test = 'hello proxy-web-storage';
local.setExpires('test', Date.now() + 10000);

// within 10's
local.test // 'hello proxy-web-storage'

// after 10's
local.test // undefined

The expires is saved to localStorage. So page refresh or close will not affect its expiration. Within 10's, the value still exists. But after 10's, it has been removed.

setExpires

set expires for an item.

key: the name of the item to set expires.
expires: accept string、number and Date.

getExpires

return the expires(Date) of the item.

key: the name of the item that has set expires.

removeExpires

cancel the expires of the item.

key: the name of the item that has set expires.

The features of proxy-web-storage are the above. But I would like to ask how to do the e2e test of localStorage? If you have any suggestion, whether it is about e2e testing or about the repository, please contact me or open an issue. Thanks for reading.