doc: improved fetch docs

[lifeisfoo]

Updated fetch documentation:

• added a fetch example
• explained its connection with undici
• explained how to get the current undici version
• explained how to use a custom dispatcher
• added link to related HTTP classes

Refs:

• https://undici.nodejs.org
• Is it possible to create a custom `fetch` with the `dispatcher` option preset undici#2167
• https://nodejs.org/en/blog/release/v18.0.0#fetch-experimental

[panva]

cc @nodejs/undici

[KhafraDev]

I am personally a -1: the basic example has bad practices (not consuming the body if (!res.ok)); Dispatcher/Agent aren't exposed in node (so why document them here?); FormData, Response, Request, and Headers are already documented.

[lifeisfoo]

@KhafraDev I took the basic example from Node.js 18 release notes so I thought it was ok, but it can be improved.

Dispatcher/Agent aren't exposed in node (so why document them here?);

As commented here and answered here:

You can consider it (globalThis[Symbol.for('undici.globalDispatcher.1')] ndr) part of the public API, we should probably document it.

Moreover, there is also 3K views question on Stackoverflow.

FormData, Response, Request, and Headers are already documented

Yes, but these classes are relevant to fetch.

[gdorsi]

Thanks @lifeisfoo for the PR and @KhafraDev for the review!

Jumping here because the discussion in this PR piqued my curiosity.

the basic example has bad practices (not consuming the body if (!res.ok));

Curious, why it's a bad practice and what would be the good practice?

[gdorsi]

Dispatcher/Agent aren't exposed in node (so why document them here?);

Setting up a custom Agent is quite a common use case and we can't just redirect to the Undici documentation, because as you said, Dispatcher/Agent aren't exposed in node.

What would be your suggestion? Shall we suggest to use undici direclty when setting up a custom Agent is needed?

[lifeisfoo]

The expanded fetch documentation could also contain information about the upcoming HTTP_PROXY env var support and the support for SOCKS proxies through undici.

Incidentally, I created this PR after struggling to work with a SOCKS proxy in Node.js, where the dispatcher override function is the key to using it.

`globalThis[Symbol.for('undici.globalDispatcher.1')] = socksDispatcher;`

From my point of view, documentation should aim to save developers hours by giving them all the information they need without having to look at the source code or perform searches on other websites.

[mcollina]

lgtm

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/57296
✔  Done loading data for nodejs/node/pull/57296
----------------------------------- PR info ------------------------------------
Title      doc: improved `fetch` docs (#57296)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     lifeisfoo:patch-1 -> nodejs:main
Labels     doc
Commits    4
 - doc: improved fetch docs
 - doc: fixed fetch md formatting
 - doc: fixed linting
 - doc: setGlobalDispatcher() instead of Symbol
Committers 1
 - Alessandro Miliucci <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/57296
Refs: https://undici.nodejs.org
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Marco Ippolito <[email protected]>
Reviewed-By: James M Snell <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/57296
Refs: https://undici.nodejs.org
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Marco Ippolito <[email protected]>
Reviewed-By: James M Snell <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Mon, 03 Mar 2025 15:41:34 GMT
   ✔  Approvals: 3
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/57296#pullrequestreview-2705675251
   ✔  - Marco Ippolito (@marco-ippolito) (TSC): https://github.com/nodejs/node/pull/57296#pullrequestreview-2705707402
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/57296#pullrequestreview-2706323620
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 57296
From https://github.com/nodejs/node
 * branch                  refs/pull/57296/merge -> FETCH_HEAD
✔  Fetched commits as 78af51cfe66b..3f2d419941b5
--------------------------------------------------------------------------------
Auto-merging doc/api/globals.md
[main f18b667fa3] doc: improved fetch docs
 Author: Alessandro Miliucci <[email protected]>
 Date: Mon Mar 3 16:32:53 2025 +0100
 1 file changed, 33 insertions(+)
Auto-merging doc/api/globals.md
[main e343f9b857] doc: fixed fetch md formatting
 Author: Alessandro Miliucci <[email protected]>
 Date: Mon Mar 3 21:28:00 2025 +0100
 1 file changed, 5 insertions(+), 4 deletions(-)
Auto-merging doc/api/globals.md
[main 57f084a690] doc: fixed linting
 Author: Alessandro Miliucci <[email protected]>
 Date: Wed Mar 12 18:36:23 2025 +0100
 1 file changed, 5 insertions(+), 2 deletions(-)
Auto-merging doc/api/globals.md
[main 0c955d0ef5] doc: setGlobalDispatcher() instead of Symbol
 Author: Alessandro Miliucci <[email protected]>
 Date: Fri Mar 21 09:43:58 2025 +0100
 1 file changed, 6 insertions(+), 3 deletions(-)
   ✔  Patches applied
There are 4 commits in the PR. Attempting autorebase.
Rebasing (2/8)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: improved fetch docs
PR-URL: #57296

Refs: https://undici.nodejs.org

Reviewed-By: Matteo Collina <[email protected]>

Reviewed-By: Marco Ippolito <[email protected]>

Reviewed-By: James M Snell <[email protected]>
[detached HEAD 848aa50343] doc: improved fetch docs

Author: Alessandro Miliucci <[email protected]>

Date: Mon Mar 3 16:32:53 2025 +0100

1 file changed, 33 insertions(+)

Rebasing (3/8)

Rebasing (4/8)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: fixed fetch md formatting
PR-URL: #57296

Refs: https://undici.nodejs.org

Reviewed-By: Matteo Collina <[email protected]>

Reviewed-By: Marco Ippolito <[email protected]>

Reviewed-By: James M Snell <[email protected]>
[detached HEAD 579ac3f7d3] doc: fixed fetch md formatting

Author: Alessandro Miliucci <[email protected]>

Date: Mon Mar 3 21:28:00 2025 +0100

1 file changed, 5 insertions(+), 4 deletions(-)

Rebasing (5/8)

Rebasing (6/8)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: fixed linting
PR-URL: #57296

Refs: https://undici.nodejs.org

Reviewed-By: Matteo Collina <[email protected]>

Reviewed-By: Marco Ippolito <[email protected]>

Reviewed-By: James M Snell <[email protected]>
[detached HEAD c64eb7d2a8] doc: fixed linting

Author: Alessandro Miliucci <[email protected]>

Date: Wed Mar 12 18:36:23 2025 +0100

1 file changed, 5 insertions(+), 2 deletions(-)

Rebasing (7/8)

Rebasing (8/8)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: setGlobalDispatcher() instead of Symbol
PR-URL: #57296

Refs: https://undici.nodejs.org

Reviewed-By: Matteo Collina <[email protected]>

Reviewed-By: Marco Ippolito <[email protected]>

Reviewed-By: James M Snell <[email protected]>
[detached HEAD 59f7a48ce3] doc: setGlobalDispatcher() instead of Symbol

Author: Alessandro Miliucci <[email protected]>

Date: Fri Mar 21 09:43:58 2025 +0100

1 file changed, 6 insertions(+), 3 deletions(-)

Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/14216151398

[nodejs-github-bot]

Landed in 828e09e