@uekichinos/stash

Lightweight localStorage/sessionStorage wrapper with TTL expiry, TypeScript generics, namespace isolation, and version-based auto-wipe. Zero dependencies.

stash.set('token', 'abc123', { ttl: '1h' })
stash.get('token')  // 'abc123' | null (null after 1 hour)

Installation

npm install @uekichinos/stash

Quick start

import { stash } from '@uekichinos/stash'

// Store a value
stash.set('user', { name: 'John' })

// Retrieve it
stash.get('user')  // { name: 'John' }

// With TTL — auto-expires after 30 minutes
stash.set('session', data, { ttl: '30m' })

// Namespace — isolate keys per module
const auth = stash.namespace('auth')
auth.set('token', 'xyz', { ttl: '1h' })

API

stash.set(key, value, options?)

Stores a value in localStorage (default) or sessionStorage.

stash.set('key', value)
stash.set('key', value, { ttl: '1h' })
stash.set('key', value, { ttl: 5000 })       // ms also accepted
stash.set('key', value, { storage: 'session' })

stash.get<T>(key, options?)

Returns the stored value, or null if missing or expired. Expired keys are removed automatically on read.

stash.get('key')                              // unknown | null
stash.get<User>('user')                       // User | null
stash.get('key', { storage: 'session' })

stash.has(key, options?)

Returns true if the key exists and has not expired.

stash.has('token')  // boolean

stash.remove(key, options?)

Deletes a key immediately.

stash.remove('token')

stash.ttl(key, options?)

Returns remaining TTL in milliseconds, null if the key has no TTL or doesn't exist.

stash.ttl('token')  // e.g. 1800000 (30 minutes remaining)

stash.keys(options?)

Returns all non-expired keys managed by stash. Expired keys are removed automatically.

stash.set('a', 1)
stash.set('b', 2, { ttl: '1h' })
stash.keys()  // ['a', 'b']

const auth = stash.namespace('auth')
auth.set('token', 'xyz')
auth.keys()  // ['token']  (not 'auth:token' — prefix is stripped)

stash.clear(options?)

Removes all keys managed by stash. Does not touch keys set outside of stash.

stash.clear()
stash.clear({ storage: 'session' })

stash.purge(options?)

Removes only expired keys. Useful for manual cleanup.

stash.purge()

stash.namespace(prefix, options?)

Returns a namespaced stash instance. Keys are stored as stash:{prefix}:{key}.

const auth = stash.namespace('auth')
auth.set('token', 'abc')   // stored as 'stash:auth:token'
auth.get('token')
auth.clear()               // only clears 'stash:auth:*' keys

With version — when version changes, all keys from older versions are wiped automatically:

// Old code (version 1) — keys are stored with v:1
const v1 = stash.namespace('app', { version: 1 })
v1.set('config', oldData)

// New code (version 2) — old v:1 keys are wiped on init
const v2 = stash.namespace('app', { version: 2 })
v2.get('config')  // null — old data gone

TTL formats

| Format | Duration | |--------|----------| | '30s' | 30 seconds | | '5m' | 5 minutes | | '2h' | 2 hours | | '7d' | 7 days | | 5000 | 5000 milliseconds |

TypeScript

All methods are fully typed. Use generics with get for typed retrieval:

interface User {
  id: number
  name: string
}

stash.set<User>('user', { id: 1, name: 'John' })
const user = stash.get<User>('user')  // User | null

Via <script> tag (no bundler)

<script src="https://unpkg.com/@uekichinos/stash/dist/index.global.js"></script>
<script>
  Stash.stash.set('key', 'value', { ttl: '1h' })
  Stash.stash.get('key')
</script>

Storage backends

| Option | Backend | |--------|---------| | 'local' (default) | localStorage — persists across sessions | | 'session' | sessionStorage — cleared when tab closes |

stash.set('draft', form, { storage: 'session' })
stash.get('draft', { storage: 'session' })

License

MIT © uekichinos