npm package: @raphaellcs/data-cleaner
Description: 数据清洗工具 - 验证、分组、透视表
Author: 梦心
Latest version: 2.0.0

# @raphaellcs/data-cleaner
[![npm](https://img.shields.io/npm/v/@raphaellcs/data-cleaner)](https://www.npmjs.com/package/@raphaellcs/data-cleaner)
[![downloads](https://img.shields.io/npm/dm/@raphaellcs/data-cleaner)](https://www.npmjs.com/package/@raphaellcs/data-cleaner)
[![license](https://img.shields.io/npm/l/@raphaellcs/data-cleaner)](https://www.npmjs.com/package/@raphaellcs/data-cleaner)

> 数据清洗工具 - 快速清洗和转换数据文件

## 🚀 功能

- **去除空行**：过滤掉空数据
- **去重**：基于字段或整行去重
- **去除空格**：trim 字符串字段
- **大小写转换**：upper/lower/title
- **列选择**：只保留指定列
- **数据过滤**：基于条件的过滤
- **排序**：按列排序
- **格式转换**：JSON ↔ CSV
- **统计信息**：查看数据概况
- **数据验证**：内置验证规则和自定义规则（新）
- **分组聚合**：字段分组和时间分组（新）
- **透视表**：创建数据透视表（新）

## 📦 安装

```bash
npx @claw-dev/data-cleaner
```

## 📖 快速开始

### 1. 查看统计

```bash
data-cleaner stats data.csv
```

输出：

```
📊 数据统计

类型: array
总数: 1523

字段:
  - name
  - email
  - age

空值数量: 45
空字符串数量: 23
```

### 2. 去除空行和空格

```bash
data-cleaner clean data.csv cleaned.csv --remove-empty --trim
```

### 3. 去重

```bash
data-cleaner clean data.csv cleaned.csv --deduplicate
```

基于特定字段去重：

```bash
data-cleaner clean data.csv cleaned.csv --deduplicate --key email
```

### 4. 列选择

```bash
data-cleaner clean data.csv cleaned.csv --columns "name,email"
```

### 5. 数据过滤

```bash
# 年龄大于 18
data-cleaner clean data.csv cleaned.csv -F "age:gt:18"

# 邮件包含 @gmail.com
data-cleaner clean data.csv cleaned.csv -F "email:contains:@gmail.com"

# 等于特定值
data-cleaner clean data.csv cleaned.csv -F "status:eq:active"
```

### 6. 排序

```bash
# 按年龄升序
data-cleaner clean data.csv cleaned.csv -S age

# 按年龄降序
data-cleaner clean data.csv cleaned.csv -S age --order desc
```

### 7. 大小写转换

```bash
# 全部大写
data-cleaner clean data.csv cleaned.csv --case upper

# 全部小写
data-cleaner clean data.csv cleaned.csv --case lower

# 首字母大写
data-cleaner clean data.csv cleaned.csv --case title
```

### 8. 格式转换

```bash
# CSV 转 JSON
data-cleaner clean data.csv output.json -f json

# JSON 转 CSV
data-cleaner clean data.json output.csv -f csv
```

## 📋 过滤操作

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `eq` | 等于 | `status:eq:active` |
| `neq` | 不等于 | `status:neq:deleted` |
| `gt` | 大于 | `age:gt:18` |
| `lt` | 小于 | `age:lt:65` |
| `gte` | 大于等于 | `age:gte:18` |
| `lte` | 小于等于 | `age:lte:65` |
| `contains` | 包含 | `email:contains:@gmail.com` |
| `startsWith` | 以...开头 | `name:startsWith:A` |
| `endsWith` | 以...结尾 | `email:endsWith:.com` |

## 🎯 使用场景

### 1. 清洗用户数据

```bash
data-cleaner clean users.csv users_cleaned.csv \
  --remove-empty \
  --deduplicate --key email \
  --trim \
  -F "status:eq:active"
```

去除空行、基于邮箱去重、去除空格、只保留活跃用户。

### 2. 提取特定列

```bash
data-cleaner clean products.csv products_simple.csv \
  --columns "id,name,price"
```

只保留产品 ID、名称和价格。

### 3. 格式转换

```bash
data-cleaner clean data.json data.csv -f csv
data-cleaner clean data.csv data.json -f json
```

在 JSON 和 CSV 之间转换。

### 4. 排序和限制

```bash
data-cleaner clean products.csv top10.csv \
  -S price --order desc \
  --limit 10
```

按价格降序，只保留前 10 个。

### 5. 数据标准化

```bash
data-cleaner clean emails.csv emails_cleaned.csv \
  --trim \
  --case lower
```

去除空格并转换为小写。

## 💡 组合使用

多个选项可以组合使用：

```bash
data-cleaner clean data.csv cleaned.csv \
  --remove-empty \
  --deduplicate --key id \
  --trim \
  --case lower \
  -F "status:eq:active" \
  -S created_at --order desc \
  --limit 1000
```

这会：
1. 去除空行
2. 基于 ID 去重
3. 去除空格
4. 转换为小写
5. 只保留状态为 active 的记录
6. 按创建时间降序排序
7. 只保留前 1000 条

## 📊 统计信息

使用 `--stats` 查看清洗前后的对比：

```bash
data-cleaner clean data.csv cleaned.csv --stats
```

输出：

```
🔧 清洗数据

输入: data.csv
输出: cleaned.csv

原始数据:
📊 数据统计

类型: array
总数: 1523

字段:
  - id
  - name
  - email
  - age
  - status

空值数量: 45
空字符串数量: 23

清洗后数据:
📊 数据统计

类型: array
总数: 1456

字段:
  - id
  - name
  - email
  - age
  - status

✅ 已保存到: cleaned.csv
   从 1523 行减少到 1456 行
```

## 🔧 高级功能

### 1. 转换为大写并去除空值

```bash
data-cleaner clean data.csv cleaned.csv \
  --remove-empty \
  --trim \
  --case upper
```

### 2. 多步清洗

可以链式调用，逐步清洗：

```bash
# 第一步：去重
data-cleaner clean data.csv step1.csv --deduplicate --key id

# 第二步：过滤
data-cleaner clean step1.csv step2.csv -F "age:gte:18"

# 第三步：排序
data-cleaner clean step2.csv final.csv -S created_at --order desc
```

### 3. 批量处理

使用 shell 脚本批量处理：

```bash
#!/bin/bash

for file in data/*.csv; do
    output="cleaned/$(basename $file)"
    data-cleaner clean "$file" "$output" --remove-empty --trim
done
```

## 🚧 待实现

- [ ] 支持更多文件格式（Excel、SQL）
- [ ] 合并多个文件

---

## ✨ 新功能（v2.0.0）

### 数据验证

验证数据是否符合规则：

```bash
data-cleaner validate data.csv --config rules.json
```

创建验证规则配置 `rules.json`：

```json
{
  "email": ["required", "email"],
  "age": [
    "required",
    {"name": "number", "message": "年龄必须是数字"},
    {"name": "min", "value": 0, "message": "年龄不能为负数"},
    {"name": "max", "value": 120, "message": "年龄不能超过120"}
  ],
  "phone": [
    {"name": "pattern", "value": "^\\d{11}$", "message": "手机号必须是11位数字"}
  ],
  "status": [
    {"name": "enum", "value": ["active", "inactive", "pending"], "message": "状态值不合法"}
  ]
}
```

**内置验证规则：**
- `required` - 必填
- `email` - 邮箱格式
- `url` - URL 格式
- `number` - 数字
- `integer` - 整数
- `positive` - 正数
- `negative` - 负数
- `min:<value>` - 最小值
- `max:<value>` - 最大值
- `minLength:<length>` - 最小长度
- `maxLength:<length>` - 最大长度
- `pattern:<regex>` - 正则匹配
- `enum:[values]` - 枚举值
- `date` - 日期
- `future` - 未来日期
- `past` - 过去日期
- `phone` - 电话号码

输出错误报告：

```bash
data-cleaner validate data.csv --config rules.json --output errors.csv --format csv
```

### 分组聚合

按字段分组并聚合：

```bash
# 按部门分组，计算平均工资
data-cleaner group employees.csv --group-by department --aggregate "salary:avg" --stats

# 多字段分组
data-cleaner group sales.csv --group-by "region,category" --aggregate "revenue:sum,count" --output grouped.json
```

时间分组：

```bash
# 按天分组
data-cleaner group orders.csv --time-field created_at --interval day --aggregate "amount:sum" --stats

# 按月分组
data-cleaner group orders.csv --time-field created_at --interval month --aggregate "amount:sum,count" --stats

# 按小时分组
data-cleaner group logs.csv --time-field timestamp --interval hour --aggregate "errors:sum" --stats
```

**聚合类型：**
- `sum` - 求和
- `avg` - 平均值
- `min` - 最小值
- `max` - 最大值
- `count` - 计数
- `count_distinct` - 去重计数
- `first` - 第一个值
- `last` - 最后一个值
- `concat` - 拼接
- `array` - 数组
- `percentile:XX` - 百分位数（如 percentile:95）

### 透视表

创建数据透视表：

```bash
data-cleaner pivot sales.csv \
  --rows region \
  --columns product \
  --values revenue \
  --agg sum
```

示例输出：

```
    productA    productB    productC
region1      15000.00    23000.00    18000.00
region2      12000.00    25000.00    21000.00
region3      18000.00    20000.00    22000.00
```

保存透视表：

```bash
data-cleaner pivot sales.csv \
  --rows region \
  --columns product \
  --values revenue \
  --agg sum \
  --output pivot.json
```

## 🤝 贡献

欢迎提交 Issue 和 PR！

## 📄 许可证

MIT © 梦心

---

Made with 🌙 by 梦心