nodejs / nodejs/undici

Improve request options docs and typings

Open
#1,169 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
JavaScript
Stars
7.7k
Forks
880
Avg merge
2d 16h
Merged PRs (30d)
68

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked discussion and the RequestOptions and DispatchOptions API documentation. Then inspect the request typings shown in the issue and compare them with the fetch options typing. Done means the relationship between request and dispatch options is clearly documented and the documented option and method requirements are consistent with the typings.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.