json2csv Documentation

json2csv is a fast and highly configurable library designed to convert JSON data into CSV or other text-delimited formats like TSV. It is compliant with the RFC4180 specification.

The library is versatile and can be used in several environments:

• As a Node.js module
• In the browser
• Via the Command Line Interface (CLI)

json2csv is a fast and highly configurable JSON to CSV converter. It supports standard JSON and NDJSON, and is designed to scale to infinitely large datasets using stream processing. Key capabilities include:

• Advanced Data Selection: Automatic field discovery, underscore-like selectors, custom data getters, and default values for missing fields.
• Customization: Support for custom input data transformation, custom CSV cell formatting, and highly customizable delimiters, quotation marks, and EOL values.
• Robustness: Automatic escaping (preserving new lines, quotes, etc.) and Unicode encoding support.
• Output Options: Optional headers and pretty printing in table format to stdout.

A transform is a function used to preprocess data records before they are converted into CSV. Each transform receives a data record, performs processing, and returns a transformed record.

Transforms are passed as an array to the transforms option when initializing a parser. They are applied in the order they are declared in the array.

const opts = {
  transforms: [
    transformA(),
    transformB(),
    (item) => ({ ...item, newField: 'value' }) // Custom inline transform
  ]
};
const parser = new Parser(opts);

The StreamParser is a streaming API designed to process JSON data incrementally. Unlike the synchronous API, which loads the entire JSON array into memory and blocks the JavaScript event loop, StreamParser processes data as it arrives.

Use StreamParser when:

• You are dealing with large datasets that might exceed available memory.
• You are working in high-concurrency environments (like a server) where blocking the event loop would impact other requests.
• You want to keep a UI responsive during data processing.

It is particularly well-suited for large datasets or systems requiring high concurrency.

You can enhance your conversion process using two specialized libraries:

• @json2csv/transforms: Provides built-in transforms like unwind and flatten. These allow you to transform your data structure before it is parsed into CSV.
• @json2csv/formatters: Provides built-in formatters for various data types (including an Excel-specific one). Formatters convert JSON data types into CSV-compatible strings.

The Parser is a synchronous JSON to CSV converter. It loads the entire dataset into memory and blocks the JavaScript event loop during processing.

When to use: Only use this for very small datasets where blocking the event loop is not a concern.

import { Parser } from '@json2csv/plainjs';

try {
  const opts = {};
  const parser = new Parser(opts);
  const csv = parser.parse(myData);
  console.log(csv);
} catch (err) {
  console.error(err);
}

Formatters allow you to control how different data types (like numbers or strings) are represented in the resulting CSV. They are configured by passing a formatters object within the options passed to a parser. The keys in the formatters object correspond to the data types (e.g., number, string), and the values are the formatter functions. You can use built-in formatters from @json2csv/formatters or provide your own custom formatter functions.

import { Parser } from '@json2csv/plainjs';
import { number as numberFormatter } from '@json2csv/formatters';

const opts = {
  formatters: {
    number: numberFormatter({ decimals: 3, separator: ',' }),
    string: (val) => val.toUpperCase() // Example of a custom formatter
  }
};

const parser = new Parser(opts);
const csv = parser.parse(myData);

A formatter is a function used to convert JavaScript values into plain text before they are added to a CSV cell. Formatters are mapped to the types returned by typeof (e.g., string, number, boolean, object, etc.) and a special headers type used for column names.

Note that the string formatter is a foundational component; other formatters like headers or object rely on the string formatter to handle the final stringification, quoting, and escaping of their values.

The Transform constructor accepts three distinct options objects:

1. opts: Configuration for the CSV generation (see Options).
2. asyncOpts: Options for the underlying parsing library (see Async Options). Not relevant in objectMode.
3. transformOpts: Standard Node.js Duplex stream options.

When providing JSON for conversion to CSV, ensure the input follows these rules:

• Valid JSON: The input must be strictly valid JSON.
• Quoted Fields: All keys must be quoted. For example, { "a": 1 } is valid, but { a: 1 } is not.
• No undefined: The value undefined is not supported in the input JSON.

json2csv provides several advanced capabilities for data conversion:

• Data Formats: Supports standard JSON as well as NDJSON (Newline Delimited JSON).
• Scalability: Uses stream processing to handle infinitely large datasets without exhausting memory.
• Data Selection: Features automatic field discovery, underscore-like selectors, custom data getters, and default values for missing fields.
• Customization:
  • Custom input data transformation.
  • Custom CSV cell formatting.
  • Configurable delimiters, quotation marks, and EOL (end-of-line) values.
• Robustness: Automatic escaping (preserving new lines and quotes) and Unicode encoding support.
• Output Options: Supports optional headers and pretty printing in table format to stdout.