@iwsio/json-csv-node

json-csv, @iwsio/json-csv-node

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

Update 5.0.0

Here we are again! Recently, an issue was opened regarding browser compatibility. Thinking through this, I decided to break out the core and buffered components into a new package @iwsio/json-csv-core that will be browser compatible (Babel transpiled for default browserslist). Also, in the spirit of code-reuse, I dumped all of that core code from this package and consumed it from core, so there can still be one central place to fix potential issues.

I'm bumping the major version for this one because of the foundational changes depending on @iwsio/json-csv-core. The core package will continue having no other upstream dependencies. This v5.0 is 100% compatible with v4. Please kindly let me know if you run into any issues. All of the original tests are still running across the two packages, and everything seems to be in order among Node 10-16.

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}]
const readable = Readable.from(things) // <readable source in object mode>
readable
  .pipe(toCsvStream(options)) // transforms to Utf8 string and emits lines
  .pipe(process.stdout) // anything Writable
})

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