idb
Date: 2021-09-08
Author: luo
Version: 1.1.4
基于 IndexedDB 的二次封装，以便客户端本地快捷操作数据库。
本封装使用 函数式编程 范式，共提供以下 API。 支持链式调用，每次调用都需 exec 执行。
支持对 IndexedDB 的批量增删改查。
| API | 解释 |
|---|---|
| open | 打开/新建 数据库 |
| table | 连接/新建 表 |
| add | 对 表 进行新增操作 |
| put | 对 表 进行更新操作 |
| delete | 对 表 进行删除操作 |
| get | 对 表 进行查询操作 |
| getAll | 查询当前 表 的所有数据 |
| clear | 清空当前 表 的所有数据 |
| exec | 执行当前命令栈所有命令 |
API
安装
// npm
npm i @thinkives/idb -S
// yarn
yarn add @thinkives/idb使用
import Idb from '@thinkives/idb'
const idb = new Idb()open
打开数据库，若 name 不存在，则新建数据库。
| params | type | require | 说明 |
|---|---|---|---|
| name | String | true | 数据库名 |
| version | Number | true | 数据库版本 |
version 在对 数据库 新增 表时候，需要更新。
const idb = new Idb()
idb.open('parent', 1).exec()table
打开指定表，若 name 不存在，则新建该表。
| params | type | require | 说明 |
|---|---|---|---|
| name | String | true | 表名 |
| primaryKey | String | false | 主键/索引 |
primaryKey: 新增时若不设置主键，将默认设置为 { autoIncrement: true }。
建议手动指定主键，否则主键将会默认从 1 开始递增。
对表进行的 add/put/delete/get 操作都将会依靠 主键 来完成。
const idb = new Idb()
idb.table('parent', 'id').exec()add
对指定表进行 新增/批量新增 操作。
| params | type | require | 说明 |
|---|---|---|---|
| data | Any or Array/Object | true | 表名 |
若 table 时传入了指定主键，则新增的数据必须包含主键属性。此时数据结构为 Object/Object[]。
若 table 时未指定主键，则新增数据类型 any。
const idb = new Idb()
idb.add({id: 1, text: 'hello'}).exec()
idb.add([
{id: 1, text: 'hello'},
{id: 2, text: 'world'}
]).exec()add 在主键重复时，将会抛出错误。因此建议使用 put 进行新增数据，除非明确要新增的数据在表中已有的数据中不存在。
put
对指定表进行 修改/批量修改 操作。
| params | type | require | 说明 |
|---|---|---|---|
| data | Any or Array/Object | true | 要修改的新数据 |
const idb = new Idb()
idb.put({id: 1, text: 'hello'}).exec()
idb.put([
{id: 1, text: 'hello'},
{id: 2, text: 'world'}
]).exec()若 table 时传入了指定主键，则修改的数据必须包含主键属性。此时数据结构为 Object/Object[]。
若修改的主键不存在，则新增该数据。
若 table 时未指定主键，则新增数据类型 any。
delete
对指定表进行 删除/批量删除 操作。
| params | type | require | 说明 |
|---|---|---|---|
| data | primaryKey or primaryKey[] | true | 主键/主键组成的数组 |
const idb = new Idb()
idb.delete(1).exec()
idb.delete([1, 2, 3]).exec()传入单个 主键或主键组成的数组 皆可。
get
对指定表进行 查询/批量查询 操作。
| params | type | require | 说明 |
|---|---|---|---|
| data | primaryKey or primaryKey[] | true | 主键/主键组成的数组 |
const idb = new Idb()
idb.get(1).exec()
idb.get([1, 2, 3]).exec()传入单个 主键或主键组成的数组 皆可。
getAll
对指定表进行 查询全部数据 操作。
| params | type | require | 说明 |
|---|---|---|---|
| - | - | - | - |
const idb = new Idb()
idb.getAll().exec()clear
对指定表进行 清空所有数据 的操作
| params | type | require | 说明 |
|---|---|---|---|
| - | - | - | - |
const idb = new Idb()
// ...something idb 内部已关联了某个库表
idb.clear().exec()batchCreateTable
对指定数据库批量创建表。
| params | type | require | 说明 |
|---|---|---|---|
| list | Array: {name: String, keyPath: String}[] | true | 由表名，主键对象组成的数组 |
const idb = new Idb()
idb.open('batch', 1).batchCreateTable([
{ name: 'user-1', keyPath: 'id' },
{ name: 'user-2', keyPath: 'id' }
]).exec(() => {
// 因为多张表创建时，实例内部不会主动关联 table。需手动声明指定。
idb.table('user-1', 'id').put({id: 10, text: 'hello'}).exec()
})exec
执行该次链式调用的所有命令。
| params | type | require | 说明 |
|---|---|---|---|
| callback(result) | Function | false | 链式调用执行结束后的回调函数 |
| abnormalCb(error) | Function | false | 链式调用执行异常中断后的回调函数 |
callback(result): 链式调用执行结束后的回调函数，本次链式调用最后一个节点的结果将会传入 result。
abnormalCb(error): 链式调用执行异常后的回调函数，本次链式调用异常中断前的最后一个节点的结果将会传入 error。
const idb = new Idb()
idb.xxx().exec(
result => {},
error => {}
)所有的命令操作，都需要调用 exec 方能执行。
Example
初始化
const idb = new Idb()
// 若数据库不存在，则为 新建 idb 数据库，新增一张 table-1 表，设置主键为 id。
// 若数据库存在，table-1 亦存在，则为 打开 idb 数据库，实例内部关联该表。
idb.open('idb', 1).table('table-1', 'id').exec()
// 上文的操作 + 对 table-1 表新增了若干数据
idb
.open('idb', 1)
.table('table-1', 'id')
.add([{id: 1, text: 'hello'}, {id: 2, text: 'world'}])
.exec()
// 上文的操作 + 对 table-1 表新增了若干数据 + 修改了主键 id 为 1 的数据
idb
.open('idb', 1)
.table('table-1', 'id')
.add([{id: 1, text: 'hello'}, {id: 2, text: 'world'}])
.put({id: 1, text: 'newhello'})
.exec()每次对表进行操作时，无需重复 open + table。
在初始化 open + table 时，内部已关联了此实例操作的数据库 + 表。
只要确保在后续的操作时，实例内部已经关联即可。
const idb = new Idb()
idb.open('idb', 1).table('table-1', 'id').exec(() => {
idb.delete(1).exec()
})当然，也可以重新执行 open + table 以更新实例内部的关联 库 + 表
const idb = new Idb()
// 实例内部关联了 idb 数据库, table-1 表
idb.open('idb', 1).table('table-1', 'id').exec()
// 实例内部重新关联了 idb-2 数据库, table-2 表
idb.open('idb-2', 1).table('table-2', 'id').exec()open 与 table 并非一定要在一起执行，单独执行亦可。
由于对库表的操作都属于异步行为，因此若要确保拿到最新状态的实例。可以这样执行。
const idb = new Idb()
// 不建议进行如下操作
// 以下操作可能会出现操作冲突
// 因为无法确保在进行 add 操作时，open table 都已被执行完毕。
idb.open('idb', 1).table('table-1', 'id').exec()
idb.add([{id: 1, text: 'hello'}, {id: 2, text: 'world'}]).exec()
// 可以这样操作
idb.open('idb', 1).table('table-1', 'id').exec(() => {
idb
.add([{id: 1, text: 'hello'}, {id: 2, text: 'world'}])
.exec()
})
// 亦可这样操作
idb
.open('idb', 1)
.table('table-1', 'id')
.add([{id: 1, text: 'hello'}, {id: 2, text: 'world'}])
.exec()