GitHub - kaue/jsonexport: {} → it's easy to convert JSON to CSV

5 min read Original article ↗

jsonexport {} → 📄

Travis Known Vulnerabilities NPM Version NPM Downloads NPM Downloads NPM License GitHub stars Try jsonexport on RunKit npm bundle size

✔ 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

Installation command is npm install jsonexport.

Run tests with npm test.

const jsonexport = require('jsonexport');

jsonexport({lang: 'Node.js', module: 'jsonexport'}, {rowDelimiter: '|'}, function(err, csv){
    if (err) return console.error(err);
    console.log(csv);
});

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

const jsonexport = require("jsonexport/dist")

Typescript

import * as jsonexport from "jsonexport/dist"

Stream

const jsonexport = require('jsonexport');
const fs = require('fs');

const reader = fs.createReadStream('data.json');
const writer = fs.createWriteStream('out.csv');

reader.pipe(jsonexport()).pipe(writer);

Promise

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

JSON Array Example

Simple Array

Code

const jsonexport = require('jsonexport');

const contacts = [{
    name: 'Bob',
    lastname: 'Smith'
},{
    name: 'James',
    lastname: 'David'
},{
    name: 'Robert',
    lastname: 'Miller'
},{
    name: 'David',
    lastname: 'Martin'
}];

jsonexport(contacts, function(err, csv){
    if (err) return console.error(err);
    console.log(csv);
});

Result

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

Complex Array

Code

const jsonexport = require('jsonexport');

const contacts = [{
   name: 'Bob',
   lastname: 'Smith',
   family: {
       name: 'Peter',
       type: 'Father'
   }
},{
   name: 'James',
   lastname: 'David',
   family:{
       name: 'Julie',
       type: 'Mother'
   }
},{
   name: 'Robert',
   lastname: 'Miller',
   family: null,
   location: [1231,3214,4214]
},{
   name: 'David',
   lastname: 'Martin',
   nickname: 'dmartin'
}];

jsonexport(contacts, function(err, csv){
    if (err) return console.error(err);
    console.log(csv);
});

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

const jsonexport = require('jsonexport');

const stats = {
    cars: 12,
    roads: 5,
    traffic: 'slow'
};

jsonexport(stats, function(err, csv){
    if(err) return console.error(err);
    console.log(csv);
});

Result

cars,12
roads,5
traffic,slow

Complex Object

Code

const jsonexport = require('jsonexport');

const stats = {
    cars: 12,
    roads: 5,
    traffic: 'slow',
    speed: {
        max: 123,
        avg: 20,
        min: 5
    },
    size: [10,20]
};

jsonexport(stats, function(err, csv){
    if(err) return console.error(err);
    console.log(csv);
});

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

const jsonexport = require('jsonexport');

//data
const contacts = {
  'a' : Buffer.from('a2b', 'utf8'),
  'b' : Buffer.from('other field', 'utf8'),
  'x' : 22,
  'z' : function(){return 'bad ace'}
};

const options = {
  //definitions to type cast
  typeHandlers: {
    Array:function(value,index,parent){
      return 'replaced-array';
    },
    Boolean:function(value,index,parent){
      return 'replaced-boolean';
    },
    Function:function(value,index,parent){
      return value();
    },
    Number:function(value,index,parent){
      return 'replaced-number';
    },
    String:function(value,index,parent){
      return 'replaced-string';
    },
    Buffer:function(value,index,parent){
      return value.toString();
    }
  }
};

jsonexport(contacts, options, function(err, csv) {
  if (err) return console.error(err);
  console.log(csv);
});

The output would be:

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

Date typeHandler?

var date = new Date();
jsonexport({
    a: date,
    b: true
}, {
    typeHandlers: {
        Object: (value, name) => {
            if (value instanceof Date) return date.toLocaleString();
            return value;
        }
    }
}, (err, csv) => {
    if (err) return console.error(err);
    console.log(csv);
});

When using typeHandlers, Do NOT do this

const options = {
  typeHandlers: {
    Object:function(value, index, parent){
      return 'EVERYTHING IS AN OBJECT';
    }
  }
};

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

Contributors