jsonexport {} → ????

✔ easy to use ???? (should work as expected without much customization)️

✔ extendable ???? (many options to customize the output)

✔️ tiny ???? (0 dependencies)

✔ scalable ???? (works with big files using Streams)

✔ fast ⚡

Project Page

Online Demo Page

Table of Contents

• Usage
• CLI
• Browser
  • Browser Import Examples
• Stream
• Promise
• JSON Array Example
  • Simple Array
  • JSON Object Example
• Options
  • typeHandlers
• Contributors

Usage

Installation command is npm install jsonexport.

Run tests with npm test.

1const jsonexport = require('jsonexport');
2
3jsonexport({lang: 'Node.js', module: 'jsonexport'}, {rowDelimiter: '|'}, function(err, csv){
4    if (err) return console.error(err);
5    console.log(csv);
6});

CLI

Global installation command is npm install -g jsonexport.

Convert JSON to CSV using cat data.json | jsonexport or jsonexport data.json

Usage: jsonexport <JSON filename> <CSV filename>

Browser

Use the code in the folder named dist to run jsonexport in the browser

Browser Import Examples

Webpack

1const jsonexport = require("jsonexport/dist")

Typescript

1import * as jsonexport from "jsonexport/dist"

Stream

1const jsonexport = require('jsonexport');
2const fs = require('fs');
3
4const reader = fs.createReadStream('data.json');
5const writer = fs.createWriteStream('out.csv');
6
7reader.pipe(jsonexport()).pipe(writer);

Promise

1const jsonexport = require('jsonexport')
2try {
3    const csv = await jsonexport({lang: 'Node.js', module: 'jsonexport'}, {rowDelimiter: '|'});
4} catch (err) {
5    console.error(err);
6}

JSON Array Example

Simple Array

Code

1const jsonexport = require('jsonexport');
2
3const contacts = [{
4    name: 'Bob',
5    lastname: 'Smith'
6},{
7    name: 'James',
8    lastname: 'David'
9},{
10    name: 'Robert',
11    lastname: 'Miller'
12},{
13    name: 'David',
14    lastname: 'Martin'
15}];
16
17jsonexport(contacts, function(err, csv){
18    if (err) return console.error(err);
19    console.log(csv);
20});

Result

name,lastname
Bob,Smith
James,David
Robert,Miller
David,Martin

Complex Array

Code

1const jsonexport = require('jsonexport');
2
3const contacts = [{
4   name: 'Bob',
5   lastname: 'Smith',
6   family: {
7       name: 'Peter',
8       type: 'Father'
9   }
10},{
11   name: 'James',
12   lastname: 'David',
13   family:{
14       name: 'Julie',
15       type: 'Mother'
16   }
17},{
18   name: 'Robert',
19   lastname: 'Miller',
20   family: null,
21   location: [1231,3214,4214]
22},{
23   name: 'David',
24   lastname: 'Martin',
25   nickname: 'dmartin'
26}];
27
28jsonexport(contacts, function(err, csv){
29    if (err) return console.error(err);
30    console.log(csv);
31});

Result

name,lastname,family.name,family.type,family,location,nickname
Bob,Smith,Peter,Father
James,David,Julie,Mother
Robert,Miller,,,,1231;3214;4214
David,Martin,,,,,dmartin

JSON Object Example

Simple Object

Code

1const jsonexport = require('jsonexport');
2
3const stats = {
4    cars: 12,
5    roads: 5,
6    traffic: 'slow'
7};
8
9jsonexport(stats, function(err, csv){
10    if(err) return console.error(err);
11    console.log(csv);
12});

Result

cars,12
roads,5
traffic,slow

Complex Object

Code

1const jsonexport = require('jsonexport');
2
3const stats = {
4    cars: 12,
5    roads: 5,
6    traffic: 'slow',
7    speed: {
8        max: 123,
9        avg: 20,
10        min: 5
11    },
12    size: [10,20]
13};
14
15jsonexport(stats, function(err, csv){
16    if(err) return console.error(err);
17    console.log(csv);
18});

