or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

formatting.mdindex.mdparsing.md
tile.json

tessl/npm-fast-csv

CSV parser and writer with streaming support for high-performance processing of large files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fast-csv@5.0.x

To install, run

npx @tessl/cli install tessl/npm-fast-csv@5.0.0

index.mddocs/

Fast CSV

Fast CSV is a comprehensive CSV parsing and formatting library for Node.js built with TypeScript. It provides efficient, stream-based processing for both reading CSV data into JavaScript objects and converting JavaScript objects into CSV format. The library is designed to handle large files efficiently without creating a large memory footprint, making it suitable for processing millions of records in production environments.

Package Information

  • Package Name: fast-csv
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install fast-csv

Core Imports

import { parse, format, write, writeToString } from "fast-csv";

For CommonJS:

const { parse, format, write, writeToString } = require("fast-csv");

Individual package imports:

import { parse, parseFile } from "@fast-csv/parse";
import { format, writeToString } from "@fast-csv/format";

Basic Usage

Parsing CSV

import { parse } from "fast-csv";
import fs from "fs";

// Parse from file stream
fs.createReadStream("data.csv")
  .pipe(parse({ headers: true }))
  .on("data", (row) => console.log(row))
  .on("end", (rowCount) => console.log(`Parsed ${rowCount} rows`));

// Parse from string
const csvData = "name,age\nJohn,25\nJane,30";
parse(csvData, { headers: true })
  .on("data", (row) => console.log(row))
  .on("end", () => console.log("Parsing complete"));

Formatting CSV

import { writeToString, format } from "fast-csv";

// Write array to CSV string
const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

const csvString = await writeToString(data, { headers: true });
console.log(csvString);

// Stream formatting
const csvStream = format({ headers: true });
csvStream.pipe(process.stdout);
csvStream.write({ name: "John", age: 25 });
csvStream.write({ name: "Jane", age: 30 });
csvStream.end();

Architecture

Fast CSV is structured as a monorepo with three main packages:

  • fast-csv: Main package providing unified interface to both parsing and formatting
  • @fast-csv/parse: Dedicated CSV parsing functionality with stream-based processing
  • @fast-csv/format: Dedicated CSV formatting functionality with flexible output options

The library uses Node.js Transform streams for efficient processing, allowing for:

  • Stream Processing: Handle large files without loading everything into memory
  • Flexible Configuration: Extensive options for different CSV dialects and formats
  • Transform Functions: Custom data transformation and validation during processing
  • Type Safety: Full TypeScript support with generic type preservation

Capabilities

CSV Parsing

Comprehensive CSV parsing functionality with support for various CSV dialects, custom transformations, and validation. Handles headers, different delimiters, quoted fields, and provides both streaming and batch processing options.

function parse<I extends Row, O extends Row>(args?: ParserOptionsArgs): CsvParserStream<I, O>;
function parseFile<I extends Row, O extends Row>(location: string, options?: ParserOptionsArgs): CsvParserStream<I, O>;
function parseString<I extends Row, O extends Row>(string: string, options?: ParserOptionsArgs): CsvParserStream<I, O>;
function parseStream<I extends Row, O extends Row>(stream: NodeJS.ReadableStream, options?: ParserOptionsArgs): CsvParserStream<I, O>;

interface ParserOptionsArgs {
  objectMode?: boolean;
  delimiter?: string;
  quote?: string | null;
  escape?: string;
  headers?: boolean | HeaderTransformFunction | HeaderArray;
  renameHeaders?: boolean;
  ignoreEmpty?: boolean;
  comment?: string;
  strictColumnHandling?: boolean;
  discardUnmappedColumns?: boolean;
  trim?: boolean;
  ltrim?: boolean;
  rtrim?: boolean;
  encoding?: string;
  maxRows?: number;
  skipLines?: number;
  skipRows?: number;
}

type Row<V = any> = RowMap<V> | RowArray<V>;
type RowMap<V = any> = Record<string, V>;
type RowArray<V = any> = V[];

CSV Parsing

CSV Formatting

Flexible CSV formatting and writing functionality supporting various output formats including strings, buffers, files, and streams. Provides extensive customization options for delimiters, quoting, headers, and data transformation.

function format<I extends Row, O extends Row>(options?: FormatterOptionsArgs<I, O>): CsvFormatterStream<I, O>;
function write<I extends Row, O extends Row>(rows: I[], options?: FormatterOptionsArgs<I, O>): CsvFormatterStream<I, O>;
function writeToString<I extends Row, O extends Row>(rows: I[], options?: FormatterOptionsArgs<I, O>): Promise<string>;
function writeToBuffer<I extends Row, O extends Row>(rows: I[], opts: FormatterOptionsArgs<I, O> = {}): Promise<Buffer>;
function writeToPath<I extends Row, O extends Row>(path: string, rows: I[], options?: FormatterOptionsArgs<I, O>): fs.WriteStream;
function writeToStream<T extends NodeJS.WritableStream, I extends Row, O extends Row>(ws: T, rows: I[], options?: FormatterOptionsArgs<I, O>): T;

interface FormatterOptionsArgs<I extends Row, O extends Row> {
  objectMode?: boolean;
  delimiter?: string;
  rowDelimiter?: string;
  quote?: string | boolean;
  escape?: string;
  quoteColumns?: boolean | boolean[] | Record<string, boolean>;
  quoteHeaders?: boolean | boolean[] | Record<string, boolean>;
  headers?: null | boolean | string[];
  writeHeaders?: boolean;
  includeEndRowDelimiter?: boolean;
  writeBOM?: boolean;
  transform?: RowTransformFunction<I, O>;
  alwaysWriteHeaders?: boolean;
}

CSV Formatting

Common Types

// Row type definitions
type Row<V = any> = RowMap<V> | RowArray<V>;
type RowMap<V = any> = Record<string, V>;
type RowArray<V = any> = V[];

// Format-specific row types
type FormatterRow = RowArray | RowHashArray | RowMap;
type RowHashArray<V = any> = [string, V][];

// Transform function types
type RowTransformCallback<R extends Row> = (error?: Error | null, row?: R) => void;
type SyncRowTransform<I extends Row, O extends Row> = (row: I) => O;
type AsyncRowTransform<I extends Row, O extends Row> = (row: I, cb: RowTransformCallback<O>) => void;
type RowTransformFunction<I extends Row, O extends Row> = SyncRowTransform<I, O> | AsyncRowTransform<I, O>;

// Validation types (parsing only)
type RowValidateCallback = (error?: Error | null, isValid?: boolean, reason?: string) => void;
type SyncRowValidate<R extends Row> = (row: R) => boolean;
type AsyncRowValidate<R extends Row> = (row: R, cb: RowValidateCallback) => void;
type RowValidate<R extends Row> = AsyncRowValidate<R> | SyncRowValidate<R>;

// Header types (parsing only)
type HeaderArray = (string | undefined | null)[];
type HeaderTransformFunction = (headers: HeaderArray) => HeaderArray;