csv-builder

Csvbuilder

Easily encode complex JSON objects to CSV with CsvBuilder's schema-like API.

Table Of Contents

• Usage
• New Features
• Installation
• API
• Migration To 1.0.0

Usage

const CsvBuilder = require('csv-builder')

const data = [
  {
    name: 'Foo Bar',
    meta: {
      active: true,
      roles: [
        'user',
        'admin'
      ]
    }
  }
]

const builder = new CsvBuilder({
  headers: ['Firstname', 'Lastname', 'Role 1', 'Role 2', 'Active'],
  alias: {
    'Role 1': 'meta.roles[0]',
    'Role 2': 'meta.roles[1]',
    'Active': 'meta.active'
  }
})
  .virtual('Firstname', user => user.name.split(' ')[0])
  .virtual('Lastname', user => user.name.split(' ')[1])

/* Each of the following produces the following CSV contents:

"Firstname","Lastname","Role 1","Role 2","Active"
"Foo","Bar","user","admin","true"

*/


// (1) Create from a Stream of objects (like a database)
getObjectStream()
  .pipe(builder.createTransformStream())
  .pipe(fs.createWriteStream('output.csv'))

// (2) Create from an existing payload (`data` is an array of objects)
builder.createReadStream(data)
  .pipe(fs.createWriteStream('output.csv'))

// (3) Roll your own
let csv = ''
csv += builder.getHeaders()
data.forEach(item => {
  csv += builder.getRow(item)
})
fs.writeFileSync('output.csv', csv)

Installation

$ npm i -s csv-builder
# or
$ yarn add csv-builder

New Features

• More cohesive API
• Expanded API to support non-stream outputs, i.e. building a CSV string row-by-row with the getHeaders() and getRow(object) methods respectively.
• Better CSV encoding (proper quoting by default)

API

CsvBuilder([options])

• headers String|Array Space separated headers, or array of headers (required)
• delimiter String The column delimiter. Default ','
• terminator String The row terminator. Default '\n'
• quoted Boolean Quote columns? Default true
• alias Object An object in the format of { "csv header": "object prop" }, object prop will be aliased to csv header. Default {}

Methods

CsvBuilder#createReadStream(payload): Stream.Readable

Creates a readable stream and consumes the payload.

• payload Array<Object> Incoming data.

CsvBuilder#createTransformStream(): Stream.Transform

Creates a transform stream. The stream expects either Objects or JSON.

CsvBuilder#headers(headers): this

• headers String|Array Space separated headers, or array of headers

CsvBuilder#alias(header, prop): this

Set single or multiple contraints. If header is an object, it will extend any existing constraints, not replace.

• header String|Object Either object {"header": "property"} Or a string "Header"
• prop String|undefined Property to correspond to header, omit if using object.

CsvBuilder#virtual(prop, fn): this

Create a virtual property. Virtual properties are treated the same as normal properties. If there is no corresponding header or alias, the virtual will not be present in resulting CSV.

• prop String Virtual property name
• fn (item: any) => any Where item is an element from the incoming data, and the return value is the corresponding value for the virtualized property.

CsvBuilder#getHeaders(): String

The headers in CSV format

CsvBuilder#getRow(item): String

Returns the CSV formated row for a given item.

• item Object A n item matching the "schema".

Migration to 1.0.0

• constraints attribute in options (for constructor) is deprecated, use alias instead.
• set(prop, value) method is deprecated, use alias(prop, value) instead.