Option cast

Table of Contents

The cast option alter a value. It works at the field level of a record. It is possible to transform its value or change its type.

  • Type: function
  • Optional
  • Default: none
  • Since: 2.2.0

Its value is expected to be a function which receive a context rich of information. It gives full control over a field. The test/options.cast.coffee test provides insights on how to use it and its supported functionalities.


The function is called with 2 arguments: the field value and a context object. The context object expose the following properties:

  • column (number|string)
    The column name if the columns options is defined or the field position.
  • empty_lines (number)
    Internal counter of empty lines encountered until this field.
  • header (boolean)
    A boolean indicating if the provided value is a part of the header.
  • index (number)
    The field position starting at 0.
  • invalid_field_length (number)
    Number of records with a non uniform length when relax_column_count is true. It was named skipped_lines until version 3.
  • lines (number)
    The number of lines which have been processed including the current line.
  • quoting (boolean)
    A boolean indicating if the field was surrounded by quotes.
  • records (number)
    The number of records which have been fully parsed. It was named count until version 3.

The cast example uses the context to transform the first filed into a date and replace the second field with the injected context:

const parse = require('csv-parse/lib/sync')
const assert = require('assert')

const data = `
const records = parse(data, {
  cast: function(value, context){
    if(context.index === 0){
      return `${value}T05:00:00.000Z`
      return context
  trim: true
assert.deepEqual(records, [
  [ '2000-01-01T05:00:00.000Z', {
    column: 1, empty_lines: 0, header: false, index: 1,
    quoting: false, lines: 1, records: 0, skipped_lines: 0
  } ],
  [ '2050-11-27T05:00:00.000Z', {
    column: 1, empty_lines: 0, header: false, index: 1,
    quoting: false, lines: 2, records: 1, skipped_lines: 0
  } ]