json2csv

json2csv is the original Node.js library for converting JSON data into CSV output, published under the plain npm name json2csv since 2012. It exposes a family of parser classes — a synchronous Parser, a promise-based AsyncParser, a StreamParser for streaming input, and a Transform stream for piping — along with a bundled CLI binary for converting files from the command line without writing any code.

The project has been in maintenance mode since 2023, when its maintainers split the codebase into smaller scoped packages (@json2csv/plainjs, @json2csv/node, @json2csv/whatwg, @json2csv/cli, and others) that now receive active development. This original json2csv package remains available on npm — at 6.0.0-alpha.2 — and continues to see wide adoption in existing Node.js projects (over 2 million weekly downloads) thanks to its stable, dependency-light API for field selection, custom formatters, and value transforms like flatten and unwind.

What You Get

• A synchronous Parser class for converting in-memory JSON arrays to CSV strings in one call
• An AsyncParser and StreamParser for processing large or streaming JSON payloads without loading everything into memory
• A Transform stream implementation for piping JSON straight into a writable CSV stream
• Built-in flatten and unwind transforms for handling nested objects and arrays
• A bundled json2csv CLI binary for converting JSON files to CSV from the terminal, with pretty-printed table output
• Per-type formatters (string, number, symbol, object) that control how values are escaped and stringified in each cell

Common Use Cases

• Exporting API or database query results as downloadable CSV reports for end users
• Converting NDJSON log files into CSV for spreadsheet analysis via the CLI
• Streaming large JSON datasets to CSV without buffering the full array in memory
• Flattening nested JSON records (e.g., orders with line items) into flat CSV rows using the unwind transform

Under The Hood

Architecture JSON2CSVBase is an abstract class centralizing options normalization, field-to-value derivation, delimiter/EOL handling, and per-cell formatting dispatch keyed by typeof value; it’s extended by JSON2CSVParser (sync), JSON2CSVAsyncParser, JSON2CSVStreamParser, and JSON2CSVTransform (a Node Transform stream), each of which implements only its own parse/push control flow while inheriting the shared row/cell processing contract. Formatters and transforms (flatten, unwind) are injected as plain functions rather than subclassed, keeping extension points functional instead of object-oriented. The entry point lib/json2csv.js is a thin barrel file re-exporting the four parser classes plus convenience parse/parseAsync wrappers, while bin/json2csv.js is a separate Commander-based CLI that requires the same library and adds file I/O, ndjson parsing, and table printing. Because none of the parser variants reimplement per-cell formatting independently, JSON2CSVBase’s processRow/processCell/processValue methods are the single point that all four variants and the CLI depend on.

Tech Stack Plain CommonJS Node.js with no TypeScript and no framework. Dependencies are deliberately minimal — @streamparser/json for the streaming parser, commander for CLI argument parsing, and lodash.get for safe nested-path access rather than full lodash. Rollup (with babel, commonjs, and node-resolve plugins) builds ESM and UMD browser bundles alongside the CommonJS lib/ used directly by Node, wired through package.json’s main/module/browser fields. Tests run on tape with tap-spec output and nyc coverage; releases use standard-version, and docs are published via docpress + gh-pages. CI runs on Travis, and linting uses a bare eslint:recommended config.

Code Quality Tests are reasonably thorough — dedicated fixture-driven suites exist per parser class (Parser, AsyncParser, AsyncParserInMemory, StreamParser, Transform, CLI, ndjson parsing), comparing output against golden JSON/CSV fixtures rather than just smoke-testing. Error handling is minimal and largely implicit: invalid fields configs and empty-data-without-fields cases throw plain, generic Errors, with no custom error hierarchy or typed errors, and formatter functions generally assume well-typed input without guarding. There is no static type checking — formatter dispatch relies on runtime typeof checks. Naming is consistent across the class hierarchy, and CI exists via Travis, though the project itself documents that it is no longer actively maintained past v6.0.0-alpha.2.

API Design The base-class-plus-functional-extension-points design keeps the everyday API small — most consumers only ever call new Parser(opts).parse(data) or the parse/parseAsync convenience exports — while power users can layer custom formatters and transforms without touching the parser classes. The fields option’s flexible shorthand (a plain string path, {label, value: path}, or {label, value: fn}) minimizes boilerplate for the common case while still supporting fully custom column derivation. Documentation is extensive for a library of this age, with runnable examples covering nearly every option combination and a hosted docs site linked from the README. The main friction is external rather than structural: the top-level README is entirely a deprecation notice pointing at a successor project, so newcomers have to look past it into docs/ or the npm listing to find working examples, even though the underlying API remains solid and the package still sees heavy download volume.