stream-exhaust

What is stream-exhaust?

The stream-exhaust npm package is used to ensure that a stream is fully consumed. This can be useful in scenarios where you need to make sure that all data from a stream is read, even if you don't need to process the data itself.

What are stream-exhaust's main functionalities?

Exhausting a Readable Stream

This feature ensures that a readable stream is fully consumed. The example demonstrates creating a readable stream from an array and using stream-exhaust to ensure all data is read.

const exhaust = require('stream-exhaust');
const { Readable } = require('stream');

const readable = Readable.from(['data1', 'data2', 'data3']);

exhaust(readable).on('end', () => {
  console.log('Stream fully consumed');
});

Exhausting a Writable Stream

This feature ensures that a writable stream is fully consumed. The example demonstrates creating a writable stream and using stream-exhaust to ensure all data is written.

const exhaust = require('stream-exhaust');
const { Writable } = require('stream');

const writable = new Writable({
  write(chunk, encoding, callback) {
    console.log(chunk.toString());
    callback();
  }
});

exhaust(writable).on('finish', () => {
  console.log('Writable stream fully consumed');
});

writable.write('data1');
writable.write('data2');
writable.end('data3');

Exhausting a Duplex Stream

This feature ensures that a duplex stream is fully consumed. The example demonstrates creating a duplex stream and using stream-exhaust to ensure all data is read and written.

const exhaust = require('stream-exhaust');
const { Duplex } = require('stream');

const duplex = new Duplex({
  read(size) {
    this.push('data');
    this.push(null);
  },
  write(chunk, encoding, callback) {
    console.log(chunk.toString());
    callback();
  }
});

exhaust(duplex).on('end', () => {
  console.log('Duplex stream fully consumed');
});

Other packages similar to stream-exhaust

stream-combiner2

The stream-combiner2 package is used to combine multiple streams into one. While it doesn't specifically focus on exhausting streams, it can be used to ensure that all streams in a pipeline are fully consumed. It is more focused on stream combination rather than exhaustion.

pump

The pump package is used to pipe streams together and ensure that all streams are properly cleaned up. It can be used to ensure that streams are fully consumed, but its primary focus is on handling stream errors and cleanup.

end-of-stream

The end-of-stream package is used to detect when a stream has finished or encountered an error. It can be used to ensure that a stream is fully consumed, but it is more focused on detecting the end of a stream rather than actively consuming it.

README

stream-exhaust

Ensure that the provided stream is flowing data, even if the stream hasn't been piped to another stream.

``javascript var exhaustively = require('stream-exhaust');

exhaustively(fs.createReadStream(__filename)) .on('close', () => { console.log('all done, despite being streams{1+N}!') });

``

Prior Art

This is based on stream-consume by aroneous. It is a separate package because it has different semantics:

1. It does not call .resume() on streams2+ streams. streams2 streams monkeypatch .pipe when entering flowing mode; avoiding resume() avoids that fate.
2. It does not examine ._readableState; instead it checks for the presence of ._read.

API

exhaust(Stream s) -> Stream s

Takes a stream, s, and returns it. Ensures that the stream is flowing, either by calling .resume() if the stream is a streams1 stream, or by piping it to a "black hole" stream that continually asks for more data.

License

MIT