@noodleseed/one 0.22.0 → 0.23.0

package/node_modules/undici/docs/docs/api/api-lifecycle.md

@@ -1,27 +1,49 @@
 # Client Lifecycle
 
-An Undici [Client](/docs/docs/api/Client.md) can be best described as a state machine. The following list is a summary of the various state transitions the `Client` will go through in its lifecycle. This document also contains detailed breakdowns of each state.
-
-> This diagram is not a perfect representation of the undici Client. Since the Client class is not actually implemented as a state-machine, actual execution may deviate slightly from what is described below. Consider this as a general resource for understanding the inner workings of the Undici client rather than some kind of formal specification.
-
-## State Transition Overview
-
-* A `Client` begins in the **idle** state with no socket connection and no requests in queue.
-  * The *connect* event transitions the `Client` to the **pending** state where requests can be queued prior to processing.
-  * The *close* and *destroy* events transition the `Client` to the **destroyed** state. Since there are no requests in the queue, the *close* event immediately transitions to the **destroyed** state.
-* The **pending** state indicates the underlying socket connection has been successfully established and requests are queueing.
-  * The *process* event transitions the `Client` to the **processing** state where requests are processed.
-  * If requests are queued, the *close* event transitions to the **processing** state; otherwise, it transitions to the **destroyed** state.
-  * The *destroy* event transitions to the **destroyed** state.
-* The **processing** state initializes to the **processing.running** state.
-  * If the current request requires draining, the *needDrain* event transitions the `Client` into the **processing.busy** state which will return to the **processing.running** state with the *drainComplete* event.
-  * After all queued requests are completed, the *keepalive* event transitions the `Client` back to the **pending** state. If no requests are queued during the timeout, the **close** event transitions the `Client` to the **destroyed** state.
-  * If the *close* event is fired while the `Client` still has queued requests, the `Client` transitions to the **process.closing** state where it will complete all existing requests before firing the *done* event.
-  * The *done* event gracefully transitions the `Client` to the **destroyed** state.
-  * At any point in time, the *destroy* event will transition the `Client` from the **processing** state to the **destroyed** state, destroying any queued requests.
-* The **destroyed** state is a final state and the `Client` is no longer functional.
-
-A state diagram representing an Undici Client instance:
+<!--type=misc-->
+
+A {Client} can be understood as a state machine. As requests are dispatched,
+processed, and drained, the client moves through a well-defined set of states
+until it is eventually destroyed. This document describes those states and the
+transitions between them.
+
+The {Client} class is not literally implemented as a state machine, so the
+actual execution may deviate slightly from what is described here. Treat this
+guide as a conceptual model for reasoning about a client's behavior rather than
+as a formal specification.
+
+## State transition overview
+
+* A {Client} begins in the **idle** state with no socket connection and no
+  queued requests.
+  * The *connect* transition moves the {Client} to the **pending** state, where
+    requests can be queued before they are processed.
+  * Calling [`client.close()`][] or [`client.destroy()`][] moves the {Client}
+    to the **destroyed** state. Because there are no queued requests in this
+    state, *close* transitions straight to **destroyed**.
+* The **pending** state indicates that the underlying socket connection has been
+  established and that requests are queueing.
+  * The *process* transition moves the {Client} to the **processing** state,
+    where requests are processed.
+  * If requests are queued, *close* transitions to **processing**; otherwise it
+    transitions to **destroyed**.
+  * The *destroy* transition moves the {Client} to **destroyed**.
+* The **processing** state initializes to the **processing.running** sub-state.
+  * If the current request body requires draining, *needDrain* moves the
+    {Client} into the **processing.busy** sub-state, which returns to
+    **processing.running** once *drainComplete* fires.
+  * After all queued requests complete, *keepalive* moves the {Client} back to
+    the **pending** state. If no requests are queued before the socket times
+    out, the {Client} transitions to **idle**.
+  * If *close* is fired while the {Client} still has queued requests, the
+    {Client} transitions to **processing.closing**, where it completes all
+    outstanding requests before firing *done*.
+  * The *done* transition moves the {Client} gracefully to **destroyed**.
+  * At any time, *destroy* moves the {Client} from **processing** to
+    **destroyed**, aborting any queued requests.
+* The **destroyed** state is final; the {Client} is no longer functional.
+
+A state diagram representing a {Client} instance:
 
 ```mermaid
 stateDiagram-v2
@@ -54,38 +76,84 @@ stateDiagram-v2
       closing --> [*] : done
   }
 ```
