为了帮助用户更好地理解和使用 @mznjs/unstorage 库，我将编写一份详细的使用文档。以下是一份示例文档：

@mznjs/unstorage 使用文档

概述

@mznjs/unstorage 是一个用于存储管理的适配器库，基于 unstorage 库扩展了加密功能和自定义存储方法。该库适用于 Node.js 和浏览器环境。

安装

使用 pnpm 安装 @mznjs/unstorage：

pnpm add @mznjs/unstorage

或者使用 npm 安装：

npm install @mznjs/unstorage

基本用法

导入库

import { cache } from '@mznjs/unstorage'

创建存储实例

const storage = cache('memory', {
  timeSuffix: '_deadtime',
  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) // []

配置选项

timeSuffix

指定存储项过期时间的后缀，默认为 _deadtime。

const storage = cache('memory', {
  timeSuffix: '_expire',
})

unencryptKeys

指定不需要加密的键列表。默认为 ['token', 'refreshToken', 'refreshToken_deadtime', 'token_deadtime']。

const storage = cache('memory', {
  unencryptKeys: ['token', 'refreshToken'],
})

useItemRaw

指定是否使用 setItemRaw 和 getItemRaw 方法进行存储和获取，默认为 false。

const storage = cache('memory', {
  useItemRaw: true,
})

自定义驱动

使用内置驱动

@mznjs/unstorage 支持多种内置驱动，包括 memory、indexedDb 等。

const storage = cache('indexedDb')

使用官方驱动

• 可以使用官方提供的驱动，例如 localStorage、sessionStorage、redis 等。 驱动列表及使用说明

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

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

• 扩展示例代码

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 库进行存储管理。