tessl/npm-fast-csv

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CSV Formatting

Name: tessl/npm-fast-csv
Author: tessl

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.

Capabilities

Format Function

Creates a new CSV formatter stream for converting data to CSV format.

/**
 * Creates a new CSV formatter stream
 * @param options - Formatter configuration options
 * @returns CsvFormatterStream instance for formatting operations
 */
function format<I extends Row, O extends Row>(
  options?: FormatterOptionsArgs<I, O>
): CsvFormatterStream<I, O>;

Usage Examples:

import { format } from "fast-csv";

// Create formatter stream
const csvStream = format({ headers: true });
csvStream.pipe(process.stdout);

// Write data
csvStream.write({ name: "John", age: 25 });
csvStream.write({ name: "Jane", age: 30 });
csvStream.end();

// Custom options
const customFormatter = format({
  delimiter: "|",
  headers: ["Name", "Age", "City"],
  quote: "'",
  quoteColumns: true
});

Write Function

Writes an array of rows to CSV format using a formatter stream.

/**
 * Writes an array of rows to CSV format
 * @param rows - Array of data rows to write
 * @param options - Formatter configuration options
 * @returns CsvFormatterStream instance
 */
function write<I extends Row, O extends Row>(
  rows: I[], 
  options?: FormatterOptionsArgs<I, O>
): CsvFormatterStream<I, O>;

Usage Examples:

import { write } from "fast-csv";

const data = [
  { name: "John", age: 25, city: "New York" },
  { name: "Jane", age: 30, city: "San Francisco" }
];

// Write with headers
write(data, { headers: true })
  .pipe(process.stdout);

// Write with custom options
write(data, {
  headers: ["Full Name", "Age", "Location"],
  delimiter: "\t",
  quote: false
});

Write to String

Converts an array of rows to a CSV string asynchronously.

/**
 * Writes rows to a CSV string asynchronously
 * @param rows - Array of data rows to convert
 * @param options - Formatter configuration options
 * @returns Promise resolving to CSV string
 */
function writeToString<I extends Row, O extends Row>(
  rows: I[], 
  options?: FormatterOptionsArgs<I, O>
): Promise<string>;

Usage Examples:

import { writeToString } from "fast-csv";

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Convert to string
const csvString = await writeToString(data, { headers: true });
console.log(csvString);
// Output:
// name,age
// John,25
// Jane,30

// With custom formatting
const customCsv = await writeToString(data, {
  headers: ["Name", "Age"],
  delimiter: ";",
  quote: '"',
  quoteColumns: true
});

Write to Buffer

Converts an array of rows to a Buffer asynchronously.

/**
 * Writes rows to a Buffer asynchronously
 * @param rows - Array of data rows to convert
 * @param opts - Formatter configuration options
 * @returns Promise resolving to Buffer containing CSV data
 */
function writeToBuffer<I extends Row, O extends Row>(
  rows: I[], 
  opts: FormatterOptionsArgs<I, O> = {}
): Promise<Buffer>;

Usage Examples:

import { writeToBuffer } from "fast-csv";

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Convert to buffer
const csvBuffer = await writeToBuffer(data, { headers: true });
console.log(csvBuffer.toString());

// Write buffer to file
import fs from "fs";
fs.writeFileSync("output.csv", csvBuffer);

Write to Path

Writes an array of rows directly to a file path.

/**
 * Writes rows directly to a file path
 * @param path - File path to write CSV data
 * @param rows - Array of data rows to write
 * @param options - Formatter configuration options
 * @returns WriteStream for the file
 */
function writeToPath<I extends Row, O extends Row>(
  path: string, 
  rows: I[], 
  options?: FormatterOptionsArgs<I, O>
): fs.WriteStream;

Usage Examples:

import { writeToPath } from "fast-csv";

const data = [
  { name: "John", age: 25, city: "New York" },
  { name: "Jane", age: 30, city: "San Francisco" }
];

// Write to file
const writeStream = writeToPath("./output/users.csv", data, {
  headers: true,
  encoding: "utf8"
});

writeStream.on("finish", () => {
  console.log("File write complete");
});

Write to Stream

Writes an array of rows to an existing writable stream.

/**
 * Writes rows to an existing writable stream
 * @param ws - Writable stream to write CSV data
 * @param rows - Array of data rows to write
 * @param options - Formatter configuration options
 * @returns The original writable stream
 */
function writeToStream<T extends NodeJS.WritableStream, I extends Row, O extends Row>(
  ws: T, 
  rows: I[], 
  options?: FormatterOptionsArgs<I, O>
): T;

Usage Examples:

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

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Write to stdout
writeToStream(process.stdout, data, { headers: true });

// Write to file stream
const fileStream = fs.createWriteStream("output.csv");
writeToStream(fileStream, data, {
  headers: ["Name", "Age"],
  delimiter: "|"
});

CsvFormatterStream Class

A Transform stream that formats data to CSV with support for custom transformations.

