Skip to content

Commit 9fc4842

Browse files
doc: document differences between Node.js fetch and WHATWG standard
1 parent 7d37fc9 commit 9fc4842

File tree

1 file changed

+9
-13
lines changed

1 file changed

+9
-13
lines changed

doc/api/globals.md

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -588,27 +588,21 @@ Node.js implements the [WHATWG Fetch Standard][] with intentional differences to
588588
##### Async iterable request bodies
589589

590590
Node.js supports async iterables as request bodies—a behavior not included in the Fetch Standard.
591-
```js
591+
```mjs
592592
const data = {
593593
async *[Symbol.asyncIterator]() {
594594
yield 'hello';
595595
yield 'world';
596-
}
596+
},
597597
};
598-
599-
await fetch('https://example.com', {
600-
method: 'POST',
601-
body: data,
602-
duplex: 'half'
603-
});
604598
```
605599

606600
When using an async iterable or a `ReadableStream` as the request body, the `duplex` option must be set to `'half'`.
607601

608602
##### FormData with stream-backed Blob objects
609603

610604
`FormData` entries may include stream-backed `Blob` objects created from the filesystem, enabling efficient uploads of large files without buffering them in memory.
611-
```js
605+
```mjs
612606
import { openAsBlob } from 'node:fs';
613607

614608
const file = await openAsBlob('./large-file.csv');
@@ -623,7 +617,7 @@ await fetch('https://example.com', { method: 'POST', body: form });
623617
##### Async iterable response bodies
624618

625619
The `Response` constructor accepts async iterables, allowing flexible construction of streaming responses in server environments.
626-
```js
620+
```mjs
627621
const res = new Response(asyncIterable);
628622
```
629623

@@ -646,15 +640,15 @@ When using `redirect: 'manual'`, Node.js returns the actual redirect response ra
646640
In Node.js, unconsumed response bodies may delay the release of underlying network resources. This can reduce connection reuse or cause stalls under load.
647641

648642
Always consume or cancel the response body:
649-
```js
643+
```mjs
650644
const res = await fetch(url);
651645
for await (const chunk of res.body) {
652646
// process chunk
653647
}
654648
```
655649

656650
For header-only requests, prefer `HEAD` to avoid creating a body:
657-
```js
651+
```mjs
658652
const headers = (await fetch(url, { method: 'HEAD' })).headers;
659653
```
660654

@@ -667,7 +661,9 @@ The `Expect` request header is not supported. Request bodies are sent immediatel
667661
#### Implementation Notes
668662

669663
Node.js uses the [undici][] HTTP client internally to implement `fetch()`. The bundled version can be inspected with:
670-
```js
664+
```mjs
665+
import process from 'node:process';
666+
671667
console.log(process.versions.undici);
672668
```
673669

0 commit comments

Comments
 (0)