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