csv-parse

csv-parse is a mature CSV parser that converts CSV text into arrays or objects. It implements the Node.js stream.Transform API while also offering simpler callback and synchronous interfaces, so you can pick the flavor that fits your workload. First released in 2010 and part of the broader CSV project by Adaltas, it is battle-tested against large datasets by a wide community.

The parser handles the full range of real-world CSV quirks: custom delimiters, quotes, escape characters, comments, BOM handling, and automatic line-break discovery. It ships with zero external dependencies and multiple distributions covering Node.js, the web, ECMAScript modules, and CommonJS.

What You Get

• A streaming parser implementing the Node.js stream.Transform API for backpressure-aware pipelines
• Callback and synchronous APIs for convenient one-shot parsing without wiring up streams
• A rich option set covering delimiters, quotes, escapes, comments, columns, casting, and BOM handling
• Multiple distributions: Node.js, browser, ESM, and CommonJS with bundled TypeScript type definitions
• Zero runtime dependencies and support across Node.js 8 through the latest release

Common Use Cases

• Ingesting large CSV exports into a Node.js data pipeline via streams
• Parsing user-uploaded CSV files into typed objects in a web application
• Quickly converting a CSV string to an array of records synchronously in a script or test
• Reading delimited data (TSV, colon-separated, custom delimiters) from external systems

Under The Hood

Architecture

csv-parse is structured around a framework-agnostic parsing core in lib/api/index.js (the transform function) that maintains an incremental byte-level state machine, tracking quoting, escapes, record delimiters, comments, and column mapping across buffer chunks via init_state.js and normalize_options.js. Three thin adapters wrap this core: lib/index.js exposes a Parser class extending Node’s stream.Transform plus a flexible parse() function that detects string/options/callback arguments; lib/sync.js drives the same core in a single blocking pass; and lib/stream.js provides a web-stream binding. Records flow out through a push callback, keeping the engine decoupled from the delivery mechanism.

Tech Stack

Written in modern JavaScript (ESM source) with hand-authored TypeScript declarations (lib/index.d.ts). The package is dependency-free at runtime and built with Rollup, producing CJS and ESM/browser distributions under dist/. Dev tooling includes Mocha with tsx for tests, Prettier, ESLint, and TypeScript for type-checking. It is part of a Lerna-managed monorepo alongside csv-generate, csv-stringify, and stream-transform.

Code Quality

Code quality is high. The repository holds roughly 90 test files plus 72 sample inputs, giving the parser broad coverage across options and edge cases; tests run under Mocha against both JS and TS. Errors are surfaced through a dedicated CsvError class carrying stable error codes (e.g. CSV_INVALID_ARGUMENT), and option normalization is centralized and heavily validated. Naming is descriptive and the core is clearly separated from its stream/sync/web adapters.

API Design

The public API is deliberately ergonomic: a single parse entry point accepts data, options, and callback in flexible order, while csv-parse/sync and csv-parse/stream subpath exports keep each usage style explicit. Options are richly documented on csv.js.org with numerous examples, and TypeScript types are bundled. Getting started requires almost no boilerplate for the sync and callback paths, while the stream API follows familiar Node.js conventions.