From 5a7a4bdea136ba468ba4b4c541770245d779128e Mon Sep 17 00:00:00 2001
From: Mikael Finstad <finstaden@gmail.com>
Date: Sat, 6 Aug 2022 13:10:45 +0200
Subject: [PATCH] Add note about empty request body (#2098)

---
 documentation/3-streams.md | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/documentation/3-streams.md b/documentation/3-streams.md
index ec029dcc4..9070e43da 100644
--- a/documentation/3-streams.md
+++ b/documentation/3-streams.md
@@ -22,6 +22,10 @@ This constructor takes the same arguments as the Got promise.
 **Note:**
 > If the `body`, `json` or `form` option is used, this stream will be read-only.
 
+**Note:**
+> - While `got.post('https://example.com')` resolves, `got.stream.post('https://example.com')` will hang indefinitely until a body is provided.
+> - If there's no body on purpose, remember to `stream.end()` or set the body option to an empty string.
+
 ```js
 import {promisify} from 'node:util';
 import stream from 'node:stream';
@@ -30,17 +34,25 @@ import got from 'got';
 
 const pipeline = promisify(stream.pipeline);
 
+// This example streams the GET response of a URL to a file.
 await pipeline(
 	got.stream('https://sindresorhus.com'),
 	fs.createWriteStream('index.html')
 );
 
 // For POST, PUT, PATCH, and DELETE methods, `got.stream` returns a `stream.Writable`.
+// This example POSTs the contents of a file to a URL.
 await pipeline(
 	fs.createReadStream('index.html'),
 	got.stream.post('https://sindresorhus.com'),
 	new stream.PassThrough()
 );
+
+// In order to POST, PUT, PATCH, or DELETE without a request body, explicitly specify an empty body:
+await pipeline(
+	got.stream.post('https://sindresorhus.com', { body: '' }),
+	new stream.PassThrough()
+)
 ```
 
 Please note that `new stream.PassThrough()` is required in order to catch read errors.\
@@ -50,10 +62,6 @@ In other words, it would only check errors when writing.
 **Tip:**
 > - Avoid `from.pipe(to)` as it doesn't forward errors.
 
-**Note:**
-> - While `got.post('https://example.com')` resolves, `got.stream.post('https://example.com')` will hang indefinitely until a body is provided.
-> - If there's no body on purpose, remember to `stream.end()` or set the body option to an empty string.
-
 ### `stream.options`
 
 **Type: [`Options`](2-options.md)**