csv42

A small and fast CSV parser with support for nested JSON.

Features

• 2 way: convert JSON to CSV and the other way around.
• Simple: straightforward and flexible API.
• Lightweight: 2KB gzipped with everything included, 1KB gzipped when only using json2csv.
• Fast: faster than the popular CSV libraries out there. See benchmark.
• Safe: handles inhomogeneous data, no risk of data loss.
• Modular: only load what you use, thanks to ES5 modules and a plugin architecture.
• Powerful:
  • Configurable properties: header, delimiter, eol.
  • Configurable fields, with custom value getters and setters and the ability to ignore fields.
  • Configurable serialization and deserialization of values via formatValue and parseValue.
  • Support for nested JSON objects: either flatten nested contents, or stringify as a JSON object.
• Standards compliant: adheres to the CSV standard RFC 4180.
• Universal: Created for the browser, but can be used in any JavaScript environment like node.js. TypeScript types included.

Note that the parser has no streaming support.

Why?

Well, you have to write a CSV parser at least once in you life, right? ;)

The csv42 library was developed specifically for https://jsoneditoronline.org, for use in the browser. Besides being small and fast, one important feature is supporting nested JSON objects. So, why the name csv42? Just because 42 is a beautiful number and to remind us that there is a whole universe of beautiful CSV libraries out there.

Install

npm install csv42

Usage

Install the library once:

Convert JSON to CSV

import { json2csv } from 'csv42'

const users = [
  { id: 1, name: 'Joe', address: { city: 'New York', street: '1st Ave' } },
  { id: 2, name: 'Sarah', address: { city: 'Manhattan', street: 'Spring street' } }
]

// By default, nested JSON properties are flattened
const csv = json2csv(users)
console.log(csv)
// id,name,address.city,address.street
// 1,Joe,New York,1st Ave
// 2,Sarah,Manhattan,Spring street

// You can turn off flattening using the option `flatten`
const csvFlat = json2csv(users, { flatten: false })
console.log(csvFlat)
// id,name,address
// 1,Joe,"{""city"":""New York"",""street"":""1st Ave""}"
// 2,Sarah,"{""city"":""Manhattan"",""street"":""Spring street""}"

// The CSV output can be fully customized and transformed using `fields`:
const csvCustom = json2csv(users, {
  fields: [
    { name: 'name', getValue: (item) => item.name },
    { name: 'address', getValue: (item) => item.address.city + ' - ' + object.address.street }
  ]
})
console.log(csvCustom)
// name,address
// Joe,New York - 1st Ave
// Sarah,Manhattan - Spring street

Convert CSV to JSON

import { csv2json } from 'csv42'

const csv = `id,name,address.city,address.street
1,Joe,New York,1st Ave
2,Sarah,Manhattan,Spring street`

// By default, fields containing a dot will be parsed inty nested JSON objects
const users = csv2json(csv)
console.log(users)
// [
//   { id: 1, name: 'Joe', address: { city: 'New York', street: '1st Ave' } },
//   { id: 2, name: 'Sarah', address: { city: 'Manhattan', street: 'Spring street' } }
// ]

// Creating nested objects can be turned off using the option `nested`
const usersFlat = csv2json(csv, { nested: false })
console.log(usersFlat)
// [
//   { id: 1, name: 'Joe', 'address.city': 'New York', 'address.street': '1st Ave' },
//   { id: 2, name: 'Sarah', 'address.city': 'Manhattan', 'address.street': 'Spring street' }
// ]

// The JSON output can be customized using `fields`
const usersCustom = csv2json(csv, {
  fields: [
    { name: 'name', setValue: (item, value) => (item.name = value) },
    { name: 'address.city', setValue: (item, value) => (item.city = value) }
  ]
})
console.log(usersCustom)
// [
//   { name: 'Joe', city: 'New York' },
//   { name: 'Sarah', city: 'Manhattan' }
// ]

API

json2csv<T>(json: T[], options?: CsvOptions<T>) : string

Where options is an object with the following properties:

| Option | Type | Description | | ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | header | boolean | If true, a header will be created as first line of the CSV. | | delimiter | string | Default delimiter is ,. A delimiter must be a single character. | | eol | \r\n or \n | End of line, can be \r\n (default) or \n. | | flatten | boolean or (value: unknown) => boolean | If true (default), plain, nested objects will be flattened in multiple CSV columns, and arrays and classes will be serialized in a single field. When false, nested objects will be serialized as JSON in a single CSV field. This behavior can be customized by providing your own callback function for flatten. For example, to flatten objects and arrays, you can use json2csv(json, { flatten: isObjectOrArray }), and to flatten a specific class, you can use json2csv(json, { flatten: value => isObject(value) \|\| isCustomClass(value) }). The option flattenis not applicable whenfields is defined. | | fields | CsvField<T>[] or CsvFieldsParser<T> | A list with fields to be put into the CSV file. This allows specifying the order of the fields and which fields to include/excluded. | | formatValue | ValueFormatter | Function used to change any type of value into a serialized string for the CSV. The build in formatter will only enclose values in quotes when necessary, and will stringify nested JSON objects.