CSV.js
Simple, blazing-fast CSV parsing/encoding in JavaScript. Full RFC 4180 compliance.
Compatible with browsers (>IE8), AMD, and NodeJS.
Installation
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 ownarray
to override autocasting. Defaults totrue
.lineDelimiter
: Thestring
that separates lines from one another. If parsing, defaults to autodetection. If encoding, defaults to'\r\n'
.cellDelimiter
: A 1-character-longstring
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 ownarray
. Defaults tofalse
.
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:
// The instance will set itself up for parsing or encoding on instantiation,// which means that each instance can only either parse or encode.// The `options` object is optionalvar csv = data options; // If the data you've supplied is an array,// CSV#encode will return the encoded CSV.// It will otherwise fail silently.var encoded = csv; // If the data you've suopplied is a string,// CSV#parse will return the parsed CSV.// It will otherwise fail silently.var parsed = csv; // The CSV instance can return the record immediately after// it's been encoded or parsed to prevent storing the results// in a large array by calling CSV#forEach and passing in a function.csv; // CSV includes some convenience class methods:CSV; // identical to `new CSV(data, options).parse()`CSV; // identical to `new CSV(data, options).encode()`CSV; // identical to `new CSV(data, options).forEach(callback)` // For overriding automatic casting, set `options.cast` to an array.// For `parsing`, valid array values are: 'Number', 'Boolean', and 'String'.CSV;// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.CSV;
Parsing
By default CSV.js will return an array of arrays
.
var data = '\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...';data/*Returns:[ [1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841] ...]*/
If the CSV's first row is a header, set header
to true
, and CSV.js will return an array of objects
.
var data = '\year,age,status,sex,population\r\n\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...';data header: true ;/*Returns:[ { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 }, { year: 1850, age: 20, status: 0, sex: 2, population: 1003841 } ...]*/
You may also supply your own header values, if the text does not contain them, by setting header
to an array
of field values.
var data = '\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...';data header: 'year' 'age' 'status' 'sex' 'population';/*Returns:[ { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 }, { year: 1850, age: 20, status: 0, sex: 2, population: 1003841 } ...]*/
Encoding
CSV.js accepts an array of arrays
or an array of objects
.
var data = 1850 20 0 1 1017281 1850 20 0 2 1003841...;data;/*Returns:1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...*/
To add headers to an array of arrays
, set header
to an array
of header field values.
var data = 1850 20 0 1 1017281 1850 20 0 2 1003841;data header: "year" "age" "status" "sex" "population" ;/*Returns:"year","age","status","sex","population"\r\n\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\*/
To add headers to an array of objects
, just set header
to true
.
var data = year: 1850 age: 20 status: 0 sex: 1 population: 1017281 year: 1850 age: 20 status: 0 sex: 2 population: 1003841 ;data header: true ;/*Returns:"year","age","status","sex","population"\r\n\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\*/
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.
var data = '\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...';data;
Likewise, if you've requested an array of objects
, you can still call CSV.prototype.forEach
:
var data = '\year,age,status,sex,population\r\n\1850,20,0,1,1017281\r\n\1850,20,0,2,1003841\r\n\...';data header: true ;
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:
var data = 1850 20 0 1 1017281 1850 20 0 2 1003841;data;
Casting
// For overriding automatic casting, set `options.cast` to an array.// For `parsing`, valid array values are: 'Number', 'Boolean', and 'String'.CSV;// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.CSV;
Convenience Methods
CSV // identical to `new CSV(data, options).parse()`CSV // identical to `new CSV(data, options).encode()`CSV // identical to `new CSV(data, options).forEach(callback)`
Special Thanks
- Benjamin Gruenbaum for helping improve performance.