fezbox

FezBox

一个包含常用工具函数的 JavaScript/TypeScript 库，按功能模块分类，便于按需引入。

✨ 特性

• 📦 模块化设计 - 支持按需引入，减少包体积
• 🔒 完整 TypeScript 支持 - 提供准确的类型定义
• 🧪 高测试覆盖率 - 102个测试用例覆盖所有核心功能
• 🎯 轻量级 - 仅依赖必要的 peer dependencies
• 📚 详细文档 - 包含完整的使用示例和 API 说明
• 🚀 高性能 - 优化的算法和实现
• 🔧 易维护 - 清晰的代码结构和完整的测试

安装

# 使用 npm
npm install fezbox

# 使用 pnpm
pnpm add fezbox

# 使用 yarn
yarn add fezbox

🚀 快速开始

完整引入

import { deepClone, formatFileSize, relativeTime, outsideClick, getQueryObject } from 'fezbox'

// 深拷贝对象
const original = { a: 1, b: { c: 2 } }
const cloned = deepClone(original)

// 格式化文件大小
const size = formatFileSize(1048576) // "1.00 Mb"

// 相对时间格式化
const time = relativeTime(new Date(Date.now() - 3600000)) // "1小时前"

// 获取所有查询参数
const params = getQueryObject('https://example.com?id=123&name=test')
console.log(params) // { id: '123', name: 'test' }

// 外部点击监听
const element = document.getElementById('myElement')
const unlisten = outsideClick.listen({
  domRefs: element,
  handler: () => console.log('点击了外部区域')
})

按需引入（推荐）

// 只引入需要的模块，减少包体积
import { deepClone } from 'fezbox/data'
import { formatFileSize, fetchFile, uploadFileByUrl } from 'fezbox/file'
import { relativeTime } from 'fezbox/time'
import { getQueryParam, getQueryObject } from 'fezbox/url'
import { decryptAES } from 'fezbox/crypto'
import { outsideClick } from 'fezbox/dom'
import { QRCodeScriptLoader } from 'fezbox/qr'
import { getLocalStorage, setCookie, getSessionStorage } from 'fezbox/storage'

📚 API 文档

📊 Data 模块

深拷贝函数，基于 JSON 序列化实现，支持对象和数组的深度复制。

import { deepClone } from 'fezbox/data'

const obj = { a: 1, b: { c: 2 } }
const cloned = deepClone(obj)

📁 File 模块

文件操作相关工具，包括文件大小格式化、文件获取和上传。

import { formatFileSize, fetchFile, uploadFileByUrl } from 'fezbox/file'

// 格式化文件大小
formatFileSize(1048576) // "1.00 Mb"

// 获取文件
const file = await fetchFile('https://example.com/image.jpg', 'image.jpg')

// 上传文件
const uploadedUrl = await uploadFileByUrl(
  'https://example.com/image.jpg',
  async (formData) => {
    const response = await fetch('/upload', { method: 'POST', body: formData })
    return await response.json()
  }
)

⏰ Time 模块

相对时间格式化，支持多种输入格式。

import { relativeTime } from 'fezbox/time'

relativeTime(new Date()) // "刚刚"
relativeTime(new Date(Date.now() - 3600000)) // "1小时前"
relativeTime(new Date(Date.now() - 86400000)) // "1天前"

🔗 URL 模块

URL 查询参数处理工具。

import { getQueryObject, getQueryParam } from 'fezbox/url'

// 获取所有查询参数
const params = getQueryObject('https://example.com?id=123&name=test')
// 返回: { id: '123', name: 'test' }

// 获取单个参数
const id = getQueryParam('id', 'https://example.com?id=123&name=test') // "123"

🔐 Crypto 模块

AES 解密功能。

import { decryptAES } from 'fezbox/crypto'

const decrypted = decryptAES('encryptedData', 'my-secret-key')

🎯 DOM 模块

DOM 操作相关工具。

import { outsideClick } from 'fezbox/dom'

