{"id":25718984,"url":"https://github.com/aiden-fe/compass-locker","last_synced_at":"2026-05-04T21:37:06.002Z","repository":{"id":47096270,"uuid":"515012648","full_name":"Aiden-FE/compass-locker","owner":"Aiden-FE","description":"数据存储管理工具,适用于Browser,Node,等多环境","archived":false,"fork":false,"pushed_at":"2024-07-02T11:42:08.000Z","size":411,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-15T18:19:02.092Z","etag":null,"topics":["browser","data-management","data-manager","data-storage","node","storage","storage-manager","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aiden-FE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-07-18T02:41:57.000Z","updated_at":"2024-07-02T11:40:29.000Z","dependencies_parsed_at":"2023-11-23T00:07:52.303Z","dependency_job_id":"e11d708c-c0e9-4cd5-a4b1-731910b6e728","html_url":"https://github.com/Aiden-FE/compass-locker","commit_stats":{"total_commits":26,"total_committers":5,"mean_commits":5.2,"dds":0.6923076923076923,"last_synced_commit":"89e46b9eaca027c6011b10d13b6a97326f8101fc"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aiden-FE%2Fcompass-locker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aiden-FE%2Fcompass-locker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aiden-FE%2Fcompass-locker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aiden-FE%2Fcompass-locker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aiden-FE","download_url":"https://codeload.github.com/Aiden-FE/compass-locker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240703207,"owners_count":19844050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","data-management","data-manager","data-storage","node","storage","storage-manager","typescript"],"created_at":"2025-02-25T16:27:34.706Z","updated_at":"2026-05-04T21:37:05.928Z","avatar_url":"https://github.com/Aiden-FE.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @compass-aiden/locker\n\u003e 数据存储工具\n\n## 特性\n\n* 适用于各平台的数据管理工具\n* 跨平台适用,可以运行在任何js环境内,仅需选择对应环境可执行的处理器即可\n* 易扩展,自由的定制适用于自身业务的存储工具\n* 无依赖的核心模块,Gzip后仅3.88kB\n* 可控制存储数据的失效时间,并支持数据读取后刷新失效时间\n* 支持限制存储数据的最大容量\n* 处理器实例支持自动降级\n\n## 快速上手\n\n### 安装依赖\n\n`npm install @compass-aiden/locker`\n\n### 安装处理器\n\n`npm install @compass-aiden/locker-[processor_name]-processor`\n\n可用的处理列表:\n\n* `@compass-aiden/locker-localstorage-processor` localStorage处理器,可运行在web环境中\n* `@compass-aiden/locker-sessionstorage-processor` sessionStorage处理器,可运行在web环境中\n* `@compass-aiden/locker-memory-processor` memory处理器,可运行在任何js环境中\n* `@compass-aiden/locker-indexdb-processor` IndexDB处理器,可运行在支持IndexDB的环境中\n\n### 使用\n\n```typescript\nimport {Locker} from \"@compass-aiden/locker\";\nimport LockerLocalStorageProcessor from \"@compass-aiden/locker-localstorage-processor\";\nimport LockerSessionStorageProcessor from \"@compass-aiden/locker-sessionstorage-processor\";\nimport LockerMemoryStorageProcessor from \"@compass-aiden/locker-memory-processor\";\nimport LockerIndexDBStorageProcessor from \"@compass-aiden/locker-indexdb-processor\";\n\n// 初始化实例\nconst localLocker = new Locker({\n  processor: new LockerLocalStorageProcessor(), // 实际处理器,可任意替换当前环境可用的处理器\n  lockerKey: 'user_id', // 可选, 唯一存储key,用来跟其他Locker实例区分或用来隔离用户数据\n  // 更多可配置项参考下方 初始化配置项\n});\n\n// 可以自动降级的实例\nconst localAutoLocker = new Locker({\n  processor: [\n    new LockerLocalStorageProcessor(),\n    new LockerSessionStorageProcessor(),\n    new LockerMemoryStorageProcessor(),\n  ], // 从左往右依次调用validate确认 setItem API可用性,决定当前实际采用的处理器\n  lockerKey: 'user_id2', // 可选, 唯一存储key,用来跟其他Locker实例区分或用来隔离用户数据\n  // 更多可配置项参考下方 初始化配置项\n});\n\n// 设置存储 option可选,对象结构. expires 超时时间, 单位ms, 0=永不超时,默认为0;autoReadRefresh 数据被读取后自动刷新超时时间,默认为false\nlocalLocker.setItem(key, value, [option]);\n\n// 读取存储 option.full 是否获取全部的存储结构化数据,默认为false,false则只取存储的value数据\nlocalLocker.getItem(key, [option]);\n\n// 移除存储\nlocalLocker.removeItem(key);\n\n// 清空存储\nlocalLocker.clear();\n\n// 页面卸载阶段前主动释放内部变量\nlocalLocker.destroy();\n```\n\n### 初始化配置项\n\n```typescript\nexport interface LockerSettings\u003cProcessor extends LockerProcessorAbstract\u003e {\n  /**\n   * @description 实际处理器\n   */\n  processor: Processor\n\n  /**\n   * @description 唯一存储key,用来跟其他Locker实例区分\n   */\n  lockerKey?: string\n\n  /**\n   * @description 垃圾回收间隔,0就是不主动清理,单位ms\n   * @default 15000\n   */\n  clearGarbageInterval?: number\n\n  /**\n   * @description 最大容量限制, 单位MB, 0就是不限制\n   * @default 0\n   */\n  maximum?: number\n\n  /**\n   * @description 调试模式\n   * @default false\n   */\n  debug?: boolean\n\n  /**\n   * @description 默认写入数据的超时设置,0就是不超时,单位ms\n   * @default 1000 * 10\n   */\n  defaultExpires?: number;\n\n  /**\n   * @description 数据被读取后是否自动刷新,从读取时间重新计算超时\n   * @default false\n   */\n  autoReadRefresh?: boolean;\n\n  /**\n   * @description 实例创建完成后的回调函数\n   */\n  created?: () =\u003e void\n}\n```\n\n### 定制自己的处理器\n\n继承基类 LockerProcessorAbstract\n\n```typescript\nimport { LockerProcessorAbstract } from '@compass-aiden/locker';\n\nexport default class LockerLocalStorageProcessor extends LockerProcessorAbstract {}\n```\n\n实现基类 LockerProcessorAbstract 上定义的方法,主要需实现的函数如下所示:\n\n```typescript\n/**\n * @description 实际处理locker的基类\n */\nexport class LockerProcessorAbstract {\n  /**\n   * @description API 可用性检查\n   * @param key\n   * @abstract\n   */\n  validate(key: 'setItem' | 'getItem' | 'clear' | 'removeItem'): boolean {}\n  \n  /**\n   * @description 设置存储\n   *\n   * 1. 检查插入新的数据项后是否会溢出最大存储限制\n   * 2. 如果会溢出限制,调用基类 clearDataBySize 方法,尝试清理指定空间\n   * 3. 如果清理的空间大小仍旧小于插入项大小停止写入并抛出异常\n   * 4. 不会溢出限制则执行写入\n   * 5. 写入失败抛出异常\n   *\n   * @param item\n   * @abstract\n   */\n  async set(item: OriginLockerItem): Promise\u003cvoid\u003e {}\n  \n  /**\n   * @description 获取存储\n   * @param key\n   * @abstract\n   */\n  async get(key: string): Promise\u003cOriginLockerItem | null\u003e {}\n  \n  /**\n   * @description 需要实现移除存储功能\n   * @param key\n   * @abstract\n   */\n  async remove(key: string): Promise\u003cvoid\u003e {}\n  \n  /**\n   * @description 获取所有数据,垃圾回收需要扫描数据是否过期, 如果扫描开销较大建议根据实际情况返回计算属性或缓存结果集\n   * @abstract\n   */\n  async getAllData(): Promise\u003cLockerItem[]\u003e {}\n}\n\n```\n\n## Roadmap\n\n- [x] 增加 localStorage 存储处理器\n- [x] 增加 sessionStorage 存储处理器\n- [x] 增加 memory 存储处理器\n- [x] 增加 IndexDB 存储处理器\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiden-fe%2Fcompass-locker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiden-fe%2Fcompass-locker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiden-fe%2Fcompass-locker/lists"}