# mk-json-2-csv > A JSON to CSV and CSV to JSON converter that natively supports sub-documents and auto-generates the CSV heading. Latest version **3.0.2** (published 2019-01-25) · MIT license · 0 weekly downloads ## Install ```sh npm install mk-json-2-csv pnpm add mk-json-2-csv yarn add mk-json-2-csv bun add mk-json-2-csv ``` Provides the commands `csv2json`, `json2csv`. ## Health **Score 20/100 (F)** — status: abandoned. Positive: no vulnerabilities; high maintenance score. Warnings: low downloads; no types; no esm support. Negative: abandoned; declining downloads. ## Facts | | | |---|---| | Version | 3.0.2 | | Published | 2019-01-25 | | First published | 2018-12-28 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >= 6 | | Dependencies | 3 | | Unpacked size | 48.2 KB | | Known vulnerabilities | 0 (+3 in 2 direct dependencies) | | Install scripts | no | | GitHub stars | 459 | | Author | mrodrig | | Maintainers | d925529 | | Keywords | json, csv, converter, json2csv, csv2json, json2csv-converter, csv2json-converter, json-2-csv, csv-2-json | ## Links - npm: https://www.npmjs.com/package/mk-json-2-csv - Repository: http://github.com/mrodrig/json-2-csv - npm.io page: https://npm.io/package/mk-json-2-csv ## Dependencies (3) - [deeks](https://npm.io/package/deeks.md) 1.0.0 - [doc-path](https://npm.io/package/doc-path.md) 1.3.1 - [underscore](https://npm.io/package/underscore.md) 1.9.1 ## Alternatives - [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads - [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads - [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads - [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads - [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads ## Recent versions - 3.0.2 (latest) — 2019-01-25 - 3.0.1 — 2019-01-24 - 3.0.0 — 2018-12-28 ## README # json-2-csv **Convert JSON to CSV _or_ CSV to JSON** [![Dependencies](https://img.shields.io/david/mrodrig/json-2-csv.svg?style=flat-square)](https://www.npmjs.org/package/json-2-csv) [![Downloads](http://img.shields.io/npm/dm/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv) [![NPM version](https://img.shields.io/npm/v/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv) [![Known Vulnerabilities](https://snyk.io/test/npm/json-2-csv/badge.svg)](https://snyk.io/test/npm/json-2-csv) [![Package Size](https://img.shields.io/bundlephobia/min/json-2-csv.svg)](https://www.npmjs.org/package/json-2-csv) [![Build Status](https://travis-ci.org/mrodrig/json-2-csv.svg?branch=master)](https://travis-ci.org/mrodrig/json-2-csv) [![Maintainability](https://api.codeclimate.com/v1/badges/8c0cc3699d054fb77abe/maintainability)](https://codeclimate.com/github/mrodrig/json-2-csv/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/8c0cc3699d054fb77abe/test_coverage)](https://codeclimate.com/github/mrodrig/json-2-csv/test_coverage) [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=rodrigues.mi%40husky.neu.edu&item_name=Open+Source+Software+Development+-+Node+Modules¤cy_code=USD&source=url) This node module will convert an array of JSON documents to a CSV string. Column headings will be automatically generated based on the keys of the JSON documents. Nested documents will have a '.' appended between the keys. It is also capable of converting CSV of the same form back into the original array of JSON documents. The columns headings will be used as the JSON document keys. All lines must have the same exact number of CSV values. ## Installation ```bash $ npm install json-2-csv ``` ## Usage ```javascript let converter = require('json-2-csv'); ``` ## Upgrading? 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). ### API #### `converter.json2csv(array, callback, options)` * `array` - An array of JSON documents to be converted to CSV. * `callback` - A function of the form `function (err, csv)`; * This function will receive any errors and/or the string of CSV generated. * `options` - (Optional) A JSON document specifying any of the following key value pairs: * `delimiter` - Document - Specifies the different types of delimiters * `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` * `excelBOM` - Boolean - Should a unicode character be prepended to allow Excel to open a UTF-8 encoded file with non-ASCII characters present. * `prependHeader` - Boolean - Should the auto-generated header be prepended as the first line in the CSV? * Default: `true` * `sortHeader` - Boolean - Should the header keys be sorted in alphabetical order? * Default: `false` * `trimHeaderFields` - Boolean - Should the header fields be trimmed? * Default: `false` * `trimFieldValues` - Boolean - Should the field values be trimmed? (*in development*) * Default: `false` * `checkSchemaDifferences` - Boolean - Should all documents have the same schema? * Default: `false` * Note: Change this to `false` if some documents are missing certain fields and you still want to convert the data. * `keys` - Array - Specify the keys (as strings) that should be converted. * 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. For examples, please refer to the [json2csv API Documentation (Link)](https://github.com/mrodrig/json-2-csv/wiki/json2csv-Documentation) #### Promisified Version: `converter.json2csvAsync(array, options)` Available in version `2.2.0`, this functionality makes use of promises from the `bluebird` module. #### `converter.csv2json(csv, callback, options)` * `csv` - A string of CSV * `callback` - A function of the form `function (err, array)`; This function will receive any errors and/or the array of JSON documents generated. * `options` - (Optional) A JSON document specifying any of the following key value pairs: * `delimiter` - Document - Specifies the different types of delimiters * `field` - String - Field Delimiter. * Default: `,` * `wrap` - String - The character that field values are wrapped in. * Default: `"` * `eol` - String - End of Line Delimiter. * Default: `\n` * `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? * Default: `false` * `trimHeaderFields` - Boolean - Should the header fields be trimmed? * Default: `false` * `trimFieldValues` - Boolean - Should the field values be trimmed? * Default: `false` * `keys` - Array - Specify the keys (as strings) that should be converted. * 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. For examples, please refer to the [csv2json API Documentation (Link)](https://github.com/mrodrig/json-2-csv/wiki/csv2json-Documentation) #### Promisified Version: `csv2jsonAsync(csv, options)` Available in version `2.2.0`, this functionality makes use of promises from the `bluebird` module. ## Tests ```bash $ npm test ``` _Note_: This requires `mocha`, `should`, and `underscore`. To see test coverage, please run: ```bash $ npm run coverage ``` Current Coverage is: ``` Statements : 100% ( 258/258 ) Branches : 100% ( 124/124 ) Functions : 100% ( 49/49 ) Lines : 100% ( 256/256 ) ``` ## Frequently Asked Questions (FAQ) Please find the updated list (relocated to the Wiki) here: [Frequently Asked Questions (Link)](https://github.com/mrodrig/json-2-csv/wiki/FAQ) ## 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) * Verifies all documents have same schema (schema field order does not matter 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. * Promisifiable via bluebird's .promisify() and .promisifyAll() (as of 1.1.1) * Wrapped value support for json2csv and csv2json (as of 1.3.0) * Support for multiple different schemas (as of 1.4.0) * Promisified versions of the functions are now available by default: json2csvAsync, csv2jsonAsync (as of 2.2.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` --- _Source: https://npm.io/package/mk-json-2-csv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._