@sparta-utils/cache-util/README.md

统一的浏览器缓存工具类，支持 localStorage、sessionStorage、memory、cookie、indexedDB，内置 SM2 加密与过期机制。A unified browser caching utility supporting localStorage, sessionStorage, memory, cookie, indexedDB with SM2 encryption and expiration.

# 📦 @sparta-utils/cache-util - 浏览器缓存工具类（含SM2加密、过期支持）

`@sparta-utils/cache-util` 是一个统一的浏览器缓存工具类，支持 `localStorage`、`sessionStorage`、`memoryStorage`、`cookieStorage` 及 `indexedDB` 五种缓存方式。  
支持缓存加密（SM2 国密算法）、缓存过期控制，且易于扩展与维护，适用于多种前端复杂缓存场景。

---

## 📥 安装

```bash
# 使用 npm
npm install @sparta-utils/cache-util

# 使用 yarn
yarn add @sparta-utils/cache-util

# 使用 pnpm
pnpm add @sparta-utils/cache-util
```

## ⚙️ 参数说明（统一传入参数）
| 参数名          | 类型        | 是否必填              | 默认值     | 说明                      |
| ------------ | --------- | ----------------- | ------- | ----------------------- |
| `key`        | `string`  | 是                 | -       | 缓存键                     |
| `value`      | `any`     | 否（仅 get/remove 时） | -       | 缓存值                     |
| `options`    | `object`  | 否                 | `{}`    | 设置项，包含以下可选字段            |
| └─ `expire`  | `number`  | 否                 | `null`  | 过期时间（单位：毫秒，null 表示永久有效） |
| └─ `encrypt` | `boolean` | 否                 | `false` | 是否启用 SM2 加密             |

## 🧩 使用示例
```ts
import {localStorage,sessionStorage,memoryStorage,cookieStorage,indexedDB} from '@sparta-utils/cache-util';

// localStorage 示例
localStorage.set('token', '123456', { expire: 10000, encrypt: true });
const token = localStorage.get('token', { encrypt: true });
localStorage.remove('token');

// sessionStorage 示例
sessionStorage.set('username', { name: '张珊', id: 1 }, { encrypt: true })
const name = sessionStorage.get('username', { encrypt: true })
console.log('sessionStorage', name) // 输出: 张三

// memoryStorage 示例（内存级别，刷新页面即失效）
memoryStorage.set('temp', { id: 1 }, { expire: 5000 });
const temp = memoryStorage.get('temp',{ encrypt: true });

// cookieStorage 示例
cookieStorage.set('lang', 'zh-CN', { expire: 86400000, encrypt: true })
const lang = cookieStorage.get('lang', { encrypt: true })
console.log('当前语言:', lang) // 输出: 当前语言: zh-CN

// indexedDB 示例（支持大数据存储）
const cache = new indexedDB('myDB', 'myStore', 2)
await cache.set('key1', { foo: 'bar' }, { expire: 60000, encrypt: true })
const val = await cache.get('key1', { encrypt: true })
console.log(val)

```

## 🔐 加密说明（SM2）
本工具内置了 SM2 加密算法（使用国密标准），加密密钥在首次使用时自动生成并保存到 localStorage，无需外部传入。你只需要传入 encrypt: true 即可自动加密/解密。

加密数据格式统一为字符串，内部自动 JSON 序列化和反序列化。

加密后的数据结构格式如下：
```ts
{
  value: "加密后的密文",
  __encrypt__: true,
  __expire__: 过期时间戳（可选）
}
```