Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add note about empty request body #2098

Merged
merged 2 commits into from Aug 6, 2022
Merged

Add note about empty request body #2098

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69688c4
Add note about empty request body
mifi Aug 3, 2022
90b2a08
Update 3-streams.md
mifi Aug 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 12 additions & 4 deletions documentation/3-streams.md
View file
Open in desktop
Expand Up @@ -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';
Expand All @@ -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.\
Expand All @@ -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)**
Expand Down