data-utils-grok/README.md

A comprehensive JavaScript utility library for data processing, organized by data types (arrays, objects, strings, forms, tables)

# 数据工具库 (Data Utils Grok)

一个按数据类型分类的JavaScript工具函数库，提供数组、对象、字符串、表单和表格数据的处理功能。

## 功能分类

### 1. 数组类型处理 (`arrayUtils.js`)
- **uniqueArray** - 数组去重
- **filterArray** - 按条件过滤数组
- **groupBy** - 按键分组
- **sortBy** - 按键排序
- **stats** - 计算数组统计信息
- **chunk** - 数组分块
- **flatten** - 数组扁平化

### 2. 对象类型处理 (`objectUtils.js`)
- **deepClone** - 深拷贝对象
- **merge** - 合并对象
- **get** - 获取嵌套属性值
- **set** - 设置嵌套属性值
- **omit** - 移除指定属性
- **pick** - 保留指定属性
- **isEmpty** - 检查对象是否为空
- **getKeys** - 获取所有键路径

### 3. 字符串类型处理 (`stringUtils.js`)
- **capitalize** - 首字母大写
- **camelToSnake** - 驼峰转下划线
- **snakeToCamel** - 下划线转驼峰
- **truncate** - 截断字符串
- **trim** - 去除空白字符
- **trimLeft** - 去除左侧空白
- **trimRight** - 去除右侧空白
- **reverse** - 反转字符串
- **countChar** - 统计字符出现次数
- **isEmpty** - 检查字符串是否为空
- **randomString** - 生成随机字符串
- **format** - 格式化字符串

### 4. 表单类型处理 (`formUtils.js`)
- **validateEmail** - 验证邮箱格式
- **validatePhone** - 验证手机号格式
- **validateIdCard** - 验证身份证号格式
- **validateUrl** - 验证URL格式
- **validatePassword** - 验证密码强度
- **serializeForm** - 序列化表单数据
- **deserializeForm** - 反序列化表单数据
- **getFormData** - 获取表单字段值
- **setFormData** - 设置表单字段值
- **resetForm** - 重置表单
- **validateForm** - 验证表单数据

### 5. 表格类型处理 (`tableUtils.js`)
- **sortTableData** - 表格数据排序
- **filterTableData** - 表格数据过滤
- **paginateTableData** - 表格数据分页
- **groupTableData** - 表格数据分组
- **aggregateTableData** - 表格数据聚合
- **exportTableToCSV** - 导出为CSV
- **exportTableToJSON** - 导出为JSON
- **deduplicateTableData** - 表格数据去重
- **transformTableData** - 表格数据转换
- **getTableStats** - 获取表格统计信息

### 6. 日期类型处理 (`dateUtils.js`)
- **formatDate** - 格式化日期
- **parseDate** - 解析日期字符串
- **getDateDiff** - 获取日期差
- **addDate** - 添加时间
- **getDateRange** - 获取日期范围
- **getRelativeTime** - 获取相对时间描述
- **isSameDay** - 检查是否为同一天
- **isToday** - 检查是否为今天
- **isYesterday** - 检查是否为昨天
- **isTomorrow** - 检查是否为明天
- **getDaysInMonth** - 获取月份天数
- **getDayOfWeek** - 获取星期几
- **getQuarter** - 获取季度
- **getAge** - 获取年龄
- **isLeapYear** - 检查是否为闰年
- **getTimestamp** - 获取时间戳
- **now** - 获取当前时间戳

## 安装

```bash
npm install
```

## 使用方法

### 完整导入
```javascript
const dataUtils = require('./src');

// 使用数组工具
const uniqueNumbers = dataUtils.uniqueArray([1, 2, 2, 3]);

// 使用对象工具
const cloned = dataUtils.deepClone({ a: 1, b: { c: 2 } });

// 使用字符串工具
const capitalized = dataUtils.capitalize('hello');

// 使用表单工具
const isValidEmail = dataUtils.validateEmail('test@example.com');

// 使用表格工具
const sortedData = dataUtils.sortTableData(tableData, 'name', 'asc');

// 使用日期工具
const formattedDate = dataUtils.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');
```

### 按分类导入
```javascript
const { arrayUtils, objectUtils, stringUtils, formUtils, tableUtils } = require('./src');

// 数组工具
const uniqueNumbers = arrayUtils.uniqueArray([1, 2, 2, 3]);

// 对象工具
const merged = objectUtils.merge({ a: 1 }, { b: 2 });

// 字符串工具
const snakeCase = stringUtils.camelToSnake('camelCase');

// 表单工具
const isValidPhone = formUtils.validatePhone('13800138000');

// 表格工具
const paginated = tableUtils.paginateTableData(data, 1, 10);

// 日期工具
const formattedDate = dateUtils.formatDate(new Date(), 'YYYY-MM-DD');
```

