csv-parser

library3.2.0jsnpmunverified

csv-parser is a high-performance streaming CSV parser for Node.js, currently at version 3.2.0. It efficiently converts CSV data into JSON objects using a Node.js readable stream interface, designed for maximum speed and rigorous compatibility with the `csv-spectrum` test suite. The library is capable of processing approximately 90,000 rows per second, with performance varying based on data characteristics. It includes TypeScript type definitions, enabling robust development in typed environments, and is compatible with browserify for client-side applications. While direct stream piping is common, a Promise-based wrapper is available via `neat-csv`. The project maintains an active release cadence, focusing on bug fixes, performance, and compatibility with modern Node.js runtimes.

http-networking

npm install csv-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CSV-PARSER

csv-parser

http-networkingjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (function)

✓ import csv from 'csv-parser'

✗ import { csv } from 'csv-parser'

The primary export is a default function (a CommonJS module exporting a function); named imports like `{ csv }` are incorrect for ESM. For CommonJS, use `const csv = require('csv-parser')`.

csv.Options (type)

✓ import csv from 'csv-parser'; type CsvOptions = csv.Options;

✗ import { Options } from 'csv-parser'

The `Options` interface for configuring the parser is nested under the default export's namespace. It is accessed via dot notation on the imported module object/function.

csv.Row (type)

✓ import csv from 'csv-parser'; type CsvRow = csv.Row;

✗ import { Row } from 'csv-parser'

The `Row` type, representing a parsed CSV record, is nested under the default export's namespace. It defines the structure of parsed CSV records.

Demonstrates how to parse a CSV file with custom headers and options, piping a file stream through `csv-parser` and collecting results. This example includes setup and cleanup for a runnable script.

import * as fs from 'fs'; import * as path from 'path'; import csv from 'csv-parser'; const results: csv.Row[] = []; const csvFilePath = path.join(__dirname, 'data.csv'); // Create a dummy CSV file for the quickstart to be runnable const dummyCsvContent = `NAME,AGE,CITY\nDaffy Duck,24,Looney Tunes City\nBugs Bunny,22,Carrotville\nElmer Fudd,55,Hunter's Hollow`; fs.writeFileSync(csvFilePath, dummyCsvContent); fs.createReadStream(csvFilePath) .pipe(csv({ separator: ',', headers: ['firstName', 'age', 'location'], skipLines: 1 })) // Example with options: custom headers, skipping original header line .on('data', (data: csv.Row) => results.push(data)) .on('end', () => { console.log('Parsed CSV Data:', results); // Expected output similar to: // [ // { firstName: 'Daffy Duck', age: '24', location: 'Looney Tunes City' }, // { firstName: 'Bugs Bunny', age: '22', location: 'Carrotville' }, // { firstName: 'Elmer Fudd', age: '55', location: 'Hunter\'s Hollow' } // ] fs.unlinkSync(csvFilePath); // Clean up the dummy file }) .on('error', (err: Error) => { console.error('Error parsing CSV:', err); fs.unlinkSync(csvFilePath); // Clean up even on error }); console.log('CSV parsing initiated...');

Debug

Known issues

breakingVersion 3.0.0 and above drops support for Node.js 8. Ensure your environment uses Node.js 10 or higher to avoid compatibility issues.

fix

Upgrade Node.js to version 10 or later.

affects: >=3.0.0

breakingIn v3.0.0, a fix for 'losing all headers after a broken line' was implemented. This might subtly change parsing behavior for malformed CSVs that previously dropped headers due to internal parsing errors.

fix

Review parsing results for CSV files with broken lines if upgrading from versions prior to v3.0.0, as behavior may differ.

affects: >=3.0.0

gotchaThe `headers` option can be provided either as an array of strings directly to `csv()`, or as a `headers` property within an options object. Misunderstanding this can lead to incorrect header mapping or parsing errors.

fix

When providing only headers: `csv(['Header1', 'Header2'])`. When providing options and headers: `csv({ separator: ',', headers: ['Header1', 'Header2'] })`.

affects: *

gotchaCombining the `strict` option with `skipLines` in versions prior to 2.3.2 could lead to unexpected parsing errors or incorrect line skipping.

fix

Upgrade to `csv-parser` v2.3.2 or later, which includes a fix for this specific interaction.

affects: <2.3.2

Errors

Common errors & fixes

TypeError: csv is not a function

Incorrect import method (e.g., named import for a default export) or attempting to instantiate a non-constructor function.

fix

For ESM, use `import csv from 'csv-parser';`. For CommonJS, use `const csv = require('csv-parser');`. Ensure `csv()` is called as a function, not with `new`.

Error: strict + skipLines error

A bug in older versions (pre-v2.3.2) when using the `strict` option concurrently with `skipLines`.

fix

Upgrade to `csv-parser` version 2.3.2 or later, which includes a fix for this specific interaction.

Losing all headers after a broken line

A parsing bug in versions prior to 3.0.0 where malformed lines could cause subsequent headers to be lost.

fix

Upgrade to `csv-parser` version 3.0.0 or later, which contains a fix for this issue.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mafintosh/csv-parser ↗

packagehttps://www.npmjs.com/package/csv-parser ↗