npm package: @mznjs/core
Description: Collect some useful function libraries
Author: supbose
Latest version: 0.0.1

## 📦 `@mznjs/core` 使用文档

### ✅ 模块概览

该模块提供了多个功能子模块：

- [cache()](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\store\index.ts#L49-L55) / [config()](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\store\index.ts#L13-L21)：缓存存储管理
- [crypto](file://d:\WorkspaceProject\cnb\MznjsCore\node_modules\uncrypto)：加密解密工具（SHA256、MD5、AES 加密/解密）
- [time](file://d:\WorkspaceProject\cnb\MznjsCore\node_modules\onetime)：时间处理工具（格式化、过期判断等）
- [CacheManager](file://d:\WorkspaceProject\cnb\MznjsCore\packages\helper\src\storage\bin\private.ts#L15-L47)：缓存过期管理辅助函数
- [logger](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\utils\log.ts#L9-L33) / `console` / `log`：日志输出实例（consola）

---

## 🔧 安装方式

```bash
npm install @mznjs/core
# 或者
pnpm add @mznjs/core
```

> 要求 Node.js ≥ 18.0

---

## 🧩 导出接口一览

| 接口名 | 类型 | 说明 |
|--------|------|------|
| [config(config?: Partial<UnstorageOptions>)](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\store\index.ts#L13-L21) | function | 初始化全局缓存配置 |
| [cache(): ExtendedUnstorage](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\store\index.ts#L49-L55) | function | 创建缓存实例 |
| `crypto.encrypt(value: string, key?: string): string` | function | AES 加密 |
| `crypto.decrypt(value: string, key?: string): string` | function | AES 解密 |
| `crypto.md5(value: string): string` | function | MD5 哈希 |
| `crypto.sha256(value: string): string` | function | SHA256 哈希 |
| `time.timeFormat(timestamp?: number, fmt?: string): string` | function | 时间戳格式化 |
| `time.isExpired(expires?: expires): boolean` | function | 判断是否已过期 |
| `time.formatDeadTime(expires?: expires): resultOptions` | function | 格式化过期时间 |
| [logger](file://d:\WorkspaceProject\cnb\MznjsCore\packages\core\src\utils\log.ts#L9-L33) | ConsolaInstance | 日志打印器 |

---

## 🧪 示例代码

### 1. 缓存模块使用

#### 初始化配置并创建缓存实例

```ts
import { config, cache } from '@mznjs/core'

// 配置缓存选项
config({
  timeSuffix: '_deadtime',
  encryptKeys: ['token', 'userinfo'],
  useItemRaw: false,
  isEncrypt: true // 启用加密
})

const storage = cache()

// 设置带过期时间的缓存
await storage.set('username', 'john_doe', { ttl: 60 }) // 60秒后过期

// 获取缓存
const user = await storage.get<string>('username')
console.log(user) // 输出: john_doe

// 删除缓存
await storage.remove('username')

// 清空所有缓存
await storage.clear()
```

#### 获取所有缓存项 & 缓存信息

```ts
await storage.set('key1', 'value1')
await storage.set('key2', 'value2')

const allItems = await storage.all()
console.log(allItems)
// 输出类似: [ { key: 'key1', value: 'value1' }, { key: 'key2', value: 'value2' } ]

const info = await storage.info()
console.log(info)
// 输出类似: { size: 2 }
```

---

### 2. 加密模块使用

#### AES 加密与解密

```ts
import { crypto } from '@mznjs/core'

const secretKey = 'my-secret-key'
const plainText = 'Sensitive data'

const encrypted = crypto.encrypt(plainText, secretKey)
console.log('Encrypted:', encrypted)

const decrypted = crypto.decrypt(encrypted, secretKey)
console.log('Decrypted:', decrypted)
// 输出: Sensitive data
```

#### MD5 和 SHA256 哈希

```ts
const input = 'hello world'

console.log(crypto.md5(input))        // 输出 MD5 哈希值
console.log(crypto.sha256(input))     // 输出 SHA256 哈希值
```

---

### 3. 时间处理模块使用

#### 时间戳格式化

```ts
import { time } from '@mznjs/core'

const timestamp = Date.now()
console.log(time.timeFormat(timestamp))         // 输出默认格式: "2024-07-10 14:23:45"
console.log(time.timeFormat(timestamp, 'yyyy年mm月dd日')) // 输出: "2024年07月10日"
```

#### 判断是否过期

```ts
const expireTime = time.formatDeadTime('1h') // 1小时后过期
console.log(expireTime)
// 输出: { msg: '', data: { ttl: 3600, expireTime: 1720612800 } }

const isExpired = time.isExpired(expireTime.data.expireTime!)
console.log(isExpired ? '已过期' : '未过期')
```

#### 自动识别时间戳单位

```ts
console.log(time.guessTimestampUnit(1720609200))      // 输出: seconds
console.log(time.guessTimestampUnit(1720609200000))   // 输出: milliseconds
```

---

### 4. 日志模块使用

```ts
import { logger, log, console } from '@mznjs/core'

logger.info('This is an info message')
logger.warn('This is a warning message')
logger.error('This is an error message')

// 等价写法
log.info('Another info message')
console.warn('Another warn message')
```

---

## ⚙️ 高级配置说明

### `UnstorageOptions` 配置项详解

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `driver` | Driver | memory | 存储驱动（支持 memory、localStorage 等） |
| `timeSuffix` | string | `_deadtime` | 过期时间键名后缀 |
| `encryptKeys` | string[] | [] | 需要强制加密的键列表 |
| `useItemRaw` | boolean | false | 是否直接操作原始数据 |
| `isEncrypt` | boolean | false | 是否启用整体加密 |

#### 示例：指定 localStorage 驱动

```ts
config({
  driver: localStorageDriver, // 需要自行引入或实现
  timeSuffix: '_expire',
  encryptKeys: ['token']
})
```

---

## 📌 注意事项

- 所有缓存操作返回 `Promise`，请使用 `await`。
- `encryptKeys` 表示即使 `isEncrypt=false`，这些字段也会被加密。
- `set(key, value, ttl)` 中 `ttl` 单位为 **秒**，非毫秒。
- `formatDeadTime()` 支持字符串格式如 `'1h'`, `'2d'` 等。

---

## 📚 参考文档

- [unstorage 文档](https://unstorage.unjs.io/)
- [consola 日志库](https://github.com/unjs/consola)
- [CryptoJS 文档](https://www.npmjs.com/package/crypto-js)
- [dayjs 时间库](https://day.js.org/)
- [radash 工具库](https://radash-docs.vercel.app/)