Comprehensive configuration system supporting delimiter detection, column filtering, type conversion, custom parsers, and output formatting options with 89+ parameters for fine-tuned CSV parsing control.
Filter and select specific columns during parsing using regular expressions.
interface CSVParseParam {
/**
* Regular expression to ignore columns by header name
* Example: /(name|age)/ ignores columns containing "name" or "age"
*/
ignoreColumns?: RegExp;
/**
* Regular expression to include only specific columns by header name
* Example: /(id|email)/ includes only columns containing "id" or "email"
*/
includeColumns?: RegExp;
}Usage Examples:
import csvtojson from "csvtojson";
// Ignore sensitive columns
const jsonArray = await csvtojson({
ignoreColumns: /password|ssn|secret/i
})
.fromString(`name,email,password,age
Alice,alice@example.com,secret123,25
Bob,bob@example.com,mypass456,30`);
// Result: [
// { name: "Alice", email: "alice@example.com", age: "25" },
// { name: "Bob", email: "bob@example.com", age: "30" }
// ]
// Include only specific columns
const jsonArray = await csvtojson({
includeColumns: /^(id|name|email)$/
})
.fromString(`id,name,email,phone,address,notes
1,Alice,alice@example.com,555-0123,123 Main St,VIP
2,Bob,bob@example.com,555-0124,456 Oak Ave,Regular`);
// Result: [
// { id: "1", name: "Alice", email: "alice@example.com" },
// { id: "2", name: "Bob", email: "bob@example.com" }
// ]Define custom parsing logic for specific columns with type conversion and validation.
interface CSVParseParam {
/**
* Custom parsers for specific columns by header name
* Supports built-in types ("string", "number", "omit") or custom functions
*/
colParser: {[key: string]: string | CellParser | ColumnParam};
}
/**
* Custom cell parser function
* @param item - The cell value as string
* @param head - The column header name
* @param resultRow - The current row object being built
* @param row - The complete raw row array
* @param columnIndex - Zero-based column index
* @returns Parsed value of any type
*/
type CellParser = (
item: string,
head: string,
resultRow: any,
row: string[],
columnIndex: number
) => any;
interface ColumnParam {
/** Treat column key as flat (no nested object creation) */
flat?: boolean;
/** Custom parser function or built-in parser name */
cellParser?: string | CellParser;
}Usage Examples:
import csvtojson from "csvtojson";
// Built-in type parsers
const jsonArray = await csvtojson({
colParser: {
"age": "number",
"salary": "number",
"notes": "string",
"internal_id": "omit" // Exclude column from output
}
})
.fromString(`name,age,salary,notes,internal_id
Alice,25,50000,Great employee,12345
Bob,30,60000,Team lead,12346`);
// Custom parser functions
const jsonArray = await csvtojson({
colParser: {
"birth_date": (dateStr) => new Date(dateStr),
"tags": (tagStr) => tagStr.split('|').map(t => t.trim()),
"is_active": (str) => str.toLowerCase() === 'true',
"metadata": (jsonStr) => {
try {
return JSON.parse(jsonStr);
} catch {
return {};
}
}
}
})
.fromString(`name,birth_date,tags,is_active,metadata
Alice,1995-06-15,admin|user|vip,true,{"role":"manager"}
Bob,1990-03-22,user,false,{"role":"developer"}`);
// Advanced custom parser with context
const jsonArray = await csvtojson({
colParser: {
"full_name": (item, head, resultRow, row, columnIndex) => {
const firstName = row[0];
const lastName = row[1];
return `${firstName} ${lastName}`;
},
"calculated_field": (item, head, resultRow) => {
// Access other fields in the same row
const price = parseFloat(resultRow.price || '0');
const quantity = parseInt(resultRow.quantity || '0');
return price * quantity;
}
}
})
.fromFile('./data.csv');Control how nested objects are created from dot notation and array notation in headers.
interface CSVParseParam {
/**
* Don't interpret dots and brackets as nested object identifiers
* Treat them as literal characters in field names
* @default false
*/
flatKeys: boolean;
}
interface ColumnParam {
/** Override global flatKeys setting for specific column */
flat?: boolean;
}Usage Examples:
import csvtojson from "csvtojson";
// Default nested object behavior
const jsonArray = await csvtojson()
.fromString(`user.name,user.email,user.address.city,tags[0],tags[1]
Alice,alice@example.com,New York,admin,user
Bob,bob@example.com,London,user,guest`);
// Result: [
// {
// user: {
// name: "Alice",
// email: "alice@example.com",
// address: { city: "New York" }
// },
// tags: ["admin", "user"]
// }
// ]
// Flat keys - treat dots/brackets as literal
const jsonArray = await csvtojson({
flatKeys: true
})
.fromString(`user.name,user.email,tags[0]
Alice,alice@example.com,admin
Bob,bob@example.com,user`);
// Result: [
// { "user.name": "Alice", "user.email": "alice@example.com", "tags[0]": "admin" },
// { "user.name": "Bob", "user.email": "bob@example.com", "tags[0]": "user" }
// ]
// Mixed behavior - some flat, some nested
const jsonArray = await csvtojson({
colParser: {
"config.setting": { flat: true }, // Keep this flat
"user.name": { flat: false } // Allow nesting for this
}
})
.fromString(`config.setting,user.name,user.email
debug,Alice,alice@example.com`);
// Result: [
// {
// "config.setting": "debug",
// user: { name: "Alice", email: "alice@example.com" }
// }
// ]Sophisticated delimiter detection and configuration options.
interface CSVParseParam {
/**
* Delimiter configuration - string, array, or "auto"
* String: specific delimiter like "," or ";"
* Array: list of potential delimiters for detection
* "auto": automatic detection from common delimiters
*/
delimiter: string | string[];
/**
* Escape character used in quoted columns
* @default '"'
*/
escape: string;
/**
* End of line character - auto-detected if omitted
*/
eol?: string;
}Usage Examples:
import csvtojson from "csvtojson";
// Auto-detect from common delimiters
const jsonArray = await csvtojson({
delimiter: "auto"
})
.fromString(`name;email;age
Alice;alice@example.com;25
Bob;bob@example.com;30`);
// Provide multiple delimiter options
const jsonArray = await csvtojson({
delimiter: [",", ";", "|", "\t"]
})
.fromFile('./unknown-format.csv');
// Complex escaping rules
const jsonArray = await csvtojson({
delimiter: ",",
quote: '"',
escape: '\\' // Use backslash for escaping
})
.fromString(`name,description
Alice,"She said \"Hello world\""
Bob,"Path: C:\\Users\\Bob\\Documents"`);Configure output format and downstream processing options.
interface CSVParseParam {
/**
* Output format type
* "json": Array of JSON objects (default)
* "csv": Array of string arrays
* "line": Array of raw line strings
*/
output: "json" | "csv" | "line";
/**
* Format for downstream consumers when streaming
* "line": Each JSON object on separate line
* "array": JSON array format with brackets
*/
downstreamFormat: "line" | "array";
/**
* Whether .then() callback receives all data
* Set false to save memory when using subscribe()
*/
needEmitAll: boolean;
}Usage Examples:
import csvtojson from "csvtojson";
// Different output formats
const csvData = `name,age,city
Alice,25,New York
Bob,30,London`;
// JSON objects (default)
const jsonArray = await csvtojson({ output: "json" })
.fromString(csvData);
// Result: [
// { name: "Alice", age: "25", city: "New York" },
// { name: "Bob", age: "30", city: "London" }
// ]
// CSV arrays
const csvArray = await csvtojson({ output: "csv" })
.fromString(csvData);
// Result: [
// ["name", "age", "city"],
// ["Alice", "25", "New York"],
// ["Bob", "30", "London"]
// ]
// Raw lines
const lineArray = await csvtojson({ output: "line" })
.fromString(csvData);
// Result: [
// "name,age,city",
// "Alice,25,New York",
// "Bob,30,London"
// ]
// Streaming with array format
csvtojson({
downstreamFormat: "array",
needEmitAll: false // Save memory
})
.fromFile('./large-file.csv')
.subscribe((jsonObj) => {
// Process each object in streaming fashion
console.log(jsonObj);
});Options for data validation and preventing parsing issues.
interface CSVParseParam {
/**
* Maximum characters per row - prevents memory issues
* @default 0 (unlimited)
*/
maxRowLength: number;
/**
* Validate column count matches header count
* @default false
*/
checkColumn: boolean;
/**
* Always split at EOL, even inside quoted fields
* @default false
*/
alwaysSplitAtEOL: boolean;
}Usage Examples:
import csvtojson from "csvtojson";
// Safe parsing for untrusted data
const jsonArray = await csvtojson({
maxRowLength: 65535, // Limit row length
checkColumn: true, // Validate column counts
alwaysSplitAtEOL: true // Prevent multiline cells
})
.fromFile('./untrusted-data.csv')
.catch((error) => {
if (error.err === 'column_mismatched') {
console.error(`Column count mismatch at line ${error.line}`);
}
if (error.err === 'row_exceed') {
console.error(`Row too long at line ${error.line}`);
}
});