promisepipe

What is promisepipe?

The 'promisepipe' npm package is designed to facilitate the piping of streams with the added benefit of returning a promise. This can be particularly useful for handling asynchronous stream operations in a more manageable and readable way.

What are promisepipe's main functionalities?

Basic Stream Piping

This feature allows you to pipe a readable stream to a writable stream and returns a promise that resolves when the piping is complete. In this example, a file is read from 'source.txt' and written to 'destination.txt'.

const fs = require('fs');
const promisepipe = require('promisepipe');

async function pipeStreams() {
  const readStream = fs.createReadStream('source.txt');
  const writeStream = fs.createWriteStream('destination.txt');
  await promisepipe(readStream, writeStream);
  console.log('Piping complete');
}

pipeStreams();

Handling Multiple Streams

This feature allows you to pipe multiple streams in sequence. In this example, a file is read from 'source.txt', compressed using gzip, and then written to 'destination.txt.gz'.

const fs = require('fs');
const zlib = require('zlib');
const promisepipe = require('promisepipe');

async function pipeMultipleStreams() {
  const readStream = fs.createReadStream('source.txt');
  const gzipStream = zlib.createGzip();
  const writeStream = fs.createWriteStream('destination.txt.gz');
  await promisepipe(readStream, gzipStream, writeStream);
  console.log('Piping and compression complete');
}

pipeMultipleStreams();

Other packages similar to promisepipe

pump

The 'pump' package is used to pipe streams together and handle errors properly. It is similar to 'promisepipe' but does not return a promise. Instead, it uses a callback to signal completion or errors.

README

promisePipe

Safely pipe node.js streams while capturing all errors to a single promise.

Install

npm install promisepipe

API

promisePipe(<readable stream>, [transform streams...], <writeable stream>)

It returns a native promise. On success the resolved value will be an array of the streams passed in. When rejected an error object is created with following keys:

• source: The stream that caused the error
• originalError: Original error from the stream
• message: The error message from original error

Note: the last stream in the chain needs to be a writable stream, not a duplex/transform stream. If you use a 3rd party library which returns deplux streams instead of writable streams, you'll need to add something like .pipe(devnull()) to the end, otherwise the promise will never resolve (#16).

Starting with v3, all streams are destroyed if there's an error to prevent memory leaks.

Example

var promisePipe = require("promisepipe");

promisePipe(
    fs.createReadStream(INPUT_FILE),
    new UpcaseTransform(),
    fs.createWriteStream(OUTPUT_FILE),
).then(function(streams){
    console.log("Done writing to the output file stream!");
}, function(err) {
    console.log("This stream failed:", err.source);
    console.log("Original error was:", err.originalError);
});

or with async-wait

var promisePipe = require("promisepipe");

(async () => {
  try {
    await promisePipe(
      fs.createReadStream(INPUT_FILE),
      new UpcaseTransform(),
      fs.createWriteStream(OUTPUT_FILE)
    );
    console.log("Done writing to the output file stream!");
  } catch (err) {
    console.log("This stream failed:", err.source);
    console.log("Original error was:", err.originalError);
  }
})();

Why?

Stream piping in node.js is cool, but error handling is not because streams do not bubble errors to the target streams.

For example if the previous example is written like this:

fs.createReadStream(INPUT_FILE)
  .pipe(new UpcaseTransform())
  .pipe(fs.createReadStream(OUTPUT_FILE))

It might crash your program at any time. You must handle the errors from each stream manually like this:

fs.createReadStream(INPUT_FILE).on("error", function(err) {
    // handle the error
}).pipe(new UpcaseTransform()).on("error", function(err) {
    // handle the error
}).pipe(fs.createReadStream(OUTPUT_FILE)).on("error", function(err) {
    // handle the error
})

Handling errors this way can be very cumbersome. promisepipe simplifies error handling by sending the first error occurance into a promise.