From 2fdd43dab9b2f56ee03e68c8e588a252b541f520 Mon Sep 17 00:00:00 2001 From: MaleDong Date: Thu, 2 Aug 2018 12:15:48 +0800 Subject: [PATCH 1/3] doc: Update `backpressuring-in-streams.md` by introducing `pipeline` since v10.0.0 Ref: https://github.com/nodejs/nodejs.org/issues/1668 --- .../docs/guides/backpressuring-in-streams.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/locale/en/docs/guides/backpressuring-in-streams.md b/locale/en/docs/guides/backpressuring-in-streams.md index f994e76422d5f..6ee78d7e6a836 100644 --- a/locale/en/docs/guides/backpressuring-in-streams.md +++ b/locale/en/docs/guides/backpressuring-in-streams.md @@ -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: + +```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: + +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`][]: + +```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)); + +// 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 @@ -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 From 4713ebc564df8fe24ced7a7c11d3ebfc5962c8a7 Mon Sep 17 00:00:00 2001 From: MaleDong Date: Fri, 3 Aug 2018 08:22:25 +0800 Subject: [PATCH 2/3] Update doc file according to suggestions --- .../docs/guides/backpressuring-in-streams.md | 44 +++++++------------ 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/locale/en/docs/guides/backpressuring-in-streams.md b/locale/en/docs/guides/backpressuring-in-streams.md index 6ee78d7e6a836..995d4e8ace745 100644 --- a/locale/en/docs/guides/backpressuring-in-streams.md +++ b/locale/en/docs/guides/backpressuring-in-streams.md @@ -88,11 +88,12 @@ 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. +[`pump`][] is only necessary for Nodejs 8.x or earlier, as for Node 10.x +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: +Here is an example of using pipeline: ```javascript const { pipeline } = require('stream'); @@ -101,7 +102,7 @@ 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: +// A pipeline to gzip a potentially huge video file efficiently: pipeline( fs.createReadStream('The.Matrix.1080p.mkv'), @@ -116,7 +117,7 @@ pipeline( } ); ``` -or if you wanna `async` with `await`, you can use it wrapped by [`promisify`][]: +You can call [`promisify`][] on pipeline to use it with `async` / `await`: ```javascript const stream = require('stream'); @@ -126,27 +127,16 @@ 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)); - -// 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); - } + try { + await pipeline( + fs.createReadStream('The.Matrix.1080p.mkv'), + zlib.createGzip(), + fs.createWriteStream('The.Matrix.1080p.mkv.gz'), + ); + console.log('Pipeline succeeded'); + } catch (err) { + console.error('Pipeline failed', err); + } } ``` From 6c97e7ecc882e89a83081a6e210a4bce3f5894d7 Mon Sep 17 00:00:00 2001 From: MaleDong Date: Fri, 3 Aug 2018 08:46:22 +0800 Subject: [PATCH 3/3] Add also --- locale/en/docs/guides/backpressuring-in-streams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/locale/en/docs/guides/backpressuring-in-streams.md b/locale/en/docs/guides/backpressuring-in-streams.md index 995d4e8ace745..c02406cb87120 100644 --- a/locale/en/docs/guides/backpressuring-in-streams.md +++ b/locale/en/docs/guides/backpressuring-in-streams.md @@ -117,7 +117,7 @@ pipeline( } ); ``` -You can call [`promisify`][] on pipeline to use it with `async` / `await`: +You can also call [`promisify`][] on pipeline to use it with `async` / `await`: ```javascript const stream = require('stream');