localstory's Introduction

localstory

A lightweight (0.8kb) wrapper around browser storage APIs (localStorage / sessionStorage).

Features

namespaces to avoid key collisions
per-value TTL expires
safe API (avoids throwing errors)
zero dependencies

npm install localstory

Usage

const store = require('localstory')(window.localStorage, 'myNamespace', { ttl: '45m' })

store.set('foo', 'bar')
store.get('foo') // 'bar'
store.unset('foo')

store.keys() // ['foo']
store.clear()

Namespacing

Use namespaces to freely use IDs without fear of collisions between different applications/stores in the same domain.

const horses = localstory(window.localStorage, 'horses')
const ponies = localstory(window.localStorage, 'ponies')

horses.set('name', 'Thunder')
ponies.get('name') // undefined

ponies.set('name', 'Sparkle')

horses.get('name') // 'Thunder'
ponies.get('name') // 'Sparkle'

Expiry / TTL

Automatically expire values. Expiry is validated on reads and once on load (can be disabled with vacuum: false). Each key can have it's own expiry time.

To enable, provide { ttl: [milliseconds] } as second parameter to the set() method:

store.set('foo', 'bar', { ttl: 1000 * 60 * 60 /* 1 hour */ })

store.get('foo') // 'bar'
store.get('foo') // one hour later... undefined

// time parameter takes human readable strings: [s]econds, [m]inutes, [h]ours, [d]ays
store.set('foo', 'bar', { ttl: '1h' })

store.vacuum() // removes all expired keys

// disable automatic vacuum on startup
const store = localstory(localStorage, 'namespace', { vacuum: false })

// set custom delay (in ms) for vacuum on startup
const store = localstory(localStorage, 'namespace', { vacuum: 15000 })