From c647f36590274811cd9a1da5140c5148dc4f0dc7 Mon Sep 17 00:00:00 2001
From: Steven <steven@ceriously.com>
Date: Wed, 16 Oct 2024 17:46:18 -0400
Subject: [PATCH 1/3] chore(docs): add request() example for conditionally
 reading the body

---
 docs/docs/api/Dispatcher.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/docs/api/Dispatcher.md b/docs/docs/api/Dispatcher.md
index 3903eca3d3c..29f66aa8e67 100644
--- a/docs/docs/api/Dispatcher.md
+++ b/docs/docs/api/Dispatcher.md
@@ -527,6 +527,7 @@ try {
   console.log('headers', headers)
   body.setEncoding('utf8')
   body.on('data', console.log)
+  body.on('error', console.error)
   body.on('end', () => {
     console.log('trailers', trailers)
   })
@@ -630,6 +631,29 @@ try {
 }
 ```
 
+#### Example 3 - Conditionally reading the body
+
+Remember to fully consume the body even in the case when it is not read.
+
+```js
+const { body, statusCode } = await client.request({
+  path: '/',
+  method: 'GET'
+})
+
+body.on('error', console.error) // prevent process from crashing on error
+
+if (statusCode === 200) {
+  const buffer = await body.arrayBuffer()
+  return buffer
+}
+
+for await (const _chunk of body) {
+  // force consumption of body to avoid memory leak
+}
+return null
+```
+
 ### `Dispatcher.stream(options, factory[, callback])`
 
 A faster version of `Dispatcher.request`. This method expects the second argument `factory` to return a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream which the response will be written to. This improves performance by avoiding creating an intermediate [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) stream when the user expects to directly pipe the response body to a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream.

From 0cfd421e17e7021d369f2c5777d91a8b504e91ca Mon Sep 17 00:00:00 2001
From: Aras Abbasi <aras.abbasi@googlemail.com>
Date: Thu, 17 Oct 2024 11:26:19 +0200
Subject: [PATCH 2/3] Update docs/docs/api/Dispatcher.md

Co-authored-by: Robert Nagy <ronagy@icloud.com>
---
 docs/docs/api/Dispatcher.md | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/docs/docs/api/Dispatcher.md b/docs/docs/api/Dispatcher.md
index 29f66aa8e67..141240fcf74 100644
--- a/docs/docs/api/Dispatcher.md
+++ b/docs/docs/api/Dispatcher.md
@@ -641,18 +641,13 @@ const { body, statusCode } = await client.request({
   method: 'GET'
 })
 
-body.on('error', console.error) // prevent process from crashing on error
-
 if (statusCode === 200) {
-  const buffer = await body.arrayBuffer()
-  return buffer
+  return await body.arrayBuffer()
 }
 
-for await (const _chunk of body) {
-  // force consumption of body to avoid memory leak
-}
+await body.dump()
+
 return null
-```
 
 ### `Dispatcher.stream(options, factory[, callback])`
 

From 39965c7e83306fe8d6c1cc113263d716b30a037e Mon Sep 17 00:00:00 2001
From: Matteo Collina <matteo.collina@gmail.com>
Date: Fri, 25 Oct 2024 16:11:06 +0200
Subject: [PATCH 3/3] Update docs/docs/api/Dispatcher.md

Co-authored-by: Ethan Arrowood <ethan@arrowood.dev>
---
 docs/docs/api/Dispatcher.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/docs/api/Dispatcher.md b/docs/docs/api/Dispatcher.md
index 141240fcf74..d531efec07c 100644
--- a/docs/docs/api/Dispatcher.md
+++ b/docs/docs/api/Dispatcher.md
@@ -648,6 +648,7 @@ if (statusCode === 200) {
 await body.dump()
 
 return null
+```
 
 ### `Dispatcher.stream(options, factory[, callback])`