https://github.com/aiden-fe/compass-locker

数据存储管理工具,适用于Browser,Node,等多环境
https://github.com/aiden-fe/compass-locker

browser data-management data-manager data-storage node storage storage-manager typescript

Last synced: 11 months ago
JSON representation

数据存储管理工具,适用于Browser,Node,等多环境

• Host: GitHub
• URL: https://github.com/aiden-fe/compass-locker
• Owner: Aiden-FE
• License: mit
• Created: 2022-07-18T02:41:57.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-07-02T11:42:08.000Z (over 1 year ago)
• Last Synced: 2025-02-15T18:19:02.092Z (11 months ago)
• Topics: browser, data-management, data-manager, data-storage, node, storage, storage-manager, typescript
• Language: TypeScript
• Homepage:
• Size: 401 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# @compass-aiden/locker

> 数据存储工具

## 特性

* 适用于各平台的数据管理工具

* 跨平台适用,可以运行在任何js环境内,仅需选择对应环境可执行的处理器即可

* 易扩展,自由的定制适用于自身业务的存储工具

* 无依赖的核心模块,Gzip后仅3.88kB

* 可控制存储数据的失效时间,并支持数据读取后刷新失效时间

* 支持限制存储数据的最大容量

* 处理器实例支持自动降级

## 快速上手

### 安装依赖

`npm install @compass-aiden/locker`

### 安装处理器

`npm install @compass-aiden/locker-[processor_name]-processor`

可用的处理列表:

* `@compass-aiden/locker-localstorage-processor` localStorage处理器,可运行在web环境中

* `@compass-aiden/locker-sessionstorage-processor` sessionStorage处理器,可运行在web环境中

* `@compass-aiden/locker-memory-processor` memory处理器,可运行在任何js环境中

* `@compass-aiden/locker-indexdb-processor` IndexDB处理器,可运行在支持IndexDB的环境中

### 使用

```typescript

import {Locker} from "@compass-aiden/locker";

import LockerLocalStorageProcessor from "@compass-aiden/locker-localstorage-processor";

import LockerSessionStorageProcessor from "@compass-aiden/locker-sessionstorage-processor";

import LockerMemoryStorageProcessor from "@compass-aiden/locker-memory-processor";

import LockerIndexDBStorageProcessor from "@compass-aiden/locker-indexdb-processor";

// 初始化实例

const localLocker = new Locker({

  processor: new LockerLocalStorageProcessor(), // 实际处理器,可任意替换当前环境可用的处理器

  lockerKey: 'user_id', // 可选, 唯一存储key,用来跟其他Locker实例区分或用来隔离用户数据

  // 更多可配置项参考下方 初始化配置项

});

// 可以自动降级的实例

const localAutoLocker = new Locker({

  processor: [

    new LockerLocalStorageProcessor(),

    new LockerSessionStorageProcessor(),

    new LockerMemoryStorageProcessor(),

  ], // 从左往右依次调用validate确认 setItem API可用性,决定当前实际采用的处理器

  lockerKey: 'user_id2', // 可选, 唯一存储key,用来跟其他Locker实例区分或用来隔离用户数据

  // 更多可配置项参考下方 初始化配置项

});

// 设置存储 option可选,对象结构. expires 超时时间, 单位ms, 0=永不超时,默认为0;autoReadRefresh 数据被读取后自动刷新超时时间,默认为false

localLocker.setItem(key, value, [option]);

// 读取存储 option.full 是否获取全部的存储结构化数据,默认为false,false则只取存储的value数据

localLocker.getItem(key, [option]);

// 移除存储

localLocker.removeItem(key);

// 清空存储

localLocker.clear();

// 页面卸载阶段前主动释放内部变量

localLocker.destroy();

```

### 初始化配置项

```typescript

export interface LockerSettings {

  /**

   * @description 实际处理器

   */

  processor: Processor

  /**

   * @description 唯一存储key,用来跟其他Locker实例区分

   */

  lockerKey?: string

  /**

   * @description 垃圾回收间隔,0就是不主动清理,单位ms

   * @default 15000

   */

  clearGarbageInterval?: number

  /**

   * @description 最大容量限制, 单位MB, 0就是不限制

   * @default 0

   */

  maximum?: number

  /**

   * @description 调试模式

   * @default false

   */

  debug?: boolean

  /**

   * @description 默认写入数据的超时设置,0就是不超时,单位ms

   * @default 1000 * 10

   */

  defaultExpires?: number;

  /**

   * @description 数据被读取后是否自动刷新,从读取时间重新计算超时

   * @default false

   */

  autoReadRefresh?: boolean;

  /**

   * @description 实例创建完成后的回调函数

   */

  created?: () => void

}

```

### 定制自己的处理器

继承基类 LockerProcessorAbstract

```typescript

import { LockerProcessorAbstract } from '@compass-aiden/locker';

export default class LockerLocalStorageProcessor extends LockerProcessorAbstract {}

```

实现基类 LockerProcessorAbstract 上定义的方法,主要需实现的函数如下所示:

```typescript

/**

 * @description 实际处理locker的基类

 */

export class LockerProcessorAbstract {

  /**

   * @description API 可用性检查

   * @param key

   * @abstract

   */

  validate(key: 'setItem' | 'getItem' | 'clear' | 'removeItem'): boolean {}

  

  /**

   * @description 设置存储

   *

   * 1. 检查插入新的数据项后是否会溢出最大存储限制

   * 2. 如果会溢出限制,调用基类 clearDataBySize 方法,尝试清理指定空间

   * 3. 如果清理的空间大小仍旧小于插入项大小停止写入并抛出异常

   * 4. 不会溢出限制则执行写入

   * 5. 写入失败抛出异常

   *

   * @param item

   * @abstract

   */

  async set(item: OriginLockerItem): Promise {}

  

  /**

   * @description 获取存储

   * @param key

   * @abstract

   */

  async get(key: string): Promise {}

  

  /**

   * @description 需要实现移除存储功能

   * @param key

   * @abstract

   */

  async remove(key: string): Promise {}

  

  /**

   * @description 获取所有数据,垃圾回收需要扫描数据是否过期, 如果扫描开销较大建议根据实际情况返回计算属性或缓存结果集

   * @abstract

   */

  async getAllData(): Promise {}

}

```

## Roadmap

- [x] 增加 localStorage 存储处理器

- [x] 增加 sessionStorage 存储处理器

- [x] 增加 memory 存储处理器

- [x] 增加 IndexDB 存储处理器