@noodleseed/one 0.22.0 → 0.23.0

package/node_modules/undici/docs/docs/api/MockCallHistoryLog.md

@@ -1,43 +1,206 @@
-# Class: MockCallHistoryLog
+# MockCallHistoryLog
 
-Access to an instance with :
+<!--introduced_in=v7.5.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-call-history.js -->
+
+> Stability: 2 - Stable
+
+A `MockCallHistoryLog` is an immutable snapshot of the configuration of a single
+request that was intercepted by a [`MockAgent`][]. Each property mirrors a part
+of the request, with the URL components already parsed by the WHATWG URL parser.
+
+Instances are not created directly. They are produced by a [`MockCallHistory`][]
+when call history is enabled on a [`MockAgent`][], and can be retrieved through
+the call history helpers such as `firstCall()`, `lastCall()`, `nthCall()`,
+`calls()`, and `filterCalls()`.
+
+```mjs
+import { MockAgent } from 'undici'
 
-```js
 const mockAgent = new MockAgent({ enableCallHistory: true })
-mockAgent.getCallHistory()?.firstCall()
+
+// after some requests have been intercepted:
+const log = mockAgent.getCallHistory()?.firstCall()
 ```
 
-## class properties
+## Class: `MockCallHistoryLog`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+Represents the configuration of one intercepted request.
+
+### `new MockCallHistoryLog(requestInit)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `requestInit` {DispatchOptions} The dispatch options of the intercepted
+  request. **Default:** `{}`.
+
+Creates a new `MockCallHistoryLog`. The `body`, `headers`, and `method`
+properties are copied directly from `requestInit`, while the URL-derived
+properties (`fullUrl`, `origin`, `path`, `searchParams`, `protocol`, `host`,
+`port`, and `hash`) are computed from `requestInit.path` and `requestInit.origin`
+using the WHATWG URL parser.
+
+This constructor is internal-facing: instances are created by
+[`MockCallHistory`][] when a request is intercepted. It is documented because the
+class is part of the public API surface.
+
+### `mockCallHistoryLog.body`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string|null|undefined}
+
+The body of the intercepted request, exactly as supplied to the dispatcher.
+
+### `mockCallHistoryLog.headers`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {Record<string, string|string[]>|null|undefined}
+
+The headers of the intercepted request.
+
+### `mockCallHistoryLog.method`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The HTTP method of the intercepted request, for example `'GET'` or `'PUT'`.
+
+### `mockCallHistoryLog.fullUrl`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The full URL of the intercepted request, including protocol, host, path, search
+parameters, and hash.
+
+### `mockCallHistoryLog.origin`
+
+<!-- YAML
+added: v7.5.0
+-->
 
-- body `mockAgent.getCallHistory()?.firstCall()?.body`
-- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
-- method `mockAgent.getCallHistory()?.firstCall()?.method` a string
-- fullUrl `mockAgent.getCallHistory()?.firstCall()?.fullUrl` a string containing the protocol, origin, path, query and hash
-- origin `mockAgent.getCallHistory()?.firstCall()?.origin` a string containing the protocol and the host
-- headers `mockAgent.getCallHistory()?.firstCall()?.headers` an object
-- path `mockAgent.getCallHistory()?.firstCall()?.path` a string always starting with `/`
-- searchParams `mockAgent.getCallHistory()?.firstCall()?.searchParams` an object
-- protocol `mockAgent.getCallHistory()?.firstCall()?.protocol` a string (`https:`)
-- host `mockAgent.getCallHistory()?.firstCall()?.host` a string
-- port `mockAgent.getCallHistory()?.firstCall()?.port` an empty string or a string containing numbers
-- hash `mockAgent.getCallHistory()?.firstCall()?.hash` an empty string or a string starting with `#`
+* Type: {string}
 
-## class methods
+The origin of the intercepted request, comprising the protocol and host, for
+example `'https://localhost:4000'`.
 
-### toMap
+### `mockCallHistoryLog.path`
 
-Returns a Map instance
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
-mockAgent.getCallHistory()?.firstCall()?.toMap()?.get('hash')
-// #hash
+* Type: {string}
+
+The pathname of the intercepted request. It always starts with `/` and never
+contains search parameters.
+
+### `mockCallHistoryLog.searchParams`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {Record<string, string>}
+
+The search parameters of the intercepted request as a plain object of key/value
+pairs.
+
+### `mockCallHistoryLog.protocol`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The protocol of the intercepted request, including the trailing colon, for
+example `'https:'` or `'http:'`.
+
+### `mockCallHistoryLog.host`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The host of the intercepted request, including the port when present.
+
+### `mockCallHistoryLog.port`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The port of the intercepted request. It is an empty string when no explicit port
+was used, otherwise a string of digits.
+
+### `mockCallHistoryLog.hash`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Type: {string}
+
+The hash fragment of the intercepted request. It is an empty string when absent,
+otherwise a string starting with `#`.
+
+### `mockCallHistoryLog.toMap()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {Map} A `Map` whose keys are the property names `protocol`, `host`,
+  `port`, `origin`, `path`, `hash`, `searchParams`, `fullUrl`, `method`, `body`,
+  and `headers`, each mapped to the corresponding value of this log.
+
+Returns the log as a `Map` of property name to value.
+
+```mjs
+mockAgent.getCallHistory()?.firstCall()?.toMap().get('hash')
+// '#hash'
 ```
 