Result

cars,12
roads,5
traffic,slow
speed.max,123
speed.avg,20
speed.min,5
size,10;20

Options

In order to get the most of out of this module, you can customize many parameters and functions.

• headerPathString - String Used to create the propriety path, defaults to . example contact: {name: 'example} = contact.name
• fillGaps - Boolean Set this option if don't want to have empty cells in case of an object with multiple nested items (array prop), defaults to false Issue #22
• fillTopRow - Boolean try filling top rows first for unpopular colums, defaults to false
• headers - Array Used to set a custom header order, defaults to [] example ['lastname', 'name']
• rename - Array Used to set a custom header text, defaults to [] example ['Last Name', 'Name']
• mapHeaders - Function Post-process headers after they are calculated with delimiters, example mapHeaders: (header) => header.replace(/foo\./, '')
• rowDelimiter - String Change the file row delimiter
  • Defaults to , (cvs format).
  • Use \t for xls format.
  • Use ; for (windows excel .csv format).
• textDelimiter - String The character used to escape the text content if needed (default to ")
• forceTextDelimiter - Boolean Set this option to true to wrap every data item and header in the textDelimiter. Defaults to false
• endOfLine - String Replace the OS default EOL.
• mainPathItem - String Every header will have the mainPathItem as the base.
• arrayPathString - String This is used to output primitive arrays in a single column, defaults to ;
• booleanTrueString - String Will be used instead of true.
• booleanFalseString - String Will be used instead of false.
• includeHeaders - Boolean Set this option to false to hide the CSV headers.
• undefinedString - String If you want to display a custom value for undefined strings, use this option. Defaults to .
• verticalOutput - Boolean Set this option to false to create a horizontal output for JSON Objects, headers in the first row, values in the second.
• typeHandlers - {typeName:(value, index, parent)=>any A key map of constructors used to match by instance to create a value using the defined function (see example)

typeHandlers

Define types by constructors and what function to run when that type is matched

1const jsonexport = require('jsonexport');
2
3//data
4const contacts = {
5  'a' : Buffer.from('a2b', 'utf8'),
6  'b' : Buffer.from('other field', 'utf8'),
7  'x' : 22,
8  'z' : function(){return 'bad ace'}
9};
10
11const options = {
12  //definitions to type cast
13  typeHandlers: {
14    Array:function(value,index,parent){
15      return 'replaced-array';
16    },
17    Boolean:function(value,index,parent){
18      return 'replaced-boolean';
19    },
20    Function:function(value,index,parent){
21      return value();
22    },
23    Number:function(value,index,parent){
24      return 'replaced-number';
25    },
26    String:function(value,index,parent){
27      return 'replaced-string';
28    },
29    Buffer:function(value,index,parent){
30      return value.toString();
31    }
32  }
33};
34
35jsonexport(contacts, options, function(err, csv) {
36  if (err) return console.error(err);
37  console.log(csv);
38});

The output would be:

a,a2b
b,other field
x,replaced-number
z,bad ace

Date typeHandler?

1var date = new Date();
2jsonexport({
3    a: date,
4    b: true
5}, {
6    typeHandlers: {
7        Object: (value, name) => {
8            if (value instanceof Date) return date.toLocaleString();
9            return value;
10        }
11    }
12}, (err, csv) => {
13    if (err) return console.error(err);
14    console.log(csv);
15});

When using typeHandlers, Do NOT do this

1const options = {
2  typeHandlers: {
3    Object:function(value, index, parent){
4      return 'EVERYTHING IS AN OBJECT';
5    }
6  }
7};

It is NOT an error, however the recursive result becomes illegable functionality strings

Contributors

• Kauê Gimenes
• Pierre Guillaume
• Acker Apple
• Victor Hahn
• Jason Macgowan
• And many more...