Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/esamattis/node-promisepipe
Safely pipe node.js streams while capturing all errors to a single promise
https://github.com/esamattis/node-promisepipe
node promise stream
Last synced: about 1 month ago
JSON representation
Safely pipe node.js streams while capturing all errors to a single promise
- Host: GitHub
- URL: https://github.com/esamattis/node-promisepipe
- Owner: esamattis
- License: mit
- Created: 2013-10-15T18:15:37.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2018-09-28T23:59:22.000Z (about 6 years ago)
- Last Synced: 2024-10-04T14:38:53.819Z (about 1 month ago)
- Topics: node, promise, stream
- Language: JavaScript
- Homepage: https://npmjs.org/package/promisepipe
- Size: 35.2 KB
- Stars: 80
- Watchers: 5
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# promisePipe
Safely pipe node.js streams while capturing all errors to a single promise.
## Install
npm install promisepipe
## API
```
promisePipe(, [transform streams...], )
```
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())`](https://www.npmjs.com/package/dev-null) to the end, otherwise the promise will never resolve ([#16](https://github.com/epeli/node-promisepipe/issues/16)).
Starting with v3, all streams are destroyed if there's an error to prevent memory leaks.
## Example
```javascript
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
```javascript
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:
```javascript
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:
```javascript
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.