excel-csv-handler 1.0.10 → 1.1.0

package/package.json

@@ -1,26 +1,31 @@
 {
-  "name": "excel-csv-handler",
-  "version": "1.0.10",
-  "description": "A Node.js utility to read/write Excel and CSV files with GBK encoding support",
-  "main": "src/index.js",
-  "types": "src/excel-csv-handler.d.ts",
-  "type": "module",
-  "keywords": [
-    "excel",
-    "csv",
-    "xlsx",
-    "gbk",
-    "node",
-    "file"
-  ],
-  "author": "Chao_bei",
-  "license": "MIT",
-  "dependencies": {
-    "fast-csv": "^5.0.5",
-    "iconv-lite": "^0.7.0",
-    "xlsx": "^0.18.5"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+	"name": "excel-csv-handler",
+	"version": "1.1.0",
+	"description": "A Node.js utility to read/write Excel and CSV files with GBK encoding support",
+	"main": "src/index.js",
+	"types": "src/excel-csv-handler.d.ts",
+	"type": "module",
+	"files": [
+		"src/",
+		"README.md"
+	],
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"keywords": [
+		"excel",
+		"csv",
+		"xlsx",
+		"gbk",
+		"node",
+		"file"
+	],
+	"author": "Chao_bei",
+	"license": "MIT",
+	"dependencies": {
+		"chardet": "^2.1.1",
+		"fast-csv": "^5.0.5",
+		"iconv-lite": "^0.7.0",
+		"xlsx": "^0.18.5"
+	}
+}

package/src/excel-csv-handler.d.ts

@@ -1,5 +1,11 @@
 // src/excel-csv-handler.d.ts
 export default class ExcelCsvHandler {
+	/**
+	 * 检测文件编码（用于 CSV 文件）
+	 * @param filePath - 文件路径
+	 * @returns 检测到的编码格式 (utf8 或 gbk)
+	 */
+	detectEncoding(filePath: string): string;
 	/**
 	 * 读取 Excel 或 CSV 文件（支持 GBK 编码）
 	 * @param filePath - 文件路径
@@ -30,10 +36,27 @@ export default class ExcelCsvHandler {
 	 * @param filePath - 文件路径
 	 * @param data - 要追加的数据
 	 * @param headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+	 * @param encoding - 编码格式，默认 'gbk'，可选 'utf8'
 	 */
 	appendCsv(
 		filePath: string,
 		data: Array<Record<string, any>>,
-		headers?: string[] | null
+		headers?: string[] | null,
+		encoding?: string
 	): Promise<void>;
+
+	/**
+	 * 从调用文件的相对路径获取绝对路径
+	 * @param importMetaUrl - 调用文件的 import.meta.url
+	 * @param relativePath - 相对路径（如 './dataset/file.docx' 或 'dataset/file.docx'）
+	 * @returns 绝对路径
+	 * 
+	 * @example
+	 * ```ts
+	 * import ExcelCsvHandler from 'excel-csv-handler';
+	 * const docxPath = ExcelCsvHandler.getAbsolutePath(import.meta.url, './dataset/sci-high-question.docx');
+	 * const csvPath = ExcelCsvHandler.getAbsolutePath(import.meta.url, 'data/output.csv');
+	 * ```
+	 */
+	static getAbsolutePath(importMetaUrl: string, relativePath: string): string;
 }

package/src/index.js

@@ -1,14 +1,54 @@
 // excel-csv-handler.js
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 
 import * as fs from 'fs';
 import * as path from 'path';
 import iconv from 'iconv-lite';
 import * as csv from 'fast-csv';
 import { writeToString } from 'fast-csv';
+import chardet from 'chardet';
 const require = createRequire(import.meta.url);
 const XLSX = require('xlsx');
 class ExcelCsvHandler {
+    /**
+     * 检测文件编码（用于 CSV 文件）
+     * @param {string} filePath - 文件路径
+     * @returns {string} 检测到的编码格式 (utf8 或 gbk)
+     */
+    detectEncoding(filePath) {
+        // 读取文件的前几个字节来检测编码
+        const buffer = fs.readFileSync(filePath);
+
+        // 检查 UTF-8 BOM
+        if (buffer.length >= 3 &&
+            buffer[0] === 0xEF &&
+            buffer[1] === 0xBB &&
+            buffer[2] === 0xBF) {
+            return 'utf8';
+        }
+
+        // 使用 chardet 库检测编码
+        const detected = chardet.detect(buffer);
+
+        // 将检测结果映射到 iconv-lite 支持的编码名称
+        if (detected) {
+            const encoding = detected.toLowerCase();
+
+            // GB2312, GBK, GB18030 都映射为 gbk
+            if (encoding.includes('gb') || encoding.includes('gbk')) {
+                return 'gbk';
+            }
+
+            // UTF-8 相关
+            if (encoding.includes('utf-8') || encoding.includes('utf8')) {
+                return 'utf8';
+            }
+        }
+
+        // 默认返回 gbk（考虑到中国用户常用 GBK）
+        return 'gbk';
+    }
     /**
      * 读取 Excel 或 CSV 文件（支持 GBK 编码）
      * @param {string} filePath - 文件路径
@@ -97,10 +137,13 @@ class ExcelCsvHandler {
     // ========= CSV 读写 =========
 
     async #readCsvFile(filePath, headerRow) {
+        // 自动检测编码
+        const encoding = this.detectEncoding(filePath);
+
         return new Promise((resolve, reject) => {
             const allRows = [];
             const stream = fs.createReadStream(filePath)
-                .pipe(iconv.decodeStream('gbk'))
+                .pipe(iconv.decodeStream(encoding))
                 .pipe(csv.parse({ headers: false, skipLines: headerRow }));
 
             stream.on('data', row => {
@@ -132,7 +175,14 @@ class ExcelCsvHandler {
         });
     }
 
-    async #writeCsvFile(filePath, data, headers = null) {
+    /**
+     * 写入 CSV 文件（以 GBK 编码保存）
+     * @param {string} filePath - 文件路径
+     * @param {Array<Object>} data - 要写入的数据
+     * @param {Array<string>} headers - 可选列顺序
+     * @param {string} encoding - 编码格式，默认 'gbk'，可选 'utf8'
+     */
+    async #writeCsvFile(filePath, data, headers = null, encoding = 'gbk') {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -145,8 +195,15 @@ class ExcelCsvHandler {
             rowDelimiter: '\r\n',
         });
 
