json-2-csv

Installation

$ npm install json-2-csv

$ npm install @mrodrig/json-2-csv-cli

Upgrading?

Usage

let converter = require('json-2-csv');
const csv = await converter.json2csv(data, options);

import { json2csv } from 'json-2-csv';

API

json2csv(array, options) => string

• array - An array of JSON documents to be converted to CSV.
• options - (Optional) A JSON document specifying any of the following key value pairs:

* Default: `false`
* Note: This provides a more accurate representation of the JSON in the returned CSV, but may be less human readable. See [#207](https://github.com/mrodrig/json-2-csv/issues/207) for more details.

* Default: `false`
* Note: An error will be thrown if some documents have differing schemas when this is set to `true`.

* `field` - String - Field Delimiter. 
  * Default: `,`
* `wrap` - String - Wrap values in the delimiter of choice (e.g. wrap values in quotes). 
  * Default: `"`
* `eol` - String - End of Line Delimiter. 
  * Default: `\n`

* Default: none

* Default: `true`
* Example:
```json
[
  {
    "a.a": "1"
  }
]
```
  * `true` will generate the following CSV:
  ```csv
  a\.a
  1
  ```
  * `false` will generate the following CSV:
  ```csv
  a.a
  1
  ```
* Note: This may result in CSV output that does not map back exactly to the original JSON.

* Default: `[]`
* Note: When used with `unwindArrays`, arrays present at excluded key paths will not be unwound.

```json
[
	{
      "make": "Nissan",
      "model": "Murano",
      "year": 2013,
      "specifications": {
        "mileage": 7106,
        "trim": "S AWD"
      }
    }
]
```

* Note: This may result in CSV output that does not map back exactly to the original JSON.

```json
[
	{ 
		"specifications": [
			{ "features": [...] },
			{ "mileage": "5000" }
		]
	}
]
```

* Note: This may result in CSV output that does not map back exactly to the original JSON. See #102 for more information.

* Default: These will be auto-detected from your data by default.
* Keys can either be specified as a String representing the key path that should be converted, or as an Object of the following format:
```javascript
{
  "field": "string", // required
  "title": "string", // optional
  "wildcardMatch": false, // optional - default: false
}
```
  * When specifying keys as an Object, the `field` property specifies the key path, while `title` specifies a more human readable field heading. Additionally, the `wildcardMatch` option allows you to optionally specify that all auto-detected fields with the specified field prefix should be included in the CSV. The list specified can contain a combination of Objects and Strings.
  * Examples:
    * `[ 'key1', 'key2', ... ]`
    * `[ 'key1', { field: 'key2', wildcardMatch: true }]`
    * `[ { field: 'key1', title: 'Key 1' }, { field: 'key2' }, 'key3', ... ]`
* Key Paths - If you are converting a nested object (ie. {info : {name: 'Mike'}}), then set this to ['info.name']

* Default: A built-in method is used to parse out a variety of different value types to well-known formats.
* Note: Using this option may override other options, including `useDateIso8601Format` and `useLocaleFormat`.

* Default: `true`

* Default: `false`

* Default: `false`

* Default: `false`

* Default: `false`
* Example:
```json
[
    {
        "_id": {"$oid": "5cf7ca3616c91100018844af"},
        "data": {"category": "Computers", "options": [{"name": "MacBook Pro 15"}, {"name": "MacBook Air 13"}]}
    },
    {
        "_id": {"$oid": "5cf7ca3616c91100018844bf"},
        "data": {"category": "Cars", "options": [{"name": "Supercharger"}, {"name": "Turbocharger"}]}
    }
]
```
* `true` will unwind the JSON to four objects, and therefore four lines of CSV values:
```csv
_id.$oid,data.category,data.options.name
5cf7ca3616c91100018844af,Computers,MacBook Pro 15
5cf7ca3616c91100018844af,Computers,MacBook Air 13
5cf7ca3616c91100018844bf,Cars,Supercharger
5cf7ca3616c91100018844bf,Cars,Turbocharger
```
* `false` will leave the values unwound and will convert the array as-is (when this option is used without expandArrayObjects):
```csv
_id.$oid,data.category,data.options
5cf7ca3616c91100018844af,Computers,"[{""name"":""MacBook Pro 15""},{""name"":""MacBook Air 13""}]"
5cf7ca3616c91100018844bf,Cars,"[{""name"":""Supercharger""},{""name"":""Turbocharger""}]"
```

* Default: `false`
* Note: If selected, values will be converted using `toISOString()` rather than `toString()` or `toLocaleString()` depending on the other options provided.

* Default: `false`
* Note: If selected, values will be converted using `toLocaleString()` rather than `toString()`

* Default: `false`

* Default: `false`

* `field` - String - Field Delimiter. 
  * Default: `,`
* `wrap` - String - The character that field values are wrapped in. 
  * Default: `"`
* `eol` - String - End of Line Delimiter. 
  * Default: `\n`

* Default: `false`

* Default: Parses the header fields directly from the CSV string
* If you want to generate a nested object (ie. `{info : {name: 'Mike'}}`), then use `.` characters in the string to denote a nested field, like ['info.name']
* If your CSV has a header line included, then don't specify the option to utilize the default values that will be parsed from the CSV.

* Default: `null`
* If you have a nested object (ie. `{info : {name: 'Mike'}}`), then set this to `['info.name']`
* If you want all keys to be converted, then specify `null` or don't specify the option to utilize the default.

* Default: `JSON.parse` - An attempt is made to convert the String back to its original value using `JSON.parse`.

* Default: `false`

* Default: `false`

CLI

$ npm install @mrodrig/json-2-csv-cli
``` 

#### json2csv

#### csv2json

## Tests

```bash
$ npm test

$ npm run coverage

Features

• Header Generation (per document keys)
• Allows for conversion of specific keys in both json2csv and csv2json via the options.keys parameter (as of 1.1.2)
• Document schema verification functionality (field order is irrelevant) (as of 1.1.0)
• Supports sub-documents natively
• Supports arrays as document values for both json2csv and csv2json
• Custom ordering of columns (see F.A.Q. for more information)
• Ability to re-generate the JSON documents that were used to generate the CSV (including nested documents)
• Allows for custom field delimiters, end of line delimiters, etc.
• Wrapped value support for json2csv and csv2json (as of 1.3.0)
• Support for multiple different schemas (as of 1.4.0)
• RFC 4180 Compliance (as of 3.0.0)
• CLI functionality (as of 3.0.0)

* `csv2json test.csv -o output.json`
* *and*
* `json2csv test.json -o output.csv -W -k arrayOfStrings -o output.csv`

• Empty field value option (as of 3.1.0)
• TypeScript typings included (as of 3.4.0) - thanks to @GabrielCastro!
• Synchronous use case support (as of 5.0.0) - thanks to @Nokel81