+
 ## State details
 
 ### idle
 
-The **idle** state is the initial state of a `Client` instance. While an `origin` is required for instantiating a `Client` instance, the underlying socket connection will not be established until a request is queued using [`Client.dispatch()`](/docs/docs/api/Client.md#clientdispatchoptions-handlers). By calling `Client.dispatch()` directly or using one of the multiple implementations ([`Client.connect()`](/docs/docs/api/Client.md#clientconnectoptions-callback), [`Client.pipeline()`](/docs/docs/api/Client.md#clientpipelineoptions-handler), [`Client.request()`](/docs/docs/api/Client.md#clientrequestoptions-callback), [`Client.stream()`](/docs/docs/api/Client.md#clientstreamoptions-factory-callback), and [`Client.upgrade()`](/docs/docs/api/Client.md#clientupgradeoptions-callback)), the `Client` instance will transition from **idle** to [**pending**](/docs/docs/api/Client.md#pending) and then most likely directly to [**processing**](/docs/docs/api/Client.md#processing).
+**idle** is the initial state of a {Client} instance. Although an `origin` is
+required to construct a {Client}, the underlying socket connection is not
+established until a request is queued through [`client.dispatch()`][]. Calling
+`client.dispatch()` directly, or through one of its higher-level wrappers
+([`client.connect()`][], [`client.pipeline()`][], [`client.request()`][],
+[`client.stream()`][], or [`client.upgrade()`][]), moves the {Client} from
+**idle** to **pending**, and then usually directly on to **processing**.
 
-Calling [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) or [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state since the `Client` instance will have no queued requests in this state.
+Calling [`client.close()`][] or [`client.destroy()`][] in this state moves the
+{Client} straight to **destroyed**, since there are no queued requests.
 
 ### pending
 
-The **pending** state signifies a non-processing `Client`. Upon entering this state, the `Client` establishes a socket connection and emits the [`'connect'`](/docs/docs/api/Client.md#event-connect) event signalling a connection was successfully established with the `origin` provided during `Client` instantiation. The internal queue is initially empty, and requests can start queueing.
+**pending** signifies a connected but non-processing {Client}. On entering this
+state, the {Client} establishes a socket connection and emits the
+[`'connect'`][] event, signalling that a connection to the `origin` supplied at
+construction time has been established. The internal queue starts empty, and
+requests can begin queueing.
 
-Calling [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) with queued requests, transitions the `Client` to the [**processing**](/docs/docs/api/Client.md#processing) state. Without queued requests, it transitions to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state.
+Calling [`client.close()`][] with queued requests moves the {Client} to the
+**processing** state; without queued requests it moves to **destroyed**.
 
-Calling [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) transitions directly to the [**destroyed**](/docs/docs/api/Client.md#destroyed) state regardless of existing requests.
+Calling [`client.destroy()`][] moves the {Client} directly to **destroyed**,
+regardless of any queued requests.
 
 ### processing
 
-The **processing** state is a state machine within itself. It initializes to the [**processing.running**](/docs/docs/api/Client.md#running) state. The [`Client.dispatch()`](/docs/docs/api/Client.md#clientdispatchoptions-handlers), [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback), and [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) can be called at any time while the `Client` is in this state. `Client.dispatch()` will add more requests to the queue while existing requests continue to be processed. `Client.close()` will transition to the [**processing.closing**](/docs/docs/api/Client.md#closing) state. And `Client.destroy()` will transition to [**destroyed**](/docs/docs/api/Client.md#destroyed).
+**processing** is itself a sub-state machine that initializes to the
+**processing.running** sub-state. [`client.dispatch()`][], [`client.close()`][],
+and [`client.destroy()`][] can all be called while the {Client} is in this
+state. `client.dispatch()` queues additional requests while existing ones
+continue to be processed, `client.close()` moves the {Client} to the
+**processing.closing** sub-state, and `client.destroy()` moves it to
+**destroyed**.
 
 #### running
 
-In the **processing.running** sub-state, queued requests are being processed in a FIFO order. If a request body requires draining, the *needDrain* event transitions to the [**processing.busy**](/docs/docs/api/Client.md#busy) sub-state. The *close* event transitions the Client to the [**process.closing**](/docs/docs/api/Client.md#closing) sub-state. If all queued requests are processed and neither [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) nor [`Client.destroy()`](/docs/docs/api/Client.md#clientdestroyerror-callback) are called, then the [**processing**](/docs/docs/api/Client.md#processing) machine will trigger a *keepalive* event transitioning the `Client` back to the [**pending**](/docs/docs/api/Client.md#pending) state. During this time, the `Client` is waiting for the socket connection to timeout, and once it does, it triggers the *timeout* event and transitions to the [**idle**](/docs/docs/api/Client.md#idle) state.
+In **processing.running**, queued requests are processed in FIFO order. If a
+request body requires draining, *needDrain* moves the {Client} to the
+**processing.busy** sub-state. The *close* transition moves the {Client} to the
+**processing.closing** sub-state. When all queued requests have completed and
+neither [`client.close()`][] nor [`client.destroy()`][] has been called, the
+*keepalive* transition moves the {Client} back to the **pending** state. There
+the {Client} waits for the socket connection to time out; once it does, the
+{Client} returns to the **idle** state.
 
 #### busy
 
-This sub-state is only entered when a request body is an instance of [Stream](https://nodejs.org/api/stream.html) and requires draining. The `Client` cannot process additional requests while in this state and must wait until the currently processing request body is completely drained before transitioning back to [**processing.running**](/docs/docs/api/Client.md#running).
+This sub-state is entered only when a request body is a {stream.Readable} that
+requires draining. The {Client} cannot process additional requests while in
+this state and waits until the current request body has been fully drained
+before returning to **processing.running**.
 
 #### closing
 
-This sub-state is only entered when a `Client` instance has queued requests and the [`Client.close()`](/docs/docs/api/Client.md#clientclosecallback) method is called. In this state, the `Client` instance continues to process requests as usual, with the one exception that no additional requests can be queued. Once all of the queued requests are processed, the `Client` will trigger the *done* event gracefully entering the [**destroyed**](/docs/docs/api/Client.md#destroyed) state without an error.
+This sub-state is entered only when a {Client} has queued requests and
+[`client.close()`][] is called. The {Client} continues to process requests as
+usual, except that no additional requests may be queued. Once all queued
+requests have been processed, *done* fires and the {Client} moves gracefully to
+**destroyed** without an error.
 
 ### destroyed
 
-The **destroyed** state is a final state for the `Client` instance. Once in this state, a `Client` is nonfunctional. Calling any other `Client` methods will result in an `ClientDestroyedError`.
+**destroyed** is the final state of a {Client} instance. Once in this state, the
+{Client} is no longer functional, and calling any further {Client} method
+rejects or fails with a {ClientDestroyedError}.
+
+[`'connect'`]: Client.md#event-connect
+[`client.close()`]: Client.md#clientclosecallback
+[`client.connect()`]: Client.md#clientconnectoptions-callback
+[`client.destroy()`]: Client.md#clientdestroyerror-callback
+[`client.dispatch()`]: Client.md#clientdispatchoptions-handlers
+[`client.pipeline()`]: Client.md#clientpipelineoptions-handler
+[`client.request()`]: Client.md#clientrequestoptions-callback
+[`client.stream()`]: Client.md#clientstreamoptions-factory-callback
+[`client.upgrade()`]: Client.md#clientupgradeoptions-callback

package/node_modules/undici/docs/docs/best-practices/client-certificate.md

@@ -1,5 +1,7 @@
 # Client certificate
 
+<!--type=misc-->
+
 Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
 
 The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla.

package/node_modules/undici/docs/docs/best-practices/crawling.md

@@ -1,5 +1,7 @@
 # Crawling
 
+<!--type=misc-->
+
 [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) defines crawlers as automated clients.
 
 Some web servers may reject requests that omit the `User-Agent` header or that use common defaults such as `'curl/7.79.1'`.
@@ -10,7 +12,7 @@ It is recommended to specify a **custom `User-Agent` header** when implementing
 
 A user agent string should include sufficient detail to identify the crawler and provide contact information. For example:
 
-```
+```text
 AcmeCo Crawler - acme.co - contact@acme.co
 ```
 

package/node_modules/undici/docs/docs/best-practices/migrating-from-v7-to-v8.md

@@ -1,5 +1,7 @@
 # Migrating from Undici 7 to 8
 
+<!--type=misc-->
+
 This guide covers the changes you are most likely to hit when upgrading an
 application or library from Undici v7 to v8.
 
@@ -225,7 +227,7 @@ After moving to Undici v8, it is worth checking these paths in your test suite:
 
 ## Related documentation
 
-- [Dispatcher](/docs/api/Dispatcher.md)
-- [Client](/docs/api/Client.md)
-- [Global Installation](/docs/api/GlobalInstallation.md)
-- [Undici Module vs. Node.js Built-in Fetch](/docs/best-practices/undici-vs-builtin-fetch.md)
+- [Dispatcher](../api/Dispatcher.md)
+- [Client](../api/Client.md)
+- [Global Installation](../api/GlobalInstallation.md)
+- [Undici Module vs. Node.js Built-in Fetch](./undici-vs-builtin-fetch.md)

package/node_modules/undici/docs/docs/best-practices/mocking-request.md

@@ -1,6 +1,8 @@
 # Mocking Request
 
-Undici has its own mocking [utility](/docs/docs/api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
+<!--type=misc-->
+
+Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
 
 Example:
 
@@ -73,7 +75,7 @@ const badRequest = await bankTransfer('1234567890', '100')
 assert.deepEqual(badRequest, { message: 'bank account not found' })
 ```
 
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
+Explore other MockAgent functionality [here](../api/MockAgent.md)
 
 ## Access agent call history
 
@@ -100,7 +102,7 @@ setGlobalDispatcher(mockAgent)
 // this call is made (not intercepted)
 await fetch(`http://localhost:3000/endpoint?query='hello'`, {
   method: 'POST',
-  headers: { 'content-type': 'application/json' }
+  headers: { 'content-type': 'application/json' },
   body: JSON.stringify({ data: '' })
 })
 
@@ -123,11 +125,11 @@ assert.ok(mockAgent.getCallHistory()?.calls().length === 0)
 
 Calling `mockAgent.close()` will automatically clear and delete every call history for you.
 
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
+Explore other MockAgent functionality [here](../api/MockAgent.md)
 
-Explore other MockCallHistory functionality [here](/docs/docs/api/MockCallHistory.md)
+Explore other MockCallHistory functionality [here](../api/MockCallHistory.md)
 
-Explore other MockCallHistoryLog functionality [here](/docs/docs/api/MockCallHistoryLog.md)
+Explore other MockCallHistoryLog functionality [here](../api/MockCallHistoryLog.md)
 
 ## Debug Mock Value
 
@@ -179,7 +181,7 @@ mockPool.intercept({
 
 in this case opts will be
 
-```
+```js
 {
   method: 'POST',
   headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },

package/node_modules/undici/docs/docs/best-practices/proxy.md

@@ -1,8 +1,10 @@
 # Connecting through a proxy
 
+<!--type=misc-->
+
 Connecting through a proxy is possible by:
 
-- Using [ProxyAgent](/docs/docs/api/ProxyAgent.md).
+- Using {ProxyAgent}.
 - Configuring `Client` or `Pool` constructor.
 
 The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url

package/node_modules/undici/docs/docs/best-practices/undici-vs-builtin-fetch.md

@@ -1,5 +1,7 @@
 # Undici Module vs. Node.js Built-in Fetch
 
+<!--type=misc-->
+
 Node.js has shipped a built-in `fetch()` implementation powered by undici since
 Node.js v18. This guide explains the relationship between the `undici` npm
 package and the built-in `fetch`, and when you should install one versus relying
@@ -57,7 +59,7 @@ await fetch('https://example.com', {
 ### `undici.install()` globals
 
 If you want the installed `undici` package to provide the globals, call
-[`install()`](/docs/api/GlobalInstallation.md):
+[`install()`](../api/GlobalInstallation.md):
 
 ```js
 import { install } from 'undici'
@@ -207,7 +209,7 @@ You can always check the exact bundled version at runtime with
 
 Installing undici from npm does not replace the built-in globals. If you want
 your installed version to replace the global `fetch` and related classes, use
-[`install()`](/docs/api/GlobalInstallation.md). Otherwise, import `fetch`
+[`install()`](../api/GlobalInstallation.md). Otherwise, import `fetch`
 directly from `'undici'`:
 
 ```js
@@ -216,9 +218,9 @@ import { fetch } from 'undici' // uses your installed version, not the built-in
 
 ## Further reading
 
-- [API Reference: Fetch](/docs/api/Fetch.md)
-- [API Reference: Client](/docs/api/Client.md)
-- [API Reference: Pool](/docs/api/Pool.md)
-- [API Reference: ProxyAgent](/docs/api/ProxyAgent.md)
-- [API Reference: MockAgent](/docs/api/MockAgent.md)
-- [API Reference: Global Installation](/docs/api/GlobalInstallation.md)
+- [API Reference: Fetch](../api/Fetch.md)
+- [API Reference: Client](../api/Client.md)
+- [API Reference: Pool](../api/Pool.md)
+- [API Reference: ProxyAgent](../api/ProxyAgent.md)
+- [API Reference: MockAgent](../api/MockAgent.md)
+- [API Reference: Global Installation](../api/GlobalInstallation.md)

package/node_modules/undici/docs/docs/best-practices/writing-tests.md

@@ -1,5 +1,7 @@
 # Writing tests
 
+<!--type=misc-->
+
 Undici is tuned for a production use case and its default will keep
 a socket open for a few seconds after an HTTP request is completed to
 remove the overhead of opening up a new socket. These settings that makes

package/node_modules/undici/docs/docs/{GettingStarted.md → getting-started.md}

@@ -1,5 +1,7 @@
 # Getting Started
 
+<!--type=misc-->
+
 ## Installation
 
 ```bash
@@ -12,7 +14,7 @@ The quickest way to get started is with `fetch`, which follows the
 [Fetch Standard](https://fetch.spec.whatwg.org/) and works the same way as
 the browser API:
 
-```js
+```mjs
 import { fetch } from 'undici'
 
 const res = await fetch('https://example.com')
@@ -24,7 +26,7 @@ console.log(data)
 
 undici also exports a `Request` class that follows the Fetch Standard:
 
-```js
+```mjs
 import { fetch, Request } from 'undici'
 
 const req = new Request('https://example.com', {
@@ -41,7 +43,7 @@ console.log(res.status)
 `res.body` is a web `ReadableStream`. Use `pipeline` from
 `node:stream/promises` to stream it to a file:
 
-```js
+```mjs
 import { fetch } from 'undici'
 import { pipeline } from 'node:stream/promises'
 import { createWriteStream } from 'node:fs'
@@ -53,10 +55,10 @@ await pipeline(res.body, createWriteStream('./file.zip'))
 > Always consume or cancel the response body. In Node.js, garbage collection
 > is not aggressive enough to release connections promptly, so leaving a body
 > unread can cause connection leaks and stalled requests. See
-> [Specification Compliance - Garbage Collection](/docs/#garbage-collection)
+> [Specification Compliance - Garbage Collection](/#garbage-collection)
 > for details.
 
-For more on `fetch`, see [API Reference: Fetch](/docs/docs/api/Fetch.md).
+For more on `fetch`, see [API Reference: Fetch](api/Fetch.md).
 
 ## Dispatchers: Connection reuse and pooling
 
@@ -111,7 +113,8 @@ pool.close()
 ### `Client` — for a single connection
 
 `Client` maps to a single TCP connection. It supports pipelining (sending
-multiple requests before responses arrive):
+multiple requests before responses arrive), which should only be enabled for
+trusted remote servers:
 
 ```js
 import { Client } from 'undici'
@@ -127,9 +130,9 @@ client.close()
 ```
 
 For more on dispatcher options and lifecycle, see:
-- [API Reference: Agent](/docs/docs/api/Agent.md)
-- [API Reference: Pool](/docs/docs/api/Pool.md)
-- [API Reference: Client](/docs/docs/api/Client.md)
+- [API Reference: Agent](api/Agent.md)
+- [API Reference: Pool](api/Pool.md)
+- [API Reference: Client](api/Client.md)
 
 ## Timeouts
 
@@ -152,7 +155,7 @@ setGlobalDispatcher(agent)
 ```
 
 Timeout errors are thrown as `HeadersTimeoutError` and `BodyTimeoutError`.
-See [API Reference: Errors](/docs/docs/api/Errors.md) for the full list.
+See [API Reference: Errors](api/Errors.md) for the full list.
 
 ## Error handling
 
@@ -217,8 +220,8 @@ const proxy = new ProxyAgent('http://proxy.internal:8080')
 setGlobalDispatcher(proxy)
 ```
 
-See [Best Practices: Proxy](/docs/docs/best-practices/proxy.md) and
-[API Reference: ProxyAgent](/docs/docs/api/ProxyAgent.md).
+See [Best Practices: Proxy](best-practices/proxy.md) and
+[API Reference: ProxyAgent](api/ProxyAgent.md).
 
 ### Mocking in tests
 
@@ -235,8 +238,8 @@ const { body } = await request('https://api.example.com/users')
 console.log(await body.json())
 ```
 
-See [Best Practices: Mocking Request](/docs/docs/best-practices/mocking-request.md)
-and [API Reference: MockAgent](/docs/docs/api/MockAgent.md).
+See [Best Practices: Mocking Request](best-practices/mocking-request.md)
+and [API Reference: MockAgent](api/MockAgent.md).
 
 ### Testing with undici
 
@@ -252,7 +255,7 @@ const agent = new Agent({
 setGlobalDispatcher(agent)
 ```
 
-See [Best Practices: Writing Tests](/docs/docs/best-practices/writing-tests.md).
+See [Best Practices: Writing Tests](best-practices/writing-tests.md).
 
 ### Customizing the global fetch
 
@@ -268,11 +271,11 @@ install()
 const res = await fetch('https://example.com')
 ```
 
-See [API Reference: Global Installation](/docs/docs/api/GlobalInstallation.md).
+See [API Reference: Global Installation](api/GlobalInstallation.md).
 
 ## Further reading
 
-- [Undici vs. Built-in Fetch](/docs/docs/best-practices/undici-vs-builtin-fetch.md) —
+- [Undici vs. Built-in Fetch](best-practices/undici-vs-builtin-fetch.md) —
   when to install undici vs using Node.js built-in fetch
-- [API Reference](/docs/docs/api/Dispatcher.md) — full dispatcher API documentation
-- [Examples](/docs/examples/) — runnable code examples
+- [API Reference](api/Dispatcher.md) — full dispatcher API documentation
+- [Examples](/examples/) — runnable code examples