nodejs / undici

An HTTP/1.1 client, written from scratch for Node.js
https://nodejs.github.io/undici
MIT License
6.19k stars 541 forks source link

Improve request options docs and typings #1169

Open ronag opened 2 years ago

ronag commented 2 years ago

https://github.com/nodejs/undici/discussions/1168#discussioncomment-1991327

https://undici.nodejs.org/#/?id=undicirequesturl-options-promise status that options RequestOptions and links to https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-requestoptions for which there's a teensy little ditty about Extends: DispatchOptions. That could be made much more visible and verbose. e.g. The options object may also contain options from DispatchOptions so that it doesn't go missed. Documentation doesn't have be terse and can be a lovely experience to read.

There's also the matter of the typings. The request typings read:

options?: { dispatcher?: Dispatcher } & Omit<Dispatcher.RequestOptions, 'origin' | 'path'>, That's an intersection, not an extension. So the documentation isn't correct that the options for request are RequestOptions. Semantic hubalaboo but it's still not correct. It can however, lead to confusion when reading the typings within an editor.

With the typings there's some inconsistency between fetch options and request options: request options require passing the method: HttpMethod property, fetch doesn't require this.

shellscape commented 2 years ago

Taking this one on. If more than a week goes by, please ping me.