pump

What is pump?

The pump npm package is a small node module that pipes streams together and destroys all of them if one of them closes. It is particularly useful for preventing memory leaks when piping together streams and handling errors properly in Node.js applications.

What are pump's main functionalities?

Piping streams together with error handling

This code demonstrates how to use pump to pipe data from a readable stream to a writable stream, such as from a file to another file, with error handling. If an error occurs in any of the streams, pump ensures that all streams are properly closed to prevent memory leaks.

const pump = require('pump');
const fs = require('fs');
const source = fs.createReadStream('/path/to/source');
const destination = fs.createWriteStream('/path/to/dest');
pump(source, destination, function(err) {
  console.log('Pipe finished', err);
});

Other packages similar to pump

through2

Through2 is a tiny wrapper around Node.js streams.Transform (Streams2/3) to avoid explicit subclassing noise. It's similar to pump in facilitating stream operations, but it focuses more on transforming stream data rather than piping and managing stream lifecycle.

mississippi

Mississippi is a collection of useful stream utilities for Node.js, including pump. It offers a variety of tools for working with streams beyond what pump provides, such as stream concatenation, parallel stream processing, and more, making it a more comprehensive toolkit for stream operations.

README

pump

pump is a small node module that pipes streams together and destroys all of them if one of them closes.

npm install pump

What problem does it solve?

When using standard source.pipe(dest) source will not be destroyed if dest emits close or an error. You are also not able to provide a callback to tell when then pipe has finished.

pump does these two things for you

Usage

Simply pass the streams you want to pipe together to pump and add an optional callback

var pump = require('pump')
var fs = require('fs')

var source = fs.createReadStream('/dev/random')
var dest = fs.createWriteStream('/dev/null')

pump(source, dest, function(err) {
  console.log('pipe finished', err)
})

setTimeout(function() {
  dest.destroy() // when dest is closed pump will destroy source
}, 1000)

You can use pump to pipe more than two streams together as well

var transform = someTransformStream()

pump(source, transform, anotherTransform, dest, function(err) {
  console.log('pipe finished', err)
})

If source, transform, anotherTransform or dest closes all of them will be destroyed.

Similarly to stream.pipe(), pump() returns the last stream passed in, so you can do:

return pump(s1, s2) // returns s2

Note that pump attaches error handlers to the streams to do internal error handling, so if s2 emits an error in the above scenario, it will not trigger a proccess.on('uncaughtException') if you do not listen for it.

If you want to return a stream that combines both s1 and s2 to a single stream use pumpify instead.

License

MIT

Related

pump is part of the mississippi stream utility collection which includes more useful stream modules similar to this one.

For enterprise

Available as part of the Tidelift Subscription.

The maintainers of pump and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.