Request headers types (#2879)

* Mention iterable in request headers type

* Update type tests with iterable headers

* Mention iterables in documentation

Author: JaoodxD

docs/docs/api/Dispatcher.md

@@ -855,10 +855,12 @@ Emitted when dispatcher is no longer busy.
 
 ## Parameter: `UndiciHeaders`
 
-* `Record<string, string | string[] | undefined> | string[] | null`
-
-Header arguments such as `options.headers` in [`Client.dispatch`](Client.md#clientdispatchoptions-handlers) can be specified in two forms; either as an object specified by the `Record<string, string | string[] | undefined>` (`IncomingHttpHeaders`) type, or an array of strings. An array representation of a header list must have an even length or an `InvalidArgumentError` will be thrown.
+* `Record<string, string | string[] | undefined> | string[] | Iterable<[string, string | string[] | undefined]> | null`
 
+Header arguments such as `options.headers` in [`Client.dispatch`](Client.md#clientdispatchoptions-handlers) can be specified in three forms:
+* As an object specified by the `Record<string, string | string[] | undefined>` (`IncomingHttpHeaders`) type.
+* As an array of strings. An array representation of a header list must have an even length, or an `InvalidArgumentError` will be thrown.
+* As an iterable that can encompass `Headers`, `Map`, or a custom iterator returning key-value pairs.
 Keys are lowercase and values are not modified.
 
 Response headers will derive a `host` from the `url` of the [Client](Client.md#class-client) instance if no `host` header was previously specified.
@@ -886,3 +888,37 @@ Response headers will derive a `host` from the `url` of the [Client](Client.md#c
   'accept', '*/*'
 ]
 ```
+
+### Example 3 - Iterable
+
+```js
+new Headers({
+  'content-length': '123',
+  'content-type': 'text/plain',
+  connection: 'keep-alive',
+  host: 'mysite.com',
+  accept: '*/*'
+})
+```
+or
+```js
+new Map([
+  ['content-length', '123'],
+  ['content-type', 'text/plain'],
+  ['connection', 'keep-alive'],
+  ['host', 'mysite.com'],
+  ['accept', '*/*']
+])
+```
+or
+```js
+{
+  *[Symbol.iterator] () {
+    yield ['content-length', '123']
+    yield ['content-type', 'text/plain']
+    yield ['connection', 'keep-alive']
+    yield ['host', 'mysite.com']
+    yield ['accept', '*/*']
+  }
+}
+```

test/types/dispatcher.test-d.ts

@@ -15,6 +15,14 @@ expectAssignable<Dispatcher>(new Dispatcher())
     ['content-type']: 'application/json'
   } satisfies IncomingHttpHeaders;
 
+  const headerInstanceHeaders = new Headers({ hello: 'world' })
+  const mapHeaders = new Map([['hello', 'world']])
+  const iteratorHeaders = {
+    *[Symbol.iterator]() {
+      yield ['hello', 'world']
+    }
+  }
+
   // dispatch
   expectAssignable<boolean>(dispatcher.dispatch({ path: '', method: 'GET' }, {}))
   expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET' }, {}))
@@ -23,6 +31,9 @@ expectAssignable<Dispatcher>(new Dispatcher())
   expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: {} }, {}))
   expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: nodeCoreHeaders }, {}))
   expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: null, reset: true }, {}))
+  expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: headerInstanceHeaders, reset: true }, {}))
+  expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: mapHeaders, reset: true }, {}))
+  expectAssignable<boolean>(dispatcher.dispatch({ origin: '', path: '', method: 'GET', headers: iteratorHeaders, reset: true }, {}))
   expectAssignable<boolean>(dispatcher.dispatch({ origin: new URL('http://localhost'), path: '', method: 'GET' }, {}))
 
   // connect

types/dispatcher.d.ts

@@ -100,7 +100,7 @@ declare namespace Dispatcher {
     /** Default: `null` */
     body?: string | Buffer | Uint8Array | Readable | null | FormData;
     /** Default: `null` */
-    headers?: IncomingHttpHeaders | string[] | null;
+    headers?: IncomingHttpHeaders | string[] | Iterable<[string, string | string[] | undefined]> | null;
     /** Query string params to be embedded in the request URL. Default: `null` */
     query?: Record<string, any>;
     /** Whether the requests can be safely retried or not. If `false` the request won't be sent until all preceding requests in the pipeline have completed. Default: `true` if `method` is `HEAD` or `GET`. */