@iwsio/json-csv-node

@iwsio/json-csv-node

This package extends @iwsio/json-csv-core specifically targeting Node.JS to support streaming. It's all the same code as before, just moved around.

Usage

Buffered (Converts to CSV with an in-memory data source)

const { toCsv } = require('@iwsio/json-csv-node')

const csv = await toCsv(data, options) // toCsv returns Promise

// optionally, you can use a callback
toCsv(data, options, function(err, csv) {...}))

Streaming (Converts a "row at a time" from a stream source)

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

const { toCsvStream } = require('@iwsio/json-csv-node')
const things = [
  {name: 'thing1', age: 20},
  {name: 'thing2', age: 30},
  {name: 'thing3', age: 45}
]
 
Readable.from(things) // <readable source in object mode>
  .pipe(toCsvStream(options)) // transforms to Utf8 string and emits lines
  .pipe(process.stdout) // anything Writable
})

NOTE: All the aliases from previous versions remain intact.

I renamed this API mostly for cosmetics and to cleanup named exports for ES Modules. It made more sense to me to import { toCSV } from 'json-csv' rather than importing the default and calling its prop. (I've been doing a lot of Typescript lately). But all the original versions are kept intact and tests are in place to assert they work.

const jsonCsv = require('@iwsio/json-csv-node')
jsonCsv.toCsv // buffered, returns promise, callback optional
jsonCsv.toCsvStream // stream, returns stream, callback optional

jsonCsv.buffered // alias to toCsv (buffered)
jsonCsv.stream // alias to toCsvStream (streamed)

jsonCsv.csv // alias to toCsvStream (streamed)
jsonCsv.csvBuffered // alias to toCsv (buffered)

Options

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

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

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

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

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 like: contact.name for the contact name.

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 () => {
  let result = await toCsv(items, options)
  console.log(result)
})()

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