npm package: @mznjs/unstorage
Description: Unstorage adapter for @mznjs/library
Author: supbose
Latest version: 3.1.0

为了帮助用户更好地理解和使用 `@mznjs/unstorage` 库，我将编写一份详细的使用文档。以下是一份示例文档：

---

# @mznjs/unstorage 使用文档

## 概述

`@mznjs/unstorage` 是一个用于存储管理的适配器库，基于 `unstorage` 库扩展了加密功能和自定义存储方法。该库适用于 Node.js 和浏览器环境。

## 安装

使用 `pnpm` 安装 `@mznjs/unstorage`：

```bash
pnpm add @mznjs/unstorage
```

或者使用 `npm` 安装：

```bash
npm install @mznjs/unstorage
```

## 基本用法

### 导入库

```typescript
import { cache } from '@mznjs/unstorage'
```

### 创建存储实例

```typescript
const storage = cache('memory', {
  timeSuffix: '_deadtime',
  unencryptKeys: ['token', 'refreshToken'],
  useItemRaw: false,
})
```

### 存储操作

#### 设置存储项

```typescript
await storage.custom.set('user', { name: 'Alice', token: 'abc123' }, { ttl: '1h' })
```

#### 获取存储项

```typescript
const user = await storage.custom.get('user')
console.log(user) // { name: 'Alice', token: 'abc123' }
```

#### 检查存储项是否过期

```typescript
const isExpired = await storage.custom.isExpired('user')
console.log(isExpired) // false
```

#### 删除存储项

```typescript
await storage.custom.remove('user')
```

#### 清除所有存储项

```typescript
await storage.custom.clearAll()
```

#### 获取所有存储键

```typescript
const keys = await storage.custom.info()
console.log(keys) // []
```

## 配置选项

### `timeSuffix`

指定存储项过期时间的后缀，默认为 `_deadtime`。

```typescript
const storage = cache('memory', {
  timeSuffix: '_expire',
})
```

### `unencryptKeys`

指定不需要加密的键列表。默认为 `['token', 'refreshToken', 'refreshToken_deadtime', 'token_deadtime']`。

```typescript
const storage = cache('memory', {
  unencryptKeys: ['token', 'refreshToken'],
})
```

### `useItemRaw`

指定是否使用 `setItemRaw` 和 `getItemRaw` 方法进行存储和获取，默认为 `false`。

```typescript
const storage = cache('memory', {
  useItemRaw: true,
})
```

## 自定义驱动

### 使用内置驱动

`@mznjs/unstorage` 支持多种内置驱动，包括 `memory`、`indexedDb` 等。

```typescript
const storage = cache('indexedDb')
```

### 使用官方驱动
- 可以使用官方提供的驱动，例如 `localStorage`、`sessionStorage`、`redis` 等。 [驱动列表及使用说明](https://unstorage.unjs.io/drivers)
```typescript
import { cache } from '@mznjs/unstorage'
import localStorageDriver from "unstorage/drivers/localstorage";// 引入官方驱动

const storage = cache(localStorageDriver({ base: "app:" })) // 使用官方驱动 
or
const storage = cache(localStorageDriver) // 使用官方驱动

用法一致，不再重复
```

## 示例代码

以下是一个完整的示例代码，展示了如何使用 `@mznjs/unstorage` 进行存储操作。

- 官方以下代码：更详细的官方示例代码：[https://github.com/unjs/unstorage/blob/main/examples/index.ts](https://github.com/unjs/unstorage/blob/main/examples/index.ts)
```typescript
import { cache } from '@mznjs/unstorage'

// 创建存储实例
const storage = cache('memory')

await storage.set('user', { name: 'Alice', token: 'abc123' })

// 获取存储项
const user = await storage.get('user')
console.log(user) // { name: 'Alice', token: 'abc123' }



```

- 扩展示例代码
```typescript
import { cache } from '@mznjs/unstorage'

// 创建存储实例
const storage = cache('memory', {
  timeSuffix: '_expire',
  unencryptKeys: ['token', 'refreshToken'],
  useItemRaw: false,
})

// 设置存储项
await storage.custom.set('user', { name: 'Alice', token: 'abc123' }, { ttl: '1h' })

// 获取存储项
const user = await storage.custom.get('user')
console.log(user) // { name: 'Alice', token: 'abc123' }

// 检查存储项是否过期
const isExpired = await storage.custom.isExpired('user')
console.log(isExpired) // false

// 删除存储项
await storage.custom.remove('user')

// 清除所有存储项
await storage.custom.clearAll()

// 获取所有存储键
const keys = await storage.custom.info()
console.log(keys) // []
```

## API 参考

### `cache(input: Storage | Driver | string | (() => Driver), opts?: UnstorageOptions): CustomStorage`

创建自定义存储实例。

- **参数**:
  - `input`: 存储驱动、驱动名称或驱动创建函数。
  - `opts`: 配置选项，可选。
- **返回**: 自定义存储实例。

### `CustomStorage`

自定义存储实例接口，继承自 `Storage` 并添加了 `custom` 对象。

- **属性**:
  - `custom`: 自定义存储方法对象。
    - `get(key: string): Promise<any>`: 获取存储项。
    - `info(): Promise<string[]>`: 获取所有存储键。
    - `set(key: string, value: StorageValue, expires?: number | string | { ttl: number | string }): Promise<void>`: 设置存储项。
    - `isExpired(key: string): Promise<boolean>`: 检查键是否过期。
    - `remove(key: string): Promise<void>`: 删除存储项。
    - `clearAll(): Promise<void>`: 清除所有存储项。

### `UnstorageOptions`

配置选项接口。

- **属性**:
  - `timeSuffix`: 存储项过期时间的后缀，默认为 `_deadtime`。
  - `unencryptKeys`: 不需要加密的键列表。
  - `useItemRaw`: 是否使用 `setItemRaw` 和 `getItemRaw` 方法进行存储和获取，默认为 `false`。

## 常见问题

### 1. 如何处理存储驱动不支持的情况？

在 Node.js 环境中，某些驱动（如 `local`、`session`、`indexedDb`）不被支持，库会自动使用 `memory` 驱动并记录日志。

### 2. 如何加密和解密存储项？

库会自动对非指定的键进行加密和解密。可以通过 `unencryptKeys` 配置选项指定不需要加密的键。

### 3. 如何设置过期时间？

可以通过 `set` 方法的 `expires` 参数设置过期时间，支持数字（秒）、字符串（如 `'1h'`）和对象（如 `{ ttl: '1h' }`）格式。


## 许可证

本项目采用 [MIT 许可证]。

---

通过这份详细的使用文档，用户可以快速上手并使用 `@mznjs/unstorage` 库进行存储管理。