Merge pull request exceljs#1169 from Alanscut/issue_1165

fix issue exceljs#1165 and update index.d.ts
stiig · Mar 23, 2020 · ee34509 · ee34509
2 parents 3dc7302 + 5bfe188
commit ee34509
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -1926,6 +1926,15 @@ workbook.xlsx.writeBuffer()
 
 #### Reading CSV
 
+Options supported when reading CSV files.
+
+| Field            |  Required   |    Type     |Description  |
+| ---------------- | ----------- | ----------- | ----------- |
+| dateFormats      |     N       |  Array      | Specify the date encoding format of dayjs. |
+| map              |     N       |  Function   | Custom Array.prototype.map() callback function for processing data. |
+| sheetName        |     N       |  String     | Specify worksheet name. |
+| parserOptions    |     N       |  Object     | [parseOptions options](https://c2fo.io/fast-csv/docs/parsing/options)  @fast-csv/format module to write csv data. |
+
 ```javascript
 // read from a file
 var workbook = new Excel.Workbook();
@@ -1973,7 +1982,12 @@ var options = {
         // the rest are numbers
         return parseFloat(value);
     }
-  }
+  },
+  // https://c2fo.io/fast-csv/docs/parsing/options
+  parserOptions: {
+    delimiter: '\t',
+    quote: false,
+  },
 };
 workbook.csv.readFile(filename, options)
   .then(function(worksheet) {
@@ -1982,7 +1996,7 @@ workbook.csv.readFile(filename, options)
 ```
 
 The CSV parser uses [fast-csv](https://www.npmjs.com/package/fast-csv) to read the CSV file.
- The options passed into the read functions above is also passed to fast-csv for parsing of the csv data.
+The formatterOptions in the options passed to the above write function will be passed to the @fast-csv/format module to write csv data.
  Please refer to the fast-csv README.md for details.
 
 Dates are parsed using the npm module [dayjs](https://www.npmjs.com/package/dayjs).
@@ -1996,6 +2010,19 @@ Please refer to the [dayjs CustomParseFormat plugin](https://github.com/iamkun/d
 
 #### Writing CSV
 
+Options supported when writing to a CSV file.
+
+| Field            |  Required   |    Type     | Description |
+| ---------------- | ----------- | ----------- | ----------- |
+| dateFormat       |     N       |  String     | Specify the date encoding format of dayjs. |
+| dateUTC          |     N       |  Boolean    | Specify whether ExcelJS uses `dayjs.utc ()` to convert time zone for parsing dates. |
+| encoding         |     N       |  String     | Specify file encoding format. |
+| includeEmptyRows |     N       |  Boolean    | Specifies whether empty rows can be written. |
+| map              |     N       |  Function   | Custom Array.prototype.map() callback function for processing row values. |
+| sheetName        |     N       |  String     | Specify worksheet name. |
+| sheetId          |     N       |  Number     | Specify worksheet ID. |
+| formatterOptions |     N       |  Object     | [formatterOptions options](https://c2fo.io/fast-csv/docs/formatting/options/) @fast-csv/format module to write csv data. |
+
 ```javascript
 
 // write to a file
@@ -2043,7 +2070,12 @@ var options = {
         // the rest are numbers
         return value;
     }
-  }
+  },
+  // https://c2fo.io/fast-csv/docs/formatting/options
+  formatterOptions: {
+    delimiter: '\t',
+    quote: false,
+  },
 };
 workbook.csv.writeFile(filename, options)
   .then(() => {
@@ -2058,7 +2090,7 @@ workbook.csv.writeBuffer()
 ```
 
 The CSV parser uses [fast-csv](https://www.npmjs.com/package/fast-csv) to write the CSV file.
- The options passed into the write functions above is also passed to fast-csv for writing the csv data.
+ The formatterOptions in the options passed to the above write function will be passed to the @fast-csv/format module to write csv data.
  Please refer to the fast-csv README.md for details.
 
 Dates are formatted using the npm module [moment](https://www.npmjs.com/package/moment).

diff --git a/README_zh.md b/README_zh.md
@@ -1396,6 +1396,15 @@ workbook.xlsx.writeBuffer()
 
 #### <a id="reading-csv">读 CSV</a>
 
+读取CSV文件时支持的选项。
+
+| Field            |  Required   |    Type     |Description  |
+| ---------------- | ----------- | ----------- | ----------- |
+| dateFormats      |     N       |  Array      | 指定dayjs的日期编码格式 |
+| map              |     N       |  Function   | 自定义 Array.prototype.map() 的callback用于解析数据 |
+| sheetName        |     N       |  String     | 指定工作表名称 |
+| parserOptions    |     N       |  Object     | [parseOptions options](https://c2fo.io/fast-csv/docs/parsing/options) @fast-csv/parse模块以解析csv数据 |
+
 ```javascript
 // read from a file
 var workbook = new Excel.Workbook();
@@ -1443,7 +1452,12 @@ var options = {
         // the rest are numbers
         return parseFloat(value);
     }
-  }
+  },
+  // https://c2fo.io/fast-csv/docs/parsing/options
+  parserOptions: {
+    delimiter: '\t',
+    quote: false,
+  },
 };
 workbook.csv.readFile(filename, options)
   .then(function(worksheet) {
@@ -1452,18 +1466,32 @@ workbook.csv.readFile(filename, options)
 ```
 
 CSV解析器使用[fast-csv](https://www.npmjs.com/package/fast-csv)来读取CSV文件。
- 传递给上述读取函数的选项也传递给fast-csv以解析csv数据。
+ 传递给上述读取函数的parserOptions选项将传递给@fast-csv/parse模块以解析csv数据。
  有关详细信息，请参阅fast-csv README.md。
 
 使用npm模块[moment](https://www.npmjs.com/package/moment)解析日期。
  如果未提供dateFormats，则使用以下内容：
 
-* moment.ISO_8601
-*'MM-DD-YYYY'
-*'YYYY-MM-DD'
+* 'YYYY-MM-DD\[T\]HH:mm:ss'
+* 'MM-DD-YYYY'
+* 'YYYY-MM-DD'
+
+请参阅 [dayjs CustomParseFormat plugin](https://github.com/iamkun/dayjs/blob/HEAD/docs/en/Plugin.md#customparseformat)，以获取有关如何构造dateFormat的详细信息。
 
 #### <a id="writing-csv">写 CSV</a>
 
+写入CSV文件时支持的选项。
+| Field            |  Required   |    Type     |Description  |
+| ---------------- | ----------- | ----------- | ----------- |
+| dateFormat       |     N       |  String     | 指定dayjs的日期编码格式 |
+| dateUTC          |     N       |  Boolean    | 指定ExcelJS是否使用`dayjs.utc（）`转换时区以解析日期 |
+| encoding         |     N       |  String     | 指定文件编码格式 |
+| includeEmptyRows |     N       |  Boolean    | 指定是否可以写入空行 |
+| map              |     N       |  Function   | 自定义Array.prototype.map()的callback，用于处理行值 |
+| sheetName        |     N       |  String     | 指定工作表名称 |
+| sheetId          |     N       |  Number     | 指定工作表ID |
+| formatterOptions |     N       |  Object     | [formatterOptions options](https://c2fo.io/fast-csv/docs/formatting/options/) @fast-csv/format模块以写入csv数据 |
+
 ```javascript
 
 // write to a file
@@ -1511,7 +1539,12 @@ var options = {
         // the rest are numbers
         return value;
     }
-  }
+  },
+  // https://c2fo.io/fast-csv/docs/formatting/options
+  formatterOptions: {
+    delimiter: '\t',
+    quote: false,
+  },
 };
 workbook.csv.writeFile(filename, options)
   .then(() => {
@@ -1526,10 +1559,10 @@ workbook.csv.writeBuffer()
 ```
 
 CSV解析器使用[fast-csv]（https://www.npmjs.com/package/fast-csv）编写CSV文件。
- 传递给上述写入函数的选项也传递给fast-csv以写入csv数据。
- 有关详细信息，请参阅fast-csv README.md。
+ 传递给上述写入函数的选项中的formatterOptions将传递给@fast-csv/format模块以写入csv数据。
+ 有关详细信息，请参阅@fast-csv README.md。
 
-使用npm模块格式化日期[时刻]（https://www.npmjs.com/package/moment）。
+使用npm模块格式化日期[moment]（https://www.npmjs.com/package/moment）。
  如果未提供dateFormat，则使用moment.ISO_8601。
  编写CSV时，您可以将布尔值dateUTC设置为true，以使ExcelJS自动解析日期
  使用`moment.utc（）`转换时区。

diff --git a/index.d.ts b/index.d.ts
@@ -1310,14 +1310,59 @@ export interface Xlsx {
 	write(stream: import('stream').Stream, options?: Partial<XlsxWriteOptions>): Promise<void>;
 }
 
+// https://c2fo.io/fast-csv/docs/parsing/options
+export interface FastCsvParserOptionsArgs {
+	objectMode: boolean;
+	delimiter: string;
+	quote: string | null;
+	escape: string;
+	headers: boolean | HeaderTransformFunction | HeaderArray;
+	renameHeaders: boolean;
+	ignoreEmpty: boolean;
+	comment: string;
+	strictColumnHandling: boolean;
+	discardUnmappedColumns: boolean;
+	trim: boolean;
+	ltrim: boolean;
+	rtrim: boolean;
+	encoding: string;
+	maxRows: number;
+	skipLines: number;
+	skipRows: number;
+}
+
+// https://c2fo.io/fast-csv/docs/formatting/options/
+export interface FastCsvFormatterOptionsArgs {
+	objectMode: boolean;
+	delimiter: string;
+	rowDelimiter: string;
+	quote: string | boolean;
+	escape: string;
+	quoteColumns: QuoteColumns;
+	quoteHeaders: QuoteColumns;
+	headers: null | boolean | string[];
+	includeEndRowDelimiter: boolean;
+	writeBOM: boolean;
+	transform: RowTransformFunction;
+	alwaysWriteHeaders: boolean;
+}
+
 export interface CsvReadOptions {
 	dateFormats: string[];
 	map(value: any, index: number): any;
+	sheetName: string;
+	parserOptions: Partial<FastCsvParserOptionsArgs>;
 }
 
 export interface CsvWriteOptions {
 	dateFormat: string;
 	dateUTC: boolean;
+	sheetName: string;
+	sheetId: number;
+	encoding: string;
+	map(value: any, index: number): any;
+	includeEmptyRows: boolean;
+	formatterOptions: Partial<FastCsvFormatterOptionsArgs>;
 }
 
 export interface Csv {
@@ -1334,12 +1379,12 @@ export interface Csv {
 	/**
 	 * Create input stream for reading
 	 */
-	createInputStream(): import('events').EventEmitter;
+	createInputStream(options?: Partial<CsvReadOptions>): import('events').EventEmitter;
 
 	/**
 	 * write to a buffer
 	 */
-	writeBuffer(): Promise<Buffer>;
+	writeBuffer(options?: Partial<CsvWriteOptions>): Promise<Buffer>;
 
 	/**
 	 * write to a file

diff --git a/lib/csv/csv.js b/lib/csv/csv.js
@@ -1,7 +1,10 @@
 const fs = require('fs');
 const fastCsv = require('fast-csv');
 const customParseFormat = require('dayjs/plugin/customParseFormat');
-const dayjs = require('dayjs').extend(customParseFormat);
+const utc = require('dayjs/plugin/utc');
+const dayjs = require('dayjs')
+  .extend(customParseFormat)
+  .extend(utc);
 const StreamBuf = require('../utils/stream-buf');
 
 const {
@@ -86,7 +89,7 @@ class CSV {
       };
 
     const csvStream = fastCsv
-      .parse(options)
+      .parse(options.parserOptions)
       .on('data', data => {
         worksheet.addRow(data.map(map));
       })
@@ -105,7 +108,7 @@ class CSV {
 
       const worksheet = this.workbook.getWorksheet(options.sheetName || options.sheetId);
 
-      const csvStream = fastCsv.format(options);
+      const csvStream = fastCsv.format(options.formatterOptions);
       stream.on('finish', () => {
         resolve();
       });

diff --git a/spec/integration/workbook/workbook.spec.js b/spec/integration/workbook/workbook.spec.js
@@ -464,6 +464,42 @@ describe('Workbook', () => {
         });
     });
 
+    it('CSV file and its configuration', function() {
+      this.timeout(5000);
+      const writeOptions = {
+        dateFormat: 'DD/MM/YYYY HH:mm:ss',
+        dateUTC: false,
+        encoding: 'utf-8',
+        includeEmptyRows: false,
+        sheetName: 'sheet1',
+        formatterOptions: {
+          delimiter: '\t',
+          quote: false,
+        },
+      };
+      const readOptions = {
+        dateFormats: ['DD/MM/YYYY HH:mm:ss'],
+        sheetName: 'sheet1',
+        parserOptions: {
+          delimiter: '\t',
+          quote: false,
+        },
+      };
+      const wb = testUtils.createTestBook(new ExcelJS.Workbook(), 'csv');
+
+      return wb.csv
+        .writeFile(TEST_CSV_FILE_NAME, writeOptions)
+        .then(() => {
+          const wb2 = new ExcelJS.Workbook();
+          return wb2.csv
+            .readFile(TEST_CSV_FILE_NAME, readOptions)
+            .then(() => wb2);
+        })
+        .then(wb2 => {
+          testUtils.checkTestBook(wb2, 'csv', false, writeOptions);
+        });
+    });
+
     it('defined names', () => {
       const wb1 = new ExcelJS.Workbook();
       const ws1a = wb1.addWorksheet('blort');