CSV Parse provides extensive configuration options (40+) for customizing parsing behavior, handling various CSV formats, and controlling output transformation.
Main configuration interface supporting both camelCase and snake_case naming conventions.
interface Options<T = string[]> {
// Character and Format Options
bom?: boolean; // Handle byte order mark
delimiter?: string | string[] | Buffer; // Field delimiter(s)
encoding?: BufferEncoding | boolean | null | undefined; // Text encoding
escape?: string | null | boolean | Buffer; // Escape character
quote?: string | boolean | Buffer | null; // Quote character
record_delimiter?: string | Buffer | null | (string | Buffer | null)[]; // Record delimiter(s)
comment?: string | boolean | null; // Comment character
// Column Handling
columns?: boolean | ColumnOption<string>[] | ((record: T) => ColumnOption<string>[]); // Column configuration
group_columns_by_name?: boolean; // Group duplicate column names
objname?: Buffer | null | number | string; // Object name field
// Data Processing
cast?: boolean | CastingFunction; // Type casting
cast_date?: boolean | CastingDateFunction; // Date casting
auto_parse?: boolean | CastingFunction; // [DEPRECATED] Use cast
auto_parse_date?: boolean | CastingDateFunction; // [DEPRECATED] Use cast_date
// Range Selection
from?: number | string; // Start record number
from_line?: null | number | string; // Start line number
to?: null | number | string; // End record number
to_line?: null | number | string; // End line number
// Whitespace Handling
trim?: boolean | null; // Trim whitespace around fields
ltrim?: boolean | null; // Left trim whitespace
rtrim?: boolean | null; // Right trim whitespace
// Line and Record Handling
skip_empty_lines?: boolean | null; // Skip empty lines
skip_records_with_empty_values?: boolean | null; // Skip records with empty values
skip_records_with_error?: boolean | null; // Skip invalid records
relax_column_count?: boolean | null; // Allow inconsistent column counts
relax_column_count_less?: boolean | null; // Allow fewer columns
relax_column_count_more?: boolean | null; // Allow more columns
relax_quotes?: boolean | null; // Preserve quotes in unquoted fields
// Advanced Options
comment_no_infix?: boolean | null; // Comments only on full lines
ignore_last_delimiters?: boolean | number; // Ignore trailing delimiters
max_record_size?: number | null | string; // Maximum record size
info?: boolean; // Include parsing info in records
raw?: boolean; // Include raw data in records
// Callback Hooks
on_record?: (record: T, context: CastingContext) => T | null | undefined; // Record transformation
on_skip?: (err: CsvError | undefined, raw: string | undefined) => undefined; // Skip handling
// Deprecated aliases (camelCase versions)
autoParse?: boolean | CastingFunction;
autoParseDate?: boolean | CastingDateFunction;
fromLine?: null | number | string;
groupColumnsByName?: boolean;
maxRecordSize?: number;
onRecord?: (record: T, context: CastingContext) => T | null | undefined;
onSkip?: (err: CsvError | undefined, raw: string | undefined) => undefined;
recordDelimiter?: string | Buffer | null | (string | Buffer | null)[];
relaxColumnCount?: boolean | null;
relaxColumnCountLess?: boolean | null;
relaxColumnCountMore?: boolean | null;
relaxQuotes?: boolean | null;
skipEmptyLines?: boolean | null;
skipRecordsWithEmptyValues?: boolean | null;
skipRecordsWithError?: boolean | null;
toLine?: null | number | string;
castDate?: boolean | CastingDateFunction;
}Essential options for handling different CSV formats and character encodings.
Usage Examples:
import { parse } from "csv-parse";
// Tab-separated values
parse(data, {
delimiter: "\t"
});
// Custom quote and escape characters
parse(data, {
quote: "'",
escape: "\\"
});
// Multiple possible delimiters
parse(data, {
delimiter: [",", ";", "|"]
});
// Windows line endings with BOM
parse(data, {
bom: true,
record_delimiter: "\r\n",
encoding: "utf8"
});
// Custom record delimiters
parse(data, {
record_delimiter: ["\n", "\r\n", "\r"]
});Options for handling CSV headers and column mapping.
type ColumnOption<K = string> = K | undefined | null | false | { name: K };Usage Examples:
import { parse } from "csv-parse";
// Auto-detect columns from first row
parse(data, {
columns: true
});
// Explicit column names
parse(data, {
columns: ['id', 'name', 'email', 'age']
});
// Skip specific columns
parse(data, {
columns: ['id', false, 'email', 'age'] // Skip second column
});
// Dynamic column mapping
parse(data, {
columns: (firstLine) => {
return firstLine.map(header =>
header.toLowerCase().replace(/\s+/g, '_')
);
}
});
// Object-style column definition
parse(data, {
columns: [
{ name: 'user_id' },
{ name: 'full_name' },
{ name: 'email_address' }
]
});
// Group duplicate column names into arrays
parse('name,age,name\nAlice,25,Alice2', {
columns: true,
group_columns_by_name: true
});
// Result: [{ name: ['Alice', 'Alice2'], age: '25' }]Options for automatic type conversion and data transformation.
type CastingFunction = (value: string, context: CastingContext) => unknown;
type CastingDateFunction = (value: string, context: CastingContext) => Date;Usage Examples:
import { parse } from "csv-parse";
// Enable automatic type casting
parse(data, {
cast: true // Converts numbers, booleans automatically
});
// Custom casting function
parse(data, {
cast: (value, context) => {
// Cast specific columns
if (context.column === 'age' || context.column === 'price') {
return parseFloat(value);
}
if (context.column === 'active') {
return value.toLowerCase() === 'true';
}
return value;
}
});
// Date casting
parse(data, {
cast: true,
cast_date: true // Uses Date.parse()
});
// Custom date casting
parse(data, {
cast_date: (value, context) => {
if (context.column === 'created_at') {
return new Date(value);
}
return value;
}
});Options for selecting specific records and handling problematic data.
Usage Examples:
import { parse } from "csv-parse";
// Parse specific record range
parse(data, {
from: 10, // Start from record 10
to: 100, // End at record 100
columns: true
});
// Parse specific line range (including header)
parse(data, {
from_line: 2, // Skip first line (header)
to_line: 50, // Stop at line 50
columns: ['id', 'name', 'email']
});
// Skip empty lines and records with empty values
parse(data, {
skip_empty_lines: true,
skip_records_with_empty_values: true,
columns: true
});
// Handle inconsistent column counts gracefully
parse(data, {
columns: true,
relax_column_count: true, // Allow any column count difference
// OR use specific relaxation:
relax_column_count_less: true, // Allow fewer columns
relax_column_count_more: false // Disallow extra columns
});
// Error recovery
parse(data, {
skip_records_with_error: true,
on_skip: (err, rawRecord) => {
console.warn(`Skipped invalid record: ${rawRecord}`);
console.warn(`Reason: ${err.message}`);
}
});Options for complex data processing and transformation scenarios.
Usage Examples:
import { parse } from "csv-parse";
// Record transformation and filtering
parse(data, {
columns: true,
on_record: (record, context) => {
// Filter out invalid records
if (!record.email || !record.email.includes('@')) {
return undefined; // Skip this record
}
// Transform record
return {
...record,
email: record.email.toLowerCase(),
processed_at: new Date(),
line_number: context.lines
};
}
});
// Include parsing metadata
parse(data, {
columns: true,
info: true, // Include info object with each record
raw: true // Include raw CSV line with each record
});
// Results: [{ info: {...}, record: {...}, raw: "..." }]
// Custom object naming
parse('key,value\nname,Alice\nage,25', {
columns: true,
objname: 'key' // Use 'key' column as object property names
});
// Result: { name: 'Alice', age: '25' }
// Memory and performance limits
parse(data, {
max_record_size: 65536, // 64KB max record size
trim: true, // Reduce memory usage
encoding: null // Return Buffer objects instead of strings
});Options for handling comments and whitespace in CSV data.
Usage Examples:
import { parse } from "csv-parse";
// Handle commented lines
const csvWithComments = `
# This is a comment
name,age,city
Alice,25,NYC
# Another comment
Bob,30,LA
`;
parse(csvWithComments, {
comment: '#',
skip_empty_lines: true,
columns: true
});
// Comments only on full lines (not inline)
parse(data, {
comment: '#',
comment_no_infix: true // Comments must start at beginning of line
});
// Whitespace handling
parse(data, {
trim: true, // Trim both leading and trailing whitespace
// OR specific trimming:
ltrim: true, // Left trim only
rtrim: true // Right trim only
});
// Preserve quotes in unquoted fields
parse('name,description\nAlice,"She said ""hello"""\nBob,Regular text', {
relax_quotes: true, // Don't treat quotes as special in unquoted fields
columns: true
});Internal normalized version of options used by the parser.
interface OptionsNormalized<T = string[]> {
// All options converted to internal format
bom: boolean;
delimiter: Buffer[];
encoding: BufferEncoding | null;
escape: null | Buffer;
quote: Buffer | null;
record_delimiter: Buffer[];
comment: string | null;
columns: boolean | ColumnOption<string>[];
cast_first_line_to_header?: (record: T) => ColumnOption<string>[];
group_columns_by_name: boolean;
// ... all other options in normalized form
}Usage Examples:
import { normalize_options } from "csv-parse";
// Manually normalize options (advanced usage)
const normalized = normalize_options({
delimiter: ',',
encoding: 'utf8',
quote: '"'
});
console.log(normalized.delimiter); // [Buffer.from(',')]
console.log(normalized.quote); // Buffer.from('"')