excel-csv-handler 1.0.6 → 1.0.10

package/debug.js

@@ -0,0 +1,121 @@
+// 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/package.json

@@ -1,26 +1,26 @@
 {
-	"name": "excel-csv-handler",
-	"version": "1.0.6",
-	"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",
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	},
-	"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"
-	}
-}
+  "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"
+  }
+}

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

@@ -1,10 +1,37 @@
 // src/excel-csv-handler.d.ts
 export default class ExcelCsvHandler {
+	/**
+	 * 读取 Excel 或 CSV 文件（支持 GBK 编码）
+	 * @param filePath - 文件路径
+	 * @param headerRow - 标题行索引（从 0 开始）
+	 * @returns Promise<Array<Object>>
+	 */
 	read(
 		filePath: string,
 		headerRow?: number
 	): Promise<Array<Record<string, string>>>;
+
+	/**
+	 * 写入 Excel 或 CSV 文件（以 GBK 编码保存 CSV，Excel 保持默认）
+	 * @param filePath - 文件路径
+	 * @param data - 要写入的数据
+	 * @param headers - 可选列顺序
+	 * @param sheetName - Excel sheet 名称（默认为 'Sheet1'）
+	 */
 	write(
+		filePath: string,
+		data: Array<Record<string, any>>,
+		headers?: string[] | null,
+		sheetName?: string
+	): Promise<void>;
+
+	/**
+	 * 追加数据到 CSV 文件末尾（以 GBK 编码）
+	 * @param filePath - 文件路径
+	 * @param data - 要追加的数据
+	 * @param headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+	 */
+	appendCsv(
 		filePath: string,
 		data: Array<Record<string, any>>,
 		headers?: string[] | null

package/src/index.js

@@ -19,27 +19,28 @@ class ExcelCsvHandler {
         const ext = path.extname(filePath).toLowerCase();
 
         if (ext === '.xlsx' || ext === '.xls') {
-            return this.readExcelFile(filePath, headerRow);
+            return this.#readExcelFile(filePath, headerRow);
         } else if (ext === '.csv') {
-            return this.readCsvFile(filePath, headerRow);
+            return this.#readCsvFile(filePath, headerRow);
         } else {
             throw new Error(`不支持的文件格式: ${ext}`);
         }
     }
 
     /**
-     * 写入 Excel 或 CSV 文件（以 GBK 编码保存 CSV，Excel 保持默认）
-     * @param {string} filePath - 文件路径
-     * @param {Array<Object>} data - 要写入的数据
-     * @param {Array<string>} headers - 可选列顺序
-     */
-    async write(filePath, data, headers = null) {
+ * 写入 Excel 或 CSV 文件（以 GBK 编码保存 CSV，Excel 保持默认）
+ * @param {string} filePath - 文件路径
+ * @param {Array<Object>} data - 要写入的数据
+ * @param {Array<string>} headers - 可选列顺序
+ * @param {string} sheetName - Excel sheet 名称（默认为 'Sheet1'）
+ */
+    async write(filePath, data, headers = null, sheetName = 'Sheet1') {
         const ext = path.extname(filePath).toLowerCase();
 
         if (ext === '.xlsx' || ext === '.xls') {
-            this.writeExcelFile(filePath, data, headers);
+            this.#writeExcelFile(filePath, data, headers, sheetName);
         } else if (ext === '.csv') {
-            await this.writeCsvFile(filePath, data, headers);
+            await this.#writeCsvFile(filePath, data, headers);
         } else {
             throw new Error(`不支持的文件格式: ${ext}`);
         }
@@ -47,7 +48,7 @@ class ExcelCsvHandler {
 
     // ========= Excel 读写 =========
 
-    readExcelFile(filePath, headerRow) {
+    #readExcelFile(filePath, headerRow) {
         const workbook = XLSX.readFile(filePath);
         const sheetName = workbook.SheetNames[0];
         const worksheet = workbook.Sheets[sheetName];
@@ -79,7 +80,7 @@ class ExcelCsvHandler {
         });
     }
 
-    writeExcelFile(filePath, data, headers = null) {
+    #writeExcelFile(filePath, data, headers = null, sheetName = 'Sheet1') {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -89,13 +90,13 @@ class ExcelCsvHandler {
         const wsData = [headers, ...data.map(row => headers.map(h => row[h] ?? ''))];
         const worksheet = XLSX.utils.aoa_to_sheet(wsData);
         const workbook = XLSX.utils.book_new();
-        XLSX.utils.book_append_sheet(workbook, worksheet, 'Sheet1');
+        XLSX.utils.book_append_sheet(workbook, worksheet, sheetName);
         XLSX.writeFile(workbook, filePath);
     }
 
     // ========= CSV 读写 =========
 
-    async readCsvFile(filePath, headerRow) {
+    async #readCsvFile(filePath, headerRow) {
         return new Promise((resolve, reject) => {
             const allRows = [];
             const stream = fs.createReadStream(filePath)
@@ -131,7 +132,7 @@ class ExcelCsvHandler {
         });
     }
 
-    async writeCsvFile(filePath, data, headers = null) {
+    async #writeCsvFile(filePath, data, headers = null) {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -147,6 +148,52 @@ class ExcelCsvHandler {
         const gbkBuffer = iconv.encode(csvString, 'gbk');
         fs.writeFileSync(filePath, gbkBuffer);
     }
+
+    /**
+     * 追加数据到 CSV 文件末尾（以 GBK 编码）
+     * @param {string} filePath - 文件路径
+     * @param {Array<Object>} data - 要追加的数据
+     * @param {Array<string>} headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+     */
+    async appendCsv(filePath, data, headers = null) {
+        if (!headers && data.length > 0) {
+            headers = Object.keys(data[0]);
+        } else if (!headers) {
+            headers = [];
+        }
+
+        // 检查文件是否存在
+        const fileExists = fs.existsSync(filePath);
+
+        if (!fileExists) {
+            // 文件不存在，自动创建并写入标题行和数据
+            await this.#writeCsvFile(filePath, data, headers);
+            return;
+        }
+
+        // 文件存在，追加数据（不包含标题行）
+        const csvString = await writeToString(data, {
+            headers: false,
+            includeEndRowDelimiter: true,
+            rowDelimiter: '\r\n',
+            writeHeaders: false,
+        });
+
+        // 将数据按照指定的列顺序格式化
+        const rows = data.map(row =>
+            headers.map(h => {
+                const value = row[h] ?? '';
+                // 如果值包含逗号、引号或换行符，需要用引号包裹并转义
+                if (value.toString().includes(',') || value.toString().includes('"') || value.toString().includes('\n')) {
+                    return '"' + value.toString().replace(/"/g, '""') + '"';
+                }
+                return value;
+            }).join(',')
+        ).join('\r\n') + '\r\n';
+
+        const gbkBuffer = iconv.encode(rows, 'gbk');
+        fs.appendFileSync(filePath, gbkBuffer);
+    }
 }
 
 export default ExcelCsvHandler;

package/test-output/multi-append.csv

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

package/test-output/new-file.csv

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

package/test-output/special.csv

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

package/test-output/test.csv

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