defs

defs is a module, which defines all special constants and convenience methods used in chain().

Its properties are mixed in or otherwise duplicated in other modules like chain() itself.

none

none is a special value, which terminates the chain and returns no value.

// import chain, {none} from 'stream-chain';
// import {chain, none} from 'stream-chain';
// const {chain, none} = require('stream-chain');

import chain from 'stream-chain';
import {none} from 'stream-chain/defs';

// a filter
dataSource
  .pipe(chain([
    x => x * x,
    x => x % 2 ? none : x,
    x => 2 * x + 1
  ]));
// skips odd values

// if dataSource produces: 1, 2, 3
// then the result will be: 3, 19

This is the definition of none:

const none = Symbol.for('object-stream.none');

stop

stop is a special value, which terminates the chain, returns no value, and stops further processing. Usually, it is used to terminate potentially infinite generators.

// import chain, {stop} from 'stream-chain';

import chain from 'stream-chain';
import {stop} from 'stream-chain/defs';

chain([
  function* () { for (let i = 0; ; ++i) yield i; }
  n => n > 1000 ? stop : n,
]);
// a stream produces numbers from 0 to 1000 inclusively

This is the definition of stop:

const stop = Symbol.for('object-stream.stop');

To be continued from this point...

final(value)

(since 2.1.0) final(value) is a helper factory function, which can be used in by chained functions (see above the array of functions).

It returns a special value, which terminates the chain and uses the passed value as the result of the chain.

// const {chain, final} = require('stream-chain');
const {chain} = require('stream-chain');
const {final} = require('stream-chain/defs');

// simple
dataSource
  .pipe(chain([[x => x * x, x => 2 * x + 1]]));
// faster than [x => x * x, x => 2 * x + 1]

// final
dataSource
  .pipe(chain([[
    x => x * x,
    x => final(x),
    x => 2 * x + 1
  ]]));
// the same as [[x => x * x, x => x]]
// the same as [[x => x * x]]
// the same as [x => x * x]

isFinal(value)

(since 2.2.0) isFinal(value) is a companion to final(). It checks if a value was marked as final returning a standard truthy/falsy result.

// const {chain, final, isFinal} = require('stream-chain');
const {chain} = require('stream-chain');
const {final, isFinal} = require('stream-chain/defs');

dataSource
  .pipe(chain([
    x => {
      let result = final(x);
      // ...
      if (isFinal(result)) {
        // do something
      } else {
        // do something else
      }
      // ...
    },
    // the rest of pipeline
  ]));

getFinalValue(value)

(since 2.2.0) getFinalValue(value) is a companion to final() and isFinal(). Its argument should be a wrapped final value. Its return will be an unwrapped value.

// const {chain, final, isFinal, getFinalValue} = require('stream-chain');
const {chain} = require('stream-chain');
const {final, isFinal, getFinalValue} = require('stream-chain/defs');

dataSource
  .pipe(chain([
    x => {
      let result = final(42);
      // ...
      if (isFinal(result)) {
        const value = getFinalValue(result);
        console.log(value);
        // do something
      } else {
        console.log(result);
        // do something else
      }
      // ...
    },
    // the rest of pipeline
  ]));

many(array)

(since 2.1.0) many(array) is a helper factory function, which is used to wrap arrays to be interpreted as multiple values returned from a function.

At the moment it is redundant: you can use a simple array to indicate that, but a naked array is being deprecated and in future versions, it will be passed as-is.

The thinking is that using many() indicates the intention better.

// const {chain, many} = require('stream-chain');
const {chain} = require('stream-chain');
const {many} = require('stream-chain/defs');

dataSource
  .pipe(chain([x => many([x, x + 1, x + 2])]));
// currently the same as [x => [x, x + 1, x + 2]]

isMany(value)

(since 2.2.0) isMany(value) is a companion to many(). It checks if a value was marked as multiple values returning a standard truthy/falsy result.

// const {chain, many, isMany} = require('stream-chain');
const {chain} = require('stream-chain');
const {many, isMany} = require('stream-chain/defs');

dataSource
  .pipe(chain([
    x => {
      let result = many([x, x + 1]);
      // ...
      if (isMany(result)) {
        // do something
      } else {
        // do something else
      }
      // ...
    },
    // the rest of pipeline
  ]));

getManyValues(value)

(since 2.2.0) getManyValues(value) is a companion to many() and isMany(). Its argument should be a wrapped multiple value. Its return will be an unwrapped value (an array of values).

// const {chain, many, isMany, getManyValues} = require('stream-chain');
const {chain} = require('stream-chain');
const {many, isMany, getManyValues} = require('stream-chain/defs');

dataSource
  .pipe(chain([
    x => {
      let result = many([1, 42, 99]);
      // ...
      if (isMany(result)) {
        const values = getManyValues(result);
        console.log(values);
        // do something
      } else {
        console.log(result);
        // do something else
      }
      // ...
    },
    // the rest of pipeline
  ]));