-        const gbkBuffer = iconv.encode(csvString, 'gbk');
-        fs.writeFileSync(filePath, gbkBuffer);
+        const buffer = iconv.encode(csvString, encoding);
+
+        // 如果是 UTF-8，添加 BOM 标记以确保 Excel 正确识别
+        if (encoding === 'utf8') {
+            const bom = Buffer.from([0xEF, 0xBB, 0xBF]);
+            fs.writeFileSync(filePath, Buffer.concat([bom, buffer]));
+        } else {
+            fs.writeFileSync(filePath, buffer);
+        }
     }
 
     /**
@@ -154,8 +211,9 @@ class ExcelCsvHandler {
      * @param {string} filePath - 文件路径
      * @param {Array<Object>} data - 要追加的数据
      * @param {Array<string>} headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+     * @param {string} encoding - 编码格式，默认 'gbk'，可选 'utf8'
      */
-    async appendCsv(filePath, data, headers = null) {
+    async appendCsv(filePath, data, headers = null, encoding = 'gbk') {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -167,10 +225,13 @@ class ExcelCsvHandler {
 
         if (!fileExists) {
             // 文件不存在，自动创建并写入标题行和数据
-            await this.#writeCsvFile(filePath, data, headers);
+            await this.#writeCsvFile(filePath, data, headers, encoding);
             return;
         }
 
+        // 文件存在时，检测现有文件的编码
+        const detectedEncoding = this.detectEncoding(filePath);
+
         // 文件存在，追加数据（不包含标题行）
         const csvString = await writeToString(data, {
             headers: false,
@@ -191,11 +252,31 @@ class ExcelCsvHandler {
             }).join(',')
         ).join('\r\n') + '\r\n';
 
-        const gbkBuffer = iconv.encode(rows, 'gbk');
-        fs.appendFileSync(filePath, gbkBuffer);
+        const buffer = iconv.encode(rows, detectedEncoding);
+        fs.appendFileSync(filePath, buffer);
     }
 }
 
+/**
+ * 从调用文件的相对路径获取绝对路径
+ * @param {string} importMetaUrl - 调用文件的 import.meta.url
+ * @param {string} relativePath - 相对路径（如 './dataset/file.docx' 或 'dataset/file.docx'）
+ * @returns {string} 绝对路径
+ * 
+ * @example
+ * // 在你的文件中使用
+ * import ExcelCsvHandler from 'excel-csv-handler';
+ * const docxPath = ExcelCsvHandler.getAbsolutePath(import.meta.url, './dataset/sci-high-question.docx');
+ * const csvPath = ExcelCsvHandler.getAbsolutePath(import.meta.url, 'data/output.csv');
+ */
+ExcelCsvHandler.getAbsolutePath = function (importMetaUrl, relativePath) {
+    const __filename = fileURLToPath(importMetaUrl);
+    const __dirname = path.dirname(__filename);
+    // 去除开头的 './' 如果存在
+    const cleanPath = relativePath.startsWith('./') ? relativePath.slice(2) : relativePath;
+    return path.join(__dirname, cleanPath);
+};
+
 export default ExcelCsvHandler;
 
 // 示例用法（取消注释可测试）

package/debug.js

@@ -1,121 +0,0 @@
-// debug.js - 测试 ExcelCsvHandler
-import ExcelCsvHandler from './src/index.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-const handler = new ExcelCsvHandler();
-
-// 创建测试目录
-const testDir = './test-output';
-if (!fs.existsSync(testDir)) {
-    fs.mkdirSync(testDir, { recursive: true });
-}
-
-console.log('🧪 开始测试 ExcelCsvHandler...\n');
-
-// 测试数据
-const testData = [
-    { 姓名: '张三', 年龄: '25', 城市: '北京' },
-    { 姓名: '李四', 年龄: '30', 城市: '上海' },
-    { 姓名: '王五', 年龄: '28', 城市: '广州' }
-];
-
-const appendData = [
-    { 姓名: '赵六', 年龄: '32', 城市: '深圳' },
-    { 姓名: '孙七', 年龄: '27', 城市: '杭州' }
-];
-
-(async () => {
-    try {
-        // ==================== 测试 1: CSV 写入 ====================
-        console.log('📝 测试 1: CSV 写入');
-        const csvPath = path.join(testDir, 'test.csv');
-        await handler.write(csvPath, testData, ['姓名', '年龄', '城市']);
-        console.log('✅ CSV 写入成功:', csvPath);
-        
-        // ==================== 测试 2: CSV 读取 ====================
-        console.log('\n📖 测试 2: CSV 读取');
-        const csvData = await handler.read(csvPath, 0);
-        console.log('✅ CSV 读取成功，数据:');
-        console.table(csvData);
-        
-        // ==================== 测试 3: appendCsv - 追加到已存在的文件 ====================
-        console.log('\n➕ 测试 3: appendCsv - 追加数据到已存在文件');
-        await handler.appendCsv(csvPath, appendData, ['姓名', '年龄', '城市']);
-        console.log('✅ 追加成功');
-        
-        // 读取追加后的数据
-        const appendedData = await handler.read(csvPath, 0);
-        console.log('📊 追加后的完整数据:');
-        console.table(appendedData);
-        
-        // ==================== 测试 4: appendCsv - 自动创建新文件 ====================
-        console.log('\n🆕 测试 4: appendCsv - 自动创建新文件');
-        const newCsvPath = path.join(testDir, 'new-file.csv');
-        // 确保文件不存在
-        if (fs.existsSync(newCsvPath)) {
-            fs.unlinkSync(newCsvPath);
-        }
-        await handler.appendCsv(newCsvPath, testData, ['姓名', '年龄', '城市']);
-        console.log('✅ 新文件创建成功:', newCsvPath);
-        
-        const newFileData = await handler.read(newCsvPath, 0);
-        console.log('📊 新文件数据:');
-        console.table(newFileData);
-        
-        // ==================== 测试 5: Excel 写入和读取 ====================
-        console.log('\n📊 测试 5: Excel 写入和读取');
-        const xlsxPath = path.join(testDir, 'test.xlsx');
-        await handler.write(xlsxPath, testData, ['姓名', '年龄', '城市'], 'Sheet1');
-        console.log('✅ Excel 写入成功:', xlsxPath);
-        
-        const xlsxData = await handler.read(xlsxPath, 0);
-        console.log('✅ Excel 读取成功，数据:');
-        console.table(xlsxData);
-        
-        // ==================== 测试 6: 包含特殊字符的数据 ====================
-        console.log('\n🔤 测试 6: 包含特殊字符的数据');
-        const specialData = [
-            { 姓名: '测试,逗号', 年龄: '25', 备注: '包含"引号"的内容' },
-            { 姓名: '测试换行', 年龄: '30', 备注: '第一行\n第二行' }
-        ];
-        const specialPath = path.join(testDir, 'special.csv');
-        await handler.write(specialPath, specialData, ['姓名', '年龄', '备注']);
-        console.log('✅ 特殊字符数据写入成功');
-        
-        const specialReadData = await handler.read(specialPath, 0);
-        console.log('✅ 特殊字符数据读取成功:');
-        console.table(specialReadData);
-        
-        // ==================== 测试 7: 连续追加多次 ====================
-        console.log('\n🔄 测试 7: 连续追加多次');
-        const multiAppendPath = path.join(testDir, 'multi-append.csv');
-        if (fs.existsSync(multiAppendPath)) {
-            fs.unlinkSync(multiAppendPath);
-        }
-        
-        // 第一次追加（创建文件）
-        await handler.appendCsv(multiAppendPath, [testData[0]], ['姓名', '年龄', '城市']);
-        console.log('  ✓ 第 1 次追加完成');
-        
-        // 第二次追加
-        await handler.appendCsv(multiAppendPath, [testData[1]], ['姓名', '年龄', '城市']);
-        console.log('  ✓ 第 2 次追加完成');
-        
-        // 第三次追加
-        await handler.appendCsv(multiAppendPath, [testData[2]], ['姓名', '年龄', '城市']);
-        console.log('  ✓ 第 3 次追加完成');
-        
-        const multiAppendData = await handler.read(multiAppendPath, 0);
-        console.log('✅ 连续追加测试成功，最终数据:');
-        console.table(multiAppendData);
-        
-        console.log('\n✨ 所有测试通过！');
-        console.log(`\n📁 测试文件已保存到: ${path.resolve(testDir)}`);
-        
-    } catch (error) {
-        console.error('\n❌ 测试失败:', error.message);
-        console.error(error.stack);
-        process.exit(1);
-    }
-})();

package/test-output/multi-append.csv

@@ -1,4 +0,0 @@
-����,����,����
-����,25,����
-����,30,�Ϻ�
-����,28,����

package/test-output/new-file.csv

@@ -1,4 +0,0 @@
-����,����,����
-����,25,����
-����,30,�Ϻ�
-����,28,����

package/test-output/special.csv

@@ -1,4 +0,0 @@
-����,����,��ע
-"����,����",25,"����""����""������"
-���Ի���,30,"��һ��
-�ڶ���"

package/test-output/test.csv

@@ -1,6 +0,0 @@
-����,����,����
-����,25,����
-����,30,�Ϻ�
-����,28,����
-����,32,����
-����,27,����