stream-chain/README.md

stream-chain

stream-chain is a simple helper to create a chain of object-mode transform streams out of regular functions, asynchronous functions, generator functions, and existing Transform and Duplex object-mode streams.

It is distributed under New BSD license.

Intro

const Chain = require('stream-chain');

const chain = new Chain([
  x => [x - 1, x, x + 1],
  x => x * x,
  async x => getFromDatabaseByKey(x),
  function* (x) {
    for (let i = x; i > 0; --i) {
      yield i;
    }
    return 0;
  }
]);
chain.on('data', data => console.log(data));
dataSource.pipe(chain.input);

Installation

npm i stream-chain

Documentation

The main module provides a class based on EventEmitter. It chains its arguments in a single pipeline optionally binding common stream events.

The constructor accepts two parameters:

• fns is an array of functions or instances of Duplex or Transform streams.
  • If a value is a function, a Transform stream is created, which calls this function with two parameters: chunk (an object), and an optional encoding. See documentation for more details on those parameters. The function will be called in the content of created stream.
  • If it is a regular function, it can return an array of values to pass to the next stream, a single value, undefined or null. Two latter values indicate that no value should be passed.
  • If it is a generator function, it can yield and/or return all necessary values. Each yield/return value will be treated like a returned value from a regular function.
  • If it is an asynchronous function, it will be waited to be resolved, and the resulting value will be treated like a returned value from a regular function.
  • Any thrown exception will be catched and passed to a callback function effectively generating an error event.
  • If a value is a valid stream, it is included as is in the pipeline.
• skipEvents is an optional Boolean parameter. If it is false (the default), 'error' events from all streams are forwarded to the created instance, 'data' and 'end' events are forwarded from the last stream of a pipeline. If it is true, no event forwarding is made.
  • This parameter is useful for handling non-standard events. In this case the forwarding of events can be done either manually, or in a constructor of a derived class.

Release History

• 1.0.0 the initial release.