parser

The parser module provides streaming decoders for CSV and NDJSON data. It is designed for use with JSH streams and emits parsed objects through events.

Typical usage looks like this.

const parser = require('parser');

Exported members

• csv(options)
• ndjson(options)
• CSVParser
• NDJSONParser

csv()

Creates a CSV parser stream.

Syntax

parser.csv([options])

Options

Return value

Returns a CSVParser instance.

CSVParser

CSV parser class exported by the module.

Creation

new parser.CSVParser([options])

The constructor accepts the same options as parser.csv().

Events

• headers: emitted once after the header row is parsed
• data: emitted for each parsed row object
• error: emitted when strict parsing fails
• end: emitted when the upstream stream finishes

Properties

• bytesWritten: number of input bytes received
• bytesRead: number of bytes consumed by the parser

Row shape

• When headers is omitted or true, the first non-skipped line becomes the header row.
• When headers is false, fields are exposed as "0", "1", "2", …
• When headers is an array, those names are used and the first line is treated as data.
• In non-strict mode, extra columns are emitted as _N fields such as _3.

ndjson()

Creates an NDJSON parser stream.

Syntax

parser.ndjson([options])

Options

Return value

Returns an NDJSONParser instance.

NDJSONParser

NDJSON parser class exported by the module.

Creation

new parser.NDJSONParser([options])

The constructor accepts the same options as parser.ndjson().

Events

• data: emitted for each parsed JSON object
• warning: emitted for invalid lines when strict: false
• error: emitted when strict parsing fails
• end: emitted when the upstream stream finishes

warning event objects contain:

Properties

• bytesWritten: number of input bytes received
• bytesRead: number of bytes consumed by the parser

CSV example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const fs = require('fs');
const parser = require('parser');

fs.createReadStream('/work/sample.csv')
    .pipe(parser.csv({
        headers: true,
        mapValues: ({ header, value }) => header === 'age' ? parseInt(value, 10) : value,
    }))
    .on('headers', (headers) => {
        console.println(headers.join(','));
    })
    .on('data', (row) => {
        console.println(row.name, row.age);
    });

NDJSON example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const fs = require('fs');
const parser = require('parser');

fs.createReadStream('/work/sample.ndjson')
    .pipe(parser.ndjson({ strict: false }))
    .on('data', (obj) => {
        console.println(obj.id);
    })
    .on('warning', (warn) => {
        console.println('Skipped line:', warn.line);
    });

Progress example

Both parser streams expose bytesWritten and bytesRead, so progress can be tracked while streaming.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const fs = require('fs');
const parser = require('parser');

const decoder = parser.csv();

fs.createReadStream('/work/sample.csv', { highWaterMark: 8 })
    .pipe(decoder)
    .on('data', () => {
        console.println(decoder.bytesWritten, decoder.bytesRead);
    });

Behavior notes

• Both parser classes extend the JSH stream.Transform implementation.
• Parsed rows and objects are emitted through data events.
• Empty lines are ignored by both parsers.
• NDJSONParser trims each line before parsing.
• CSVParser removes a trailing \r so \r\n input is handled correctly.