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

const asObjects = require('stream-csv-as-json/as-objects.js');

Usage

const chain = require('stream-chain');
const {parser} = require('stream-csv-as-json');
const asObjects = require('stream-csv-as-json/as-objects.js');
const fs = require('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:

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
useStringValues	boolean	false	Use stringValue tokens (instead of stringChunk/endString) to read header field names
useValues	boolean	—	Alias for useStringValues
fieldPrefix	string	'field'	Prefix for auto-generated field names

If packKeys is false, streamKeys is forced to true.

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.

useStringValues

By default, asObjects reads field names from the header row using stringChunk/endString tokens (the streamed representation). Set useStringValues: true to read from stringValue tokens instead. This must match the parser's packing/streaming configuration:

• If the parser emits only stringValue (pack only mode), set useStringValues: true.
• If the parser emits both (the default), either setting 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)	Duplex stream	Object mode both sides
asObjects.asObjects	self-reference	For destructuring
asObjects.withParser(options)	flushable function	Parser + asObjects pipeline
asObjects.withParserAsStream(options)	Duplex stream	Same, as a Duplex (writable: text, readable: object mode)