### 直接导入特定模块
```javascript
const arrayUtils = require('./src/arrayUtils');
const objectUtils = require('./src/objectUtils');
const stringUtils = require('./src/stringUtils');
const formUtils = require('./src/formUtils');
const tableUtils = require('./src/tableUtils');
const dateUtils = require('./src/dateUtils');
```

## 运行测试

```bash
npm test
```

## 示例

### 数组处理示例
```javascript
const { uniqueArray, groupBy, sortBy, stats } = require('./src');

// 数组去重
const numbers = [1, 2, 2, 3, 3, 4];
const unique = uniqueArray(numbers); // [1, 2, 3, 4]

// 对象数组去重
const users = [
  { id: 1, name: 'John' },
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
];
const uniqueUsers = uniqueArray(users, 'id');

// 分组
const grouped = groupBy(users, 'name');

// 排序
const sorted = sortBy(users, 'id', true);

// 统计
const numbers = [1, 2, 3, 4, 5];
const statistics = stats(numbers);
// { sum: 15, average: 3, min: 1, max: 5 }
```

### 对象处理示例
```javascript
const { deepClone, merge, get, set } = require('./src');

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

// 合并对象
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const merged = merge(obj1, obj2);

// 获取嵌套属性
const user = { profile: { address: { city: 'Beijing' } } };
const city = get(user, 'profile.address.city');

// 设置嵌套属性
set(user, 'profile.age', 30);
```

### 字符串处理示例
```javascript
const { capitalize, camelToSnake, snakeToCamel, format } = require('./src');

// 首字母大写
const result = capitalize('hello'); // 'Hello'

// 命名转换
const snakeCase = camelToSnake('camelCase'); // 'camel_case'
const camelCase = snakeToCamel('snake_case'); // 'snakeCase'

// 字符串格式化
const template = 'Hello {name}, you are {age} years old';
const data = { name: 'John', age: 30 };
const formatted = format(template, data);
// 'Hello John, you are 30 years old'
```

### 表单处理示例
```javascript
const { validateEmail, validatePassword, serializeForm } = require('./src');

// 验证邮箱
const isValidEmail = validateEmail('test@example.com');

// 验证密码强度
const passwordResult = validatePassword('StrongPass123!', {
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSpecialChars: true
});

// 序列化表单数据
const formData = { name: 'John', age: 30 };
const serialized = serializeForm(formData); // 'name=John&age=30'
```

### 表格处理示例
```javascript
const { sortTableData, filterTableData, paginateTableData, exportTableToCSV } = require('./src');

const tableData = [
  { id: 1, name: 'John', age: 30, city: 'Beijing' },
  { id: 2, name: 'Jane', age: 25, city: 'Shanghai' },
  { id: 3, name: 'Bob', age: 35, city: 'Beijing' }
];

// 排序
const sorted = sortTableData(tableData, 'age', 'asc');

// 过滤
const filtered = filterTableData(tableData, { city: 'Beijing' });

// 分页
const paginated = paginateTableData(tableData, 1, 2);

// 导出CSV
const columns = [{ key: 'name', title: 'Name' }, { key: 'age', title: 'Age' }];
const csv = exportTableToCSV(tableData, columns);
```

### 日期处理示例
```javascript
const { formatDate, parseDate, getDateDiff, addDate, getRelativeTime } = require('./src');

// 格式化日期
const formatted = formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');

// 解析日期字符串
const date = parseDate('2024-01-15', 'YYYY-MM-DD');

// 计算日期差
const diff = getDateDiff(new Date('2024-01-01'), new Date('2024-01-10'), 'days');

// 添加时间
const futureDate = addDate(new Date(), 7, 'days');

// 获取相对时间
const relativeTime = getRelativeTime(new Date('2024-01-01'));
```
```

## 项目结构

```
src/
├── index.js          # 主入口文件
├── arrayUtils.js     # 数组类型处理
├── objectUtils.js    # 对象类型处理
├── stringUtils.js    # 字符串类型处理
├── formUtils.js      # 表单类型处理
├── tableUtils.js     # 表格类型处理
└── dateUtils.js      # 日期类型处理

tests/
└── index.test.js     # 测试文件
```

## 贡献

欢迎提交Issue和Pull Request来改进这个工具库。

## 许可证

ISC