Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
doc: Update backpressuring-in-streams.md by introducing pipeline
since v10.0.0

Ref: #1668
  • Loading branch information
MaleDong committed Aug 2, 2018
commit 2fdd43dab9b2f56ee03e68c8e588a252b541f520
64 changes: 64 additions & 0 deletions locale/en/docs/guides/backpressuring-in-streams.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,68 @@ a chunk of data were to fail to be properly received, the `Readable` source or
properly destroy all the streams in a pipeline if one of them fails or closes,
and is a must have in this case!

As for Node 10.0.0 or later version, [`pipeline`][] is introduced to replace for
[`pump`][]. This is a module method to pipe between streams forwarding errors
and properly cleaning up and provide a callback when the pipeline is complete.

You can use it like this following:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to stay consistent with other parts of the document, lets rephrase this:

Here is an example of using pipeline:

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


```javascript
const { pipeline } = require('stream');
const fs = require('fs');
const zlib = require('zlib');

// Use the pipeline API to easily pipe a series of streams
// together and get notified when the pipeline is fully done.
// A pipeline to gzip a potentially huge tar file efficiently:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tar file -> video file?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


pipeline(
fs.createReadStream('The.Matrix.1080p.mkv'),
zlib.createGzip(),
fs.createWriteStream('The.Matrix.1080p.mkv.gz'),
(err) => {
if (err) {
console.error('Pipeline failed', err);
} else {
console.log('Pipeline succeeded');
}
}
);
```
or if you wanna `async` with `await`, you can use it wrapped by [`promisify`][]:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's replace "wanna" since it is not formal english

You can call [promisify][] on pipeline to use it with async/await:


```javascript
const stream = require('stream');
const fs = require('fs');
const zlib = require('zlib');

const pipeline = util.promisify(stream.pipeline);

async function run() {
await pipeline(
fs.createReadStream('The.Matrix.1080p.mkv'),
zlib.createGzip(),
fs.createWriteStream('The.Matrix.1080p.mkv.gz'),
);
}

// Either of the following ways you can call the `run()`:

// Way 1: You can use this to catch exceptions in async mode.
run().catch((err) => console.log('Pipeline failed', err));
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel this is redundant, maybe just having the following code snippet is enough:

async function run() {
  try {
    await pipeline(
       fs.createReadStream('The.Matrix.1080p.mkv'),
       zlib.createGzip(),
       fs.createWriteStream('The.Matrix.1080p.mkv.gz'),
    );
  } catch(err) {
    console.error('Pipeline failed', err);
  }
}

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


// Way 2: You can also use 'try...catch...' to surround the `run()`
// in another `async` function, something like this following:
async function executeRun() {
try {
await run();
console.log('Pipeline succeeded');
} catch(err) {
console.error('Pipeline failed', err);
}
}
```

## Too Much Data, Too Quickly

There are instances where a [`Readable`][] stream might give data to the
Expand Down Expand Up @@ -580,3 +642,5 @@ Node.js.
[`.pipe()`]: https://nodejs.org/docs/latest/api/stream.html#stream_readable_pipe_destination_options
[piped]: https://nodejs.org/docs/latest/api/stream.html#stream_readable_pipe_destination_options
[`pump`]: https://github.com/mafintosh/pump
[`pipeline`]: https://nodejs.org/api/stream.html#stream_stream_pipeline_streams_callback
[`promisify`]: https://nodejs.org/api/util.html#util_util_promisify_original