npm package: @mznjs/store
Description: Store adapter for unstorage
Author: supbose
Latest version: 3.1.0

以下是对 `@mznjs/store` 模块的完整使用文档，**并重点说明了 [custom](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\interface.ts#L3-L23) 接口的使用方式和示例**。

---

## 📦 `@mznjs/store` 使用文档

### 1. 安装

```bash
pnpm add @mznjs/store
```

---

### 2. 初始化存储配置

你可以通过调用 [config()](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\index.ts#L15-L23) 方法来初始化存储模块的配置。支持的驱动包括：

- [memory](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\drives.ts#L17-L21)（内存）
- [redis](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\drives.ts#L13-L15)
- [mongodb](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\drives.ts#L29-L31)

```ts
import { config } from '@mznjs/store'

// 默认使用 memory 驱动
config()

// 使用 Redis 示例
config({
  driver: 'redis',
  driveOpts: {
    host: 'localhost',
    port: 6379,
  },
})

// 使用 MongoDB 示例
config({
  driver: 'mongodb',
  driveOpts: {
    uri: 'mongodb://localhost:27017',
    dbName: 'mydb',
  },
})
```

> ⚠️ 注意：只能初始化一次，重复调用会输出警告信息 `Storage already initialized`。

---

### 3. 创建缓存实例并操作数据

使用 `cache()` 方法可以创建一个缓存实例，用于后续的缓存操作。

```ts
import { cache } from '@mznjs/store'

const storage = cache()

// 设置缓存
await storage.setItem('key', 'value')

// 获取缓存
const value = await storage.getItem('key')
console.log(value) // 输出: 'value'

// 删除缓存
await storage.removeItem('key')
```

---

### 4. custom 自定义接口详解

`custom` 是 `CustomStorage` 接口中扩展的一组自定义方法集合，允许你执行更细粒度的操作或特定于驱动的功能。

#### 接口定义如下：

```ts
custom: {
  get: (key: string) => Promise<any>
  info: () => Promise<string[]>
  all: () => Promise<string[]>
  set: (key: string, value: StorageValue, expires?: number | string | { ttl: number | string }) => Promise<void>
  remove: (key: string) => Promise<void>
  del: (key: string) => Promise<void>
  clear: () => Promise<void>
}
```

#### 各方法说明：

| 方法名 | 参数 | 返回值 | 描述 |
|-------|------|--------|------|
| `get(key)` | `key`: 键名 | `Promise<any>` | 获取指定键的值 |
| `info()` | 无 | `Promise<string[]>` | 获取当前存储的元信息（如键列表） |
| `all()` | 无 | `Promise<string[]>` | 获取所有键名列表 |
| `set(key, value, expires?)` | `key`, `value`, `expires`（可选过期时间） | `Promise<void>` | 设置键值对，并可指定过期时间 |
| `remove(key)` / `del(key)` | `key` | `Promise<void>` | 删除指定键 |
| `clear()` | 无 | `Promise<void>` | 清空所有缓存 |

---

### 5. 使用 `custom` 接口的完整示例

```ts
import { cache } from '@mznjs/store'

const storage = cache()

// 使用 custom.set 设置带过期时间的缓存项
await storage.custom.set('user:123', { name: 'Alice' }, { ttl: 3600 }) // 过期时间为 1 小时

// 使用 custom.get 获取缓存项
const user = await storage.custom.get('user:123')
console.log(user) // 输出: { name: 'Alice' }

// 获取所有键名
const keys = await storage.custom.all()
console.log(keys) // 输出: ['user:123']

// 删除指定键
await storage.custom.del('user:123')

// 清空所有缓存
await storage.custom.clear()
```

---

### 6. 支持的驱动类型

| 驱动名称 | 描述 |
|---------|------|
| `memory` | 内存缓存驱动，默认使用 |
| `redis`  | Redis 缓存驱动，需要提供 `host` 和 `port` 等参数 |
| `mongodb` | MongoDB 缓存驱动，需要提供 `uri` 和 `dbName` 等参数 |

---

### 7. 默认配置

默认配置保存在 `DEFAULT_CONFIG` 中，包含以下内容：

```ts
{
  driver: 'memory', // 默认使用内存驱动
}
```

可以通过传入自定义的 [UnstorageOptions](file://d:\WorkspaceProject\cnb\mznjs-packages-utility\packages\store\src\interface.ts#L18-L30) 覆盖默认值。

---

### 8. 接口定义

- **`UnstorageOptions`** - 配置选项接口
  - `driver`: 指定使用的驱动名称，可选值为 `'memory'`、`'redis'`、`'mongodb'`
  - `driveOpts`: 驱动的额外配置项，具体结构取决于所选驱动
  - `isEncrypt`: 是否启用加密，默认为 `false`
  - `encryptKeys`: 需要加密的 key 列表（可选）

- **`CacheInstance`** - 缓存实例接口（继承自 `CustomStorage`）
  - 提供标准的缓存操作方法及 `custom` 扩展方法

---

### ✅ 总结

1. 先调用 `config()` 初始化配置。
2. 然后调用 `cache()` 获取缓存实例。
3. 使用 `custom` 接口进行更灵活的缓存操作，如 `set`, `get`, `del`, `clear` 等。

---

### 🧪 示例项目结构（推荐）

```ts
// index.ts
import { config, cache } from '@mznjs/store'

config({
  driver: 'redis',
  driveOpts: {
    host: 'redis-host',
    port: 6379,
  },
})

const storage = cache()

async function run() {
  await storage.custom.set('user:123', { name: 'Bob' }, { ttl: 60 })
  const user = await storage.custom.get('user:123')
  console.log(user) // { name: 'Bob' }

  const keys = await storage.custom.all()
  console.log(keys) // [ 'user:123' ]

  await storage.custom.del('user:123')
}

run()
```