or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

errors.mdindex.mdoptions.mdstreaming.mdsync.md
tile.json

tessl/npm-csv-parse

CSV parsing implementing the Node.js stream.Transform API

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

To install, run

npx @tessl/cli install tessl/npm-csv-parse@6.1.0

index.mddocs/

CSV Parse

CSV Parse is a comprehensive CSV parsing library for Node.js and web environments that implements the Node.js stream.Transform API. It converts CSV text input into arrays or objects with extensive configuration options, supporting both streaming and callback-based APIs for maximum flexibility.

Package Information

  • Package Name: csv-parse
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install csv-parse
  • Homepage: https://csv.js.org/parse

Core Imports

Main streaming API:

import { parse, Parser, CsvError, normalize_options } from "csv-parse";

Synchronous API:

import { parse, CsvError } from "csv-parse/sync";

Web Streams API:

import { parse } from "csv-parse/stream";

Browser ESM:

import { parse, Parser, CsvError, normalize_options } from "csv-parse/browser/esm";
import { parse as parseSync } from "csv-parse/browser/esm/sync";

CommonJS:

const { parse, Parser, CsvError, normalize_options } = require("csv-parse");
const { parse: parseSync } = require("csv-parse/sync");

Basic Usage

import { parse } from "csv-parse";

// Stream API with callback
parse('name,age\nAlice,25\nBob,30', { columns: true }, (err, records) => {
  if (err) throw err;
  console.log(records);
  // [{ name: 'Alice', age: '25' }, { name: 'Bob', age: '30' }]
});

// Transform stream usage
const parser = parse({ columns: true, delimiter: "," });
parser.on("readable", function () {
  let record;
  while ((record = parser.read()) !== null) {
    console.log(record);
  }
});
parser.write("name,age\n");
parser.write("Alice,25\n");
parser.end();

Architecture

CSV Parse is built around several key components:

  • Transform Stream API: Core Parser class extending Node.js Transform for streaming processing
  • Multiple Entry Points: Streaming (parse), synchronous (csv-parse/sync), and Web Streams (csv-parse/stream) APIs
  • Configuration System: Extensive options system with 40+ configuration parameters
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • Error Handling: Detailed error reporting with specific error codes and context
  • Format Support: Multiple distribution formats (ESM, CommonJS, browser UMD)

Capabilities

Streaming Parser

Main streaming API that implements Node.js Transform stream interface. Ideal for processing large CSV files and real-time data streams.

function parse(): Parser;
function parse(options: Options): Parser;
function parse(callback: Callback): Parser;
function parse(options: Options, callback: Callback): Parser;
function parse(input: string | Buffer | Uint8Array): Parser;
function parse(input: string | Buffer | Uint8Array, callback: Callback): Parser;
function parse(input: string | Buffer | Uint8Array, options: Options): Parser;
function parse(input: string | Buffer | Uint8Array, options: Options, callback: Callback): Parser;

class Parser extends Transform {
  constructor(options: Options);
  readonly options: OptionsNormalized;
  readonly info: Info;
}

Streaming API

Synchronous Parser

Synchronous parsing API for immediate processing of smaller CSV data sets. Perfect for configuration files and small data imports.

function parse(input: Buffer | string | Uint8Array): string[][];
function parse(input: Buffer | string | Uint8Array, options: Options): string[][];
function parse<T>(input: Buffer | string | Uint8Array, options: OptionsWithColumns<T>): T[];

Synchronous API

Configuration Options

Comprehensive configuration system with 40+ options for customizing parsing behavior. Supports delimiters, quotes, escape characters, column handling, and more.

interface Options<T = string[]> {
  bom?: boolean;
  cast?: boolean | CastingFunction;
  cast_date?: boolean | CastingDateFunction;
  columns?: boolean | ColumnOption<string>[] | ((record: T) => ColumnOption<string>[]);
  comment?: string | boolean | null;
  delimiter?: string | string[] | Buffer;
  encoding?: BufferEncoding | boolean | null | undefined;
  escape?: string | null | boolean | Buffer;
  from?: number | string;
  from_line?: null | number | string;
  quote?: string | boolean | Buffer | null;
  record_delimiter?: string | Buffer | null | (string | Buffer | null)[];
  skip_empty_lines?: boolean | null;
  to?: null | number | string;
  to_line?: null | number | string;
  trim?: boolean | null;
  on_record?: (record: T, context: CastingContext) => T | null | undefined;
  // ... and 25+ more options
}

Configuration Options

Error Handling

Comprehensive error handling system with specific error codes and detailed context information for debugging parsing issues.

class CsvError extends Error {
  readonly code: CsvErrorCode;
  constructor(code: CsvErrorCode, message: string | string[], options?: OptionsNormalized, ...contexts: unknown[]);
}

type CsvErrorCode = 
  | "CSV_INVALID_ARGUMENT"
  | "CSV_INVALID_CLOSING_QUOTE"
  | "CSV_INVALID_COLUMN_DEFINITION"
  | "CSV_INVALID_COLUMN_MAPPING"
  | "CSV_INVALID_OPTION_BOM"
  | "CSV_INVALID_OPTION_CAST"
  | "CSV_INVALID_OPTION_CAST_DATE"
  | "CSV_INVALID_OPTION_COLUMNS"
  | "CSV_INVALID_OPTION_COMMENT"
  | "CSV_INVALID_OPTION_DELIMITER"
  | "CSV_INVALID_OPTION_GROUP_COLUMNS_BY_NAME"
  | "CSV_INVALID_OPTION_ON_RECORD"
  | "CSV_MAX_RECORD_SIZE"
  | "CSV_NON_TRIMABLE_CHAR_AFTER_CLOSING_QUOTE"
  | "CSV_OPTION_COLUMNS_MISSING_NAME"
  | "CSV_QUOTE_NOT_CLOSED"
  | "CSV_RECORD_INCONSISTENT_FIELDS_LENGTH"
  | "CSV_RECORD_INCONSISTENT_COLUMNS"
  | "CSV_UNKNOWN_ERROR"
  | "INVALID_OPENING_QUOTE";

Error Handling

Utility Functions

Internal utility functions exposed for advanced use cases and custom parser implementations.

function normalize_options(opts: Options): OptionsNormalized;

Types

Core type definitions used across all APIs:

type Callback<T = string[]> = (
  err: CsvError | undefined,
  records: T[],
  info?: Info
) => void;

interface Info {
  readonly comment_lines: number;
  readonly empty_lines: number;
  readonly lines: number;
  readonly records: number;
  readonly bytes: number;
  readonly invalid_field_length: number;
  readonly columns: boolean | { name: string }[] | { disabled: true }[];
}

interface CastingContext {
  readonly column: number | string;
  readonly empty_lines: number;
  readonly error: CsvError;
  readonly header: boolean;
  readonly index: number;
  readonly quoting: boolean;
  readonly lines: number;
  readonly raw: string | undefined;
  readonly records: number;
  readonly invalid_field_length: number;
}

type CastingFunction = (value: string, context: CastingContext) => unknown;
type CastingDateFunction = (value: string, context: CastingContext) => Date;
type ColumnOption<K = string> = K | undefined | null | false | { name: K };