# comma-separated-values

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

Latest version **3.6.4** (published 2015-10-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install comma-separated-values
pnpm add comma-separated-values
yarn add comma-separated-values
bun add comma-separated-values
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.6.4 |
| Published | 2015-10-27 |
| First published | 2014-05-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1533 |
| Author | = |
| Maintainers | knrz |
| Keywords | csv, csv parse, csv encode, csv rfc, tsv, tsv parse, tsv encode, tsv rfc |

## Links

- npm: https://www.npmjs.com/package/comma-separated-values
- Repository: https://github.com/knrz/CSV.js
- Issues: https://github.com/knrz/CSV.js/issues
- npm.io page: https://npm.io/package/comma-separated-values

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 3.6.4 (latest) — 2015-10-27
- 3.6.3 — 2015-08-05
- 3.6.2 — 2015-05-25
- 3.6.1 — 2014-11-04
- 3.6.0 — 2014-09-07
- 3.5.1 — 2014-09-07
- 3.5.0 — 2014-09-07
- 3.4.1 — 2014-09-07
- 3.4.0 — 2014-09-06
- 3.3.1 — 2014-09-02
- 3.3.0 — 2014-08-17
- 3.2.2 — 2014-08-17
- 3.2.1 — 2014-06-21
- 3.2.0 — 2014-06-15
- 3.1.3 — 2014-06-15
- … 9 more at https://npm.io/package/comma-separated-values/versions

## README

CSV.js
======

Simple, blazing-fast CSV parsing/encoding in JavaScript. Full [RFC 4180](http://tools.ietf.org/html/rfc4180) 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 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
// 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 optional
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 suopplied 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).parse()`
CSV.encode(data, options); // identical to `new CSV(data, options).encode()`
CSV.forEach(data, options, callback); // 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.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });
```


Parsing
-------

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

```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]
  ...
]
*/
```


If the CSV's first row is a header, set `header` 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 }
  ...
]
*/
```


You may also supply your own header values, if the text does not contain them, by setting `header` 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 }
  ...
]
*/
```


Encoding
--------

CSV.js accepts an `array of arrays` 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\
...
*/
```


To add headers to an `array of arrays`, 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\
*/
```


To add headers to an `array of objects`, 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\
*/
```


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.

```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]
   */
});
```

Likewise, if you've requested an `array of objects`, 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 }
   */
});
```


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:

```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
// For overriding automatic casting, set `options.cast` to an array.
// For `parsing`, valid array values are: 'Number', 'Boolean', and 'String'.
CSV.parse(data, { cast: ['String', 'Number', 'Number', 'Boolean'] });
// For `encoding`, valid array values are 'Array', 'Object', 'String', 'Null', and 'Primitive'.
CSV.encode(data, { cast: ['Primitive', 'Primitive', 'String'] });
```


Convenience Methods
-------------------

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


Special Thanks
--------------

- [Benjamin Gruenbaum](https://github.com/benjamingr) for helping improve performance.

---
_Source: https://npm.io/package/comma-separated-values · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._