CSV Parse options

Introduction

All options are optional. The options from the Node.js Stream Writable are also supported and passed as is. Only the "objectMode" is overwritten to always equal "true".

Available options

  • bom (boolean)
    Since version 4.4.0
    If true, detect and exclude the byte order mark (BOM) from the CSV input if present.
  • cast (boolean|function)
    Since version 2.2.0
    Alter the value of a field. If true, the parser will attempt to convert input string to native types. If a function, receive the value as first argument, a context as second argument and return a new value. This option was named auto_parse until version 2.
  • cast_date (boolean|function)
    Since version 1.0.5
    If true, the parser will attempt to convert input string to dates. If a function, receive the value as argument and return a new value. It requires the cast option to be active. This option was named auto_parse_date until version 2. Be careful, it relies on Date.parse.
  • columns (array|boolean|function)
    Since early days
    Generate records as object literals instead of arrays. List of fields as an array, a user defined callback accepting the first line and returning the column names, or true if auto-discovered in the first CSV line. Defaults to null. Affects the result data set in the sense that records will be objects instead of arrays. A value "false" "null", or "undefined" inside the column array skips the column from the output.
  • comment (string|buffer)
    Since early days
    Treat all the characters after this one as a comment; one or multiple characters; disabled by default by defining an empty string ''.
  • delimiter (string|Buffer)
    Since early days
    Set the field delimiter. One or multiple character. Defaults to "," (comma).
  • escape (string|Buffer)
    Since early days
    Set the escape character; one character/byte only; only apply to quote and escape characters inside quoted fields; defaults to double quote.
  • from (number)
    Since version 1.2.0
    Start handling records from the requested number of records. One-based, to emit first record provide 1 (not 0)
  • from_line (number)
    Since version 4.0.0
    Start handling records from the requested line number.
  • info (boolean)
    Since version 4.0.0
    Generate two properties info and record where info is a snapshot of the info object at the time the record was created and record is the parsed array or object; note, it can be used conjointly with the raw option.
  • ltrim (boolean)
    Since early days
    If true, ignore whitespace immediately following the delimiter (i.e. left-trim all fields). Defaults to false. Does not remove whitespace in a quoted field.
  • max_record_size (integer)
    Since version 4.0.0
    Maximum number of characters to be contained in the field and line buffers before an exception is raised. It was previously named "maxlimitondataread".
  • objname (string|Buffer)
    Since early days
    Name of header-record title to name objects by; the string or Buffer value must not be empty and it must match a header value.
  • on_record (function)
    Since 4.7.0
    Alter and filter records by executing a user defined function.
  • quote (char|boolean)
    Since early days
    Optional character surrounding a field; one character only; disabled if null, false or empty; defaults to double quote.
  • raw (boolean)
    Since version 1.1.6
    Generate two properties raw and record where raw is the original CSV content and record is the parsed array or object; note, it can be used conjointly with the info option.
  • relax (boolean)
    Since early days
    Preserve quotes inside unquoted field (be warned, it doesn't make coffee).
  • relax_column_count (boolean)
    Since version 1.0.6
    Discard inconsistent columns count; disabled if null, false or empty; default to false.
  • record_delimiter (chars|array)
    Since version 4.0.0
    One or multiple characters used to delimit records; defaults to auto discovery if not provided. Supported auto discovery methods are Linux ("\n"), Apple ("\r") and Windows ("\r\n") row delimiters. It was previously named rowDelimiter.
  • rtrim (boolean)
    Since early days
    If true, ignore whitespace immediately preceding the delimiter (i.e. right-trim all fields). Defaults to false. Does not remove whitespace in a quoted field.
  • skip_empty_lines (boolean)
    Since version 0.0.5
    Don't generate records for empty lines (line matching /\s*/), defaults to false.
  • skip_lines_with_error (boolean)
    Since version 2.1.0
    Skip a line with error found inside and directly go process the next line.
  • skip_lines_with_empty_values (boolean)
    Since version 1.1.8
    Don't generate records for lines containing empty column values (column matching /\s*/), empty Buffer or equals to null and undefined if their value was casted, defaults to false.
  • to (number)
    Since version 1.2.0
    Stop handling records after the requested number of records.
  • to_line (number)
    Since version 4.0.0
    Stop handling records after the requested line number.
  • trim (boolean)
    Since early days
    If true, ignore whitespace immediately around the delimiter. Defaults to false. Does not remove whitespace in a quoted field.

Choose your style

The code uses snake case as the conventional style for function and variable names. In snake case, all letters are lowercase and underscores separate words. It is however accepted to provide options in camel case. Thus, record_delimiter and recordDelimiter are equivalent when initialising a new parser. The option will be converted into snake case and exposed as such. For example, in case you need to access the record_delimiter option, use generate().options.record_delimiter and not generate().options.recordDelimiter. Choose the case which best fit your coding style.