Simple, lightweight, intelligent CSV-parser for Node.js — now in TypeScript

• TypeScript rewrite — full type definitions, strict mode, ES2022 output.
• Promise support — callbacks are now optional; you can await the result.
• Worker-thread support — parsing of CSV files larger than 3 MB is automatically off-loaded to a separate worker_threads thread so your main thread stays responsive.
• Pagination — query large datasets selectively and securely using { start, count }.

npm install csv-array

This package exports a highly efficient function to parse CSV files. Under the hood, it intelligently shifts between main-thread streaming and worker-thread batching depending on the size of the target payload.

function parseCSV(
  fileName: string,
  callBack?: ParseCSVCallback,
  considerFirstRowAsHeading?: boolean,
  pagination?: Pagination
): void | Promise<CSVRow[]>

You can use standard callbacks or omit the callback parameter entirely to receive a Promise<CSVRow[]>:

// Standard async/await Promises
const data = await parseCSV("data.csv");

// Callbacks
parseCSV("data.csv", (data) => console.log(data));

If your provided file exceeds 10 MB in size, csv-array automatically spawns a Node.js worker_threads instance. This completely isolates heavy disk I/O and string parsing logic, meaning your main server thread will never freeze. Your API usage patterns remain identical whether the file is 1 MB or 2 GB.

Reading massive CSV files into an array often results in Out of Memory crash errors. To prevent this, structural pagination can be strictly applied. The internal stream closes the moment your requested chunk is achieved, ensuring optimal execution times.

The library is cleanly typed, exporting standard module boundaries like parseCSV, and typings like CSVRow, CSVObjectRow, and Pagination. This allows deep integration into strict typed pipelines.

import { parseCSV, CSVRow, Pagination } from 'csv-array';

async function processData() {
  
  // Example 1: Standard usage with headings (Returns an array of objects)
  // No callback is passed, so we can await it cleanly!
  const users = await parseCSV('users.csv');
  console.log('First user name:', users[0]['Name']);

  // Example 2: Without heading objects (Returns an array of raw strings)
  const rawRows = await parseCSV('data.csv', undefined, false);
  console.log('Header keys:', rawRows[0]);
  console.log('First entry payload:', rawRows[1]);

  // Example 3: Handling massive files using Pagination & Callbacks
  const paginationConfig: Pagination = { start: 1500, count: 25 };
  
  parseCSV(
    'massive-system-dataset.csv', 
    (data: CSVRow[]) => {
       console.log(`Memory-safe slice executed! Received ${data.length} records.`);
    }, 
    true, 
    paginationConfig
  );

}

processData();

If you find any issues feel free to contact me at [email protected]