Stringer

Stringer is a Transform stream. It consumes a token stream and converts it to text representing a CSV file. It is very useful when you want to edit a stream with filters and a custom code, and save it back to a file.

If Parser corresponds to JSON.parse(), then Stringer corresponds to JSON.stringify() but for CSV.

This Stringer was modeled after stream-json's Stringer. Its options and the behavior is compatible.

Introduction

const {stringer} = require('stream-csv-as-json/Stringer');
const {parser}   = require('stream-csv-as-json');
const {chain}    = require('stream-chain');
const {filter}   = require('stream-json/filters/Filter');

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

chain([
  fs.createReadStream('data.csv.gz'),
  zlib.createGunzip(),
  parser(),
  filter({filter: /^[0-4]\b/}),
  stringer(),
  zlib.Gzip(),
  fs.createWriteStream('edited.csv.gz')
]);

API

Stringer has no special API. It is based on Transform with its writable part operating in object mode and its readable part operating in text mode.

constructor(options)

options is an optional object described in details in node.js' Stream documentation. Additionally, the following optional custom flags are recognized, which can be truthy or falsy with no default value:

• useValues serves as the initial value for selecting packed or streamed values of strings. It is here for consistency with stream-json.
• useStringValues specifies, if we need to use packed strings or streamed ones.

By default Stringer converts chunks to strings and outputs them. But it is possible to force it to use packed values instead of streamed chunks, providing that an upstream sends packed values. In some cases, when no streamed chunks are present in a token stream, we have to force the use of values.

Internally it is controlled by a flag:

• By default, this flag is false.
• If useValues is set, it is assigned to the flag. This option is here for consistency with stream-json.
• If useStringValues is set, it is assigned to the flag.

Examples:

Supplied options	useStringValues
{}	false
{useValues: true}	true
{useValues: true, useStringValues: false}	false
{useStringValues: false, useValues: true}	false
{useStringValues: true}	true

Static methods and properties

stringer(options) and make(options)

make() and stringer() are two aliases of the factory function. It takes options described above, and return a new instance of Stringer. stringer() helps to reduce a boilerplate when creating data processing pipelines:

const {stringer} = require('stream-csv-as-json/Stringer');
const {chain}  = require('stream-chain');
const {parser} = require('stream-csv-as-json');
const {filter} = require('stream-json/filters/Filter');

const fs = require('fs');

const pipeline = chain([
  fs.createReadStream('sample.csv'),
  parser(),
  filter({filter: /^[0-4]\b/}),
  stringer()
], {}); // empty 'options' is used to force text mode on both sides of a chain.

make.Constructor

Constructor property of make() (and stringer()) is set to Stringer. It can be used for indirect creating of filters or metaprogramming if needed.

withParser()

withParser() takes one argument:

• options is an object described in Parser's options. It is used to initialize both streams (a Parser instance and a stream returned by make()).

It returns a stream produced by stream-chain, which wraps the pipeline. The most important utility of withParser() is that it correctly sets object modes of the returned stream: object mode for the Readable part and text mode for the Writable part.

This static method is created using withParser() utility. It simplifies a case when a stream should be immediately preceded by a parser.

const Stringer = require('stream-json/filters/Stringer');
const fs = require('fs');

const pipeline = fs.createReadStream('sample.json')
  .pipe(Stringer.withParser({filter: 'data'}));