or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-parsing.mderror-handling.mdindex.mdstream-processing.mdtransformation-hooks.md
tile.json

tessl/npm-csvtojson

A comprehensive CSV to JSON conversion library for Node.js with streaming support, extensive customization, and high-performance parsing capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/csvtojson@2.0.x

To install, run

npx @tessl/cli install tessl/npm-csvtojson@2.0.0

index.mddocs/

csvtojson

csvtojson is a comprehensive Node.js CSV parser that converts CSV data to JSON with extensive customization options. It strictly follows RFC 4180 CSV standards and provides high-performance parsing capabilities for processing millions of lines of CSV data. The library supports both streaming and batch processing modes, includes browser compatibility, and offers both programmatic API and command-line interface.

Package Information

  • Package Name: csvtojson
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install csvtojson
  • Node.js Compatibility: >=4.0.0

Core Imports

import csvtojson from "csvtojson";
import { Converter } from "csvtojson";

For CommonJS:

const csvtojson = require("csvtojson");
const { Converter } = require("csvtojson");

Basic Usage

import csvtojson from "csvtojson";

// Parse CSV from file
const jsonArray = await csvtojson()
  .fromFile("./data.csv");

// Parse CSV from string
const jsonArray = await csvtojson()
  .fromString("a,b,c\n1,2,3\n4,5,6");

// Parse with custom options
const jsonArray = await csvtojson({
  delimiter: ",",
  noheader: false,
  trim: true
})
.fromFile("./data.csv");

// Stream processing
csvtojson()
  .fromFile("./large-file.csv")
  .subscribe((jsonObj, lineNumber) => {
    console.log(`Line ${lineNumber}:`, jsonObj);
  });

Architecture

csvtojson is built around several key components:

  • Factory Function: Main export that creates Converter instances with optional parameters
  • Converter Class: Core parser extending Node.js Transform stream for streaming capabilities
  • Configuration System: Extensive parameter system with 89+ options for parsing customization
  • Processing Pipeline: Multi-stage parsing with raw data hooks, line processing, and result transformation
  • Error Handling: Custom CSVError class with specific error types for parsing issues
  • Browser Support: Webpack-bundled version for client-side usage

Capabilities

Core Parsing

Primary CSV parsing functionality with factory function interface and extensive configuration options.

function csvtojson(
  param?: Partial<CSVParseParam>, 
  options?: TransformOptions
): Converter;

interface CSVParseParam {
  delimiter: string | string[];
  quote: string;
  trim: boolean;
  noheader: boolean;
  headers?: string[];
  output: "json" | "csv" | "line";
  // ... 80+ additional parameters
}

Core Parsing

Stream Processing

Advanced streaming capabilities for large CSV files with input sources from files, streams, and strings.

class Converter extends Transform {
  fromFile(filePath: string, options?: CreateReadStreamOption): Converter;
  fromStream(readStream: Readable): Converter; 
  fromString(csvString: string): Converter;
  then<TResult1, TResult2>(
    onfulfilled?: (value: any[]) => TResult1 | PromiseLike<TResult1>,
    onrejected?: (reason: any) => TResult2 | PromiseLike<TResult2>
  ): PromiseLike<TResult1 | TResult2>;
}

Stream Processing

Data Transformation Hooks

Preprocessing hooks for raw data and individual lines before parsing occurs.

interface Converter {
  preRawData(onRawData: PreRawDataCallback): Converter;
  preFileLine(onFileLine: PreFileLineCallback): Converter;
  subscribe(
    onNext?: (data: any, lineNumber: number) => void | PromiseLike<void>,
    onError?: (err: CSVError) => void,
    onCompleted?: () => void
  ): Converter;
}

type PreRawDataCallback = (csvString: string) => string | PromiseLike<string>;
type PreFileLineCallback = (line: string, lineNumber: number) => string | PromiseLike<string>;

Data Transformation Hooks

Configuration & Parameters

Comprehensive configuration system supporting delimiter detection, column filtering, type conversion, and output formatting.

interface CSVParseParam {
  delimiter: string | string[];
  ignoreColumns?: RegExp;
  includeColumns?: RegExp;
  flatKeys: boolean;
  checkType: boolean;
  colParser: {[key: string]: string | CellParser | ColumnParam};
  nullObject: boolean;
  downstreamFormat: "line" | "array";
  // ... additional parameters
}

Configuration & Parameters

Error Handling

Custom error handling with specific error types for parsing issues and validation.

class CSVError extends Error {
  static column_mismatched(index: number, extra?: string): CSVError;
  static unclosed_quote(index: number, extra?: string): CSVError;
  
  constructor(err: string, line: number, extra?: string);
  toJSON(): {err: string, line: number, extra?: string};
}

Error Handling

Command Line Interface

Complete command-line tool for CSV conversion with extensive options and examples.

# Basic usage
csvtojson input.csv

# With options
csvtojson --delimiter=";" --noheader input.csv

# Output to file
csvtojson input.csv > output.json

Command Line Interface

Types

interface CreateReadStreamOption {
  flags?: string;
  encoding?: string;
  fd?: number;
  mode?: number;
  autoClose?: boolean;
  start?: number;
  end?: number;
  highWaterMark?: number;
}

type CellParser = (
  item: string, 
  head: string, 
  resultRow: any, 
  row: string[], 
  columnIndex: number
) => any;

interface ColumnParam {
  flat?: boolean;
  cellParser?: string | CellParser;
}