@~lisfan/storage

Storage

离线存储器

API documentation

Feature 特性

• 让离线存储支持存储更多的数据类型
• 为离线存储增加有效期，若已超过时效则不读取

Detail 详情

• 底层依赖了localforage模块，并且封装了让localforage支持sessionStorage存储的一个扩展插件，顺便修复了该插件iterate()方法的bug

• 提供的大多数方法都是异步的，部分实例上的属性数据需要等待完全初始化完成才能获取的到，所以为了确保它已经完全初始化，需将逻辑代码写在调用ready()方法后的resolved函数里

• 提供的API模仿localforage-like风格，但增减了一部分，同时也可能更改了部分方法的逻辑，但大致上还是可以参考文档localforage的文档的

• 支持localforage所有全局配置项参数，各配置参数作用也是相同的，但细微之处会有差异，且额外扩展了一些新的配置项，同时支持自定义数据存储单元的配置项

• 若maxAge设置的存活时间为0，则不会进行离线存储数据，且为了保证一个命名空间下所有的的数据时效性检测（同时移除已过期的数据），会很消耗性能，所以只针对于部分API操作进行了特殊处理，因此这部分API应该尽量少使用，如keys()和iterate()方法

• 额外扩展了如下配置选项

  • 数据存储有效期控制maxAge：默认数据可存活时间（毫秒单位），可选值有：0=不缓存，小于0的值=永久缓存（默认），大于0的值=可存活时间

• 与 localforage 模块的的一些区别

  • 驱动器的常量值变化，改成以下对应的值，且作为了是类的静态属性成员
    • Storage.SESSIONSTORAGE: 使用sessionstorage离线存储，默认项
    • Storage.LOCALSTORAGE: 使用localstorage离线存储
    • Storage.INDEXEDDB: 使用indexedDB离线存储
    • Storage.WEBSQL: 使用webSQL离线存储
  • 驱动器的默认使用顺序变更：根据浏览器支持情况，优先选择sessionStorage，之后再根据localforage的默认值选择
  • Storage实例移除类似localforage API末尾的callback形参
  • Storage.supports方法作为静态方法成员，而不是像localforage#supports方法作为实例方法成员
  • Storage中不存在像localforage#setDriver、localforage#createInstance、localforage#defineDriver等API
  • Storage#length作为一个实例属性值，而不是像localforage#length作为一个异步方法
  • Storage#getItem方法取的值若不存在时，将进入reject，抛出not found，而不是返回null
  • 移除了Storage#key方法
  • 扩展支持的一些新的数据类型存储
  • 默认支持localforage支持的如下数据类型存储
    • null
    • Number
    • String
    • Array
    • Object
    • Blob
    • ArrayBuffer
    • Float32Array
    • Float64Array
    • Int8Array
    • Int16Array
    • Int32Array
    • Uint8Array
    • Uint8ClampedArray
    • Uint16Array
    • Uint32Array
  • 在此基础上又扩充了对如下数据类型的存储（因为在某些实际的使用场景中还是需要用的到，内部存储时将使用了如下格式进行存储）
    • undefined => [storage undefined]#undefined
    • NaN => [storage nan]#NaN
    • Infinity => [storage infinity]#Infinity
    • -Infinity => [storage infinity]#-Infinity
    • new Date() => [storage date]#1507600033804
    • /regexp/g => [storage regexp]#/regexp/g
    • new RegExp('regexp', 'g') => [storage regexp]#/regexp/g
    • function(){}`` => [storage function]#function(){}`
    • new Function('a', 'b', 'return a+b') => [storage function]#function anonymous(){}
  • 不对以下数据类型进行存储
    • Symbol
    • Error

Install 安装

npm install -S @~lisfan/storage

Usage 起步

import storage,{Storage} from '@~lisfan/storage'

// 在存值或取值前确保实例已完全初始化完成
storage.ready().then(()=>{
  // 设置值
  storage.setItem('someKey','someData').then((data)=>{
    // 设置成功
  })

  // 设置值存活有效期10秒钟
  storage.setItem('someKey','someData',{maxAge:10*1000}).then((data)=>{
  })
})


// 自定义存储器实例
const storageOther = new Storage({
  name: 'storageOther'
})

// 获取值
storageOther.ready().then(()=>{
  storageOther.getItem('someKey').then((data)=>{
    // 取到了值
  }).catch((err)=>{
    // err 为 'notfound'
    // 值不存在
    // err 为 'outdated'
    // 值过期
  })
})