jsonexport {} → 📄

!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
- 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.

``javascript
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

Browser

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

$3

Webpack
`javascript
const jsonexport = require("jsonexport/dist")
`

Typescript
`javascript
import * as jsonexport from "jsonexport/dist"
`

Stream

`javascript
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

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

JSON Array Example

$3

#### Code

`javascript
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
`

$3

#### Code

`javascript
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

$3

#### Code

`javascript
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
`

$3

#### Code

`javascript
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

`javascript
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?

`javascript
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

`javascript
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

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