parser

Parser

The parser is the core of the package. It consumes CSV text and produces a stream of {name, value} tokens using a SAX-inspired protocol compatible with stream-json.

parser(options) is a factory function returning a flushable function for use in stream-chain pipelines. It is composed with fixUtf8Stream() to handle split multi-byte characters at chunk boundaries.

Import

// ESM
import parser from 'stream-csv-as-json/parser.js';

// CommonJS
const parser = require('stream-csv-as-json/parser.js');

Or via the main module:

// ESM
import {parser} from 'stream-csv-as-json';

// CommonJS
const {parser} = require('stream-csv-as-json');

Usage

As a function in a chain() pipeline:

import chain from 'stream-chain';
import fs from 'node:fs';

const pipeline = chain([fs.createReadStream('data.csv'), parser()]);

pipeline.on('data', token => console.log(token.name, token.value));

As a Duplex stream:

import fs from 'node:fs';

fs.createReadStream('data.csv')
  .pipe(parser.asStream())
  .on('data', token => console.log(token.name, token.value));

Options

All options are optional.

Option	Type	Default	Description
packStrings	boolean	true	Emit stringValue tokens with the complete field value
packValues	boolean	—	Alias for packStrings
streamStrings	boolean	true	Emit startString/stringChunk/endString tokens
streamValues	boolean	—	Alias for streamStrings
separator	string	','	Field separator character

If packStrings is false, streamStrings is forced to true — at least one representation must be emitted.

Option resolution

Both packValues/packStrings and streamValues/streamStrings follow the same pattern: the generic alias (packValues, streamValues) is applied first, then the specific option (packStrings, streamStrings) overrides it.

Supplied options	packStrings	streamStrings
{}	true	true
{packValues: false}	false	true
{packValues: false, packStrings: true}	true	true
{packStrings: true, streamStrings: false}	true	false
{packStrings: false, streamStrings: false}	false	true

Token stream

Each row is an array of string values:

startArray
  startString → stringChunk* → endString → stringValue?
  startString → stringChunk* → endString → stringValue?
  ...
endArray

Three configurations are supported:

1. Default (packStrings: true, streamStrings: true): startString, 0+ stringChunk, endString, then stringValue.
2. Pack only (packStrings: true, streamStrings: false): stringValue only.
3. Stream only (packStrings: false): startString, 0+ stringChunk, endString only.

CSV parsing rules

• Follows RFC 4180.
• Quoted fields: "" escapes to ", embedded separators and newlines are preserved.
• Both \r\n and \n line endings are supported.
• Uses sticky RegExp (/y flag) for performance.

API summary

Name	Returns	Description
parser(options)	flushable function	For use in chain()
parser.asStream(options)	Duplex stream	Writable: text, Readable: object mode
parser.parser	self-reference	For destructuring: const {parser} = require(...)