or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdparser-stream.mdparsing-functions.md
tile.json

index.mddocs/

Fast CSV Parse

Fast CSV Parse is a high-performance streaming CSV parsing library for Node.js that avoids large memory footprints when processing large datasets. It provides flexible configuration options for handling various CSV formats, custom delimiters, header processing, data transformation, and error handling with full TypeScript support.

Package Information

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

Core Imports

import { parse, parseFile, parseStream, parseString, CsvParserStream } from "@fast-csv/parse";

For CommonJS:

const { parse, parseFile, parseStream, parseString, CsvParserStream } = require("@fast-csv/parse");

Basic Usage

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

// Parse a CSV file with headers
parseFile("data.csv", { headers: true })
  .on("error", error => console.error(error))
  .on("data", row => console.log(row))
  .on("end", rowCount => console.log(`Parsed ${rowCount} rows`));

// Parse with transformation
parseFile("data.csv", { headers: true })
  .transform(row => ({
    id: parseInt(row.id),
    name: row.name.trim(),
    active: row.active === "true"
  }))
  .on("data", row => console.log(row));

Architecture

Fast CSV Parse is built around several key components:

  • Parser Functions: Factory functions (parse, parseFile, parseStream, parseString) that create configured parser streams
  • CsvParserStream: Core Transform stream that handles the actual CSV parsing with chainable transformation and validation
  • Configuration System: Comprehensive options for delimiter, quote handling, headers, trimming, and row limits
  • Type System: Full TypeScript generics for input/output row types with support for both object and array row formats

Capabilities

Core Parsing Functions

Factory functions for creating CSV parser streams from different input sources with configurable 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 parseStream<I extends Row, O extends Row>(stream: NodeJS.ReadableStream, options?: ParserOptionsArgs): CsvParserStream<I, O>;
function parseString<I extends Row, O extends Row>(string: string, options?: ParserOptionsArgs): CsvParserStream<I, O>;

Core Parsing Functions

CSV Parser Stream

Transform stream class that provides chainable transformation and validation methods for processing CSV data.

class CsvParserStream<I extends Row, O extends Row> extends Transform {
  constructor(parserOptions: ParserOptions);
  transform(transformFunction: RowTransformFunction<I, O>): CsvParserStream<I, O>;
  validate(validateFunction: RowValidate<O>): CsvParserStream<I, O>;
}

CSV Parser Stream

Configuration Options

Comprehensive configuration system for customizing CSV parsing behavior including delimiters, quotes, headers, and data processing options.

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;
}

Configuration Options

Parser Options Class

Internal options class with computed properties and validation, also available for direct instantiation.

class ParserOptions {
  constructor(opts?: ParserOptionsArgs);
  readonly escapedDelimiter: string;
  readonly objectMode: boolean;
  readonly delimiter: string;
  readonly ignoreEmpty: boolean;
  readonly quote: string | null;
  readonly escape: string | null;
  readonly escapeChar: string | null;
  readonly comment: string | null;
  readonly supportsComments: boolean;
  readonly ltrim: boolean;
  readonly rtrim: boolean;
  readonly trim: boolean;
  readonly headers: boolean | HeaderTransformFunction | HeaderArray | null;
  readonly renameHeaders: boolean;
  readonly strictColumnHandling: boolean;
  readonly discardUnmappedColumns: boolean;
  readonly carriageReturn: string;
  readonly NEXT_TOKEN_REGEXP: RegExp;
  readonly encoding: BufferEncoding;
  readonly limitRows: boolean;
  readonly maxRows: number;
  readonly skipLines: number;
  readonly skipRows: number;
}

Core Types

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

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>;

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>;

interface RowValidationResult<R extends Row> {
  row: R | null;
  isValid: boolean;
  reason?: string;
}

type HeaderArray = (string | undefined | null)[];
type HeaderTransformFunction = (headers: HeaderArray) => HeaderArray;

type RowTransformCallback<R extends Row> = (error?: Error | null, row?: R) => void;
type RowValidateCallback = (error?: Error | null, isValid?: boolean, reason?: string) => void;
type RowValidatorCallback<R extends Row> = (error: Error | null, result?: RowValidationResult<R>) => void;

function isSyncTransform<I extends Row, O extends Row>(
  transform: RowTransformFunction<I, O>
): transform is SyncRowTransform<I, O>;

function isSyncValidate<R extends Row>(
  validate: RowValidate<R>
): validate is SyncRowValidate<R>;