class CsvFormatterStream<I extends Row, O extends Row> extends Transform {
  /**
   * Adds a transform function to modify rows before formatting
   * @param transformFunction - Function to transform each row
   * @returns This stream instance for chaining
   */
  transform(transformFunction: RowTransformFunction<I, O>): CsvFormatterStream<I, O>;
}

Usage Examples:

import { format } from "fast-csv";

// With transform function
format({ headers: true })
  .transform((row) => ({
    name: row.name.toUpperCase(),
    age: row.age,
    status: row.age >= 18 ? "adult" : "minor"
  }))
  .on("data", (chunk) => process.stdout.write(chunk));

// Async transform
format({ headers: true })
  .transform((row, callback) => {
    // Simulate async operation
    setTimeout(() => {
      callback(null, { ...row, timestamp: Date.now() });
    }, 10);
  });

Configuration Options

FormatterOptionsArgs Interface

Complete configuration options for CSV formatting operations.

interface FormatterOptionsArgs<I extends Row, O extends Row> {
  /** Enable object mode for streaming (default: true) */
  objectMode?: boolean;
  
  /** Field delimiter character (default: ',') */
  delimiter?: string;
  
  /** Row delimiter string (default: '\n') */
  rowDelimiter?: string;
  
  /** Quote character or boolean to enable/disable quoting (default: '"') */
  quote?: string | boolean;
  
  /** Escape character (default: same as quote) */
  escape?: string;
  
  /** Column quoting configuration: boolean, array, or column map */
  quoteColumns?: boolean | boolean[] | Record<string, boolean>;
  
  /** Header quoting configuration: boolean, array, or column map */
  quoteHeaders?: boolean | boolean[] | Record<string, boolean>;
  
  /** Headers: null for none, boolean for auto-generate, array for custom */
  headers?: null | boolean | string[];
  
  /** Write headers to output (default: true when headers provided) */
  writeHeaders?: boolean;
  
  /** Include row delimiter at end of output (default: false) */
  includeEndRowDelimiter?: boolean;
  
  /** Write UTF-8 BOM at start of output (default: false) */
  writeBOM?: boolean;
  
  /** Transform function to modify rows before formatting */
  transform?: RowTransformFunction<I, O>;
  
  /** Always write headers even for empty data (default: false) */
  alwaysWriteHeaders?: boolean;
}

Row Types

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

Transform Types

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

Quote Configuration Types

// Column quoting configuration types
type QuoteColumns = boolean | boolean[] | QuoteColumnMap;
interface QuoteColumnMap {
  [columnName: string]: boolean;
}

Advanced Usage Examples

Custom Quoting Configuration

import { writeToString } from "fast-csv";

const data = [
  { name: "John Doe", age: 25, email: "john@example.com" },
  { name: "Jane Smith", age: 30, email: "jane@example.com" }
];

// Quote specific columns
const csv1 = await writeToString(data, {
  headers: true,
  quoteColumns: { name: true, email: true } // Only quote name and email
});

// Quote by column index
const csv2 = await writeToString(data, {
  headers: ["Name", "Age", "Email"],
  quoteColumns: [true, false, true] // Quote first and third columns
});

// Quote all columns
const csv3 = await writeToString(data, {
  headers: true,
  quoteColumns: true
});

Custom Delimiters and Row Separators

import { writeToString } from "fast-csv";

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Tab-separated values
const tsv = await writeToString(data, {
  headers: true,
  delimiter: "\t"
});

// Pipe-separated with custom row delimiter
const psv = await writeToString(data, {
  headers: true,
  delimiter: "|",
  rowDelimiter: "\r\n"
});

// Custom quote and escape characters
const custom = await writeToString(data, {
  headers: true,
  quote: "'",
  escape: "\\",
  delimiter: ";"
});

UTF-8 BOM and Encoding

import { writeToPath } from "fast-csv";

const data = [
  { name: "José", city: "São Paulo" },
  { name: "François", city: "Montréal" }
];

// Write with BOM for Excel compatibility
writeToPath("./unicode-data.csv", data, {
  headers: true,
  writeBOM: true,
  encoding: "utf8"
});

Events

The CsvFormatterStream emits standard Transform stream events:

'data': Emitted for each formatted chunk of CSV data
'end': Emitted when formatting is complete
'error': Emitted when formatting errors occur
'finish': Emitted when all data has been processed

// Event handling example
format({ headers: true })
  .on("data", (chunk) => console.log("Chunk:", chunk.toString()))
  .on("end", () => console.log("Formatting complete"))
  .on("error", (error) => console.error("Format error:", error));

docs

tessl/npm-fast-csv

formatting.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

CSV Formatting

Capabilities

Format Function

Write Function

Write to String

Write to Buffer

Write to Path

Write to Stream

CsvFormatterStream Class

Configuration Options

FormatterOptionsArgs Interface

Row Types

Transform Types

Quote Configuration Types

Advanced Usage Examples

Custom Quoting Configuration

Custom Delimiters and Row Separators

UTF-8 BOM and Encoding

Events

formatting.mddocs/