Skip to content

Latest commit

 

History

History
181 lines (140 loc) · 6.5 KB

README.md

File metadata and controls

181 lines (140 loc) · 6.5 KB
Raw

stream-compare

Build Status Coverage Dependency Status Supported Node Version Version on NPM

Compare the output of two Readable streams using a caller-provided comparison/assertion function.

Introductory Example

const assert = require('assert');
const fs = require('fs');
const streamCompare = require('stream-compare');

const stream1 = fs.createReadStream(file);
const stream2 = fs.createReadStream(file);
streamCompare(stream1, stream2, assert.deepStrictEqual).catch((err) => {
  console.log(err); // AssertionError if streams differ
});

Features

This package is similar to the stream-equal package with several additional features:

  • Support for caller-defined comparisons, which can return errors or values not limited to equality.
  • Support for both incremental and one-shot comparisons.
  • Support for caller-defined data reduction to avoid storing the entire stream history in memory before comparison.
  • Makes no assumptions about the type of values read beyond whether they should be treated as objects (objectMode) or a stream of Buffers or strings.
  • Does not do any coercion of the values read.
  • Support for comparing (caller-configurable) events emitted by the streams.
  • Support reading in flowing or non-flowing mode.
  • Support for optionally aborting comparison on stream errors.
  • Support for catching multiple end/error events (within one tick by default, or an optional configurable delay).
  • Utility function for creating an incremental comparison and data-reduction function from a standard data comparison function (e.g. assert.deepEqual).

Installation

This package can be installed using npm, either globally or locally, by running:

npm install stream-compare

Recipes

Compare Incrementally

In order to avoid unnecessary memory use for streams with large amounts of data and avoid unnecessary delays for streams which produce data slowly, the output can be compared incrementally and inconclusive output can be removed. This is done by the incremental function. To make this easier, the utility function makeIncremental creates such a function from a data comparison function and/or an events comparison function:

const options = {
  incremental: streamCompare.makeIncremental(
    assert.deepStrictEqual,     // Compares data
    assert.deepStrictEqual,     // Compares events
  ),
};
streamCompare(stream1, stream2, options).catch((err) => {
  console.log(err); // AssertionError if stream data values differ
});

Compare Data Values Separately

Sometimes it may be desirable to compare the values returned by .read() or 'data' events separately, rather than concatenated together. This can be done by setting objectMode: true (even if the values aren't Objects):

const options = {
  compare: assert.deepStrictEqual,
  objectMode: true,
};
streamCompare(stream1, stream2, options).catch((err) => {
  console.log(err); // AssertionError if stream data values differ
});

Compare Data and Event Interleaving

In order to compare the ordering of 'data' events with other events, add 'data' to the events option and set readPolicy to 'flowing' or 'none'. Any 'data' events and their arguments will appear with any other matching events in the events property of the state object.

const options = {
  compare: assert.deepStrictEqual,
  events: ['close', 'data', 'end', 'error'],
  readPolicy: 'none',
};
streamCompare(stream1, stream2, options).catch((err) => {
  console.log(err); // AssertionError if stream events (including 'data') differ
});

Control comparison checkpoints

The returned Promise includes additional methods for controlling the comparison. A non-incremental compare can be run before both streams end using .checkpoint(). Additionally, the comparison can be concluded before both streams end using .end(). The full details are available in the API Documentation.

const { PassThrough } = require('stream');

const stream1 = new PassThrough();
const stream2 = new PassThrough();
const comparison = streamCompare(stream1, stream2, assert.deepStrictEqual);
comparison.then(
  () => console.log('streams are equal'),
  (err) => console.log(`streams differ: ${err}`),
);
stream1.write('Hello');
stream2.write('Hello');
setImmediate(() => {
  comparison.checkpoint();

  stream1.write(' world!');
  stream2.write(' world!');

  setImmediate(() => comparison.end());
});

More examples can be found in the test specifications.

API Docs

For the details of using this module as a library, see the API Documentation.

Contributing

Contributions are appreciated. Contributors agree to abide by the Contributor Covenant Code of Conduct. If this is your first time contributing to a Free and Open Source Software project, consider reading How to Contribute to Open Source in the Open Source Guides.

If the desired change is large, complex, backwards-incompatible, can have significantly differing implementations, or may not be in scope for this project, opening an issue before writing the code can avoid frustration and save a lot of time and effort.

License

This project is available under the terms of the MIT License. See the summary at TLDRLegal.

The template upon which this project is based is available under the terms of CC0 1.0 Universal.