1 | # json-2-csv
|
2 | **Convert JSON to CSV _or_ CSV to JSON**
|
3 |
|
4 | [![Dependencies](https://img.shields.io/david/mrodrig/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv)
|
5 | [![Downloads](https://img.shields.io/npm/dm/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv)
|
6 | [![NPM version](https://img.shields.io/npm/v/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv)
|
7 | [![Minzipped Size](https://flat.badgen.net/bundlephobia/minzip/json-2-csv)](https://bundlephobia.com/result?p=json-2-csv)
|
8 |
|
9 | [![Build Status](https://travis-ci.org/mrodrig/json-2-csv.svg?branch=master)](https://travis-ci.org/mrodrig/json-2-csv)
|
10 | [![Coverage Status](https://coveralls.io/repos/github/mrodrig/json-2-csv/badge.svg?branch=stable)](https://coveralls.io/github/mrodrig/json-2-csv?branch=stable)
|
11 | [![Maintainability](https://api.codeclimate.com/v1/badges/8c0cc3699d054fb77abe/maintainability)](https://codeclimate.com/github/mrodrig/json-2-csv/maintainability)
|
12 | [![Typings](https://shields-staging.herokuapp.com/npm/types/json-2-csv.svg?style=flat)](https://www.npmjs.org/package/json-2-csv)
|
13 |
|
14 | This node module will convert an array of JSON documents to a CSV string.
|
15 | Column headings will be automatically generated based on the keys of the JSON documents. Nested documents will have a '.' appended between the keys.
|
16 |
|
17 | It is also capable of converting CSV of the same form back into the original array of JSON documents.
|
18 | The columns headings will be used as the JSON document keys. All lines must have the same exact number of CSV values.
|
19 |
|
20 | ## Installation
|
21 |
|
22 | ```bash
|
23 | $ npm install json-2-csv
|
24 | ```
|
25 |
|
26 | CLI:
|
27 | ```bash
|
28 | $ npm install @mrodrig/json-2-csv-cli
|
29 | ```
|
30 |
|
31 | ## Upgrading?
|
32 |
|
33 | Upgrading to v3 from v2? Check out the [upgrade guide](https://github.com/mrodrig/json-2-csv/blob/master/upgrade_guides/UPGRADE_2_to_3.md).
|
34 |
|
35 | ## Usage
|
36 |
|
37 | ```javascript
|
38 | let converter = require('json-2-csv');
|
39 | ```
|
40 | or
|
41 | ```javascript
|
42 | import { json2csv } from 'json-2-csv';
|
43 | ```
|
44 | Looking for examples? Check out the Wiki: [json-2-csv Wiki](https://github.com/mrodrig/json-2-csv/wiki)
|
45 |
|
46 | ### API
|
47 |
|
48 | #### `converter.json2csv(array, callback, options)`
|
49 |
|
50 | * `array` - An array of JSON documents to be converted to CSV.
|
51 | * `callback` - A function of the form `function (err, csv)`;
|
52 | * This function will receive any errors and/or the string of CSV generated.
|
53 | * `options` - (Optional) A JSON document specifying any of the following key value pairs:
|
54 | * `checkSchemaDifferences` - Boolean - Should all documents have the same schema?
|
55 | * Default: `false`
|
56 | * Note: An error will be thrown if some documents have differing schemas when this is set to `true`.
|
57 | * `delimiter` - Document - Specifies the different types of delimiters
|
58 | * `field` - String - Field Delimiter.
|
59 | * Default: `,`
|
60 | * `wrap` - String - Wrap values in the delimiter of choice (e.g. wrap values in quotes).
|
61 | * Default: `"`
|
62 | * `eol` - String - End of Line Delimiter.
|
63 | * Default: `\n`
|
64 | * `emptyFieldValue` - Any - Value that, if specified, will be substituted in for field values that are `undefined`, `null`, or an empty string.
|
65 | * Default: none
|
66 | * `excelBOM` - Boolean - Should a unicode character be prepended to allow Excel to open a UTF-8 encoded file with non-ASCII characters present.
|
67 | * `expandArrayObjects` - Boolean - Should objects in array values be deep-converted to CSV?
|
68 | * Default: `false`
|
69 | * Example:
|
70 | ```json
|
71 | [
|
72 | {
|
73 | "specifications": [
|
74 | { "features": [...] },
|
75 | { "mileage": "5000" }
|
76 | ]
|
77 | }
|
78 | ]
|
79 | ```
|
80 | * `true` uses the following keys:
|
81 | * `['specifications.features', 'specifications.mileage']`
|
82 | * `false` uses the following keys:
|
83 | * `['specifications']`
|
84 | * Note: This may result in CSV output that does not map back exactly to the original JSON. See #102 for more information.
|
85 | * `keys` - Array - Specify the keys (as strings) that should be converted.
|
86 | * Default: These will be auto-detected from your data by default.
|
87 | * Keys can either be specified as a String representing the key path that should be converted, or as an Object with the `key` property specifying the path. When specifying keys as an Object, you can also optionally specify a `title` which will be used for that column in the header. The list specified can contain a combination of Objects and Strings.
|
88 | * `[ 'key1', 'key2', ... ]`
|
89 | * `[ { key: 'key1', title: 'Key 1' }, { key: 'key2' }, 'key3', ... ]`
|
90 | * Key Paths - If you are converting a nested object (ie. {info : {name: 'Mike'}}), then set this to ['info.name']
|
91 | * `prependHeader` - Boolean - Should the auto-generated header be prepended as the first line in the CSV?
|
92 | * Default: `true`
|
93 | * `sortHeader` - Boolean - Should the header keys be sorted in alphabetical order?
|
94 | * Default: `false`
|
95 | * `trimFieldValues` - Boolean - Should the field values be trimmed?
|
96 | * Default: `false`
|
97 | * `trimHeaderFields` - Boolean - Should the header fields be trimmed?
|
98 | * Default: `false`
|
99 | * `unwindArrays` - Boolean - Should array values be "unwound" such that there is one line per value in the array?
|
100 | * Default: `false`
|
101 | * Example:
|
102 | ```json
|
103 | [
|
104 | {
|
105 | "_id": {"$oid": "5cf7ca3616c91100018844af"},
|
106 | "data": {"category": "Computers", "options": [{"name": "MacBook Pro 15"}, {"name": "MacBook Air 13"}]}
|
107 | },
|
108 | {
|
109 | "_id": {"$oid": "5cf7ca3616c91100018844bf"},
|
110 | "data": {"category": "Cars", "options": [{"name": "Supercharger"}, {"name": "Turbocharger"}]}
|
111 | }
|
112 | ]
|
113 | ```
|
114 | * `true` will unwind the JSON to four objects, and therefore four lines of CSV values:
|
115 | ```csv
|
116 | _id.$oid,data.category,data.options.name
|
117 | 5cf7ca3616c91100018844af,Computers,MacBook Pro 15
|
118 | 5cf7ca3616c91100018844af,Computers,MacBook Air 13
|
119 | 5cf7ca3616c91100018844bf,Cars,Supercharger
|
120 | 5cf7ca3616c91100018844bf,Cars,Turbocharger
|
121 | ```
|
122 | * `false` will leave the values unwound and will convert the array as-is (when this option is used without expandArrayObjects):
|
123 | ```csv
|
124 | _id.$oid,data.category,data.options
|
125 | 5cf7ca3616c91100018844af,Computers,"[{""name"":""MacBook Pro 15""},{""name"":""MacBook Air 13""}]"
|
126 | 5cf7ca3616c91100018844bf,Cars,"[{""name"":""Supercharger""},{""name"":""Turbocharger""}]"
|
127 | ```
|
128 | * Note: This may result in CSV output that does not map back exactly to the original JSON.
|
129 | * `useDateIso8601Format` - Boolean - Should date values be converted to an ISO8601 date string?
|
130 | * Default: `false`
|
131 | * Note: If selected, values will be converted using `toISOString()` rather than `toString()` or `toLocaleString()` depending on the other options provided.
|
132 | * `useLocaleFormat` - Boolean - Should values be converted to a locale specific string?
|
133 | * Default: `false`
|
134 | * Note: If selected, values will be converted using `toLocaleString()` rather than `toString()`
|
135 |
|
136 |
|
137 | For examples, please refer to the [json2csv API Documentation (Link)](https://github.com/mrodrig/json-2-csv/wiki/json2csv-Documentation)
|
138 |
|
139 | #### Promisified Version: `converter.json2csvAsync(array, options)`
|
140 |
|
141 | Available in version `2.2.0`, this functionality makes use of promises from the `bluebird` module.
|
142 |
|
143 | #### `converter.csv2json(csv, callback, options)`
|
144 |
|
145 | * `csv` - A string of CSV
|
146 | * `callback` - A function of the form `function (err, array)`; This function will receive any errors and/or the array of JSON documents generated.
|
147 | * `options` - (Optional) A JSON document specifying any of the following key value pairs:
|
148 | * `delimiter` - Document - Specifies the different types of delimiters
|
149 | * `field` - String - Field Delimiter.
|
150 | * Default: `,`
|
151 | * `wrap` - String - The character that field values are wrapped in.
|
152 | * Default: `"`
|
153 | * `eol` - String - End of Line Delimiter.
|
154 | * Default: `\n`
|
155 | * `excelBOM` - Boolean - Does the CSV contain a unicode character prepended in order to allow Excel to open a UTF-8 encoded file with non-ASCII characters present?
|
156 | * Default: `false`
|
157 | * `keys` - Array - Specify the keys (as strings) that should be converted.
|
158 | * Default: `null`
|
159 | * If you have a nested object (ie. `{info : {name: 'Mike'}}`), then set this to `['info.name']`
|
160 | * If you want all keys to be converted, then specify `null` or don't specify the option to utilize the default.
|
161 | * `trimHeaderFields` - Boolean - Should the header fields be trimmed?
|
162 | * Default: `false`
|
163 | * `trimFieldValues` - Boolean - Should the field values be trimmed?
|
164 | * Default: `false`
|
165 |
|
166 | For examples, please refer to the [csv2json API Documentation (Link)](https://github.com/mrodrig/json-2-csv/wiki/csv2json-Documentation)
|
167 |
|
168 | #### Promisified Version: `csv2jsonAsync(csv, options)`
|
169 |
|
170 | Available in version `2.2.0`, this functionality makes use of promises from the `bluebird` module.
|
171 |
|
172 | ### CLI
|
173 | Note: As of `3.5.8`, the command line interface functionality has been pulled out to a separate package. Please be sure to
|
174 | install the `@mrodrig/json-2-csv-cli` NPM package if you wish to use the CLI functionality shown below:
|
175 |
|
176 | ```bash
|
177 | $ npm install @mrodrig/json-2-csv-cli
|
178 | ```
|
179 |
|
180 | #### json2csv
|
181 | ```
|
182 | Usage: json2csv <jsonFile> [options]
|
183 |
|
184 | Options:
|
185 | -V, --version output the version number
|
186 | -o, --output [output] Path of output file. If not provided, then stdout will be used
|
187 | -f, --field <delimiter> Optional field delimiter
|
188 | -w, --wrap <delimiter> Optional wrap delimiter
|
189 | -e, --eol <delimiter> Optional end of line delimiter
|
190 | -b, --excel-bom Excel Byte Order Mark character prepended to CSV
|
191 | -W, --without-header Withhold the prepended header
|
192 | -s, --sort-header Sort the header fields
|
193 | -H, --trim-header Trim header fields
|
194 | -F, --trim-fields Trim field values
|
195 | -S, --check-schema Check for schema differences
|
196 | -E, --empty-field-value <value> Empty field value
|
197 | -A, --expand-array-objects Expand array objects
|
198 | -k, --keys [keys] Keys of documents to convert to CSV
|
199 | -h, --help output usage information
|
200 | ```
|
201 |
|
202 | #### csv2json
|
203 | ```
|
204 | Usage: csv2json <csvFile> [options]
|
205 |
|
206 | Options:
|
207 | -V, --version output the version number
|
208 | -c, --csv <csv> Path of json file to be converted
|
209 | -o, --output [output] Path of output file. If not provided, then stdout will be used
|
210 | -f, --field <delimiter> Optional field delimiter
|
211 | -w, --wrap <delimiter> Optional wrap delimiter
|
212 | -e, --eol <delimiter> Optional end of line delimiter
|
213 | -b, --excel-bom Excel Byte Order Mark character prepended to CSV
|
214 | -H, --trim-header Trim header fields
|
215 | -F, --trim-fields Trim field values
|
216 | -k, --keys [keys] Keys of documents to convert to CSV
|
217 | -h, --help output usage information
|
218 | ```
|
219 |
|
220 | ## Tests
|
221 |
|
222 | ```bash
|
223 | $ npm test
|
224 | ```
|
225 |
|
226 | To see test coverage, please run:
|
227 | ```bash
|
228 | $ npm run coverage
|
229 | ```
|
230 |
|
231 | Current Coverage is:
|
232 | ```
|
233 | Statements : 100% ( 286/286 )
|
234 | Branches : 100% ( 166/166 )
|
235 | Functions : 100% ( 73/73 )
|
236 | Lines : 100% ( 280/280 )
|
237 | ```
|
238 |
|
239 | ## Frequently Asked Questions (FAQ)
|
240 | Please find the updated list (relocated to the Wiki) here: [Frequently Asked Questions (Link)](https://github.com/mrodrig/json-2-csv/wiki/FAQ)
|
241 |
|
242 | ## Features
|
243 | * Header Generation (per document keys)
|
244 | * Allows for conversion of specific keys in both json2csv and csv2json via the options.keys parameter (as of 1.1.2)
|
245 | * Document schema verification functionality (field order is irrelevant) (as of 1.1.0)
|
246 | * Supports sub-documents natively
|
247 | * Supports arrays as document values for both json2csv and csv2json
|
248 | * Custom ordering of columns (see F.A.Q. for more information)
|
249 | * Ability to re-generate the JSON documents that were used to generate the CSV (including nested documents)
|
250 | * Allows for custom field delimiters, end of line delimiters, etc.
|
251 | * Wrapped value support for json2csv and csv2json (as of 1.3.0)
|
252 | * Support for multiple different schemas (as of 1.4.0)
|
253 | * Promisified versions of the functions are now available by default: json2csvAsync, csv2jsonAsync (as of 2.2.0)
|
254 | * RFC 4180 Compliance (as of 3.0.0)
|
255 | * CLI functionality (as of 3.0.0)
|
256 | * `csv2json test.csv -o output.json`
|
257 | * *and*
|
258 | * `json2csv test.json -o output.csv -W -k arrayOfStrings -o output.csv`
|
259 | * Empty field value option (as of 3.1.0)
|
260 | * TypeScript typings included (as of 3.4.0) - thanks to [@GabrielCastro](https://github.com/GabrielCastro)!
|