{"id":13173,"library":"fast-csv","title":"Fast CSV Parser and Writer","description":"fast-csv is a robust and high-performance CSV parser and writer library for Node.js, designed to handle large datasets efficiently. The current stable version is 5.0.5. It generally maintains a steady release cadence, with minor updates and bug fixes appearing every few months, and major versions released less frequently, typically when significant API changes or new features warrant it. Key differentiators include its streaming API, which allows for processing CSV data without buffering the entire file into memory, making it suitable for very large files. It supports both parsing (reading) and formatting (writing) CSV data, offering flexible configuration options for headers, delimiters, quotes, and escape characters, and ships with full TypeScript type definitions.","status":"active","version":"5.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/C2FO/fast-csv","tags":["javascript","csv","parser","fast","writer","csv writer","CSV","typescript"],"install":[{"cmd":"npm install fast-csv","lang":"bash","label":"npm"},{"cmd":"yarn add fast-csv","lang":"bash","label":"yarn"},{"cmd":"pnpm add fast-csv","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM imports are recommended for modern Node.js projects. CommonJS `require` still works.","wrong":"const { parseFile } = require('fast-csv');","symbol":"parseFile","correct":"import { parseFile } from 'fast-csv';"},{"note":"The `format` function is a named export, not a default export.","wrong":"import format from 'fast-csv';","symbol":"format","correct":"import { format } from 'fast-csv';"},{"note":"Import types separately using `import type` for clarity and better tree-shaking with TypeScript.","symbol":"FormatterOptions","correct":"import type { FormatterOptions } from 'fast-csv';"}],"quickstart":{"code":"import { parseFile, format } from 'fast-csv';\nimport * as fs from 'node:fs';\n\nconst inputFilePath = './data.csv';\nconst outputFilePath = './output.csv';\n\n// Create a dummy CSV file for demonstration\nfs.writeFileSync(inputFilePath, 'header1,header2\\nvalue1,value2\\nvalue3,value4');\n\nconst rows: { header1: string; header2: string }[] = [];\n\nparseFile(inputFilePath, { headers: true })\n  .on('error', error => console.error('Error parsing CSV:', error))\n  .on('data', row => rows.push(row))\n  .on('end', (rowCount: number) => {\n    console.log(`Parsed ${rowCount} rows.`);\n    console.log('Original Rows:', rows);\n\n    // Modify data and write to a new CSV\n    const modifiedRows = rows.map(row => ({ \n      header1: `MODIFIED_${row.header1}`, \n      header2: `${row.header2}_END` \n    }));\n\n    const ws = fs.createWriteStream(outputFilePath);\n    format(modifiedRows, { headers: true })\n      .on('error', error => console.error('Error writing CSV:', error))\n      .pipe(ws)\n      .on('end', () => console.log('CSV file successfully written to output.csv'));\n  });\n","lang":"typescript","description":"Demonstrates reading a CSV file, modifying its content, and then writing the modified data to a new CSV file using streaming APIs."},"warnings":[{"fix":"Ensure `@types/node` is installed as a dev dependency (`npm install --save-dev @types/node`) if you are using TypeScript and targeting Node.js APIs directly in your project.","message":"Version 5.0.0 introduced breaking changes related to internal dependencies and potentially minor API adjustments. Specifically, `@types/node` was removed from package dependencies, implying users should manage their `@types/node` installation if required for their environment.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always explicitly set the `headers` option in `parseFile` or `parseStream` to `true` if your CSV has headers and you want object-based rows, or to `false` if you expect array-based rows.","message":"When parsing CSVs without explicit `headers: true`, the data will be returned as an array of strings per row. If `headers: true` is used, data will be returned as objects where keys correspond to header names. Mixing these assumptions can lead to runtime errors.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Always include an `.on('error', errorHandler)` listener in your parsing and formatting pipelines to gracefully handle issues like file read errors, invalid CSV formats, or write errors.","message":"The `fast-csv` parser uses an event-driven streaming approach. Forgetting to attach 'error' event listeners to the parser stream can lead to unhandled promise rejections or uncaught exceptions, silently terminating your application when malformed data or I/O errors occur.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"For precise control over quoting, refer to the `quote` and `quoteColumns` options in the `FormatterOptions`. If you want to force quoting for all fields, you might need a custom transform or specific formatter configuration.","message":"Default quoting behavior for the formatter can sometimes lead to unexpected results if fields contain delimiters or newlines but are not explicitly quoted. The formatter attempts to be smart about quoting, but specific scenarios might require overriding this.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `format()` function returns a writable stream, usually by providing an array of data. When writing to a file, ensure `fs.createWriteStream()` is correctly called and that the `format` function is called with the data to be written.","cause":"Attempting to call `.pipe()` on a `fast-csv` stream that hasn't been properly initialized or is not a Writable stream.","error":"TypeError: Cannot read properties of undefined (reading 'pipe')"},{"fix":"Add an `.on('error', (err) => console.error(err))` listener to your `parseFile`, `parseStream`, `format`, or `pipe` chain to catch and handle errors gracefully.","cause":"A stream operation (parsing or formatting) encountered an error (e.g., malformed CSV, file read/write error) but no error handler was attached.","error":"Error: Unhandled 'error' event."},{"fix":"Check the official documentation or type definitions (`.d.ts` files) for the correct named exports. For example, `format` is a named export, not `formatDefault` or a default export.","cause":"Trying to import `formatDefault` or other symbols that are not explicitly exported by the `fast-csv` module, or using an incorrect import style.","error":"TS2305: Module '\"fast-csv\"' has no exported member 'formatDefault'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}