Clarifying `Dispatcher` API in order to improve documentation

Hi folks, I'm working on improving our documentation and I'd like to clarify some aspects of the API starting with Dispatcher.

Dispatcher is essentially an abstract class: https://github.com/nodejs/undici/blob/main/lib/dispatcher.js#L5 that is only extended by DispatcherBase and MockAgent.

Most other classes extend DispatcherBase (such as Client).

Within index.js, the Dispatcher prototype gets the lib/api functions applied to it: https://github.com/nodejs/undici/blob/main/index.js#L33

This is necessary so that classes such as Client can work.

Client extends DispatcherBase which extends Dispatcher. Calling client.request() is reliant on lib/api/api-request.js existing on Dispatcher.

Now interestingly enough the following code is valid, but non-functional:

import { Dispatcher } from "undici";

let d = new Dispatcher();

const r = await d.request({
  origin: 'http://example.com'
});

const t = await r.text();

console.log(t);

Throws the following error:

❯ node local-script.mjs 
/Users/ethanarrowood/Documents/github/nodejs/undici/lib/dispatcher.js:7
    throw new Error('not implemented')
          ^

Error: not implemented
    at Dispatcher.dispatch (/Users/ethanarrowood/Documents/github/nodejs/undici/lib/dispatcher.js:7:11)
    at Dispatcher.request (/Users/ethanarrowood/Documents/github/nodejs/undici/lib/api/api-request.js:169:10)
    at /Users/ethanarrowood/Documents/github/nodejs/undici/lib/api/api-request.js:162:15
    at new Promise (<anonymous>)
    at Dispatcher.request (/Users/ethanarrowood/Documents/github/nodejs/undici/lib/api/api-request.js:161:12)
    at file:///Users/ethanarrowood/Documents/github/nodejs/undici/local-script.mjs:5:19
    at ModuleJob.run (node:internal/modules/esm/module_job:195:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:336:24)
    at async loadESM (node:internal/process/esm_loader:34:7)
    at async handleMainPromise (node:internal/modules/run_main:106:12)

Node.js v18.19.0

Regarding documentation how should the Dispatcher class be documented particularly regarding methods like request?

It currently does: https://undici.nodejs.org/#/docs/api/Dispatcher?id=dispatcherrequestoptions-callback, but the code examples reference Client.

Start by reading lib/dispatcher.js, index.js, and lib/api/api-request.js to trace how Dispatcher and its subclasses expose request(). Compare that behavior with the current Dispatcher.request documentation and its Client-based examples. Done means the documentation clearly explains Dispatcher’s role, its request method, and the non-functional base-class behavior.