XLXZ Utils

一个包含存储管理和防抖功能的实用工具包。

功能

🗄️ Storage（存储管理）

• 响应式存储：基于 Vue 3 的响应式系统
• 层级化键值对：支持点分隔的键名（如 user.settings.theme）
• 文件持久化：支持多种文件系统后端
• 防抖保存：自动防抖写入，减少 I/O 操作
• 严格模式：可选的类型安全模式
• 装饰器支持：提供类装饰器简化使用

⏱️ Debouncer（防抖器）

• 装饰器模式：使用 @debounce 装饰器
• 两种模式：Leading（冷却）和 Trailing（传统防抖）
• 类型安全：完整的 TypeScript 支持

安装

npm install @xlxz/utils

如果你需要使用 Storage 功能，还需要安装 Vue 3：

npm install vue

快速开始

Storage 使用示例

import { Storage, StorageClass } from '@xlxz/utils';

// 基础使用
const storage = new Storage(fileSystem, 'myApp');
await storage.loadFrom('config.json');

const userTheme = storage.useStorage('user.theme', 'light');
console.log(userTheme.value); // 'light'

userTheme.value = 'dark'; // 自动保存到文件

// 使用装饰器
@StorageClass(storage)
class UserSettings {
  @Storage('user.name', 'Anonymous')
  username!: StorageValue<string>;
  
  @Storage('user.age', 18)
  age!: StorageValue<number>;
}

Debouncer 使用示例

import { debounce } from '@xlxz/utils';

class SearchComponent {
  @debounce(300) // 300ms 防抖
  onSearchInput(query: string) {
    console.log('Searching for:', query);
  }
  
  @debounce(1000, false) // 传统防抖模式
  onSave() {
    console.log('Saving...');
  }
}

API 文档

Storage

构造函数

new Storage(fileSystem: IFileSystemBase, name?: string)

主要方法

• useStorage<T>(key: string, defaultValue: T): StorageValue<T> - 创建或获取存储值
• loadFrom(filePath: string): Promise<void> - 从文件加载数据
• mergeData(data: Record<string, any>, force?: boolean): void - 合并数据
• toObject(): Record<string, any> - 导出为对象
• dispose(): void - 清理资源

StorageValue

响应式存储值，具有以下属性：

• value: T - 当前值
• defaultValue: T - 默认值
• isDefaultValue: boolean - 是否为默认值

Debouncer

@debounce(delay: number = 300, leading: boolean = true)

参数：

• delay: 防抖延迟时间（毫秒）
• leading: 是否启用 leading 模式
  • true: 冷却模式，立即执行，然后进入冷却期
  • false: 传统防抖，延迟执行

文件系统接口

Storage 需要一个实现 IFileSystemBase 接口的文件系统：

interface IFileSystemBase {
  readFile(filePath: string, createIfNotExists?: boolean): Promise<string>;
  writeFile(filePath: string, data: string, createIfNotExists?: boolean): Promise<void>;
  checkFileExists(filePath: string): Promise<boolean>;
  // ... 其他方法
}

你可以实现自己的文件系统适配器，或使用以下常见实现：

• Web 环境：基于 localStorage 的实现
• Node.js 环境：基于 fs 的实现
• 云存储：基于各种云服务 API 的实现

类型定义

包含完整的 TypeScript 类型定义，支持：

• 泛型约束
• 类型推断
• 智能提示

许可证

MIT License

贡献

欢迎提交 Issues 和 Pull Requests！

更新日志

1.0.0

• 初始版本
• 包含 Storage 和 Debouncer 功能
• 完整的 TypeScript 支持
• Vue 3 响应式集成