json-csv

json-csv

This is a simple Node.JS module that can transorm JSON data to CSV. This version 4.x is in maintenance mode and will only receive critical updates. Please see @iwsio/json-csv-node for the latest, active version of this package.

Update v6 - June 2023

The latest version 6 just released in June 2023 and includes better type definitions along with ESM & CommonJS support. Read more about it on the v6 blog post.

Usage

Buffered

const jsoncsv = require('json-csv')

const csv = await jsoncsv.buffered(data, options) //returns Promise

//optionally, you can use the callback
jsoncsv.buffered(data, options, (err, csv) => {...}))

• data: Array of JS objects
• options: {fields: [], ...}
• optional callback: returns string result

Streaming

When using the streaming API, you can pipe data to it in object mode.

const jsoncsv = require('json-csv')

const readable = some_readable_source //<readable source in object mode>
readable
  .pipe(jsoncsv.stream(options)) //transforms to Utf8 string and emits lines
  .pipe(something_else_writable)
})

Options

{
  //field definitions for CSV export
  fields :
  [
    {
      //required: field name for source value
      name: 'string',

      //required: column label for CSV header
      label: 'string',

      //optional: transform value before exporting
      transform: function(value) { return value; }
    }
  ],

  // Other default options:
  fieldSeparator: ","
  ,ignoreHeader: false
  ,encoding: "utf8"
}

Advanced Example

Here, you can see we're using a deeper set of objects for our source data and we're using dot notation in the field definitions.

const items = [
  {
    downloaded: false,
    contact: {
      company: 'Widgets, LLC',
      name: 'John Doe',
      email: '[e-mail]',
    },
    registration: {
      year: 2013,
      level: 3,
    },
  },
  {
    downloaded: true,
    contact: {
      company: 'Sprockets, LLC',
      name: 'Jane Doe',
      email: '[e-mail]',
    },
    registration: {
      year: 2013,
      level: 2,
    },
  },
]
const options = {
  fields: [
    {
      name: 'contact.company', // uses dot notation
      label: 'Company',
    },
    {
      name: 'contact.name',
      label: 'Name',
    },
    {
      name: 'contact.email',
      label: 'Email',
    },
    {
      name: 'downloaded',
      label: "Downloaded",
      transform: (v) => v ? 'downloaded' : 'pending',
    },
    {
      name: 'registration.year',
      label: 'Year',
    },
    {
      name: 'registration.level',
      label: 'Level',
      transform: (v) => {
        switch (v) {
          case 1: return 'Test 1'
          case 2: return 'Test 2'
          default: return 'Unknown'
        }
      },
    },
  ],
}

async function writeCsv() {
  try {
    let result = await csv.buffered(items, options)
    console.log(result)
  } catch (err) {
    console.error(err)
  }
}

writeCsv()

Output

Company,Name,Email,Downloaded,Year,Level
"Widgets, LLC",John Doe,[e-mail],pending,2013,Unknown
"Sprockets, LLC",Jane Doe,[e-mail],downloaded,2013,Test 2