Fastest-writable NPM

fastest-writable

Node.js Writable which goes at the speed of its fastest peer Writable and ends peers which can't keep up.

Alternative to readable.pipe which goes at the rate of the slowest peer.
Peers which aren't drained when a write occurs are ended.
With no peers added, fastest-writable consumes data as fast as it is written and throws it away.
Full set of unit tests with 100% coverage.

Example:

var stream = require('stream'),
    assert = require('assert'),
    FastestWritable = require('fastest-writable').FastestWritable,
    source = new stream.PassThrough(),
    fw = new FastestWritable(),
    dest1 = new stream.PassThrough({ highWaterMark: 1 }),
    dest2 = new stream.PassThrough({ highWaterMark: 1 });

source.pipe(fw);
fw.add_peer(dest1);
fw.add_peer(dest2);

source.write('foo');
assert.equal(dest1.read().toString(), 'foo');
source.write('bar');
// drain emitted next tick
process.nextTick(function ()
{
    assert(dest2._writableState.ended);
});

The API is described here.

Installation

npm install fastest-writable

Licence

MIT

Test

grunt test

Code Coverage

grunt coverage

c8 results are available here.

Coveralls page is here.

Lint

grunt lint

API

FastestWritable(options)

Creates a new FastestWritable object which can write to multiple peer stream.Writable objects.

Inherits from stream.Writable so you can use any Writable method or event in addition to those described here.

Parameters:

{Object} [options] Configuration options. This is passed onto Writable's constructor and can contain the following extra property:
- {Boolean} [end_peers_on_finish] Whether to call writable.end on all peers when this FastestWritable object emits a finish event. Defaults to true.
- {Boolean} [destroy_peers_on_destroy] Whether to call writable.destroy on all peers when this FastestWritable is destroyed. Defaults to true.
- {Boolean} [emit_laggard] Whether to emit an event named laggard on any peers which can't keep up instead of ending them. Defaults to false.

Go: TOC

FastestWritable.prototype.add_peer(peer)

Add a peer Writable to the list of peers to which data will be written.

When writable.write is called on this FastestWritable object, the data is written to every peer. FastestWritable drains when at least one of its peers drains. When writable.write is called again, writable.end is called on any peer which hasn't drained from the previous writable.write call.

If this FastestWritable object has no peer Writables then it drains immediately.

Parameters:

{stream.Writable} peer Peer Writable to add.

Go: TOC | FastestWritable.prototype

FastestWritable.prototype.remove_peer(peer, end)

Remove a peer Writable from the list of peers to which data will be written.

Parameters:

{stream.Writable} peer Peer Writable to remove.
{Boolean} end Whether to call writable.end on the peer once it's been removed from the list. Defaults to true.

Go: TOC | FastestWritable.prototype

FastestWritable.events.empty()

empty event

A FastestWritable object emits an empty event when it has no more Writable objects in its list of peers.

Note that when a FastestWritable object is empty, it is always drained and throws any data it receives away.

You could, for example, end the FastestWritable object when empty is emitted.

Go: TOC | FastestWritable.events

FastestWritable.events.waiting(stop_waiting)

waiting event

A FastestWritable object emits a waiting event when it's waiting for any of its peers to drain.

When a peer drains, the FastestWritable object will emit a ready event. If there are no listeners for the ready event then it will emit a drain event.

Parameters:

{Function} stop_waiting Call this function to force the FastestWritable object to drain without waiting for any of its peers to drain. You could use this to implement a timeout, for example. It's safe to call stop_waiting more than once or even after a peer has drained of its own accord.

Go: TOC | FastestWritable.events

FastestWritable.events.ready(num_waiting, total, drain)

ready event

A FastestWritable object emits a ready event when one of its peers drains. It gives you the ability to control when the FastestWritable object emits drain.

Parameters:

{Integer} num_waiting Number of peers which still haven't drained for the latest data written to the FastestWritable object.
{Integer} total Number of peers which received the latest data written to the FastestWritable object.
{Function} drain Call this function to let the FastestWritble object drain without waiting for any more of its peers to drain. It's safe to call drain more than once.

Go: TOC | FastestWritable.events

FastestWritable.events.laggard(peer)

laggard event

A FastestWritable object emits a laggard event when one of its peers can't keep up, if emit_laggard was passed to the constructor. Note a laggard event is also emitted on the peer.

Parameters: