as‐objects

asObjects

asObjects converts a token stream of arrays (rows) into a token stream of objects, using the first row as field names.

asObjects(options) is a factory function returning a flushable function for use in stream-chain pipelines.

Import

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

For Web Streams, import from the browser-safe /web entry:

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

Usage

import chain from 'stream-chain';
import {parser} from 'stream-csv-as-json';
import asObjects from 'stream-csv-as-json/as-objects.js';
import fs from 'node:fs';

// data.csv:
// a,b,c
// 1,2,3

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

pipeline.on('data', token => console.log(token));
// {name: 'startObject'}
// {name: 'keyValue', value: 'a'}
// {name: 'stringValue', value: '1'}
// {name: 'keyValue', value: 'b'}
// {name: 'stringValue', value: '2'}
// {name: 'keyValue', value: 'c'}
// {name: 'stringValue', value: '3'}
// {name: 'endObject'}

With withParser

withParser combines the parser and asObjects into a single pipeline, so you can pipe CSV text directly:

import fs from 'node:fs';

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

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

Options

All options are optional.

Option	Type	Default	Description
packKeys	boolean	true	Emit keyValue tokens with the complete field name
packValues	boolean	—	Alias for packKeys
streamKeys	boolean	true	Emit startKey/stringChunk/endKey tokens for field names
streamValues	boolean	—	Alias for streamKeys
fieldPrefix	string	'field'	Prefix for auto-generated field names

If packKeys is false, streamKeys is forced to true.

useStringValues / useValues are accepted but deprecated no-ops — kept only for backward compatibility. The header collector auto-detects the parser's mode (stream tokens or packed stringValue), so no explicit hint is needed.

fieldPrefix

When a data row has more columns than the header row, missing field names are generated as fieldPrefix + index (zero-based). For example, with header a,b and data 1,2,3,4:

• Fields: a, b, field2, field3

With {fieldPrefix: 'col'}: a, b, col2, col3.

The same fallback applies when a header cell itself is empty (e.g., header a,,c produces keys a, field1, c).

Header auto-detection

asObjects consumes the first row to build the field-name list. The collector handles every parser configuration:

• Default parser (both streams and packed values emitted): captures from startString / stringChunk / endString and ignores the matching stringValue.
• Pack-only (parser({streamStrings: false})): captures from stringValue directly.
• Stream-only (parser({packStrings: false})): captures from stringChunk / endString.

Wire any parser into asObjects() without an explicit option — it works.

Behavior

1. Header phase: The first row is consumed silently to build the list of field names. No tokens are emitted for it.
2. Data phase: Subsequent rows are transformed:
   • startArray → startObject
   • Before each field value: key tokens are emitted (startKey/stringChunk/endKey and/or keyValue)
   • Field value tokens (startString/stringChunk/endString/stringValue) are passed through unchanged
   • endArray → endObject

API summary

Name	Returns	Description
asObjects(options)	flushable function	For use in chain()
asObjects.asStream(options)	Node Duplex stream	Object mode both sides
asObjects.asWebStream(options)	Web {readable, writable} pair	Web Streams substrate
asObjects.withParser(options)	flushable function	Parser + asObjects pipeline
asObjects.withParserAsStream(options)	Node Duplex stream	Combined pipeline, Node Duplex
asObjects.withParserAsWebStream(options)	Web {readable, writable} pair	Combined pipeline, Web Streams

The /web entry (stream-csv-as-json/web/as-objects.js) carries only the .asWebStream / .withParserAsWebStream variants.