kid-joker/stokado

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

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

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

storage.setItem(key, value, { expires, disposable })

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')

stokado's Issues

Array length monitor

Is there a better way?

refactor the createInstrumentations

it should be better.

设置过期时间后，无法修改对象值

local.test = { hello: 'world' }
local.setExpires('test', Date.now() + 60 * 60 * 48 * 1000)
local.test.hello = 'stokado'  // doesn't work
local.test.other = 'stokado'  // doesn't work
local.test = { hellow: 'stokado' }  // works, 但是过期时间没了

有一个神奇的bug：使用session相关的方法getItem,setItem,key这些Storage原生的方法，都会作用到local上

session.setItem('test',true)事实上，设置进localStorage了。

暂时解决方案：folk了一份，把encode，decode方法导出去了，结合原生的sessionStorage.setItem('test',encode(true))来用。

Consider add indexdb support as a storage engine

Most browsers limit the default maximum storage size up to 5MB unless user relax the limit.
indexedDB allows a larger store. It is nice if support indexedDB

Console 里面总是输出'abc'

ts项目中引入报错

看了一下最后dist，没生成.d.ts文件

refactor the transform.ts

add e2e test

SSR problem

How to deal with it in SSR?

用不起来

stokado 1.1.1
vue 3.3.2

<script setup lang="ts">
import { local } from 'stokado'
local.test = 'hello stokado'
</script>

报错：

Uncaught (in promise) TypeError: Cannot set properties of undefined (setting 'test')

原来的 proxy-web-storage 正常。