# storage-free

**Repository Path**: git_zs/storage-free

## Basic Information

- **Project Name**: storage-free
- **Description**: 一个简单易用的storage插件，在浏览器中可以使用localstorage和sessionstorage两种模式，在原生的基础上封装了一层时效性功能和JSON序列化功能(此功能可选是否需要)
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-09-15
- **Last Updated**: 2023-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 使用

`npm i storage-free --save`

## 特点

**storage-free以下统称SF**

1. **有效期：** 在储存一个内容时传入有效期，在读取这条数据是SF会判断要读取的内容是否过期，如果过期则会返回null判断有效期时默认使用new Date(); 如果传入了依赖时间则会使用**依赖时间**；（此设定主要是为了防止用户在修改主机时间后欺骗程序获取错误的当前时间，**依赖时间**主要是提供给开发者，可以传入服务器时间以保证不被篡改）
2. **定制化：** 将主体调用存储部分以回调函数的形式分离开放，使用者可以根据不同的storageAPI以达到兼容不同的平台目的
3. **分组概念：** 因同域不同html的localStorage共享的特性，在使用储存是可能出现key污染，所以引入分组概念
   1. 每一个储存的key都会被带上组名，但开发者完全不用关心这个
      1. 例如：存储`info`信息时，开发者传入`info`作为key，SF会将它存为`info${分隔符}${组名}` 的形式，读取时也只需传入`info`，中间过程无需关心
   2. 清空逻辑处理，清空逻辑会默认删除当前分组的所以储存内容
4. **浏览器中使用：** 如果只在浏览器中使用可跳过**自定义储存API : customStorage**的讲解，直接看**浏览器储存：browserStorage**
5. **简单易懂：** 整体代码非常少，也没有任何复杂的逻辑

## 文档

### 自定义储存API : customStorage

> 使用此方法可以自定义储存器，例如小程序或uniapp的storageAPI，并返回一个提供增删改查的对象（return storage）

**options**

|属性/方法名|描述|类型|默认值|
|--|--|--|--|
|separator|key与分组的分隔符|string|'-'|
|group|分组|string|-|
|isJson|是否需要做JSON序列化，开启是便无需自己JSON.stringify和parse了，如uniapp这种已存在这样功能的可以关闭|boolean|true|
|getCustomTime|如果需要使用服务器时间可使用此方法，并返回一个时间戳|():number =>|-|
|customSetItem`必填`|自定义储存器的setItem方法用于储存，提供参数(key, value)|function|-|
|customGetItem`必填`|自定义储存器的getItem方法用于获取对应key的value，提供参数(key)|function|-|
|customRemoveItem`必填`|自定义储存器的removeItem方法用于删除key对应内容，提供参数(key)|function|-|

**return storage method**

|方法名|描述|
|--|--|
|setItem|添加一条持久化数据到本地；入参(key, value, time) time为有效时长时间戳|
|getItem|查询一条已经存在的持久化数据，未查询到返回null；入参（key）；返回的是一个promise使用await或then接收结果|
|removeItem|删除一条已存在的持久化数据；入参（key）|
|clear|清空当前分组的所有持久化数据；入参（key[]）key[]为本地所有已存在持久化数据的key，SF会通过分隔符+分组进行过滤；如不使用分组功能清空时可以不使用SF的clear方法；|

**示例**

```javascript
isSession// 此示例也是下方browserStorage的代码
import { customStorage } from "storage-free";
export default ({ separator, group, isJson, isSession } = {}) => {
  const storage = isSession ? window.sessionStorage : window.localStorage;
  const custom = customStorage({
    separator,
    group,
    isJson: isJson ?? true,
    customSetItem(key, value) {
      storage.setItem(key, value);
    },
    customGetItem(key) {
      return storage.getItem(key);
    },
    customRemoveItem(key) {
      storage.removeItem(key);
    },
  });
  return {
    ...custom,
    clear() {
      custom.clear(Object.keys(storage));
    },
  };
};




```

<br/>

### 浏览器储存：browserStorage

> 浏览器中使用可以直接使用此方法，已封装好方便快捷使用，源码即上方示例的代码

**options**

|属性/方法名|描述|类型|默认值|
|--|--|--|--|
|separator|key与分组的分隔符|string|'-'|
|group|分组|string|-|
|isJson|是否需要做JSON序列化，开启是便无需自己JSON.stringify和parse了，如uniapp这种已存在这样功能的可以关闭|boolean|true|
|isSession|是否使用sessionStorage|boolean|false|

**return storage method**

|方法名|描述|
|--|--|
|setItem|添加一条持久化数据到本地；入参(key, value, time) time为有效时长时间戳|
|getItem|查询一条已经存在的持久化数据，未查询到返回null；入参（key）；返回的是一个promise使用await或then接收结果|
|removeItem|删除一条已存在的持久化数据；入参（key）|
|clear|清空所有当前分组下的持久化数据|

**使用示例**

```javascript
import { browserStorage } from "storage-free";

const storage = browserStorage({ separator: "~", group: "test" });

storage.setItem(
  "info",
  {
    username: "zs",
    token: "123456",
    userinfo: { type: 1 },
  },
  5000
);

// 5秒后获取的就为null了
setInterval(async () => {
  console.log(await storage.getItem("info"));
}, 1000);

```

**推荐方式**

推荐在项目中封装一个storage文件 然后抛出 browserStorage 的执行结果

```javascript
// storage.js文件
// 分组概念一般在多项目共用一个域名的场景下使用，此作为演示
// 初始化 test分组
export const test = browserStorage({ separator: "~", group: "test" });
// 初始化 dog分组
export const dog = browserStorage({ separator: "~", group: "dog" });
```

```javascript
// 需要使用的文件
import { test } from "storage.js";

test.setItem("test", "test", 10 * 1000);
```