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.

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

kaue/jsonexport

kaue

Reviews

Repository Details

jsonexport {} → 📄

Usage

CLI

Browser

Browser Import Examples

Stream

Promise

JSON Array Example

Simple Array

Code

Result

Complex Array

Code

Result

JSON Object Example

Simple Object

Code

Result

Complex Object

Code

Result

Options

typeHandlers

Contributors

More Repositories