Skip to content

Latest commit

 

History

History
211 lines (144 loc) · 5.13 KB

v2.zh.md

File metadata and controls

211 lines (144 loc) · 5.13 KB
Raw
         __                __  __                __
  ____  /\ \__     ___    /\ \/  \      __      /\ \     ___   
 / ,__\ \ \ ,_\   / __`\  \ \    <    /'__`\    \_\ \   / __`\ 
/\__, `\ \ \ \/  /\ \_\ \  \ \  ^  \ /\ \_\.\_ /\ ,. \ /\ \_\ \
\/\____/  \ \ \_ \ \____/   \ \_\ \_\\ \__/.\_\\ \____\\ \____/
 \/___/    \ \__\ \/___/     \/_/\/_/ \/__/\/_/ \/___ / \/___/ 
            \/__/

English | 中文

stokado(/stəˈkɑːdoʊ/) 是 storage 的世界语(一种国际辅助语言)，喻意为 stokado 也是 storage 的辅助代理。

stokado 借助 proxy，更好地更方便地管理 storage，实现了相关语法糖、序列化、监听订阅、设置过期、一次性取值等功能。

在codesandbox试一试，也可以查看 tests 文件夹下的测试用例。

Install

npm i stokado
// mjs
import { local, session } from 'stokado'
// cjs
const { local, session } = require('stokado')

CDN

<script src="https://cdn.jsdelivr.net/npm/stokado"></script>
<!-- or https://www.unpkg.com/stokado -->
<script>
  const { local, session } = window.stokado
</script>

Features

1. Syntax sugar

保持storage值的类型不变并且可以直接操作数组和对象。

import { local, session } from 'stokado'

local.test = 'hello stokado' // 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 = 'stokado' // works

// array
local.test = ['hello']
local.test.push('stokado') // 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 stokado!'
}
local.test() === 'hello stokado!' // true

test和对应的value是实际保存到localStorage的。同时，local和session也支持Web Storage的方法和属性：key()，getItem()，setItem()，removeItem()，clear() 和 length。

Extra:

setItem(key, value, options) 支持设置属性，options 配置字段如下：

类型 作用
expires string | number | Date 设置过期时间
disposable boolean 设置一次性

2. Subscribe

监听值的变化。

import { local } from 'stokado'

local.on('test', (newVal, oldVal) => {
  console.log('test', newVal, oldVal)
})
local.on('test.a', (newVal, oldVal) => {
  console.log('test.a', newVal, oldVal)
})

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

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

监听指定项。

参数：

  • key：监听指定项的名字。支持对象的二级监听，例如：obj.a 对于 Object 和 list[0] 对于 Array，还支持数组长度的监听。
  • callback：指定项的值发生变化时，触发的回调函数。参数包括newValue 和 oldValue。
once

只监听指定项一次。

  • key：监听指定项的名字。支持对象的二级监听，例如：obj.a 对于 Object 和 list[0] 对于 Array，还支持数组长度的监听。
  • callback：指定项的值发生变化时，触发的回调函数。参数包括newValue 和 oldValue。
off

取消监听指定项或者移除所有监听。

  • key（可选）：期望移除监听的指定项。如果为空，则移除所有监听。
  • callback（可选）：移除指定项的某一回调函数。如果为空，则移除指定项绑定的所有监听事件。

3. Expired

为指定项设置过期时间。

import { local } from 'stokado'

local.setItem('test', 'hello stokado', { expires: Date.now() + 10000 })
// local.test = 'hello stokado'
// local.setExpires('test', Date.now() + 10000)

// within 10's
local.test // 'hello stokado'

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

过期时间也会保存到Web Storage中，并不会刷新页面导致过期失效。 所以在10秒内无论你怎么刷新，值还是会存在。 但是在10秒以后，指定项就被移除了。

setExpires

为指定项设置过期时间。

  • key：设置过期的指定项名字。
  • expires：过期时间。接受string、number 和 Date类型。
getExpires

获取指定的过期时间，返回类型为Date。

  • key: 设置了过期时间的指定项名字。
removeExpires

取消指定项的过期设置。

  • key: 设置了过期时间的指定项名字。

4. Disposable

一次性取值。

import { local } from 'stokado'

local.setItem('test', 'hello stokado', { disposable: true })
// local.test = 'hello stokado'
// local.setDisposable('test')

local.test // 'hello stokado'
local.test // undefined
setDisposable

为指定项设置一次性取值。

  • key：设置一次性的指定项名字。