npm package: @huaiyou/utils
Description: Common utility functions
Latest version: 1.0.0

# @huaiyou/utils

> 通用工具函数库，提供常用的日期、防抖节流、深拷贝、本地存储等功能。

## 📦 安装

```bash
pnpm add @huaiyou/utils
```

## 🚀 使用方法

### 日期格式化

```typescript
import { formatDate } from '@huaiyou/utils';

const date = new Date('2024-01-15 10:30:45');

formatDate(date); // "2024-01-15"
formatDate(date, 'YYYY-MM-DD HH:mm:ss'); // "2024-01-15 10:30:45"
formatDate(date, 'YYYY/MM/DD'); // "2024/01/15"
```

### 防抖 (Debounce)

```typescript
import { debounce } from '@huaiyou/utils';

const handleSearch = debounce((query: string) => {
  console.log('Searching for:', query);
}, 300);

// 只有在停止输入 300ms 后才会执行
handleSearch('apple');
handleSearch('apple pie');
```

### 节流 (Throttle)

```typescript
import { throttle } from '@huaiyou/utils';

const handleScroll = throttle(() => {
  console.log('Scroll event');
}, 100);

// 每 100ms 最多执行一次
window.addEventListener('scroll', handleScroll);
```

### 深拷贝

```typescript
import { deepClone } from '@huaiyou/utils';

const original = {
  name: 'John',
  age: 30,
  hobbies: ['reading', 'gaming'],
  address: {
    city: 'New York',
    zip: '10001',
  },
};

const cloned = deepClone(original);
cloned.address.city = 'Boston';

console.log(original.address.city); // "New York"
console.log(cloned.address.city); // "Boston"
```

### 随机字符串

```typescript
import { randomString } from '@huaiyou/utils';

randomString(8); // "aB3xY9Zk"
randomString(16); // "Q2wE4rT6yU8iO0pA"
```

### 本地存储

```typescript
import { storage } from '@huaiyou/utils';

// 存储数据
storage.set('user', { id: 1, name: 'John' });

// 获取数据
const user = storage.get<{ id: number; name: string }>('user');
console.log(user?.name); // "John"

// 删除数据
storage.remove('user');

// 清空所有数据
storage.clear();
```

## 📋 API 文档

### formatDate

格式化日期为字符串。

```typescript
function formatDate(date: Date, format?: string): string;
```

**参数:**

- `date`: 要格式化的日期对象
- `format`: 格式字符串（默认: `'YYYY-MM-DD'`）
  - `YYYY`: 年份
  - `MM`: 月份
  - `DD`: 日期
  - `HH`: 小时
  - `mm`: 分钟
  - `ss`: 秒

**返回:** 格式化后的日期字符串

### debounce

创建防抖函数。

```typescript
function debounce<T extends (...args: unknown[]) => unknown>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void;
```

**参数:**

- `func`: 要防抖的函数
- `wait`: 等待时间（毫秒）

**返回:** 防抖后的函数

### throttle

创建节流函数。

```typescript
function throttle<T extends (...args: unknown[]) => unknown>(
  func: T,
  limit: number
): (...args: Parameters<T>) => void;
```

**参数:**

- `func`: 要节流的函数
- `limit`: 时间限制（毫秒）

**返回:** 节流后的函数

### deepClone

深拷贝对象。

```typescript
function deepClone<T>(obj: T): T;
```

**参数:**

- `obj`: 要拷贝的对象

**返回:** 深拷贝后的对象

**支持类型:**

- 普通对象
- 数组
- Date 对象
- 基本类型

### randomString

生成随机字符串。

```typescript
function randomString(length: number): string;
```

**参数:**

- `length`: 字符串长度

**返回:** 随机字符串（包含大小写字母和数字）

### storage

本地存储工具对象。

```typescript
interface Storage {
  get<T>(key: string): T | null;
  set<T>(key: string, value: T): void;
  remove(key: string): void;
  clear(): void;
}
```

**方法:**

- `get<T>(key)`: 获取存储的数据
- `set<T>(key, value)`: 存储数据
- `remove(key)`: 删除数据
- `clear()`: 清空所有数据

## 🔧 高级用法

### 组合使用

```typescript
import { debounce, storage } from '@huaiyou/utils';

const saveToStorage = debounce((data: unknown) => {
  storage.set('draft', data);
}, 500);

// 自动保存草稿（500ms 防抖）
function handleInput(value: string) {
  saveToStorage({ content: value, timestamp: Date.now() });
}
```

### TypeScript 类型支持

```typescript
import { storage } from '@huaiyou/utils';

interface UserSettings {
  theme: 'light' | 'dark';
  language: string;
}

// 类型安全的存储
storage.set<UserSettings>('settings', {
  theme: 'dark',
  language: 'en',
});

// 类型安全的获取
const settings = storage.get<UserSettings>('settings');
if (settings) {
  console.log(settings.theme); // TypeScript 知道这是 'light' | 'dark'
}
```

## ✅ 测试

所有工具函数都有完整的单元测试覆盖。

```bash
# 运行测试
pnpm test

# 监听模式
pnpm test:watch

# 测试覆盖率
pnpm test:coverage
```

## 🤝 贡献

欢迎添加更多实用工具函数！请确保：

1. 添加 TypeScript 类型定义
2. 编写单元测试
3. 更新文档

## 📄 License

MIT