doc: add esm example for zlib

PR-URL: #55946 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>

Author: peixotoleonardo

doc/api/zlib.md

@@ -11,7 +11,11 @@ Gzip, Deflate/Inflate, and Brotli.
 
 To access it:
 
-```js
+```mjs
+importosfrom'node:zlib';
+```
+
+```cjs
 constzlib=require('node:zlib');
 ```
 
@@ -21,13 +25,35 @@ Compressing or decompressing a stream (such as a file) can be accomplished by
 piping the source stream through a `zlib``Transform` stream into a destination
 stream:
 
-```js
-const{createGzip } =require('node:zlib');
-const{pipeline } =require('node:stream');
+```mjs
+import{
+createReadStream,
+createWriteStream,
+} from'node:fs';
+importprocessfrom'node:process';
+import{createGzip } from'node:zlib';
+import{pipeline } from'node:stream';
+
+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;
+ }
+});
+```
+
+```cjs
 const{
 createReadStream,
 createWriteStream,
 } =require('node:fs');
+constprocess=require('node:process');
+const{createGzip } =require('node:zlib');
+const{pipeline } =require('node:stream');
 
 constgzip=createGzip();
 constsource=createReadStream('input.txt');
@@ -39,17 +65,43 @@ pipeline(source, gzip, destination, (err) =>{
 process.exitCode=1;
  }
 });
+```
 
-//Or, Promisified
+Or, using the promise `pipeline` API:
 
-const{promisify } =require('node:util');
-constpipe=promisify(pipeline);
+```mjs
+import{
+createReadStream,
+createWriteStream,
+} from'node:fs';
+importprocessfrom'node:process';
+import{createGzip } from'node:zlib';
+import{pipeline } from'node:stream/promises';
+
+asyncfunctiondo_gzip(input, output){
+constgzip=createGzip();
+constsource=createReadStream(input);
+constdestination=createWriteStream(output);
+awaitpipeline(source, gzip, destination);
+}
+
+awaitdo_gzip('input.txt', 'input.txt.gz');
+```
+
+```cjs
+const{
+createReadStream,
+createWriteStream,
+} =require('node:fs');
+constprocess=require('node:process');
+const{createGzip } =require('node:zlib');
+const{pipeline } =require('node:stream/promises');
 
 asyncfunctiondo_gzip(input, output){
 constgzip=createGzip();
 constsource=createReadStream(input);
 constdestination=createWriteStream(output);
-awaitpipe(source, gzip, destination);
+awaitpipeline(source, gzip, destination);
 }
 
 do_gzip('input.txt', 'input.txt.gz')
@@ -61,7 +113,39 @@ do_gzip('input.txt', 'input.txt.gz')
 
 It is also possible to compress or decompress data in a single step:
 
-```js
+```mjs
+importprocessfrom'node:process';
+import{Buffer } from'node:buffer';
+import{deflate, unzip } from'node:zlib';
+
+constinput='.................................';
+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');
+unzip(buffer, (err, buffer) =>{
+if (err){
+console.error('An error occurred:', err);
+process.exitCode=1;
+ }
+console.log(buffer.toString());
+});
+
+// Or, Promisified
+
+import{promisify } from'node:util';
+constdo_unzip=promisify(unzip);
+
+constunzippedBuffer=awaitdo_unzip(buffer);
+console.log(unzippedBuffer.toString());
+```
+
+```cjs
 const{deflate, unzip } =require('node:zlib');
 
 constinput='.................................';
@@ -104,7 +188,19 @@ limitations in some applications.
 Creating and using a large number of zlib objects simultaneously can cause
 significant memory fragmentation.
 
-```js
+```mjs
+importzlibfrom'node:zlib';
+import{Buffer } from'node:buffer';
+
+constpayload=Buffer.from('This is some data');
+
+// WARNING: DO NOT DO THIS!
+for (let i =0; i <30000; ++i){
+zlib.deflate(payload, (err, buffer) =>{});
+}
+```
+
+```cjs
 constzlib=require('node:zlib');
 
 constpayload=Buffer.from('This is some data');
@@ -138,7 +234,47 @@ Using `zlib` encoding can be expensive, and the results ought to be cached.
 See [Memory usage tuning][] for more information on the speed/memory/compression
 tradeoffs involved in `zlib` usage.
 
-```js
+```mjs
+// Client request example
+importfsfrom'node:fs';
+importzlibfrom'node:zlib';
+importhttpfrom'node:http';
+importprocessfrom'node:process';
+import{pipeline } from'node: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':
+pipeline(response, zlib.createBrotliDecompress(), output, onError);
+break;
+// Or, just use zlib.createUnzip() to handle both of the following cases:
+case'gzip':
+pipeline(response, zlib.createGunzip(), output, onError);
+break;
+case'deflate':
+pipeline(response, zlib.createInflate(), output, onError);
+break;
+default:
+pipeline(response, output, onError);
+break;
+ }
+});
+```
+
+```cjs
 // Client request example
 constzlib=require('node:zlib');
 consthttp=require('node:http');
@@ -177,7 +313,52 @@ request.on('response', (response) =>{
 });
 ```
 
-```js
+```mjs
+// server example
+// Running a gzip operation on every request is quite expensive.
+// It would be much more efficient to cache the compressed buffer.
+importzlibfrom'node:zlib';
+importhttpfrom'node:http';
+importfsfrom'node:fs';
+import{pipeline } from'node:stream';
+
+http.createServer((request, response) =>{
+constraw=fs.createReadStream('index.html');
+// Store both a compressed and an uncompressed version of the resource.
+response.setHeader('Vary', 'Accept-Encoding');
+constacceptEncoding=request.headers['accept-encoding'] ||'';
+
+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' });
+pipeline(raw, zlib.createDeflate(), response, onError);
+ } elseif (/\bgzip\b/.test(acceptEncoding)){
+response.writeHead(200,{'Content-Encoding':'gzip' });
+pipeline(raw, zlib.createGzip(), response, onError);
+ } elseif (/\bbr\b/.test(acceptEncoding)){
+response.writeHead(200,{'Content-Encoding':'br' });
+pipeline(raw, zlib.createBrotliCompress(), response, onError);
+ } else{
+response.writeHead(200,{});
+pipeline(raw, response, onError);
+ }
+}).listen(1337);
+```
+
+```cjs
 // server example
 // Running a gzip operation on every request is quite expensive.
 // It would be much more efficient to cache the compressed buffer.
@@ -315,7 +496,43 @@ quality, but can be useful when data needs to be available as soon as possible.
 In the following example, `flush()` is used to write a compressed partial
 HTTP response to the client:
 
-```js
+```mjs
+importzlibfrom'node:zlib';
+importhttpfrom'node:http';
+import{pipeline } from'node: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();
+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);
+ }
+ });
+
+ 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.
+// Calling .flush() will make the data available as soon as the client
+// is ready to receive it.
+output.flush();
+ });
+ }, 1000);
+}).listen(1337);
+```
+
+```cjs
 constzlib=require('node:zlib');
 consthttp=require('node:http');
 const{pipeline } =require('node:stream');