Simple, blazing-fast CSV parsing/encoding in JavaScript. Full RFC 4180 compliance.
npm install @afzalimdad9/comma-separated-valuesCSV.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 @afzalimdad9/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:
``javascript
options
// The instance will set itself up for parsing or encoding on instantiation,
// which means that each instance can only either parse or encode.
// The object is optional
new CSV(data, options).parse()
var csv = new 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.encode();
// If the data you've supplied is a string,
// CSV#parse will return the parsed CSV.
// It will otherwise fail silently.
var parsed = csv.parse();
// 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.forEach(function(record) {
// do something with the record
});
// CSV includes some convenience class methods:
CSV.parse(data, options); // identical to
new CSV(data, options).encode()
CSV.encode(data, options); // identical to
new CSV(data, options).forEach(callback)
CSV.forEach(data, options, callback); // identical to
options.cast
// For overriding automatic casting, set to an array.
parsing
// For , valid array values are: 'Number', 'Boolean', and 'String'.
encoding
CSV.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
// For , valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
`
CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });
array of arrays
Parsing
-------
By default CSV.js will return an .
`
javascript
`
var data = '\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
';
new CSV(data).parse()
/*
Returns:
[
[1850, 20, 0, 1, 1017281],
[1850, 20, 0, 2, 1003841]
...
]
*/
header
If the CSV's first row is a header, set to true, and CSV.js will return an array of objects.
`
javascript
`
var data = '\
year,age,status,sex,population\r\n\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
';
new CSV(data, { header: true }).parse();
/*
Returns:
[
{ year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
{ year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
...
]
*/
header
You may also supply your own header values, if the text does not contain them, by setting to an array of field values.
`
javascript
`
var data = '\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
';
new CSV(data, {
header: ['year', 'age', 'status', 'sex', 'population']
}).parse();
/*
Returns:
[
{ year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
{ year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
...
]
*/
array of arrays
Encoding
--------
CSV.js accepts an or an array of objects.
`
javascript
`
var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]...];
new CSV(data).encode();
/*
Returns:
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
*/
array of arrays
To add headers to an , set header to an array of header field values.
`
javascript
`
var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]];
new CSV(data, { header: ["year", "age", "status", "sex", "population"] }).encode();
/*
Returns:
"year","age","status","sex","population"\r\n\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
*/
array of objects
To add headers to an , just set header to true.
`
javascript
`
var data = [
{ year: 1850, age: 20, status: 0, sex: 1, population: 1017281 },
{ year: 1850, age: 20, status: 0, sex: 2, population: 1003841 }
];
new CSV(data, { header: true }).encode();
/*
Returns:
"year","age","status","sex","population"\r\n\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
*/
CSV.prototype.forEach
Streaming
---------
If the dataset that you've provided is to be parsed, calling and supplying a function will call your function and supply it with the parsed record immediately after it's been parsed.
`
javascript
`
var data = '\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
';
new CSV(data).forEach(function(array) {
/*
* do something with the incoming array
* array example:
* [1850, 20, 0, 1, 1017281]
*/
});
array of objects
Likewise, if you've requested an , you can still call CSV.prototype.forEach:
`
javascript
`
var data = '\
year,age,status,sex,population\r\n\
1850,20,0,1,1017281\r\n\
1850,20,0,2,1003841\r\n\
...
';
new CSV(data, { header: true }).forEach(function(object) {
/*
* do something with the incoming object
* object example:
* { year: 1850, age: 20, status: 0, sex: 1, population: 1017281 }
*/
});
CSV.prototype.forEach
If you're dataset is to be encoded, will call your function and supply the CSV-encoded line immediately after the line has been encoded:
`
javascript
`
var data = [[1850, 20, 0, 1, 1017281], [1850, 20, 0, 2, 1003841]];
new CSV(data).forEach(function(line) {
/*
* do something with the incoming line
* line example:
* "1850,20,0,1,1017281\r\n\""
*/
});
`
Casting
-------
javascript
options.cast
// For overriding automatic casting, set to an array.
parsing
// For , valid array values are: 'Number', 'Boolean', and 'String'.
encoding
CSV.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
// For , valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
`
CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });
`
Convenience Methods
-------------------
javascript
new CSV(data, options).parse()
CSV.parse(data, options) // identical to
new CSV(data, options).encode()
CSV.encode(data, options) // identical to
new CSV(data, options).forEach(callback)
CSV.forEach(data, options, callback) // identical to
``