browser-localstorge 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Aurora]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# browser-localstorge
+
+1️⃣2️⃣3️⃣4️⃣5️⃣6️⃣7️⃣8️⃣
+
+## 📌localStorage 存储
+
+### 初始化
+
+`new BrowserStoreKit(type, options)`
+
+| 属性名 | 含义 | 格式、默认值 |
+| :----:| :----: | :----: |
+| type | 存储模块类型 | `string`，目前支持三种模式：LOCAL_STORAGE, SESSION_STORAGE, INDEXED_DB（请从库中导入使用）。 |
+| options | 配置参数 | `object`，根据模式的不同设置项的属性也不同。添加localStorage下的属性，会在LOCAL_STORAGE模式下生效。 |
+---
+
+示例参考：
+
+```javascript
+import BrowserStoreKit, { LOCAL_STORAGE, SESSION_STORAGE, INDEXED_DB } from 'browser-localstorage'
+
+const localKit = new BrowserStoreKit(LOCAL_STORAGE, {
+    // 使用localStorage的时候，这边配置项参数就给属性localStorage赋值即可（session同理）
+    localStorage: {
+        auto_cover: true,
+        auto_parse: true,
+        auto_stringify: true,
+        debug: false,
+    }
+})
+
+// 实例化之后，就可以执行localKit的方法了
+localKit.setItem(...)
+localKit.getItem(...)
+...
+```
+
+下面介绍一下配置项参数的含义：
+
+> 目前，**localStorage** 和 **sessionStorage** 的配置项参数是一致的。
+
+| 属性名 | 含义 | 格式、默认值 |
+| :----:| :----: | :----: |
+| auto_cover | setItem是否自动将结果覆盖 | `boolean`，默认为`true`。因为localStorage本身的逻辑也是自动覆盖。 |
+| auto_parse | 是否自动将结果反序列化（`JSON.parse`） | `boolean`，默认为`false`。通过`getItem`获取到的数据不会自动被parse |
+| auto_stringify | 是否自动将非字符串的对象序列化（`JSON.stringify`） | `boolean`，默认为`true`。 |
+| debug | 是否开启debug（调试）模式 | `boolean`，默认为`false`。如果打开，则会在控制台输出存储信息。调试信息格式见下。 |
+
+控制台输出的调试信息格式大致如下：
+```javascript
+[2025-04-22 10:16:42] 🔗localStorage 📎[getItem]: 数据项获取成功➡️(key: 2)➡️值为{"id":"2","name":"咪咪","age":"3.56"}
+```
+
+这其实没有什么实质性的大作用，但是console能够给到你一些足够的安全感~
+
+### 1️⃣新增 / 修改数据 `setItem`
+
+- key：`string`类型，**必填项**，表示键。
+- value：`any`类型，**必填项**，表示存储的值。
+
+> 注意：value的类型可以是任意类型，但是在存储的时候可能会自动将其序列化为字符串。
+
+```javascript
+localKit.setItem(key, value)
+```
+
+### 2️⃣删除数据 `removeItem`
+根据键删除数据
+
+- key：`string`类型，**必填项**，表示键。
+
+```javascript
+localKit.removeItem(key)
+```
+
+### 3️⃣查找数据 `getItem`
+根据键查找数据
+
+- key：`string`类型，**必填项**，表示键。
+
+```javascript
+localKit.getItem(key)
+```
+
+### 4️⃣清空数据 `clear`
+清空本地localStorage中的所有数据，无参数。不可撤销请谨慎使用。
+
+```javascript
+localKit.clear()
+```
+
+### 5️⃣获取数据长度 `length`
+获取localStorage中的所有数据的长度，无参数。
+
+```javascript
+localKit.length()
+```
+
+## 📌sessionStorage 存储
+
+`sessionStorage`不做过多的赘述，因为它和`localStorage`的使用是**完全一致**的。
+请仔细阅读上面的localStorage文档部分即可。
+
+## 📌indexedDB 存储🔥🔥🔥
+
+简单介绍一下`indexedDB`的使用方法。它与前面的localStorage和sessionStorage的使用方式是**完全不同**的。因此在使用之前，希望你仔细阅读下面的文档。
+
+### 1️⃣初始化
+
+首先初始化 `indexedDB`
+
+```javascript
+import BrowserStoreKit, { INDEXED_DB } from 'browser-localstorage'
+
+const DBKit = new BrowserStoreKit(INDEXED_DB, {
+    // 在使用indexedDB的时候，需要配置indexedDB的参数
+    indexedDB: {
+        databaseName: "testDB",
+        tableName: "testTable",
+        primaryKey: "id",
+        autoIncrement: true,
+        auto_cover: false,
+        debug: false
+    }
+})
+
+// 这一步十分重要❗❗❗
+// 请注意，因为indexedDB是异步操作，因此在实例化之后需要再执行init方法
+// 这一步保证你的数据库和数据表已经处于打开状态，以此来进行后续的操作
+
+await DBKit.init()
+```
+
+| 属性名 | 含义 | 格式、默认值 |
+| :----:| :----: | :----: |
+| `databaseName` | 数据库名称（用来指定打开的数据库） | `string`，必填。建议尽量保证唯一，纯英文。 |
+| `tableName` | 数据表名称（用来指定打开的数据表） | `string`，必填。同一个数据库下面可以有多张数据表~ |
+| `primaryKey` | 主键（学过数据表的应该都知道） | `string`，必填，默认为`id`。作为数据表的唯一主键，必须保持唯一性。 |
+| `autoIncrement` | 是否自动递增 | `boolean`，默认为`true`。如果打开，每个数据项的主键（默认为id）会保持自动递增。 |
+| `auto_cover` | 是否开启自动覆盖 | `boolean`，默认为`false`。如果打开，当你指定`setItem`并且相同键已经有值的情况下，会提醒警告并停止执行。 |
+| `debug` | 是否开启debug（调试）模式 | `boolean`，默认为`false`。如果打开，则会在控制台输出存储信息。 |
+
+---
+
+请注意 `primaryKey（主键）` 和 `autoIncrement（是否自动递增）` 两者之间的关系：
+
+`primaryKey`为必需参数，并且要保证**唯一性**，主要作用如下：
+
+1. 在新增数据的时候，作为唯一主键
+2. 在<u>修改、查找、删除数据</u>的时候作为查找线索
+
+当你申明了`autoIncrement`参数值为true的时候，这意味着：
+
+BrowserStoreKit会在你每次插入数据（`setItem`）的时候，为你的数据增加一个主键（也就是参数primaryKey），这个过程是自动的，且遵循的逻辑是递增（i++）
+
+> 例如，当你调用`setItem`新增数据的时候是这样的：
+
+```javascript
+await DBKit.setItem({ name: '老王', age: 48 })
+```
+
+> 当你后续调用getItem的时候，会拿到`{ id: 2, name: '老王', age: 48 }`
+
+
+> 请注意，indexedDB模式下，所有的操作（下面几种）都是**异步**的，因此在使用的时候需要使用`await`关键字。
+
+### 2️⃣新增 / 修改数据 `setItem`
+
+`DBKit.setItem(key, value)`
+
+- key：`string | number`类型，**必填项**，表示键。
+- value：`Object`类型，**必填项**，表示存储的值。
+
+在自增模式下，key可以传入`null`，因为此时会自动生成主键。
+
+```javascript
+DBKit.setItem(id, { name, age }).then(r => {
+    console.log("-----setItem返回结果-----")
+    console.log(r)
+})
+```
+
+### 3️⃣删除数据 `removeItem`
+
+- key：`string | number`类型，**必填项**，表示键。
+
+```javascript
+DBKit.removeItem(key).then(r => {
+    console.log("-----removeItem返回结果-----")
+    console.log(r)
+})
+```
+
+### 4️⃣查找数据 `getItem`
+
+- key：`string | number`类型，**必填项**，表示键。
+
+```javascript
+DBKit.getItem(key).then(r => {
+    console.log("-----getItem返回结果-----")
+    console.log(r)
+})
+```
+
+### 5️⃣清空数据 `clear`
+
+无参数，谨慎使用。
+
+```javascript
+DBKit.clear().then(r => {
+    console.log("-----clear返回结果-----")
+    console.log(r)
+})
+```
+
+### 6️⃣获取数据长度 `length`
+
+无参数。
+
+```javascript
+DBKit.length().then(r => {
+    console.log("-----length返回结果-----")
+    console.log(r)
+})
+```
+
+## 📌批量操作 `BatchProcess`
+
+考虑到**indexedDB**存储的特性，在<u>批量处理、数据量比较大</u>的场景下会有比较高的应用频率。因此在原来的基础上，设计了**批量操作的API**，可以对数据进行批量**新增**、**删除**以及**查找**。请注意，批量操作目前仅支持**indexedDB**模式。
+
+批量操作统一使用`batchProcess`方法，该方法接受三个参数
+
+- `mode`：`<string>`类型：批量操作的模式，目前支持三种模式，分别是新增（`add`）、查找（`get`）以及删除（`delete`）。
+
+- `itemList`：`Array<string | number | Object>`类型：批量操作的数据集合。
+
+- `options`：`Object`类型：批量操作的配置项。
+
+### 批量新增操作 `ADD`
+
+```javascript
+let startIndex = 1
+const dataList = new Array(5).fill(0).map((item, index) => {
+    return { id: startIndex + index, name: `我是第${startIndex+index}个name`, age: startIndex + index }
+})
+
+// 当我们执行批量新增的时候，数组的Item项为Object类型
+// 并且，如果是自增模式下，Item不需要指定主键属性（id），因为会自动生成主键
+// 此示例演示的是，非自增模式下，Item需要指定主键属性（id）
+DBKit.batchProcess("add", dataList).then(r => {
+    console.log("-----batchSetItem返回结果-----")
+    console.log(r)
+})
+``` 
+
+### 批量删除操作 `DELETE`
+
+根据主键删除数据
+
+```javascript
+// 当我们执行批量新增的时候，数组的Item项为number或string类型
+DBKit.batchProcess("delete", [1, 2, 3, 4, 5]).then(r => {
+    console.log("-----batchRemoveItem返回结果-----")
+    console.log(r)
+})
+``` 
+
+### 批量查询操作 `GET`
+
+根据主键查询数据
+
+```javascript
+// 当我们执行批量新增的时候，数组的Item项为number或string类型
+DBKit.batchProcess("get", [1, 2, 3, 4, 5]).then(r => {
+    console.log("-----batchGetItem返回结果-----")
+    console.log(r)
+})
+``` 
+
+# 写在最后💻
+
+如果觉得这个库对你有帮助，欢迎给我一个star⭐️⭐️⭐️
+如果有什么问题，欢迎提issue。
+
+我会尽力在后面迭代升级中完善这个库，希望能够给你带来帮助~
+
+# 版本更新记录📋
+
+## 1.0.0 (2025-05)
+
+1.0.0 首个正式版上线