{"id":13027,"library":"csv-parser","title":"Streaming CSV Parser","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mafintosh/csv-parser","tags":["javascript","csv","parser","fast","json","typescript"],"install":[{"cmd":"npm install csv-parser","lang":"bash","label":"npm"},{"cmd":"yarn add csv-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add csv-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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')`.","wrong":"import { csv } from 'csv-parser'","symbol":"default export (function)","correct":"import csv from 'csv-parser'"},{"note":"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.","wrong":"import { Options } from 'csv-parser'","symbol":"csv.Options (type)","correct":"import csv from 'csv-parser';\ntype CsvOptions = csv.Options;"},{"note":"The `Row` type, representing a parsed CSV record, is nested under the default export's namespace. It defines the structure of parsed CSV records.","wrong":"import { Row } from 'csv-parser'","symbol":"csv.Row (type)","correct":"import csv from 'csv-parser';\ntype CsvRow = csv.Row;"}],"quickstart":{"code":"import * as fs from 'fs';\nimport * as path from 'path';\nimport csv from 'csv-parser';\n\nconst results: csv.Row[] = [];\nconst csvFilePath = path.join(__dirname, 'data.csv');\n\n// Create a dummy CSV file for the quickstart to be runnable\nconst dummyCsvContent = `NAME,AGE,CITY\\nDaffy Duck,24,Looney Tunes City\\nBugs Bunny,22,Carrotville\\nElmer Fudd,55,Hunter's Hollow`;\nfs.writeFileSync(csvFilePath, dummyCsvContent);\n\nfs.createReadStream(csvFilePath)\n  .pipe(csv({\n    separator: ',',\n    headers: ['firstName', 'age', 'location'],\n    skipLines: 1\n  })) // Example with options: custom headers, skipping original header line\n  .on('data', (data: csv.Row) => results.push(data))\n  .on('end', () => {\n    console.log('Parsed CSV Data:', results);\n    // Expected output similar to:\n    // [\n    //   { firstName: 'Daffy Duck', age: '24', location: 'Looney Tunes City' },\n    //   { firstName: 'Bugs Bunny', age: '22', location: 'Carrotville' },\n    //   { firstName: 'Elmer Fudd', age: '55', location: 'Hunter\\'s Hollow' }\n    // ]\n    fs.unlinkSync(csvFilePath); // Clean up the dummy file\n  })\n  .on('error', (err: Error) => {\n    console.error('Error parsing CSV:', err);\n    fs.unlinkSync(csvFilePath); // Clean up even on error\n  });\n\nconsole.log('CSV parsing initiated...');","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade Node.js to version 10 or later.","message":"Version 3.0.0 and above drops support for Node.js 8. Ensure your environment uses Node.js 10 or higher to avoid compatibility issues.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review parsing results for CSV files with broken lines if upgrading from versions prior to v3.0.0, as behavior may differ.","message":"In 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"When providing only headers: `csv(['Header1', 'Header2'])`. When providing options and headers: `csv({ separator: ',', headers: ['Header1', 'Header2'] })`.","message":"The `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.","severity":"gotcha","affected_versions":"*"},{"fix":"Upgrade to `csv-parser` v2.3.2 or later, which includes a fix for this specific interaction.","message":"Combining the `strict` option with `skipLines` in versions prior to 2.3.2 could lead to unexpected parsing errors or incorrect line skipping.","severity":"gotcha","affected_versions":"<2.3.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Incorrect import method (e.g., named import for a default export) or attempting to instantiate a non-constructor function.","error":"TypeError: csv is not a function"},{"fix":"Upgrade to `csv-parser` version 2.3.2 or later, which includes a fix for this specific interaction.","cause":"A bug in older versions (pre-v2.3.2) when using the `strict` option concurrently with `skipLines`.","error":"Error: strict + skipLines error"},{"fix":"Upgrade to `csv-parser` version 3.0.0 or later, which contains a fix for this issue.","cause":"A parsing bug in versions prior to 3.0.0 where malformed lines could cause subsequent headers to be lost.","error":"Losing all headers after a broken line"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}