doc: update zlib doc

Just some general improvements to zlib docs and examples
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: #31665
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

Author: jasnell

doc/api/zlib.md

@@ -4,60 +4,121 @@
 
 > Stability: 2 - Stable
 
-The `zlib` module provides compression functionality implemented using Gzip and
-Deflate/Inflate, as well as Brotli. It can be accessed using:
+The `zlib` module provides compression functionality implemented using Gzip,
+Deflate/Inflate, and Brotli.
+
+To access it:
 
 ```js
 constzlib=require('zlib');
 ```
 
+Compression and decompression are built around the Node.js [Streams API][].
+
 Compressing or decompressing a stream (such as a file) can be accomplished by
-piping the source stream data through a `zlib` stream into a destination stream:
+piping the source stream through a `zlib``Transform` stream into a destination
+stream:
 
 ```js
-constgzip=zlib.createGzip();
-constfs=require('fs');
-constinp=fs.createReadStream('input.txt');
-constout=fs.createWriteStream('input.txt.gz');
-
-inp.pipe(gzip)
- .on('error', () => {
-// handle error
- })
- .pipe(out)
- .on('error', () => {
-// handle error
+const { createGzip } =require('zlib');
+const { pipeline } =require('stream');
+const {
+createReadStream,
+createWriteStream
+} =require('fs');
+
+constgzip=createGzip();
+constsource=createReadStream('input.txt');
+constdestination=createWriteStream('input.txt.gz');
+
+pipeline(source, gzip, destination, (err) => {
+if (err) {
+console.error('An error occurred:', err);
+process.exitCode=1;
+ }
+});
+
+// Or, Promisified
+
+const { promisify } =require('util');
+constpipe=promisify(pipeline);
+
+asyncfunctiondo_gzip(input, output) {
+constgzip=createGzip();
+constsource=createReadStream(input);
+constdestination=createWriteStream(output);
+awaitpipe(source, gzip, destination);
+}
+
+do_gzip('input.txt', 'input.txt.gz')
+ .catch((err) => {
+console.error('An error occurred:', err);
+process.exitCode=1;
  });
 ```
 
 It is also possible to compress or decompress data in a single step:
 
 ```js
+const { deflate, unzip } =require('zlib');
+
 constinput='.................................';
-zlib.deflate(input, (err, buffer) => {
-if (!err) {
-console.log(buffer.toString('base64'));
- } else {
-// handle error
+deflate(input, (err, buffer) => {
+if (err) {
+console.error('An error occurred:', err);
+process.exitCode=1;
  }
+console.log(buffer.toString('base64'));
 });
 
 constbuffer=Buffer.from('eJzT0yMAAGTvBe8=', 'base64');
-zlib.unzip(buffer, (err, buffer) => {
-if (!err) {
-console.log(buffer.toString());
- } else {
-// handle error
+unzip(buffer, (err, buffer) => {
+if (err) {
+console.error('An error occurred:', err);
+process.exitCode=1;
  }
+console.log(buffer.toString());
 });
+
+// Or, Promisified
+
+const { promisify } =require('util');
+constdo_unzip=promisify(unzip);
+
+do_unzip(buffer)
+ .then((buf) =>console.log(buf.toString()))
+ .catch((err) => {
+console.error('An error occurred:', err);
+process.exitCode=1;
+ });
 ```
 
-## Threadpool Usage
+## Threadpool Usage and Performance Considerations
+
+All `zlib` APIs, except those that are explicitly synchronous, use the Node.js
+internal threadpool. This can lead to surprising effects and performance
+limitations in some applications.
 
-All zlib APIs, except those that are explicitly synchronous, use libuv's
-threadpool. This can lead to surprising effects in some applications, such as
-subpar performance (which can be mitigated by adjusting the [pool size][])
-and/or unrecoverable and catastrophic memory fragmentation.
+Creating and using a large number of zlib objects simultaneously can cause
+significant memory fragmentation.
+
+```js
+constzlib=require('zlib');
+
+constpayload=Buffer.from('This is some data');
+
+// WARNING: DO NOT DO THIS!
+for (let i =0; i <30000; ++i) {
+zlib.deflate(payload, (err, buffer) => {});
+}
+```
+
+In the preceding example, 30,000 deflate instances are created concurrently.
+Because of how some operating systems handle memory allocation and
+deallocation, this may lead to to significant memory fragmentation.
+
+It is strongly recommended that the results of compression
+operations be cached to avoid duplication of effort.
 
 ## Compressing HTTP requests and responses
 
@@ -80,26 +141,35 @@ tradeoffs involved in `zlib` usage.
 constzlib=require('zlib');
 consthttp=require('http');
 constfs=require('fs');
