Configuration Options

/**
 * Configuration options for CSV parser initialization
 */
interface ParserOptionsArgs {
  /** Enable object mode (default: true) - outputs objects when true, strings when false */
  objectMode?: boolean;
  
  /** Field delimiter character (default: ",") */
  delimiter?: string;
  
  /** Quote character for escaping fields (default: '"') - set to null to disable */
  quote?: string | null;
  
  /** Escape character (default: null - uses quote character) */
  escape?: string;
  
  /** Header handling - true/false for auto-detection, array for custom headers, function for transformation */
  headers?: boolean | HeaderTransformFunction | HeaderArray;
  
  /** Whether to rename duplicate headers by appending numbers (default: false) */
  renameHeaders?: boolean;
  
  /** Skip empty rows (default: false) */
  ignoreEmpty?: boolean;
  
  /** Comment character - lines starting with this are ignored (default: null) */
  comment?: string;
  
  /** Strict column count validation (default: false) */
  strictColumnHandling?: boolean;
  
  /** Discard columns not in header mapping (default: false) */
  discardUnmappedColumns?: boolean;
  
  /** Trim whitespace from all fields (default: false) */
  trim?: boolean;
  
  /** Trim whitespace from left side of fields (default: false) */
  ltrim?: boolean;
  
  /** Trim whitespace from right side of fields (default: false) */
  rtrim?: boolean;
  
  /** Character encoding (default: "utf8") */
  encoding?: string;
  
  /** Maximum number of rows to parse (default: 0 - unlimited) */
  maxRows?: number;
  
  /** Number of lines to skip at file start (default: 0) */
  skipLines?: number;
  
  /** Number of rows to skip after headers (default: 0) */
  skipRows?: number;
}

/**
 * Internal parser options class with computed properties
 */
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;
}

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

// Tab-separated values
parse({ delimiter: "\t" });

// Semicolon-separated with single quotes
parse({ 
  delimiter: ";", 
  quote: "'" 
});

// Pipe-separated without quotes
parse({ 
  delimiter: "|", 
  quote: null 
});

// Custom escape character
parse({ 
  quote: '"', 
  escape: "\\" 
});

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

// Auto-detect headers from first row
parse({ headers: true });

// No headers - return arrays
parse({ headers: false });

// Custom header names
parse({ 
  headers: ["id", "name", "email", "age"] 
});

// Transform headers function
parse({ 
  headers: (headers) => headers.map(h => h.toLowerCase().replace(/\s+/g, "_"))
});

// Rename duplicate headers
parse({ 
  headers: true,
  renameHeaders: true  // "name", "name_1", "name_2", etc.
});

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

// Trim whitespace
parse({ 
  trim: true  // Trims both sides
});

parse({ 
  ltrim: true,  // Left trim only
  rtrim: true   // Right trim only
});

// Skip empty rows
parse({ 
  ignoreEmpty: true 
});

// Comment support
parse({ 
  comment: "#"  // Lines starting with # are ignored
});

// Row limits and skipping
parse({ 
  maxRows: 1000,    // Process only first 1000 rows
  skipLines: 2,     // Skip first 2 lines of file
  skipRows: 5       // Skip first 5 data rows after headers
});

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

// Strict column validation
parse({ 
  headers: ["id", "name", "email"],
  strictColumnHandling: true,      // Error if row has wrong column count
  discardUnmappedColumns: true     // Ignore extra columns
});

// Character encoding
parse({ 
  encoding: "latin1"  // Support different text encodings
});

// Output mode
parse({ 
  objectMode: false  // Output JSON strings instead of objects
});

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

// Standard CSV file processing
parseFile("data.csv", {
  headers: true,
  trim: true,
  ignoreEmpty: true,
  comment: "#"
});

// Excel CSV export processing
parseFile("export.csv", {
  headers: true,
  delimiter: ",",
  quote: '"',
  trim: true,
  renameHeaders: true,
  encoding: "utf8"
});

// Large file processing with limits
parseFile("large-dataset.csv", {
  headers: true,
  maxRows: 10000,
  skipLines: 1,
  ignoreEmpty: true,
  objectMode: true
});

// European CSV format (semicolon delimiter)
parseFile("european-data.csv", {
  delimiter: ";",
  quote: '"',
  headers: true,
  trim: true,
  encoding: "utf8"
});

// Tab-separated values with custom headers
parseFile("data.tsv", {
  delimiter: "\t",
  headers: ["user_id", "username", "email", "signup_date"],
  trim: true,
  skipLines: 1
});

type HeaderArray = (string | undefined | null)[];

/**
 * Function to transform header array
 * @param headers - Original headers from CSV
 * @returns Transformed headers array
 */
type HeaderTransformFunction = (headers: HeaderArray) => HeaderArray;

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

// Normalize header names
parse({
  headers: (headers) => headers.map(header => 
    header?.toLowerCase()
           .replace(/\s+/g, "_")
           .replace(/[^a-z0-9_]/g, "")
  )
});

// Add prefixes to headers
parse({
  headers: (headers) => headers.map(header => `col_${header}`)
});

// Handle missing headers
parse({
  headers: (headers) => headers.map((header, index) => 
    header || `column_${index + 1}`
  )
});

// This will throw an error
parse({ delimiter: "abc" }); // Error: delimiter option must be one character long

// Valid configurations
parse({ delimiter: "," });   // OK
parse({ delimiter: "\t" });  // OK
parse({ delimiter: "|" });   // OK