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

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

Or via the main module:

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

For Web Streams, import from the browser-safe /web entry (no node:*):

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

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 Node.js Duplex stream:

import fs from 'node:fs';

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

As a Web TransformStream (browser or any Web Streams runtime):

import {chain} from 'stream-chain/web';
import parser from 'stream-csv-as-json/web/parser.js';

const pipeline = chain([response.body.pipeThrough(new TextDecoderStream()), parser()]);
for await (const token of pipeline.readable) 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

The parser produces a stream of {name, value} tokens using the same protocol as stream-json. This means the output is fully compatible with stream-json utilities — you can use filters, streamers, and other components downstream.

Each row is represented as 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.
• Row terminator acceptance is lenient — CRLF (RFC 4180), LF, and bare CR all work.
• A leading UTF-8 BOM (U+FEFF) at the very start of the input is stripped.
• Uses sticky RegExp (/y flag) for performance. Each parser instance owns its own pattern set.

Errors

The parser throws on malformed quoted values:

• "Parser cannot parse input: expected a quoted value" — input ends mid-quote (unterminated quoted field).
• "Parser cannot parse input: unexpected character after a quoted value" — content other than the separator, CR, LF, or another " appears immediately after a closing ".

Errors propagate through stream-chain as a normal stream 'error' event.

API summary

Name	Returns	Description
parser(options)	flushable function	For use in chain()
parser.asStream(options)	Node Duplex stream	Writable: text, Readable: object mode
parser.asWebStream(options)	Web {readable, writable} pair	Web Streams substrate

.asWebStream is attached on the Node entry too; the /web entry carries only .asWebStream. The /core entry (stream-csv-as-json/core/parser.js) is the substrate-free factory with no adapters.