csv-parser

csv-parser is a Node.js Transform stream that turns CSV data into JSON row objects as it arrives, so files of any size can be processed with flat memory usage instead of being loaded whole into memory first. It is written as a single hand-tuned module with zero runtime dependencies, and its correctness is checked against the community csv-spectrum acid-test suite covering quoted fields, embedded commas and newlines, and escaped quote characters.

Beyond the library API, the package ships a csv-parser CLI binary that converts a CSV file or stdin into newline-delimited JSON directly from the command line, and TypeScript definitions are bundled and verified with tsd so consumers get accurate types without a separate @types package.

What You Get

• Streaming Transform interface - Pipe any Readable stream (file, HTTP response, stdin) through csv() and receive parsed row objects via the standard data event, without buffering the whole file in memory.
• Header inference and mapping - Object keys are derived automatically from the first row, or supplied as a custom headers array; mapHeaders and mapValues callbacks let you rename or transform data as it’s parsed.
• Configurable dialect options - separator, quote, escape, newline, skipLines, and skipComments handle TSVs, custom quote characters, and files with leading comments or blank preamble lines.
• Bundled CLI - The csv-parser executable converts CSV files or stdin into newline-delimited JSON directly from the command line, with flags mirroring the library’s options.

Common Use Cases

• ETL and data import pipelines - Backend services stream uploaded CSV exports (e.g. from CRMs or spreadsheets) directly into a database without holding the full file in memory.
• Log and report processing - Ops scripts read large CSV log dumps row-by-row to compute aggregates or filter records.
• One-off command-line conversions - Developers pipe a CSV file through the bundled CLI into newline-delimited JSON for use with tools like jq.
• Custom dialect handling - Teams parsing TSVs or CSVs with nonstandard quote/escape characters configure separator/quote/escape instead of writing a bespoke parser.

Under The Hood

Architecture The package is a single-file module (index.js) exporting a factory function that instantiates a CsvParser class extending Node’s stream.Transform in object mode. Parsing is done with hand-rolled byte-level scanning rather than regex or a grammar library: _transform buffers cross-chunk partial lines via this._prev and walks the incoming buffer byte by byte, while parseLine/parseCell tokenize each row into cells while tracking quote/escape state. All parsing state lives in one this.state object (quoted, escaped, lineNumber, previousEnd, rowLength), and header inference is folded into the same parseLine path rather than a separate stage. A sanitizeHeader guard rejects dangerous keys (__proto__, constructor, prototype) before writeRow builds each output object. There is no separate lexer/tokenizer/writer layering — it is a flat, single-class design optimized for throughput over separation of concerns, so a change to the core buffer-scanning loop in _transform would ripple through nearly everything downstream that depends on its byte offsets.

Tech Stack The library has zero runtime dependencies — package.json declares none — and targets plain Node.js (engines: node >= 10) with no build step; the shipped index.d.ts is hand-written and verified against real usage via tsd rather than compiled from TypeScript source. Development tooling is comprehensive: ava for tests, nyc for coverage, eslint with eslint-config-standard for linting, husky + lint-staged + pre-commit to gate commits, and commitlint to enforce conventional commit messages. The csv-spectrum package supplies the acid-test fixtures used in the test suite, and execa/globby/chalk/text-table/time-span back the bin/bench.js benchmarking script. CI runs on Travis (.travis.yml) with Codecov for coverage reporting.

Code Quality The test/ directory is organized one file per option or feature (headers, escape, quote, newline, skipLines, skipComments, maxRowBytes, strict, mapHeaders, mapValues, byteOffset, plus a general issues.test.js and test.js), giving each configuration surface its own focused coverage, backed by fixture files and snapshots. Type definitions are exercised through tsd (index.test-d.ts), so the public TypeScript surface is checked against actual call signatures rather than left unverified. Errors are surfaced idiomatically through the stream’s error event (a RangeError for header/row length mismatches in strict mode, a plain Error when maxRowBytes is exceeded) rather than thrown or swallowed. Naming is terse but consistent (parseCell, parseLine, writeRow), and eslint-config-standard plus pre-commit hooks keep style uniform across contributions.

API Design Getting started requires two lines — require('csv-parser') and .pipe(csv()) — with sensible defaults for every option (comma separator, double-quote quoting/escaping, auto-detected newline style). mapHeaders and mapValues give consumers a single, well-defined extension point for renaming or coercing data inline instead of requiring a second pass over parsed rows, and passing an array directly (csv(['Name', 'Age'])) is a shorthand for the common case of supplying explicit headers. Bundled, tsd-verified type definitions mean TypeScript consumers get accurate autocomplete and compile-time checks without installing a separate @types package, and the equivalent CLI binary covers the no-code case by mirroring the same option names as command-line flags.