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.