@mznjs/store v3.1.0

以下是对 @mznjs/store 模块的完整使用文档，并重点说明了 custom 接口的使用方式和示例。

📦 @mznjs/store 使用文档

1. 安装

pnpm add @mznjs/store

2. 初始化存储配置

你可以通过调用 config() 方法来初始化存储模块的配置。支持的驱动包括：

• memory（内存）
• redis
• mongodb

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() 方法可以创建一个缓存实例，用于后续的缓存操作。

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 接口中扩展的一组自定义方法集合，允许你执行更细粒度的操作或特定于驱动的功能。

接口定义如下：

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>
}

各方法说明：

5. 使用 custom 接口的完整示例

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. 支持的驱动类型

7. 默认配置

默认配置保存在 DEFAULT_CONFIG 中，包含以下内容：

{
  driver: 'memory', // 默认使用内存驱动
}

可以通过传入自定义的 UnstorageOptions 覆盖默认值。

8. 接口定义

• UnstorageOptions - 配置选项接口

  • driver: 指定使用的驱动名称，可选值为 'memory'、'redis'、'mongodb'
  • driveOpts: 驱动的额外配置项，具体结构取决于所选驱动
  • isEncrypt: 是否启用加密，默认为 false
  • encryptKeys: 需要加密的 key 列表（可选）

• CacheInstance - 缓存实例接口（继承自 CustomStorage）

  • 提供标准的缓存操作方法及 custom 扩展方法

✅ 总结

1. 先调用 config() 初始化配置。
2. 然后调用 cache() 获取缓存实例。
3. 使用 custom 接口进行更灵活的缓存操作，如 set, get, del, clear 等。

🧪 示例项目结构（推荐）

// 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()