-### toString
+### `mockCallHistoryLog.toString()`
 
-Returns a string computed with any class property name and value pair
+<!-- YAML
+added: v7.5.0
+-->
 
-```js
+* Returns: {string} A string representation of the log.
+
+Returns a string built from every property name and value pair. Each pair is
+joined with `->` and pairs are separated with `|`. Object values such as
+`searchParams` and `headers` are serialized with `JSON.stringify()`.
+
+```mjs
 mockAgent.getCallHistory()?.firstCall()?.toString()
 // protocol->https:|host->localhost:4000|port->4000|origin->https://localhost:4000|path->/endpoint|hash->#here|searchParams->{"query":"value"}|fullUrl->https://localhost:4000/endpoint?query=value#here|method->PUT|body->"{ "data": "hello" }"|headers->{"content-type":"application/json"}
 ```
+
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockCallHistory`]: MockCallHistory.md#class-mockcallhistory

package/node_modules/undici/docs/docs/api/MockClient.md

@@ -1,73 +1,183 @@
-# Class: MockClient
+# MockClient
 
-Extends: `undici.Client`
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-client.js -->
 
-A mock client class that implements the same api as [MockPool](/docs/docs/api/MockPool.md).
+> Stability: 2 - Stable
 
-## `new MockClient(origin, [options])`
+A `MockClient` is a [`Client`][] that intercepts requests matching registered
+routes and replies with mocked responses instead of contacting the network.
+It is created by a [`MockAgent`][] when the agent is configured with a single
+connection, and it exposes the same interception API as [`MockPool`][].
 
-Arguments:
+A `MockClient` is not constructed directly in most cases; instead it is obtained
+through [`mockAgent.get(origin)`][] once the agent has `connections` set to `1`.
 
-* **origin** `string` - It should only include the **protocol, hostname, and port**.
-* **options** `MockClientOptions` - It extends the `Client` options.
+```mjs
+import { MockAgent } from 'undici'
 
-Returns: `MockClient`
+// `connections: 1` makes the agent hand out `MockClient` instances.
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+```
 
-### Parameter: `MockClientOptions`
+```cjs
+const { MockAgent } = require('undici')
 
-Extends: `ClientOptions`
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+```
+
+## Class: `MockClient`
 
-* **agent** `Agent` - the agent to associate this MockClient with.
+<!-- YAML
+added: v4.0.0
+-->
 
-### Example - Basic MockClient instantiation
+* Extends: {Client}
 
-We can use MockAgent to instantiate a MockClient ready to be used to intercept specified requests. It will not do anything until registered as the agent to use and any mock request are registered.
+Extends [`Client`][] and implements the `Interceptable` interface, allowing
+requests made through it to be matched against registered mocks.
 
-```js
+### `new MockClient(origin[, options])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `origin` {string} The origin to associate this mock client with. It should
+  only include the protocol, hostname, and port.
+* `options` {MockClientOptions} Extends the [`Client`][] options.
+* Returns: {MockClient}
+
+The `agent` option is required and must implement the `Agent` interface;
+otherwise an `InvalidArgumentError` is thrown.
+
+#### Parameter: `MockClientOptions`
+
+Extends: `ClientOptions`
+
+* `agent` {MockAgent} The agent to associate this mock client with.
+* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
+  when matching the path of intercepted requests. **Default:** `false`.
+
+### `mockClient.intercept(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {MockInterceptor.Options} The matching criteria for the requests to
+  intercept.
+  * `path` {string|RegExp|Function} The path to match against. A function
+    receives the request path as a `string` and returns a `boolean`.
+  * `method` {string|RegExp|Function} The method to match against. A function
+    receives the request method as a `string` and returns a `boolean`.
+    **Default:** `'GET'`.
+  * `body` {string|RegExp|Function} The body to match against. A function
+    receives the request body as a `string` and returns a `boolean`.
+  * `headers` {Object|Function} The headers to match against, as a map of header
+    name to a `string`, `RegExp`, or matching function, or a single function
+    that receives all headers and returns a `boolean`.
+  * `query` {Object} The query parameters to match against.
+  * `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is
+    ignored when matching. Inherited from the mock client's
+    `ignoreTrailingSlash` option when not set.
+* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
+
+Registers a route on the mock client and returns a [`MockInterceptor`][] for any
+matching request that uses the same origin as this mock client. The interceptor
+is then used to define the reply, for example with `reply()` or
+`replyWithError()`.
+
+```mjs
 import { MockAgent } from 'undici'
 
-// Connections must be set to 1 to return a MockClient instance
 const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+
