@raphaellcs/data-cleaner 1.0.0

package/README.md

@@ -0,0 +1,315 @@
+# @claw-dev/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）
+- [ ] 自定义转换函数
+- [ ] 正则表达式替换
+- [ ] 数据验证规则
+- [ ] 合并多个文件
+- [ ] 分组统计
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 PR！
+
+## 📄 许可证
+
+MIT © 梦心
+
+---
+
+Made with 🌙 by 梦心

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../src/index.js');

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@raphaellcs/data-cleaner",
+  "version": "1.0.0",
+  "description": "数据清洗工具 - 快速清洗和转换数据文件",
+  "main": "src/index.js",
+  "bin": {
+    "data-cleaner": "./bin/cli.js"
+  },
+  "scripts": {
+    "clean": "node src/index.js clean"
+  },
+  "keywords": [
+    "data",
+    "cleaning",
+    "csv",
+    "json",
+    "transformation"
+  ],
+  "author": "梦心",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^4.1.2",
+    "csv-parse": "^5.5.0",
+    "csv-stringify": "^6.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { program } = require('commander');
+const chalk = require('chalk');
+const { parse } = require('csv-parse');
+const { stringify } = require('csv-stringify');
+
+// 读取文件
+function readFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const content = fs.readFileSync(filePath, 'utf-8');
+  
+  if (ext === '.json') {
+    return JSON.parse(content);
+  } else if (ext === '.csv') {
+    return new Promise((resolve, reject) => {
+      parse(content, { columns: true }, (err, data) => {
+        if (err) reject(err);
+        else resolve(data);
+      });
+    });
+  }
+  
+  return content;
+}
+
+// 写入文件
+function writeFile(filePath, data, format) {
+  const dir = path.dirname(filePath);
+  
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  
+  if (format === 'json') {
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  } else if (format === 'csv') {
+    return new Promise((resolve, reject) => {
+      stringify(data, { header: true }, (err, output) => {
+        if (err) reject(err);
+        else {
+          fs.writeFileSync(filePath, output, 'utf-8');
+          resolve();
+        }
+      });
+    });
+  } else {
+    fs.writeFileSync(filePath, data, 'utf-8');
+  }
+}
+
+// 清洗数据
+function cleanData(data, options) {
+  let cleaned = data;
+  
+  // 去除空行
+  if (options.removeEmpty) {
+    if (Array.isArray(cleaned)) {
+      cleaned = cleaned.filter(item => {
+        if (typeof item === 'string') return item.trim() !== '';
+        if (typeof item === 'object' && item !== null) {
+          return Object.values(item).some(v => v !== null && v !== undefined && v !== '');
+        }
+        return true;
+      });
+    }
+  }
+  
+  // 去重
+  if (options.deduplicate) {
+    if (Array.isArray(cleaned)) {
+      const seen = new Set();
+      cleaned = cleaned.filter(item => {
+        const key = options.key ? item[options.key] : JSON.stringify(item);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+    }
+  }
+  
+  // 去除空格
+  if (options.trim) {
+    if (Array.isArray(cleaned)) {
+      cleaned = cleaned.map(item => {
+        if (typeof item === 'object' && item !== null) {
+          const result = {};
+          for (const [key, value] of Object.entries(item)) {
+            result[key] = typeof value === 'string' ? value.trim() : value;
+          }
+          return result;
+        }
+        return item;
+      });
+    }
+  }
+  
+  // 大小写转换
+  if (options.case) {
+    if (Array.isArray(cleaned)) {
+      cleaned = cleaned.map(item => {
+        if (typeof item === 'object' && item !== null) {
+          const result = {};
+          for (const [key, value] of Object.entries(item)) {
+            if (typeof value === 'string') {
+              switch (options.case) {
+                case 'upper':
+                  result[key] = value.toUpperCase();
+                  break;
+                case 'lower':
+                  result[key] = value.toLowerCase();
+                  break;
+                case 'title':
+                  result[key] = value.replace(/\w\S*/g, txt => 
+                    txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase()
+                  );
+                  break;
+              }
+            } else {
+              result[key] = value;
+            }
+          }
+          return result;
+        }
+        return item;
+      });
+    }
+  }
+  
+  // 列选择
+  if (options.columns) {
+    if (Array.isArray(cleaned)) {
+      cleaned = cleaned.map(item => {
+        if (typeof item === 'object' && item !== null) {
+          const result = {};
+          for (const col of options.columns) {
+            if (col in item) {
+              result[col] = item[col];
+            }
+          }
+          return result;
+        }
+        return item;
+      });
+    }
+  }
+  
+  // 过滤
+  if (options.filter) {
+    if (Array.isArray(cleaned)) {
+      const { column, operator, value } = options.filter;
+      cleaned = cleaned.filter(item => {
+        const itemValue = item[column];
+        switch (operator) {
+          case 'eq':
+            return itemValue == value;
+          case 'neq':
+            return itemValue != value;
+          case 'gt':
+            return itemValue > value;
+          case 'lt':
+            return itemValue < value;
+          case 'gte':
+            return itemValue >= value;
+          case 'lte':
+            return itemValue <= value;
+          case 'contains':
+            return String(itemValue).includes(value);
+          case 'startsWith':
+            return String(itemValue).startsWith(value);
+          case 'endsWith':
+            return String(itemValue).endsWith(value);
+          case 'regex':
+            return new RegExp(value).test(String(itemValue));
+          default:
+            return true;
+        }
+      });
+    }
+  }
+
+// 数据转换
+  if (options.transform) {
+    if (Array.isArray(cleaned)) {
+      const { column, transform: transformFn } = options.transform;
+      cleaned = cleaned.map(item => {
+        if (column && item[column] !== undefined) {
+          switch (transformFn) {
+            case 'uppercase':
+              item[column] = String(item[column]).toUpperCase();
+              break;
+            case 'lowercase':
+              item[column] = String(item[column]).toLowerCase();
+              break;
+            case 'capitalize':
+              item[column] = String(item[column]).charAt(0).toUpperCase() + String(item[column]).slice(1).toLowerCase();
+              break;
+            case 'trim':
+              item[column] = String(item[column]).trim();
+              break;
+            case 'number':
+              item[column] = Number(item[column]);
+              break;
+            case 'string':
+              item[column] = String(item[column]);
+              break;
+            default:
+              if (transformFn.startsWith('replace:')) {
+                const [from, to] = transformFn.split(':')[1].split(',');
+                item[column] = String(item[column]).split(from).join(to);
+              } else if (transformFn.startsWith('multiply:')) {
+                const factor = Number(transformFn.split(':')[1]);
+                item[column] = Number(item[column]) * factor;
+              } else if (transformFn.startsWith('divide:')) {
+                const divisor = Number(transformFn.split(':')[1]);
+                item[column] = Number(item[column]) / divisor;
+              }
+          }
+        }
+        return item;
+      });
+    }
+  }
+  
+  // 排序
+  if (options.sort) {
+    if (Array.isArray(cleaned)) {
+      const { column, order = 'asc' } = options.sort;
+      cleaned = cleaned.sort((a, b) => {
+        const aVal = a[column];
+        const bVal = b[column];
+        if (aVal < bVal) return order === 'asc' ? -1 : 1;
+        if (aVal > bVal) return order === 'asc' ? 1 : -1;
+        return 0;
+      });
+    }
+  }
+  
+  // 限制数量
+  if (options.limit) {
+    if (Array.isArray(cleaned)) {
+      cleaned = cleaned.slice(0, options.limit);
+    }
+  }
+  
+  return cleaned;
+}
+
+// 统计数据
+function getStats(data) {
+  if (!Array.isArray(data)) {
+    return {
+      type: typeof data,
+      count: 1
+    };
+  }
+  
+  const stats = {
+    type: 'array',
+    count: data.length,
+    fields: [],
+    nullCount: 0,
+    emptyCount: 0
+  };
+  
+  if (data.length > 0 && typeof data[0] === 'object' && data[0] !== null) {
+    stats.fields = Object.keys(data[0]);
+    
+    for (const item of data) {
+      for (const [key, value] of Object.entries(item)) {
+        if (value === null || value === undefined) {
+          stats.nullCount++;
+        } else if (value === '') {
+          stats.emptyCount++;
+        }
+      }
+    }
+  }
+  
+  return stats;
+}
+
+// 打印统计
+function printStats(stats) {
+  console.log(chalk.cyan('\n📊 数据统计\n'));
+  console.log(chalk.gray(`类型: ${stats.type}`));
+  console.log(chalk.gray(`总数: ${stats.count}`));
+  
+  if (stats.fields && stats.fields.length > 0) {
+    console.log(chalk.cyan('\n字段:'));
+    for (const field of stats.fields) {
+      console.log(chalk.gray(`  - ${field}`));
+    }
+  }
+  
+  if (stats.nullCount > 0) {
+    console.log(chalk.yellow(`\n空值数量: ${stats.nullCount}`));
+  }
+  
+  if (stats.emptyCount > 0) {
+    console.log(chalk.yellow(`空字符串数量: ${stats.emptyCount}`));
+  }
+  
+  console.log();
+}
+
+// CLI 配置
+program
+  .name('data-cleaner')
+  .description('数据清洗工具 - 快速清洗和转换数据文件')
+  .version('1.0.0');
+
+program
+  .command('stats <file>')
+  .description('显示文件统计信息')
+  .action(async (file) => {
+    if (!fs.existsSync(file)) {
+      console.log(chalk.red(`文件不存在: ${file}`));
+      process.exit(1);
+    }
+    
+    const data = await readFile(file);
+    const stats = getStats(data);
+    printStats(stats);
+  });
+
+program
+  .command('clean <input> [output]')
+  .option('-f, --format <type>', '输出格式（json/csv）')
+  .option('--remove-empty', '去除空行')
+  .option('--deduplicate', '去重')
+  .option('-k, --key <field>', '去重时使用的字段')
+  .option('--trim', '去除空格')
+  .option('--case <type>', '大小写转换（upper/lower/title）')
+  .option('-c, --columns <items>', '选择列（逗号分隔）')
+  .option('-F, --filter <expr>', '过滤表达式（column:operator:value）')
+  .option('-S, --sort <column>', '按列排序')
+  .option('--order <dir>', '排序方向（asc/desc）', 'asc')
+  .option('-l, --limit <number>', '限制输出数量', parseInt)
+  .option('--transform <expr>', '转换表达式（column:transform[:args]）')
+  .option('--stats', '显示统计信息')
+  .description('清洗数据文件')
+  .action(async (input, output, options) => {
+    if (!fs.existsSync(input)) {
+      console.log(chalk.red(`文件不存在: ${input}`));
+      process.exit(1);
+    }
+    
+    const ext = path.extname(input).toLowerCase();
+    const outputFormat = options.format || (ext === '.json' ? 'json' : 'csv');
+    const outputFile = output || input.replace(/\.[^.]+$/, `.cleaned.${outputFormat}`);
+    
+    console.log(chalk.cyan(`\n🔧 清洗数据\n`));
+    console.log(chalk.gray(`输入: ${input}`));
+    console.log(chalk.gray(`输出: ${outputFile}\n`));
+    
+    const data = await readFile(input);
+    
+    // 显示原始统计
+    if (options.stats) {
+      console.log(chalk.cyan('原始数据:'));
+      printStats(getStats(data));
+    }
+    
+    // 解析过滤表达式
+    if (options.filter) {
+      const parts = options.filter.split(':');
+      if (parts.length === 3) {
+        options.filter = {
+          column: parts[0],
+          operator: parts[1],
+          value: parts[2]
+        };
+      }
+    }
+
+    // 解析转换表达式
+    if (options.transform) {
+      const parts = options.transform.split(':');
+      if (parts.length >= 2) {
+        options.transform = {
+          column: parts[0],
+          transform: parts[1]
+        };
+      }
+    }
+
+    // 解析列
+    if (options.columns) {
+      options.columns = options.columns.split(',');
+    }
+    
+    // 清洗数据
+    const cleaned = cleanData(data, options);
+    
+    // 显示清洗后统计
+    if (options.stats) {
+      console.log(chalk.cyan('清洗后数据:'));
+      printStats(getStats(cleaned));
+    }
+    
+    // 写入文件
+    await writeFile(outputFile, cleaned, outputFormat);
+    
+    console.log(chalk.green(`✅ 已保存到: ${outputFile}`));
+    
+    // 显示差异
+    const originalCount = Array.isArray(data) ? data.length : 1;
+    const cleanedCount = Array.isArray(cleaned) ? cleaned.length : 1;
+    if (originalCount !== cleanedCount) {
+      console.log(chalk.yellow(`   从 ${originalCount} 行减少到 ${cleanedCount} 行`));
+    }
+    
+    console.log();
+  });
+
+program.parse();