const element = document.getElementById('dropdown')
const unlisten = outsideClick.listen({
  domRefs: element,
  handler: () => {
    console.log('点击了下拉菜单外部')
    element.classList.remove('open')
  }
})

🔲 QR Code 模块

二维码生成与转换工具，支持自动依赖管理。

特性：

• 🚀 零配置启动 - 自动检测并加载缺失的依赖
• 📊 渐进式功能 - 根据可用依赖启用不同功能
• 🗜️ 智能压缩 - 自动选择最优的数据压缩方案

import { QRCodeScriptLoader } from 'fezbox/qr'

// 零配置使用，依赖会自动加载
const loader = new QRCodeScriptLoader({
  sandbox: true,        // 沙箱模式（推荐）
  autoCompress: true,   // 自动压缩
  debug: true          // 调试模式
})

// 生成二维码数据
const result = await loader.generateQRCodeData('Hello World')
if (result.success) {
  console.log('生成成功:', result.data)
} else {
  console.log('生成失败:', result.error)
}

// 检查功能可用性
console.log('生成功能:', loader.isFeatureAvailable('generate'))
console.log('解析功能:', loader.isFeatureAvailable('parse'))
console.log('压缩功能:', loader.isFeatureAvailable('compress'))

// 从图片解析二维码
const code = await loader.parseQRCodeFromImageData(imageData)

💾 Storage 模块

提供统一的本地存储解决方案，包括 localStorage、sessionStorage 和 Cookie 的操作。

特性：

• 统一的 API 设计
• 自动 JSON 序列化/反序列化
• 过期时间支持（localStorage 和 Cookie）
• SSR 兼容性
• 完整的错误处理
• TypeScript 类型安全

import { getLocalStorage, setLocalStorage, setSessionStorage, getSessionStorage, setCookie, getCookie } from 'fezbox/storage'

// localStorage 基本操作
setLocalStorage('user', { name: 'John', age: 25 })
const user = getLocalStorage('user')

// 带过期时间的存储（1小时后过期）
setLocalStorage('tempData', { session: 'abc123' }, { 
  expires: Date.now() + 60 * 60 * 1000 
})

// sessionStorage 操作
setSessionStorage('formData', { name: 'John', email: '[e-mail]' })
const formData = getSessionStorage('formData')

// Cookie 操作
setCookie('theme', 'dark', { expires: 7, secure: true })
const theme = getCookie('theme')

// 类型安全
interface UserInfo { id: number; name: string }
const userInfo = getLocalStorage<UserInfo>('userInfo')

📖 完整API文档: 查看 docs/api/ 目录 了解每个模块的详细使用说明

📦 依赖

运行时依赖

• crypto-js (用于加密功能)
• dayjs (用于时间处理)

开发依赖

• vitest (测试框架)
• typescript (类型支持)
• vite (构建工具)
• eslint + prettier (代码质量)

🛠️ 开发

# 安装依赖
pnpm install

# 开发模式 (监听文件变化)
pnpm run dev

# 构建
pnpm run build

# 运行测试
pnpm test

# 生成覆盖率报告
pnpm run test:coverage

# 类型检查
pnpm run typecheck

# 代码格式化
pnpm run format

# 代码检查
pnpm run lint

# 修复代码问题
pnpm run lint:fix

📊 测试

项目包含完整的测试覆盖：

• 102个测试用例 覆盖所有核心功能
• 高代码覆盖率 确保代码质量
• 10个测试文件 按模块组织
• 自动化的 CI/CD 集成

运行测试并查看覆盖率报告：

pnpm run test:coverage

覆盖率报告会生成在 coverage/ 目录下。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发流程

• Fork 项目
• 创建功能分支 (git checkout -b feature/AmazingFeature)
• 提交更改 (git commit -m 'Add some AmazingFeature')
• 推送到分支 (git push origin feature/AmazingFeature)
• 创建 Pull Request

代码规范

• 使用 TypeScript 编写
• 遵循 ESLint 和 Prettier 规范
• 编写对应的测试用例
• 确保所有测试通过

许可证

MIT