Option columns

The columns option controls the generation of records at the field level. For example, it is used to name headers, to order columns in the generated records, and to filter columns. It applies when records are provided as objects and arrays.

Consider the tests as an exhaustive source of inspiration, examples and supported features. Also, refer to the "header" option to learn how to print columns names on the first line.

• Type: array | object
• Optional
• Default: undefined
• Since: 0.0.1
• Related: header — see Available Options

Usage

The columns option can be an array of { 'key': string, 'header': string } objects, or an array of column names (strings).

As objects, columns are defined with the properties:

• key (string)
  Name of property present in the input records; required.
• header (string)
  Value to be printed in the first header line; to be used conjointly with the header option; defaults to key.

Here is an example:

import { stringify } from 'csv-stringify';
import assert from 'node:assert';

stringify([
  { a: '1', b: '2' }
], {
  columns: [ { key: 'a' }, { key: 'b' } ]
}, function(err, data){
  assert.equal(data, '1,2\n');
});

A shorter variation is to declare column elements as strings. The previous example is simplified by defining a column as a simple string:

import { stringify } from 'csv-stringify';
import assert from 'node:assert';

stringify([
  { a: '1', b: '2' }
], {
  columns: [ 'a', 'b' ]
}, function(err, data){
  assert.equal(data, '1,2\n');
});

Order

The order definition matters. It reflects the order of the generated records. Reversing the order of the columns option in the above example to [ { key: 'b' }, { key: 'a' } ] results in reversed generated CSV data: 2,1\n.

With records ingested in the form of objects, it is possible to re-order all columns. Columns keys are also auto discovered in the first record unless defined.

With records ingested in the form of arrays, order reflects the field positions. It is not possible to re-order columns, only to filter out the last ones.

Nested properties

With records provided as object, the column key can refer to nested properties of the input. It supports both array and object references.

import { stringify } from 'csv-stringify';
import assert from 'node:assert';

stringify([{
  an_array: [{
  }, {
    field_2: '1_val_1'
  }],
  an_object: {
    field_4: '1_val_2'
  }
},{
  an_array: [{
  }, {
    field_2: '2_val_1'
  }],
  an_object: {
    field_4: '2_val_2'
  }
}], {columns: [
  'an_object.field_4',
  'an_array[1].field_2'
]}, (err, records) => {
  assert.equal(records, '1_val_2,1_val_1\n2_val_2,2_val_1\n');
});

Undefined properties

If a column is defined but it is not matching any properties in the data source, the value will be an empty string. If the data source defines a property which is not defined in the column option, the property will simply be disregarded. This is an example:

import { stringify } from 'csv-stringify';
import assert from 'node:assert';

stringify([
  { year: 'XXXX', phone: 'XXX XXXX', nocolumn: 'XXX' },
  { year: 'YYYY', phone: 'YYY YYYY', nocolumn: 'XXX' }
],{
  columns: ['phone', 'year', 'nofield']
}, function(err, data){
  assert.equal(
    data,
    'XXX XXXX,XXXX,\n' +
    'YYY YYYY,YYYY,\n'
  );
});