Pick

Pick is a token item filter based on FilterBase. It selects objects from a stream ignoring the rest. Its filter is not called for subobjects of selected objects.

Unless Pick selects just one object, it produces a stream of objects similar to JSON Streaming supported by Parser. Usually, the result is piped through StreamValues. Other streamers could be unsuitable.

Introduction

const {pick} = require('stream-json/filters/pick.js');
const {streamArray} = require('stream-json/streamers/stream-array.js');
const {chain} = require('stream-chain');
const fs = require('fs');

// our data stream:
// {total: 123456789, meta: {...}, data: [...]}
// we are interested in 'data'

const pipeline = chain([fs.createReadStream('sample.json'), pick.withParser({filter: 'data'}), streamArray()]);

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

More complex example:

const {pick} = require('stream-json/filters/pick.js');
const {parser} = require('stream-json/parser.js');
const {streamValues} = require('stream-json/streamers/stream-values.js');

// our data stream: array of objects,
// each object looks like that:
// {total: 123456789, meta: {...}, data: [...]}
// we want the content of all 'data' subobjects

const pipeline = chain([fs.createReadStream('sample.json'), parser(), pick({filter: /^\d+\.data\.\d+/}), streamValues()]);

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

API

Pick has no special API. Based on FilterBase it uses the following options:

• filter
  • If it returns a truthy value, the current object is streamed out with all its possible subobjects.
  • It is called only for the following tokens: startObject, startArray, startString, startNumber, stringValue, numberValue, nullValue, trueValue, falseValue.
• pathSeparator
• once

See their definitions in FilterBase.

Static methods and properties

pick(options)

pick() is the factory function. It takes options described above and returns a filter function for use in chain():

const {chain} = require('stream-chain');
const {parser} = require('stream-json/parser.js');
const {pick} = require('stream-json/filters/pick.js');

const fs = require('fs');

const pipeline = chain([fs.createReadStream('sample.json'), parser(), pick({filter: 'data'})]);

let objectCounter = 0;
pipeline.on('data', data => data.name === 'startObject' && ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

pick.asStream(options)

Returns a Duplex stream (object-mode both sides) wrapping pick() for .pipe() usage:

const {pick} = require('stream-json/filters/pick.js');
const {parser} = require('stream-json/parser.js');

const pipeline = fs
  .createReadStream('sample.json')
  .pipe(parser.asStream())
  .pipe(pick.asStream({filter: 'data'}));

withParser()

withParser() takes one argument:

• options — combined Parser and filter options. Passed to both the parser and pick().

Returns a Duplex stream (text-mode writable, object-mode readable) wrapping a parser() + pick() pipeline via stream-chain.

Built with the withParser() utility.

const {pick} = require('stream-json/filters/pick.js');
const fs = require('fs');

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

let objectCounter = 0;
pipeline.on('data', data => data.name === 'startObject' && ++objectCounter);
pipeline.on('end', () => console.log(`Found ${objectCounter} objects.`));

Web Streams

pick ships in two substrate-specific entries with the same factory shape:

• Node — stream-json/filters/pick.js. Has asStream, asWebStream, withParser, withParserAsStream, withParserAsWebStream.
• Web — stream-json/web/filters/pick.js. Has asWebStream, withParser, withParserAsWebStream. Pulls in no Node-stream imports.

Both factories return the same flushable, so chain on either substrate auto-wraps it. Use chain from stream-chain on Node and from stream-chain/web on Web.

// Web
import {chain} from 'stream-chain/web';
import {parser} from 'stream-json/web/parser.js';
import {pick} from 'stream-json/web/filters/pick.js';
import {streamArray} from 'stream-json/web/streamers/stream-array.js';

const pipeline = chain([source, parser.asWebStream(), pick({filter: 'data'}), streamArray()]);
for await (const item of pipeline.readable) console.log(item);

Or the parser-included shortcut:

const {readable, writable} = pick.withParserAsWebStream({filter: 'data'});
sourceReadable.pipeTo(writable);
for await (const tok of readable) console.log(tok);