Merge branch 'main' into fix/3817

benchmarks/timers/now-absolute.mjs

@@ -0,0 +1,13 @@
+import { bench, group, run } from 'mitata'
+import timers from '../../lib/util/timers.js'
+
+group(() => {
+  bench('Date.now()', () => {
+    Date.now()
+  })
+  bench('nowAbsolute()', () => {
+    timers.nowAbsolute()
+  })
+})
+
+await run()

docs/docs/api/Agent.md

@@ -16,62 +16,62 @@ Returns: `Agent`
 
 ### Parameter: `AgentOptions`
 
-Extends: [`PoolOptions`](Pool.md#parameter-pooloptions)
+Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
 
 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
 
 ## Instance Properties
 
 ### `Agent.closed`
 
-Implements [Client.closed](Client.md#clientclosed)
+Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
 
 ### `Agent.destroyed`
 
-Implements [Client.destroyed](Client.md#clientdestroyed)
+Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
 
 ## Instance Methods
 
 ### `Agent.close([callback])`
 
-Implements [`Dispatcher.close([callback])`](Dispatcher.md#dispatcherclosecallback-promise).
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
 
 ### `Agent.destroy([error, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
 
 ### `Agent.dispatch(options, handler: AgentDispatchOptions)`
 
-Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
 
 #### Parameter: `AgentDispatchOptions`
 
-Extends: [`DispatchOptions`](Dispatcher.md#parameter-dispatchoptions)
+Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
 
 * **origin** `string | URL`
 
-Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
 
 ### `Agent.connect(options[, callback])`
 
-See [`Dispatcher.connect(options[, callback])`](Dispatcher.md#dispatcherconnectoptions-callback).
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
 
 ### `Agent.dispatch(options, handler)`
 
-Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
 
 ### `Agent.pipeline(options, handler)`
 
-See [`Dispatcher.pipeline(options, handler)`](Dispatcher.md#dispatcherpipelineoptions-handler).
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
 
 ### `Agent.request(options[, callback])`
 
-See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
 
 ### `Agent.stream(options, factory[, callback])`
 
-See [`Dispatcher.stream(options, factory[, callback])`](Dispatcher.md#dispatcherstreamoptions-factory-callback).
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
 
 ### `Agent.upgrade(options[, callback])`
 
-See [`Dispatcher.upgrade(options[, callback])`](Dispatcher.md#dispatcherupgradeoptions-callback).
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).

docs/docs/api/BalancedPool.md

@@ -15,7 +15,7 @@ Arguments:
 
 ### Parameter: `BalancedPoolOptions`
 
-Extends: [`PoolOptions`](Pool.md#parameter-pooloptions)
+Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
 
 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
 
@@ -28,15 +28,15 @@ Returns an array of upstreams that were previously added.
 
 ### `BalancedPool.closed`
 
-Implements [Client.closed](Client.md#clientclosed)
+Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
 
 ### `BalancedPool.destroyed`
 
-Implements [Client.destroyed](Client.md#clientdestroyed)
+Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
 
 ### `Pool.stats`
 
-Returns [`PoolStats`](PoolStats.md) instance for this pool.
+Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
 
 ## Instance Methods
 
@@ -54,46 +54,46 @@ Removes an upstream that was previously added.
 
 ### `BalancedPool.close([callback])`
 
-Implements [`Dispatcher.close([callback])`](Dispatcher.md#dispatcherclosecallback-promise).
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
 
 ### `BalancedPool.destroy([error, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
 
 ### `BalancedPool.connect(options[, callback])`
 
-See [`Dispatcher.connect(options[, callback])`](Dispatcher.md#dispatcherconnectoptions-callback).
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
 
 ### `BalancedPool.dispatch(options, handlers)`
 
-Implements [`Dispatcher.dispatch(options, handlers)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
 
 ### `BalancedPool.pipeline(options, handler)`
 
-See [`Dispatcher.pipeline(options, handler)`](Dispatcher.md#dispatcherpipelineoptions-handler).
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
 
 ### `BalancedPool.request(options[, callback])`
 
-See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
 
 ### `BalancedPool.stream(options, factory[, callback])`
 
-See [`Dispatcher.stream(options, factory[, callback])`](Dispatcher.md#dispatcherstreamoptions-factory-callback).
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
 
 ### `BalancedPool.upgrade(options[, callback])`
 
-See [`Dispatcher.upgrade(options[, callback])`](Dispatcher.md#dispatcherupgradeoptions-callback).
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
 
 ## Instance Events
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](Dispatcher.md#event-connect).
+See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](Dispatcher.md#event-disconnect).
+See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](Dispatcher.md#event-drain).
+See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).

docs/docs/api/CacheStore.md

@@ -2,7 +2,8 @@
 
 A Cache Store is responsible for storing and retrieving cached responses.
 It is also responsible for deciding which specific response to use based off of
-a response's `Vary` header (if present).
+a response's `Vary` header (if present). It is expected to be compliant with
+[RFC-9111](https://www.rfc-editor.org/rfc/rfc9111.html).
 
 ## Pre-built Cache Stores
 
@@ -21,27 +22,33 @@ The store must implement the following functions:
 
 ### Getter: `isFull`
 
-This tells the cache interceptor if the store is full or not. If this is true,
+Optional. This tells the cache interceptor if the store is full or not. If this is true,
 the cache interceptor will not attempt to cache the response.
 
-### Function: `createReadStream`
+### Function: `get`
 
 Parameters:
 
 * **req** `Dispatcher.RequestOptions` - Incoming request
 
-Returns: `CacheStoreReadable | Promise<CacheStoreReadable | undefined> | undefined` - If the request is cached, a readable for the body is returned. Otherwise, `undefined` is returned.
+Returns: `GetResult | Promise<GetResult | undefined> | undefined` - If the request is cached, the cached response is returned. If the request's method is anything other than HEAD, the response is also returned.
+If the request isn't cached, `undefined` is returned.
+
+Response properties:
+
+* **response** `CacheValue` - The cached response data.
+* **body** `Readable | undefined` - The response's body.
 
 ### Function: `createWriteStream`
 
 Parameters:
 
 * **req** `Dispatcher.RequestOptions` - Incoming request
-* **value** `CacheStoreValue` - Response to store
+* **value** `CacheValue` - Response to store
 
-Returns: `CacheStoreWriteable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
+Returns: `Writable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
 
-## `CacheStoreValue`
+## `CacheValue`
 
 This is an interface containing the majority of a response's data (minus the body).
 
@@ -55,15 +62,11 @@ This is an interface containing the majority of a response's data (minus the bod
 
 ### Property `rawHeaders`
 
-`(Buffer | Buffer[])[]` - The response's headers.
-
-### Property `rawTrailers`
-
-`string[] | undefined` - The response's trailers.
+`Buffer[]` - The response's headers.
 
 ### Property `vary`
 
-`Record<string, string> | undefined` - The headers defined by the response's `Vary` header
+`Record<string, string | string[]> | undefined` - The headers defined by the response's `Vary` header
 and their respective values for later comparison
 
 For example, for a response like
@@ -103,7 +106,7 @@ and defines extra properties relevant to the cache interceptor.
 
 ### Getter: `value`
 
-The response's [`CacheStoreValue`](#cachestorevalue)
+The response's [`CacheStoreValue`](/docs/docs/api/CacheStore.md#cachestorevalue)
 
 ## `CacheStoreWriteable`
 

docs/docs/api/Client.md

@@ -86,37 +86,37 @@ const client = new Client('https://localhost:3000', {
 
 ### `Client.close([callback])`
 
-Implements [`Dispatcher.close([callback])`](Dispatcher.md#dispatcherclosecallback-promise).
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
 
 ### `Client.destroy([error, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
 
 Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided).
 
 ### `Client.connect(options[, callback])`
 
-See [`Dispatcher.connect(options[, callback])`](Dispatcher.md#dispatcherconnectoptions-callback).
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
 
 ### `Client.dispatch(options, handlers)`
 
-Implements [`Dispatcher.dispatch(options, handlers)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
 
 ### `Client.pipeline(options, handler)`
 
-See [`Dispatcher.pipeline(options, handler)`](Dispatcher.md#dispatcherpipelineoptions-handler).
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
 
 ### `Client.request(options[, callback])`
 
-See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
 
 ### `Client.stream(options, factory[, callback])`
 
-See [`Dispatcher.stream(options, factory[, callback])`](Dispatcher.md#dispatcherstreamoptions-factory-callback).
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
 
 ### `Client.upgrade(options[, callback])`
 
-See [`Dispatcher.upgrade(options[, callback])`](Dispatcher.md#dispatcherupgradeoptions-callback).
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
 
 ## Instance Properties
 
@@ -142,7 +142,7 @@ Property to get and set the pipelining factor.
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](Dispatcher.md#event-connect).
+See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
 
 Parameters:
 
@@ -188,7 +188,7 @@ try {
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](Dispatcher.md#event-disconnect).
+See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
 
 Parameters:
 
@@ -233,7 +233,7 @@ try {
 
 Emitted when pipeline is no longer busy.
 
-See [Dispatcher Event: `'drain'`](Dispatcher.md#event-drain).
+See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
 
 #### Example - Client drain event
 

docs/docs/api/Dispatcher.md

@@ -377,7 +377,7 @@ Returns: `stream.Duplex`
 
 #### Parameter: PipelineOptions
 
-Extends: [`RequestOptions`](#parameter-requestoptions)
+Extends: [`RequestOptions`](/docs/docs/api/Dispatcher.md#parameter-requestoptions)
 
 * **objectMode** `boolean` (optional) - Default: `false` - Set to `true` if the `handler` will return an object stream.
 
@@ -467,7 +467,7 @@ Returns: `void | Promise<ResponseData>` - Only returns a `Promise` if no `callba
 
 #### Parameter: `RequestOptions`
 
-Extends: [`DispatchOptions`](#parameter-dispatchoptions)
+Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
 
 * **opaque** `unknown` (optional) - Default: `null` - Used for passing through context to `ResponseData`.
 * **signal** `AbortSignal | events.EventEmitter | null` (optional) - Default: `null`.
@@ -654,7 +654,7 @@ return null
 
 A faster version of `Dispatcher.request`. This method expects the second argument `factory` to return a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream which the response will be written to. This improves performance by avoiding creating an intermediate [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) stream when the user expects to directly pipe the response body to a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream.
 
-As demonstrated in [Example 1 - Basic GET stream request](#example-1---basic-get-stream-request), it is recommended to use the `option.opaque` property to avoid creating a closure for the `factory` method. This pattern works well with Node.js Web Frameworks such as [Fastify](https://fastify.io). See [Example 2 - Stream to Fastify Response](#example-2---stream-to-fastify-response) for more details.
+As demonstrated in [Example 1 - Basic GET stream request](/docs/docs/api/Dispatcher.md#example-1---basic-get-stream-request), it is recommended to use the `option.opaque` property to avoid creating a closure for the `factory` method. This pattern works well with Node.js Web Frameworks such as [Fastify](https://fastify.io). See [Example 2 - Stream to Fastify Response](/docs/docs/api/Dispatch.md#example-2---stream-to-fastify-response) for more details.
 
 Arguments:
 
@@ -936,7 +936,7 @@ await client.request({ path: '/', method: 'GET' })
 
 The `redirect` interceptor allows you to customize the way your dispatcher handles redirects.
 
-It accepts the same arguments as the [`RedirectHandler` constructor](./RedirectHandler.md).
+It accepts the same arguments as the [`RedirectHandler` constructor](/docs/docs/api/RedirectHandler.md).
 
 **Example - Basic Redirect Interceptor**
 
@@ -954,7 +954,7 @@ client.request({ path: "/" })
 
 The `retry` interceptor allows you to customize the way your dispatcher handles retries.
 
-It accepts the same arguments as the [`RetryHandler` constructor](./RetryHandler.md).
+It accepts the same arguments as the [`RetryHandler` constructor](/docs/docs/api/RetryHandler.md).
 
 **Example - Basic Redirect Interceptor**
 
@@ -1260,7 +1260,7 @@ The `cache` interceptor implements client-side response caching as described in
 
 **Options**
 
-- `store` - The [`CacheStore`](./CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](./CacheStore.md#memorycachestore).
+- `store` - The [`CacheStore`](/docs/docs/api/CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](/docs/docs/api/CacheStore.md#memorycachestore).
 - `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
 
 ## Instance Events
@@ -1309,13 +1309,13 @@ Emitted when dispatcher is no longer busy.
 
 * `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:
+Header arguments such as `options.headers` in [`Client.dispatch`](/docs/docs/api/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.
+Response headers will derive a `host` from the `url` of the [Client](/docs/docs/api/Client.md#class-client) instance if no `host` header was previously specified.
 
 ### Example 1 - Object