CSV.js

Simple, blazing-fast CSV parsing/encoding in JavaScript. Full RFC 4180 compliance.

Compatible with browsers (>IE8), AMD, and NodeJS.

Installation

MASTER is currently under development. As such, csv.src.js and csv.js are both unusable. Make sure you download csv.min.js.

Download csv.min.js and reference to it using your preferred method.

If you use Bower, or npm, install the comma-separated-values package.

Instantiation

Create a CSV instance with var csv = new CSV(data);, where data is a plain-text CSV string. You can supply options with the format var csv = new CSV(data, { option: value });.

Options

• cast: true to automatically cast numbers and booleans to their JavaScript equivalents. false otherwise. Supply your own array to override autocasting. Defaults to true.
• lineDelimiter: The string that separates lines from one another. If parsing, defaults to autodetection. If encoding, defaults to '\r\n'.
• cellDelimiter: A 1-character-long string that separates values from one another. If parsing, defaults to autodetection. If encoding, defaults to ','.
• header: true if the first row of the CSV contains header values, or supply your own array. Defaults to false.

You can update an option's value any time after instantiation with csv.set(option, value).

Quickstart

For those accustomed to JavaScript, the CSV.js API:

1// The instance will set itself up for parsing or encoding on instantiation,
2// which means that each instance can only either parse or encode.
3// The `options` object is optional
4var csv = new CSV(data, [options]);
5
6// If the data you've supplied is an array,
7// CSV#encode will return the encoded CSV.
8// It will otherwise fail silently.
9var encoded = csv.encode();
10
11// If the data you've supplied is a string,
12// CSV#parse will return the parsed CSV.
13// It will otherwise fail silently.
14var parsed = csv.parse();
15
16// The CSV instance can return the record immediately after
17// it's been encoded or parsed to prevent storing the results
18// in a large array by calling CSV#forEach and passing in a function.
19csv.forEach(function(record) {
20  // do something with the record
21});
22
23// CSV includes some convenience class methods:
24CSV.parse(data, options); // identical to `new CSV(data, options).parse()`
25CSV.encode(data, options); // identical to `new CSV(data, options).encode()`
26CSV.forEach(data, options, callback); // identical to `new CSV(data, options).forEach(callback)`
27
28// For overriding automatic casting, set `options.cast` to an array.
29// For `parsing`, valid array values are: 'Number', 'Boolean', and 'String'.
30CSV.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
31// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
32CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });

Parsing

By default CSV.js will return an array of arrays.

1var data = '\
21850,20,0,1,1017281\r\n\
31850,20,0,2,1003841\r\n\
4...
5';
6new CSV(data).parse()
7/*
8Returns:
9[
10  [1850, 20, 0, 1, 1017281],
11  [1850, 20, 0, 2, 1003841]
12  ...
13]
14*/

If the CSV's first row is a header, set header to true, and CSV.js will return an array of objects.

1var data = '\
2year,age,status,sex,population\r\n\
31850,20,0,1,1017281\r\n\
41850,20,0,2,1003841\r\n\
5...
6';
7new CSV(data, { header: true }).parse();
8/*
9Returns:
10[
11  { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
12  { year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
13  ...
14]
15*/

You may also supply your own header values, if the text does not contain them, by setting header to an array of field values.

1var data = '\
21850,20,0,1,1017281\r\n\
31850,20,0,2,1003841\r\n\
4...
5';
6new CSV(data, {
7  header: ['year', 'age', 'status', 'sex', 'population']
8}).parse();
9/*
10Returns:
11[
12  { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
13  { year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
14  ...
15]
16*/

Encoding

CSV.js accepts an array of arrays or an array of objects.

1var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]...];
2new CSV(data).encode();
3/*
4Returns:
51850,20,0,1,1017281\r\n\
61850,20,0,2,1003841\r\n\
7...
8*/

To add headers to an array of arrays, set header to an array of header field values.

1var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]];
2new CSV(data, { header: ["year", "age", "status", "sex", "population"] }).encode();
3/*
4Returns:
5"year","age","status","sex","population"\r\n\
61850,20,0,1,1017281\r\n\
71850,20,0,2,1003841\r\n\
8*/

To add headers to an array of objects, just set header to true.

1var data = [
2  { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
3  { year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
4];
5new CSV(data, { header: true }).encode();
6/*
7Returns:
8"year","age","status","sex","population"\r\n\
91850,20,0,1,1017281\r\n\
101850,20,0,2,1003841\r\n\
11*/

Streaming

If the dataset that you've provided is to be parsed, calling CSV.prototype.forEach and supplying a function will call your function and supply it with the parsed record immediately after it's been parsed.

1var data = '\
21850,20,0,1,1017281\r\n\
31850,20,0,2,1003841\r\n\
4...
5';
6new CSV(data).forEach(function(array) {
7  /*
8   * do something with the incoming array
9   * array example:
10   *   [1850, 20, 0, 1, 1017281]
11   */
12});

Likewise, if you've requested an array of objects, you can still call CSV.prototype.forEach:

1var data = '\
2year,age,status,sex,population\r\n\
31850,20,0,1,1017281\r\n\
41850,20,0,2,1003841\r\n\
5...
6';
7new CSV(data, { header: true }).forEach(function(object) {
8  /*
9   * do something with the incoming object
10   * object example:
11   *   { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 }
12   */
13});

If you're dataset is to be encoded, CSV.prototype.forEach will call your function and supply the CSV-encoded line immediately after the line has been encoded:

1var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]];
2new CSV(data).forEach(function(line) {
3  /*
4   * do something with the incoming line
5   * line example:
6   *   "1850,20,0,1,1017281\r\n\""
7   */
8});

Casting

1// For overriding automatic casting, set `options.cast` to an array.
2// For `parsing`, valid array values are: 'Number', 'Boolean', and 'String'.
3CSV.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
4// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
5CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });

Convenience Methods

1CSV.parse(data, options) // identical to `new CSV(data, options).parse()`
2CSV.encode(data, options) // identical to `new CSV(data, options).encode()`
3CSV.forEach(data, options, callback) // identical to `new CSV(data, options).forEach(callback)`

Special Thanks

• Benjamin Gruenbaum for helping improve performance.