https://github.com/uhop/stream-fork
Fork a writable stream into several parallel writable streams.
https://github.com/uhop/stream-fork
stream-processing streams
Last synced: about 1 year ago
JSON representation
Fork a writable stream into several parallel writable streams.
- Host: GitHub
- URL: https://github.com/uhop/stream-fork
- Owner: uhop
- Created: 2018-05-29T05:00:37.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-11-12T00:52:26.000Z (over 5 years ago)
- Last Synced: 2025-04-21T06:09:28.376Z (about 1 year ago)
- Topics: stream-processing, streams
- Language: JavaScript
- Homepage:
- Size: 36.1 KB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# stream-fork [![NPM version][npm-img]][npm-url]
[npm-img]: https://img.shields.io/npm/v/stream-fork.svg
[npm-url]: https://npmjs.org/package/stream-fork
`stream-fork` is a [Writable stream](https://nodejs.org/api/stream.html#stream_writable_streams), which writes into dependent Writable streams properly handling [backpressure](https://nodejs.org/en/docs/guides/backpressuring-in-streams/). It is a way to make forks in a linear pipeline of streams.
Originally `stream-fork` was used internally with [stream-chain](https://www.npmjs.com/package/stream-chain) and [stream-json](https://www.npmjs.com/package/stream-json) to create flexible data processing pipelines.
`stream-fork` is a lightweight, no-dependencies micro-package. It is distributed under New BSD license.
## Intro
```js
const Fork = require('stream-fork');
const fs = require('fs');
const zlib = require('zlib');
const gzip = zlib.createGzip();
gzip.pipe(fs.createWriteStream('log.txt.gz'));
// push data to both the gzip chain and stdout
const forkStream = new Fork([gzip, process.stdout], {});
dataSource.pipe(forkStream);
// now we have data on our screen and as a compressed log file
```
## Installation
```bash
npm i --save stream-fork
# or: yarn add stream-fork
```
## Documentation
`Fork`, which is returned by `require('stream-fork')`, is a specialized [Writable](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream. It propagates every piece of data downstream to its dependent Writable streams (including [Transform](https://nodejs.org/api/stream.html#stream_class_stream_transform) and [Duplex](https://nodejs.org/api/stream.html#stream_class_stream_duplex) streams).
Many details about this package can be discovered by looking at test files located in `tests/` and in the source code (`main.js`).
### Constructor: `new Fork(outputs[, options])`
The constructor accepts following arguments:
* `outputs` is an array of Writable streams, which will be used duplicate written chunks or items.
* `options` is an options object, which is used to create a Writable stream. Read all about it in [Implementing a Writable stream](https://nodejs.org/api/stream.html#stream_implementing_a_writable_stream). If it is not specified or falsy, `{objectMode: true}` is assumed. This default is useful for creating object mode streams.
* Additionally following custom options are recognized:
* `ignoreErrors` is a flag. When its value is truthy, a `Fork` instance never fails on `write()` silently ignoring downstream errors. Otherwise, the first encountered downstream error is reported upstream as its own error. The default: `false`.
```js
const forkObj = new Fork(streams); // object mode
const forkChk = new Fork(streams, {}); // chunk mode (text or buffers)
```
### Property: `outputs`
It is an array of Writable streams supplied in the constructor above. If a stream fails on writing a chunk, eventually it will be removed from the array.
```js
const forkStream = new Fork(streams);
forkStream.outputs.length === streams.length; // true
```
### Method: `isEmpty()`
It returns `true` if `outputs` property is empty, and `false` otherwise. If `isEmpty()` is `true`, it means that the stream do not duplicate data.
```js
const forkStream = new Fork([]);
forkStream.isEmpty(); // true
```
### Static method: `fork(outputs[, options])`
It is a factory function, which accepts the same arguments as the constructor, and returns a fully constructed `Fork` object.
```js
// replicating the introduction example above
const {fork} = require('stream-fork');
dataSource.pipe(fork([gzip, process.stdout], {}));
```
## Release History
- 1.0.5 *technical release.*
- 1.0.4 *bugfix: forward errors correctly, thx [dbubovych](https://github.com/dbubovych).*
- 1.0.3 *technical release to support Node 14.*
- 1.0.2 *workaround for Node 6: use `'finish'` event instead of `_final()`.*
- 1.0.1 *improved documentation.*
- 1.0.0 *the initial release.*