Repository files navigation

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

constassert=require('assert');constfs=require('fs');conststreamCompare=require('stream-compare');conststream1=fs.createReadStream(file);conststream2=fs.createReadStream(file);streamCompare(stream1,stream2,assert.deepStrictEqual).catch((err)=>{console.log(err);// AssertionError if streams differ});

This package is similar to thestream-equal package with severaladditional features:

• Support for caller-defined comparisons, which can return errors or valuesnot limited to equality.
• Support for both incremental and one-shot comparisons.
• Support for caller-defined data reduction to avoid storing the entire streamhistory in memory before comparison.
• Makes no assumptions about the type of values read beyond whether theyshould be treated as objects (objectMode) or a stream of Buffers orstrings.
• 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-reductionfunction from a standard data comparison function (e.g.assert.deepEqual).

This package can be installedusingnpm, either globally or locally, by running:

npm install stream-compare

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

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

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

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

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

constoptions={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});

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

const{ PassThrough}=require('stream');conststream1=newPassThrough();conststream2=newPassThrough();constcomparison=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 thetestspecifications.

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

Contributions are appreciated. Contributors agree to abide by theContributorCovenant Code ofConduct.If this is your first time contributing to a Free and Open Source Softwareproject, consider readingHow to Contribute to OpenSourcein the Open Source Guides.

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

This project is available under the terms of theMIT License.See thesummary at TLDRLegal.

Thetemplate upon whichthis project is based is available under the terms ofCC0 1.0 Universal.