# em-util-lib

**Repository Path**: imjohn_top/em-util-lib

## Basic Information

- **Project Name**: em-util-lib
- **Description**: 常用前端方法工具库，包含日期处理、字符串处理、对象/数组工具、DOCX文档生成等功能
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# em-util-lib

常用前端方法工具库，包含日期处理、字符串处理、对象/数组工具、DOCX文档生成等功能

## 特性

- 📅 **日期工具** - 日期格式化、日期计算、相对时间等
- 🔤 **字符串工具** - 大小写转换、格式化、验证、脱敏等
- 📦 **对象/数组工具** - 深拷贝、深合并、路径访问、去重、分组等
- 📝 **DOCX 文档生成** - 基于 docx 库提供便捷的文档生成方法
- 📘 **TypeScript 支持** - 完整的类型定义
- 🧪 **Jest 测试** - 完整的测试用例覆盖

## 安装

```bash
npm install em-util-lib
```

## 快速开始

```typescript
import { formatDate, deepClone, toCamelCase } from 'em-util-lib';

// 日期格式化
console.log(formatDate(new Date(), 'YYYY-MM-DD')); // 2024-01-15

// 深拷贝
const obj = { a: 1, b: { c: 2 } };
const cloned = deepClone(obj);

// 字符串转换
console.log(toCamelCase('hello-world')); // helloWorld
```

## API 文档

### 日期工具 (dateUtils)

#### formatDate(date, format)
日期格式化工具 / /** 格式化日期

**参数:**
- `date` - 日期对象或时间戳
 *
- `format` - 格式化字符串，默认 'YYYY-MM-DD HH:mm:ss'
 *

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

#### daysBetween(date1, date2)
计算两个日期之间的天数差

**参数:**
- `date1` - 第一个日期
 *
- `date2` - 第二个日期
 *

**返回值:** 天数差

#### isToday(date)
判断是否是今天

**参数:**
- `date` - 要检查的日期
 *

**返回值:** 是否是今天

#### addDays(date, days)
添加天数到日期

**参数:**
- `date` - 原始日期
 *
- `days` - 要添加的天数
 *

**返回值:** 新的日期对象

#### getMonthName(month, locale)
获取月份的名称

**参数:**
- `month` - 月份索引 (0-11)
 *
- `locale` - 语言，默认 'zh-CN'
 *

**返回值:** 月份名称

#### getRelativeTime(date)
获取相对时间描述

**参数:**
- `date` - 日期
 *

**返回值:** 相对时间描述

### 对象和数组工具 (objectUtils)

#### unset(obj, target, source, obj, path, defaultValue, obj, path, value, obj, path)
对象和数组处理工具 / /** 深拷贝对象

**参数:**
- `obj` - 要拷贝的对象
 *
- `target` - 目标对象
 *
- `source` - 源对象
 *
- `obj` - 对象
 *
- `path` - 路径，如 'a.b.c'
 *
- `defaultValue` - 默认值
 *
- `obj` - 对象
 *
- `path` - 路径
 *
- `value` - 值
 *
- `obj` - 对象
 *
- `path` - 路径
 *

**返回值:** 深拷贝后的对象
 */
export function deepClone<T>(obj: T): T {
  if (obj === null || typeof obj !== 'object') return obj;
  if (obj instanceof Date) return new Date(obj.getTime()) as unknown as T;
  if (obj instanceof Array) return obj.map(item => deepClone(item)) as unknown as T;
  if (obj instanceof Object) {
    const cloned = {} as T;
    for (const key in obj) {
      if (Object.prototype.hasOwnProperty.call(obj, key)) {
        cloned[key] = deepClone(obj[key]);
      }
    }
    return cloned;
  }
  return obj;
}

/**
 * 深度合并对象
 *

#### isEqual(arr, arr, keyFn, arr, size, arr, count, obj, obj1, obj2)
数组去重

**参数:**
- `arr` - 输入数组
 *
- `arr` - 输入数组
 *
- `keyFn` - 分组条件函数
 *
- `arr` - 输入数组
 *
- `size` - 每块大小
 *
- `arr` - 输入数组
 *
- `count` - 获取数量，默认 1
 *
- `obj` - 输入对象
 *
- `obj1` - 第一个对象
 *
- `obj2` - 第二个对象
 *

**返回值:** 去重后的数组
 */
export function unique<T>(arr: T[]): T[] {
  return [...new Set(arr)];
}

/**
 * 按指定条件分组
 *

#### toQueryString(obj)
将对象转换为查询字符串

**参数:**
- `obj` - 输入对象
 *

**返回值:** 查询字符串

#### fromQueryString(str)
将查询字符串转换为对象

**参数:**
- `str` - 查询字符串
 *

**返回值:** 转换后的对象

### 字符串工具 (stringUtils)

#### toCamelCase(str)
字符串处理工具 / /** 将字符串转换为驼峰格式

**参数:**
- `str` - 输入字符串
 *

**返回值:** 驼峰格式字符串

#### toKebabCase(str)
将字符串转换为短横线连接格式

**参数:**
- `str` - 输入字符串
 *

**返回值:** 短横线连接格式字符串

#### toSnakeCase(str)
将字符串转换为下划线连接格式

**参数:**
- `str` - 输入字符串
 *

**返回值:** 下划线连接格式字符串

#### capitalize(str)
首字母大写

**参数:**
- `str` - 输入字符串
 *

**返回值:** 首字母大写的字符串

#### truncate(str, maxLength, suffix)
截断字符串

**参数:**
- `str` - 输入字符串
 *
- `maxLength` - 最大长度
 *
- `suffix` - 后缀，默认 '...'
 *

**返回值:** 截断后的字符串

#### reverse(str)
反转字符串

**参数:**
- `str` - 输入字符串
 *

**返回值:** 反转后的字符串

#### isEmail(str)
检查是否是邮箱格式

**参数:**
- `str` - 输入字符串
 *

**返回值:** 是否是邮箱格式

#### isPhone(str)
检查是否是手机号格式（中国大陆）

**参数:**
- `str` - 输入字符串
 *

**返回值:** 是否是手机号格式

#### randomString(length)
生成随机字符串

**参数:**
- `length` - 字符串长度，默认 8
 *

**返回值:** 随机字符串

#### maskString(str, start, end, mask)
脱敏处理

**参数:**
- `str` - 输入字符串
 *
- `start` - 开始保留的字符数，默认 3
 *
- `end` - 结尾保留的字符数，默认 4
 *
- `mask` - 替换字符，默认 '*'
 *

**返回值:** 脱敏后的字符串

#### getByteLength(str)
计算字符串字节长度

**参数:**
- `str` - 输入字符串
 *

**返回值:** 字节长度

## 开发

### 安装依赖

```bash
npm install
```

### 运行测试

```bash
npm test
```

### 构建

```bash
npm run build
```

### 生成文档

```bash
# 生成HTML文档
npm run docs

# 更新README文档
npm run docs:md
```

### 发布到 NPM

```bash
npm publish
```

## License

MIT