@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

The README file is missing