Configuration & Parameters

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

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" }
// ]

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

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');

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

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" }
//   }
// ]

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

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"`);

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

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);
});

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

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}`);
  }
});