Have ideas to improve npm?Join in the discussion! »

    jsonexport
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/jsonexport package

    3.2.0 • Public • Published

    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

    Install

    npm i jsonexport

    DownloadsWeekly Downloads

    178,919

    Version

    3.2.0

    License

    Apache-2.0

    Unpacked Size

    97.4 kB

    Total Files

    38

    Last publish

    Collaborators

    • avatar
    • avatar