Stringer

Stringer is a Transform stream. It consumes a token stream and converts it to text representing a JSON object. 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(). However, it will only convert a stream of tokens generated by Parser. Feeding raw objects into Stringer will output empty strings.

(Since 1.6.0) If you need to output JSONL instead of a regular JSON, take a look at jsonl/Stringer.

Introduction

const {stringer} = require('stream-json/Stringer');
const {parser}   = require('stream-json');
const {chain}    = require('stream-chain');
const {pick}     = require('stream-json/filters/Pick');

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

chain([
  fs.createReadStream('data.json.gz'),
  zlib.createGunzip(),
  parser(),
  pick({filter: 'data'}),
  stringer(),
  zlib.Gzip(),
  fs.createWriteStream('edited.json.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 a falsy value as the default:

• useValues serves as the initial value for selecting packed or streamed values of strings, numbers, and keys.
• useKeyValues specifies, if we need to use packed keys or streamed ones.
• useStringValues specifies, if we need to use packed strings or streamed ones.
• useNumbersValues specifies, if we need to use packed numbers or streamed ones.
• makeArray (since 1.4.0) forces all incoming JSON objects to be wrapped in an array.
  • If no input, an empty array will be produced.

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 each type of value is controlled by a flag:

• By default, this flag is false.
• If useValues is set, it is assigned to each flag.
• If an individual option is set, it is assigned to the flag.

Examples:

Supplied options	useKeyValues	useStringValues	useNumberValues
{}	false	false	false
{useValues: true}	true	true	true
{useValues: true, useKeyValues: false}	false	true	true
{useKeyValues: false, useValues: true}	false	true	true
{useStringValues: true}	false	true	false
{useKeyValues: true, useStringValues: false, useNumberValues: true}	true	false	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-json/Stringer');
const {chain}  = require('stream-chain');
const {parser} = require('stream-json');
const {pick}   = require('stream-json/filters/Pick');

const fs = require('fs');

const pipeline = chain([
  fs.createReadStream('sample.json'),
  parser(),
  pick({filter: 'data'}),
  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 stringers or metaprogramming if needed.