Skip to content

Commit 5e0c6cd

Browse files
BendingBenderBendingBender
authored
feat(TS): expose TS interfaces, add type tests (#128)
fix: change `skipComments` option type to `boolean | string`
1 parent 73dcfe1 commit 5e0c6cd

6 files changed

Lines changed: 898 additions & 57 deletions

File tree

‎.travis.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
language: node_js
22
node_js:
3+
- 12
34
- 10
45
- 8
56
- 6

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,13 +112,13 @@ csv({ separator: '\t' });
112112

113113
## API
114114

115-
### csv([options|headers])
115+
### csv([options | headers])
116116

117-
Returns: `Array[object]`
117+
Returns: `Array[Object]`
118118

119119
#### options
120120

121-
Type: `object`
121+
Type: `Object`
122122

123123
As an alternative to passing an `options` object, you may pass an `Array[String]`
124124
which specifies the headers to use. For example:
@@ -140,7 +140,7 @@ in a CSV row.
140140

141141
##### headers
142142

143-
Type: `Array[String]|boolean`
143+
Type: `Array[String] | Boolean`
144144

145145
Specifies the headers to use. Headers define the property key for each value in
146146
a CSV row. If no `headers` option is provided, `csv-parser` will use the first

‎index.d.ts‎

Lines changed: 143 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,146 @@
1-
declare module 'csv-parser' {
2-
import { Transform } from 'stream';
3-
4-
interface CsvParser extends Transform {}
5-
interface CsvParserOptions {
6-
escape?: string;
7-
headers?: ReadonlyArray<string> | boolean;
8-
mapHeaders?: (args: { header: string; index: number }) => string | null;
9-
mapValues?: (args: { header: string; index: number; value: any }) => any;
10-
newline?: string;
11-
quote?: string;
12-
raw?: boolean;
13-
separator?: string;
14-
skipComments?: number | string;
15-
skipLines?: number;
16-
maxRowBytes?: number;
17-
strict?: boolean;
18-
}
1+
/// <reference types="node"/>
2+
import { Transform } from 'stream';
3+
4+
declare namespace csvParser {
5+
type CsvParser = Transform;
6+
7+
interface Options {
8+
/**
9+
* A single-character string used to specify the character used to escape strings in a CSV row.
10+
*
11+
* @default '"'
12+
*/
13+
readonly escape?: string;
14+
15+
/**
16+
* Specifies the headers to use. Headers define the property key for each value in a CSV row. If no `headers` option is provided, `csv-parser` will use the first line in a CSV file as the header specification.
17+
*
18+
* If `false`, specifies that the first row in a data file does _not_ contain headers, and instructs the parser to use the row index as the key for each row.
19+
*
20+
* Suppose you have a CSV file `data.csv` which contains the data:
21+
*
22+
* ```
23+
NAME,AGE
24+
Daffy Duck,24
25+
Bugs Bunny,22
26+
```
27+
* Using `headers: false` with the data from `data.csv` would yield:
28+
* ```
29+
[
30+
{ '0': 'Daffy Duck', '1': 24 },
31+
{ '0': 'Bugs Bunny', '1': 22 }
32+
]
33+
```
34+
*/
35+
readonly headers?: ReadonlyArray<string> | boolean;
36+
37+
/**
38+
* A function that can be used to modify the values of each header. Return `null` to remove the header, and it's column, from the results.
39+
*
40+
* @example
41+
*
42+
* csv({
43+
* mapHeaders: ({ header, index }) => header.toLowerCase()
44+
* });
45+
*/
46+
readonly mapHeaders?: (args: { header: string; index: number }) => string | null;
47+
48+
/**
49+
* A function that can be used to modify the value of each column value.
50+
*
51+
* @example
52+
*
53+
* csv({
54+
* mapValues: ({ header, index, value }) => value.toLowerCase()
55+
* });
56+
*/
57+
readonly mapValues?: (args: { header: string; index: number; value: any }) => any;
58+
59+
/**
60+
* Specifies a single-character string to denote the end of a line in a CSV file.
61+
*
62+
* @default '\n'
63+
*/
64+
readonly newline?: string;
65+
66+
/**
67+
* Specifies a single-character string to denote a quoted string.
68+
*
69+
* @default '"'
70+
*/
71+
readonly quote?: string;
1972

20-
const csvParser: (
21-
optionsOrHeaders?: CsvParserOptions | ReadonlyArray<string>
22-
) => CsvParser;
73+
/**
74+
* If `true`, instructs the parser not to decode UTF-8 strings.
75+
*/
76+
readonly raw?: boolean;
2377

24-
export = csvParser;
78+
/**
79+
* Specifies a single-character string to use as the column separator for each row.
80+
*
81+
* @default ','
82+
*/
83+
readonly separator?: string;
84+
85+
/**
86+
* Instructs the parser to ignore lines which represent comments in a CSV file. Since there is no specification that dictates what a CSV comment looks like, comments should be considered non-standard. The "most common" character used to signify a comment in a CSV file is `"#"`. If this option is set to `true`, lines which begin with `#` will be skipped. If a custom character is needed to denote a commented line, this option may be set to a string which represents the leading character(s) signifying a comment line.
87+
*
88+
* @default false
89+
*/
90+
readonly skipComments?: boolean | string;
91+
92+
/**
93+
* Specifies the number of lines at the beginning of a data file that the parser should skip over, prior to parsing headers.
94+
*
95+
* @default 0
96+
*/
97+
readonly skipLines?: number;
98+
99+
/**
100+
* Maximum number of bytes per row. An error is thrown if a line exeeds this value. The default value is on 8 peta byte.
101+
*
102+
* @default Number.MAX_SAFE_INTEGER
103+
*/
104+
readonly maxRowBytes?: number;
105+
106+
/**
107+
* If `true`, instructs the parser that the number of columns in each row must match the number of `headers` specified.
108+
*/
109+
readonly strict?: boolean;
110+
}
25111
}
112+
113+
/**
114+
* Streaming CSV parser that aims for maximum speed as well as compatibility with the [csv-spectrum](https://npmjs.org/csv-spectrum) CSV acid test suite.
115+
*
116+
* @param optionsOrHeaders - As an alternative to passing an `options` object, you may pass an `Array[String]` which specifies the headers to use. If you need to specify options _and_ headers, please use the the object notation with the `headers` property.
117+
*
118+
* @example
119+
*
120+
* // data.csv:
121+
* //
122+
* // NAME,AGE
123+
* // Daffy Duck,24
124+
* // Bugs Bunny,22
125+
*
126+
* import csv = require('csv-parser');
127+
* import * as fs from 'fs';
128+
*
129+
* const results = [];
130+
*
131+
* fs.createReadStream('data.csv')
132+
* .pipe(csv())
133+
* .on('data', (data) => results.push(data))
134+
* .on('end', () => {
135+
* console.log(results);
136+
* // [
137+
* // { NAME: 'Daffy Duck', AGE: '24' },
138+
* // { NAME: 'Bugs Bunny', AGE: '22' }
139+
* // ]
140+
* });
141+
*/
142+
declare const csvParser: (
143+
optionsOrHeaders?: csvParser.Options | ReadonlyArray<string>
144+
) => csvParser.CsvParser;
145+
146+
export = csvParser;

‎index.test-d.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import { expectType } from 'tsd';
2+
import csvParser = require('.');
3+
4+
const options: csvParser.Options = {};
5+
6+
expectType<csvParser.CsvParser>(csvParser(['Name', 'Age']));
7+
expectType<csvParser.CsvParser>(csvParser({ escape: '"' }));
8+
expectType<csvParser.CsvParser>(csvParser({ headers: ['Name', 'Age'] }));
9+
expectType<csvParser.CsvParser>(csvParser({ headers: false }));
10+
expectType<csvParser.CsvParser>(
11+
csvParser({
12+
mapHeaders: ({ header, index }) => {
13+
expectType<string>(header);
14+
expectType<number>(index);
15+
return header.toLowerCase();
16+
},
17+
})
18+
);
19+
expectType<csvParser.CsvParser>(csvParser({ mapHeaders: ({ header, index }) => null }));
20+
expectType<csvParser.CsvParser>(
21+
csvParser({
22+
mapValues: ({ header, index, value }) => {
23+
expectType<string>(header);
24+
expectType<number>(index);
25+
expectType<any>(value);
26+
27+
return value.toLowerCase();
28+
},
29+
})
30+
);
31+
expectType<csvParser.CsvParser>(csvParser({ mapValues: ({ header, index, value }) => null }));
32+
expectType<csvParser.CsvParser>(csvParser({ newline: '\n' }));
33+
expectType<csvParser.CsvParser>(csvParser({ quote: '"' }));
34+
expectType<csvParser.CsvParser>(csvParser({ raw: true }));
35+
expectType<csvParser.CsvParser>(csvParser({ separator: ',' }));
36+
expectType<csvParser.CsvParser>(csvParser({ skipComments: true }));
37+
expectType<csvParser.CsvParser>(csvParser({ skipComments: '#' }));
38+
expectType<csvParser.CsvParser>(csvParser({ skipLines: 1 }));
39+
expectType<csvParser.CsvParser>(csvParser({ maxRowBytes: 1 }));
40+
expectType<csvParser.CsvParser>(csvParser({ strict: true }));

0 commit comments

Comments
 (0)