+mockClient.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
+```
+
+### `mockClient.cleanMocks()`
+
+<!-- YAML
+added: v7.11.0
+-->
 
+Removes all registered interceptors from the mock client. Pending mocks defined
+before this call no longer match incoming requests.
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ connections: 1 })
 const mockClient = mockAgent.get('http://localhost:3000')
+
+mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
+mockClient.cleanMocks()
 ```
 
-## Instance Methods
+### `mockClient.close()`
 
-### `MockClient.intercept(options)`
+<!-- YAML
+added: v4.0.0
+-->
 
-Implements: [`MockPool.intercept(options)`](/docs/docs/api/MockPool.md#mockpoolinterceptoptions)
+* Returns: {Promise} Fulfills with `undefined` once the mock client is closed.
 
-### `MockClient.cleanMocks()`
+Closes the mock client, gracefully waiting for any enqueued requests to
+complete, and removes it from the associated [`MockAgent`][].
 
-Implements: [`MockPool.cleanMocks()`](/docs/docs/api/MockPool.md#mockpoolcleanmocks)
+```mjs
+import { MockAgent } from 'undici'
 
-### `MockClient.close()`
+const mockAgent = new MockAgent({ connections: 1 })
+const mockClient = mockAgent.get('http://localhost:3000')
+
+await mockClient.close()
+```
 
-Implements: [`MockPool.close()`](/docs/docs/api/MockPool.md#mockpoolclose)
+### `mockClient.dispatch(options, handlers)`
 
-### `MockClient.dispatch(options, handlers)`
+<!-- YAML
+added: v4.0.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+* `options` {DispatchOptions} The request options.
+* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait before dispatching further requests, otherwise `true`.
 
-### `MockClient.request(options[, callback])`
+Dispatches a request, matching it against the registered mocks. This override of
+[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
+behaviour for every higher-level method such as `request`.
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+### `mockClient.request(options[, callback])`
 
-#### Example - MockClient request
+<!-- YAML
+added: v4.0.0
+-->
 
-```js
+* `options` {DispatchOptions}
+* `callback` {Function} (optional) Invoked with the response when no `Promise`
+  is requested.
+* Returns: {Promise} Fulfills with the mocked response when no `callback` is
+  provided.
+
+Performs a request and resolves it against the registered mocks. Inherited from
+[`Client`][]; see [`dispatcher.request(options[, callback])`][] for the full
+parameter and return value documentation.
+
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent({ connections: 1 })
-
 const mockClient = mockAgent.get('http://localhost:3000')
 mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await mockClient.request({
+const { statusCode, body } = await mockClient.request({
   origin: 'http://localhost:3000',
   path: '/foo',
   method: 'GET'
@@ -79,3 +189,11 @@ for await (const data of body) {
   console.log('data', data.toString('utf8')) // data foo
 }
 ```
+
+[`Client`]: Client.md#class-client
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockInterceptor`]: MockPool.md#return-mockinterceptor
+[`MockPool`]: MockPool.md#class-mockpool
+[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin

package/node_modules/undici/docs/docs/api/MockErrors.md

@@ -1,12 +1,63 @@
 # MockErrors
 
-Undici exposes a variety of mock error objects that you can use to enhance your mock error handling.
-You can find all the mock error objects inside the `mockErrors` key.
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-errors.js -->
+
+> Stability: 2 - Stable
+
+undici raises a dedicated error when a mocked request cannot be matched against
+any registered interceptor. The mock error classes are exposed through the
+`mockErrors` namespace of the package:
+
+```js
+import { mockErrors } from 'undici'
+
+if (err instanceof mockErrors.MockNotMatchedError) {
+  // handle an unmatched mocked request
+}
+```
+
+Like every other undici error, the classes in this namespace extend
+[`UndiciError`][] and carry a stable `code` string, so failures can be
+distinguished programmatically without relying on the error message.
+
+## Class: `MockNotMatchedError`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {UndiciError}
+
+Thrown when a request issued against a [`MockAgent`][] does not match any of the
+registered mock dispatches and the agent is configured to disable net connect.
+
+* `name` {string} Always `'MockNotMatchedError'`.
+* `code` {string} Always `'UND_MOCK_ERR_MOCK_NOT_MATCHED'`.
+
+### `new MockNotMatchedError([message])`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `message` {string} The error message. **Default:** `'The request does not match any registered mock dispatches'`.
+
+Creates a new `MockNotMatchedError`. When `message` is omitted, a default
+message describing the unmatched request is used.
 
 ```js
 import { mockErrors } from 'undici'
+
+try {
+  // ... perform a request that no mock matches ...
+} catch (err) {
+  if (err.code === 'UND_MOCK_ERR_MOCK_NOT_MATCHED') {
+    console.error('No registered mock matched the request')
+  }
+}
 ```
 
-| Mock Error            | Mock Error Codes                | Description                                                |
-| --------------------- | ------------------------------- | ---------------------------------------------------------- |
-| `MockNotMatchedError` | `UND_MOCK_ERR_MOCK_NOT_MATCHED` | The request does not match any registered mock dispatches. |
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`UndiciError`]: Errors.md#class-undicierror