__                __  __                __
  ____  /\ \__     ___    /\ \/  \      __      /\ \     ___   
 / ,__\ \ \ ,_\   / __`\  \ \    <    /'__`\    \_\ \   / __`\ 
/\__, `\ \ \ \/  /\ \_\ \  \ \  ^  \ /\ \_\.\_ /\ ,. \ /\ \_\ \
\/\____/  \ \ \_ \ \____/   \ \_\ \_\\ \__/.\_\\ \____\\ \____/
 \/___/    \ \__\ \/___/     \/_/\/_/ \/__/\/_/ \/___ / \/___/ 
            \/__/

English | 中文

v2 document

Stokado(/stəˈkɑːdoʊ/) is the Esperanto(an international auxiliary language) for storage, meaning that Stokado is also an auxiliary agent for storage.

stokado can proxy objects of any storage-like, providing getter/setter syntax sugars, serialization, subscription listening, expiration setting, one-time value retrieval.

Usage

Install

npm install stokado

Proxy

import { createProxyStorage } from 'stokado'

const storage = createProxyStorage(localStorage)

storage.getItem('test')

createProxyStorage(storage[, name])

createProxyStorage takes two parameters: an object of storage-like and an optional name. The name is used to synchronize storage modifications with other pages. By default, localStorage has the same name, whereas sessionStorage does not; for other objects, it needs to be passed in manually.

Features

1. Syntax sugar

Operate storage directly through object-oriented approach

Of course, localStorage and sessionStorage are supported natively

const storage = createProxyStorage(localStorage)

storage.test = 'hello stokado'

storage.test // 'hello stokado'

delete storage.test

The storage also have the same methods and properties: key(), getItem(), setItem(), removeItem(), clear() and length.

2. Serializer

Keep the type of storage value unchanged

// number
storage.test = 0
storage.test === 0

// boolean
storage.test = false
storage.test === false

// undefined
storage.test = undefined
storage.test === undefined

// null
storage.test = null
storage.test === null

// object
storage.test = { hello: 'world' }
storage.test.hello === 'stokado'

// array
storage.test = ['hello']
storage.test.push('stokado')
storage.test.length // 2

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

// RegExp
storage.test = /d(b+)d/g
storage.test.test('cdbbdbsbz')

// function
storage.test = function () {
  return 'hello stokado!'
}
storage.test() === 'hello stokado!'

3. Subscribe

Subscribe to value changes

storage.on(key, callback)

storage.once(key, callback)

storage.off([[key], callback])

• 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.

Tips: For off, if a callback exists, it removes the trigger of the specified callback; otherwise, it removes all callbacks bound to the key; if the key is empty, it removes all listening callbacks.

4. Expired

Set expires for items

storage.setExpires(key, expires)

storage.getExpires(key)

storage.removeExpires(key)

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

5. Disposable

Get the value once, which can be used for communication through storage.

storage.setDisposable(key)

• key：the name of the item to set disposable.

6. Options

Get expires and disposable configuration information for the specified item

storage.getOptions(key)

Set expires and disposable using setItem

Work with localForage

localForage provides the same API as localStorage, it can be used in conjunction with stokado.

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

const local = createProxyStorage(localForage, 'localForage')

However, localForage uses an async API, it needs to be called using Promise.

await (local.test = 'hello localForage')

// or

await local.setItem('test', 'hello localForage')

Multiple instances

You can create multiple instances of localForage that point to different stores using createInstance.

const store = localforage.createInstance({
  name: 'nameHere'
})
const proxyStore = createProxyStorage(store, 'store')

const otherStore = localforage.createInstance({
  name: 'otherName'
})
const proxyOtherStore = createProxyStorage(otherStore, 'otherStore')