Csvbuilder

!travis

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

``js

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


`bash
$ 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\* 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.