+const { pipeline } =require('stream');
+
 constrequest=http.get({ host:'example.com',
  path:'/',
  port:80,
  headers: { 'Accept-Encoding':'br,gzip,deflate' } });
 request.on('response', (response) => {
 constoutput=fs.createWriteStream('example.com_index.html');
 
+constonError= (err) => {
+if (err) {
+console.error('An error occurred:', err);
+process.exitCode=1;
+ }
+ };
+
 switch (response.headers['content-encoding']) {
 case'br':
-response.pipe(zlib.createBrotliDecompress()).pipe(output);
+pipeline(response, zlib.createBrotliDecompress(), output, onError);
 break;
 // Or, just use zlib.createUnzip() to handle both of the following cases:
 case'gzip':
-response.pipe(zlib.createGunzip()).pipe(output);
+pipeline(response, zlib.createGunzip(), output, onError);
 break;
 case'deflate':
-response.pipe(zlib.createInflate()).pipe(output);
+pipeline(response, zlib.createInflate(), outout, onError);
 break;
 default:
-response.pipe(output);
+pipeline(response, output, onError);
 break;
  }
 });
@@ -112,6 +182,8 @@ request.on('response', (response) => {
 constzlib=require('zlib');
 consthttp=require('http');
 constfs=require('fs');
+const { pipeline } =require('stream');
+
 http.createServer((request, response) => {
 constraw=fs.createReadStream('index.html');
 // Store both a compressed and an uncompressed version of the resource.
@@ -121,20 +193,32 @@ http.createServer((request, response) => {
  acceptEncoding ='';
  }
 
+constonError= (err) => {
+if (err) {
+// If an error occurs, there's not much we can do because
+// the server has already sent the 200 response code and
+// some amount of data has already been sent to the client.
+// The best we can do is terminate the response immediately
+// and log the error.
+response.end();
+console.error('An error occurred:', err);
+ }
+ };
+
 // Note: This is not a conformant accept-encoding parser.
 // See https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
 if (/\bdeflate\b/.test(acceptEncoding)) {
 response.writeHead(200, { 'Content-Encoding':'deflate' });
-raw.pipe(zlib.createDeflate()).pipe(response);
+pipeline(raw, zlib.createDeflate(), response, onError);
  } elseif (/\bgzip\b/.test(acceptEncoding)) {
 response.writeHead(200, { 'Content-Encoding':'gzip' });
-raw.pipe(zlib.createGzip()).pipe(response);
+pipeline(raw, zlib.createGzip(), response, onError);
  } elseif (/\bbr\b/.test(acceptEncoding)) {
 response.writeHead(200, { 'Content-Encoding':'br' });
-raw.pipe(zlib.createBrotliCompress()).pipe(response);
+pipeline(raw, zlib.createBrotliCompress(), response, onError);
  } else {
 response.writeHead(200, {});
-raw.pipe(response);
+pipeline(raw, response, onError);
  }
 }).listen(1337);
 ```
@@ -154,11 +238,11 @@ zlib.unzip(
 // For Brotli, the equivalent is zlib.constants.BROTLI_OPERATION_FLUSH.
  { finishFlush:zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
-if (!err) {
-console.log(buffer.toString());
- } else {
-// handle error
+if (err) {
+console.error('An error occurred:', err);
+process.exitCode=1;
  }
+console.log(buffer.toString());
  });
 ```
 
@@ -234,14 +318,28 @@ HTTP response to the client:
 ```js
 constzlib=require('zlib');
 consthttp=require('http');
+const { pipeline } =require('stream');
 
 http.createServer((request, response) => {
 // For the sake of simplicity, the Accept-Encoding checks are omitted.
 response.writeHead(200, { 'content-encoding':'gzip' });
 constoutput=zlib.createGzip();
-output.pipe(response);
+let i;
+
+pipeline(output, response, (err) => {
+if (err) {
+// If an error occurs, there's not much we can do because
+// the server has already sent the 200 response code and
+// some amount of data has already been sent to the client.
+// The best we can do is terminate the response immediately
+// and log the error.
+clearInterval(i);
+response.end();
+console.error('An error occurred:', err);
+ }
+ });
 
-setInterval(() => {
+i =setInterval(() => {
 output.write(`The current time is ${Date()}\n`, () => {
 // The data has been passed to zlib, but the compression algorithm may
 // have decided to buffer the data for more efficient compression.
@@ -399,7 +497,7 @@ changes:
 
 <!--type=misc-->
 
-Each zlib-based class takes an `options` object. All options are optional.
+Each zlib-based class takes an `options` object. No options are required.
 
 Some options are only relevant when compressing and are
 ignored by the decompression classes.
@@ -1058,6 +1156,6 @@ Decompress a chunk of data with [`Unzip`][].
 [Brotli parameters]: #zlib_brotli_constants
 [Memory Usage Tuning]: #zlib_memory_usage_tuning
 [RFC 7932]: https://www.rfc-editor.org/rfc/rfc7932.txt
-[pool size]: cli.html#cli_uv_threadpool_size_size
+[Streams API]: stream.md
 [zlib documentation]: https://zlib.net/manual.html#Constants
 [zlib.createGzip example]: #zlib_zlib