@rushstack/stream-collator

What is @rushstack/stream-collator?

@rushstack/stream-collator is a Node.js library that allows you to manage and collate multiple streams of output, ensuring that the output from different streams is properly interleaved and displayed in a coherent manner. This is particularly useful for managing the output of concurrent processes, such as build tools or test runners.

What are @rushstack/stream-collator's main functionalities?

Collating Multiple Streams

This feature allows you to register multiple streams and collate their output. The collator ensures that the output from different streams is properly interleaved and displayed in a coherent manner.

const { StreamCollator } = require('@rushstack/stream-collator');

const collator = new StreamCollator();

const stream1 = collator.registerStream('stream1');
const stream2 = collator.registerStream('stream2');

stream1.write('Output from stream 1\n');
stream2.write('Output from stream 2\n');

stream1.end();
stream2.end();

collator.on('data', (data) => {
  process.stdout.write(data);
});

Handling Stream Completion

This feature allows you to handle the completion of all registered streams. The 'end' event is emitted when all streams have finished writing.

const { StreamCollator } = require('@rushstack/stream-collator');

const collator = new StreamCollator();

const stream1 = collator.registerStream('stream1');
const stream2 = collator.registerStream('stream2');

stream1.write('Output from stream 1\n');
stream2.write('Output from stream 2\n');

stream1.end();
stream2.end();

collator.on('end', () => {
  console.log('All streams have completed');
});

Error Handling

This feature allows you to handle errors from any of the registered streams. The 'error' event is emitted when an error occurs in any of the streams.

const { StreamCollator } = require('@rushstack/stream-collator');

const collator = new StreamCollator();

const stream1 = collator.registerStream('stream1');
const stream2 = collator.registerStream('stream2');

stream1.write('Output from stream 1\n');
stream2.write('Output from stream 2\n');

stream1.emit('error', new Error('Stream 1 error'));

collator.on('error', (err) => {
  console.error('Error:', err.message);
});

Other packages similar to @rushstack/stream-collator

merge-stream

The 'merge-stream' package allows you to merge multiple streams into a single stream. Unlike @rushstack/stream-collator, it does not provide advanced features for managing the interleaving of output or handling stream completion and errors in a coordinated manner.

multistream

The 'multistream' package allows you to combine multiple streams into a single stream. It focuses on sequentially combining streams rather than interleaving their output. It is simpler but less powerful compared to @rushstack/stream-collator.

stream-combiner2

The 'stream-combiner2' package allows you to combine multiple streams into a pipeline. It is useful for creating complex stream processing pipelines but does not provide the same level of control over output interleaving and stream management as @rushstack/stream-collator.

README

stream-collator

This library enables a tool to display live console output from multiple asynchronous processes, while ensuring that their output does not get jumbled together.

How does it work?

The stream-collator manages the output of these streams, ensuring that no two streams are writing to the console at the same time. At any given time, one stream registered with the collator is the active stream, which means that particular stream will be live streaming, while the others will wait for that stream to finish before their output is displayed.

For example, if you have 3 streams (e.g. from using child_process.spawn()).

Stream A will write: AAAAA

Stream B will write: BBBBBBBBBBBBBBBBBBBB

Stream C will write: CCCCCCCCCC

If these streams are all being piped directly to stdout (without stream-collator), you could end up with jumbled output:

ABACCCBCCCCBBABBCBBABBBBBBCCAB

Something like the following would be much more useful to users of your application:

AAAAABBBBBBBBBBBBBBBCCCCCCCCCC

This is where the stream-collator comes in!

Usage

Install the stream-collator:

npm install --save @rushstack/stream-collator

Import the collator:

import StreamCollator from '@rushstack/stream-collator'; // es6

const StreamCollator = require('@rushstack/stream-collator'); // commonjs

A stream collator adheres to the NodeJS Stream API, meaning that it effectively is special type of ReadableStream. This makes working with the stream collator very simple. Imagine we had the 3 streams from the example above:

const streamA = getRepeaterStream('A', 5); // fake helper function that returns a ReadableStream
const streamB = getRepeaterStream('B', 15); // fake helper function that returns a ReadableStream
const streamC = getRepeaterStream('C', 10); // fake helper function that returns a ReadableStream

Next, instantiate a stream collator instance and register the streams with it:

const collator = new StreamCollator();

collator.register(streamA);
collator.register(streamB);
collator.register(streamC);

collator is now a stream which can be accessed with the standard stream API's. For example, you could pass the output to process.stdout:

collator.pipe(process.stdout);

Or a file:

var wstream = fs.createWriteStream('myOutput.txt');

collator.pipe(wstream);

The active stream

At any given time, a single stream is designated as the active stream. The output of the active stream will always be live-streamed. This is particularly useful for long-running streams. When the active stream finishes, a new stream is selected as the active stream and all of its contents up to that point will be emitted. Whenever an active stream finishes, all background streams which have been completed will be emitted.

Helper streams

Two additional stream classes are also exported with this package:

DualTaskStream

A utility string-based stream with two sub-streams, stdout and stderr. These streams can be written to, and will be emitted by this class. Anything written to stderr will be automatically wrapped in red coloring, unless is begins with the text Warning -, in which case it will write the warning to stdout in yellow.

PersistentStream

A special string-based stream with a function readAll() which will return the contents of everything that has been written to the stream as a string, regardless of whether the stream is open or closed.

Improvements

NOTE: Ending the collator stream could be improved with an option that lets you select between the following behaviors:

• Close the collator stream when ANY registered stream has been closed
• Close the collator stream when ALL registered streams have been closed
• Don't automatically close the collator stream