@emiliosp/pi-maestro 0.17.0 → 0.18.0

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

@@ -1,618 +0,0 @@
-# MockPool
-
-<!--introduced_in=v4.0.0-->
-<!--type=module-->
-<!-- source_link=lib/mock/mock-pool.js -->
-
-> Stability: 2 - Stable
-
-A `MockPool` is a [`Pool`][] that intercepts requests matching registered routes
-and replies with mocked responses instead of contacting the network. It is
-created by a [`MockAgent`][] and exposes the same interception API as
-[`MockClient`][].
-
-A `MockPool` is not constructed directly in most cases; instead it is obtained
-through [`mockAgent.get(origin)`][]. Once registered as the global dispatcher,
-any request whose origin matches the pool is matched against the mocks it holds.
-
-```mjs
-import { MockAgent } from 'undici'
-
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-```
-
-```cjs
-const { MockAgent } = require('undici')
-
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-```
-
-## Class: `MockPool`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* Extends: {Pool}
-
-Extends [`Pool`][] and implements the `Interceptable` interface, allowing
-requests made through it to be matched against registered mocks.
-
-### `new MockPool(origin[, options])`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* `origin` {string} The origin to associate this mock pool with. It should only
-  include the protocol, hostname, and port.
-* `options` {MockPoolOptions} Extends the [`Pool`][] options.
-* Returns: {MockPool}
-
-The `agent` option is required and must implement the `Agent` interface;
-otherwise an `InvalidArgumentError` is thrown.
-
-#### Parameter: `MockPoolOptions`
-
-Extends: `PoolOptions`
-
-* `agent` {MockAgent} The agent to associate this mock pool with.
-* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
-  when matching the path of intercepted requests. **Default:** `false`.
-
-### `mockPool.intercept(options)`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* `options` {MockPoolInterceptOptions} The matching criteria for the requests to
-  intercept.
-* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
-
-Registers a route on the mock pool and returns a [`MockInterceptor`][] for any
-matching request that uses the same origin as this mock pool. The interceptor is
-then used to define the reply, for example with `reply()` or `replyWithError()`.
-
-Each `intercept()` call is consumed by a single matching request. To match more
-than one request, call `intercept()` once per expected request, or use
-`persist()` or `times()` on the returned [`MockScope`][]. When no registered
-mock matches a request, a real request is attempted unless network connections
-have been disabled on the [`MockAgent`][], in which case a `MockNotMatchedError`
-is thrown.
-
-A request is intercepted only when every defined matcher passes. The accepted
-matcher forms behave as follows:
-
-| Matcher type | Condition to pass            |
-| :----------: | ---------------------------- |
-| `string`     | Exact match against the value |
-| `RegExp`     | The expression must match    |
-| `Function`   | The function must return `true` |
-
-#### Parameter: `MockPoolInterceptOptions`
-
-* `path` {string|RegExp|Function} A matcher for the HTTP request path. The
-  function form has the signature `(path: string) => boolean`. When a `RegExp`
-  or function is used, it matches against the request path including all query
-  parameters in alphabetical order. When a `string` is used, query parameters
-  can instead be supplied through `query`.
-* `method` {string|RegExp|Function} A matcher for the HTTP request method. The
-  function form has the signature `(method: string) => boolean`.
-  **Default:** `'GET'`.
-* `body` {string|RegExp|Function} A matcher for the HTTP request body. The
-  function form has the signature `(body: string) => boolean`.
-* `headers` {Object|Function} A matcher for the HTTP request headers, given
-  either as a map of header name to a `string`, `RegExp`, or
-  `(value: string) => boolean` matcher, or as a single function that receives
-  all headers and returns a `boolean`. When a map is used, the request must
-  match every defined header; extra headers not listed here do not affect
-  matching.
-* `query` {Object} A matcher for the HTTP request query string parameters. Only
-  applies when a `string` was provided for `path`.
-* `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is ignored
-  when matching. Inherited from the mock pool's `ignoreTrailingSlash` option
-  when not set.
-
-#### Return: `MockInterceptor`
-
-The reply behaviour of a matching request is defined through the returned
-`MockInterceptor`.
-
-* `reply(statusCode[, data[, responseOptions]])` {Function} Defines the reply
-  for a matching request.
-  * `statusCode` {number} The status code of the mocked reply.
-  * `data` {string|Buffer|Object|Function} The body of the mocked reply.
-    Objects are serialized to JSON; strings and `Buffer`s are sent as-is. The
-    function form has the signature
-    `(opts: MockResponseCallbackOptions) => string | Buffer | Object` and is
-    invoked with the incoming request to compute the reply body.
-  * `responseOptions` {MockResponseOptions} Additional reply options.
-    **Default:** `{}`.
-  * Returns: {MockScope}
-* `reply(callback)` {Function} Defines the reply for a matching request,
-  computing all reply options dynamically rather than just the body.
-  * `callback` {Function} A `(opts: MockResponseCallbackOptions) =>
-    { statusCode, data, responseOptions }` function invoked with the incoming
-    request. The callback may be asynchronous; a returned promise is awaited
-    and must resolve to the same shape.
-  * Returns: {MockScope}
-* `replyWithError(error)` {Function} Defines an error for a matching request to
-  throw.
-  * `error` {Error} The error thrown when a request matches.
-  * Returns: {MockScope}
-* `defaultReplyHeaders(headers)` {Function} Sets default headers included on
-  every subsequent reply defined on this interceptor, in addition to any headers
-  set on a specific reply.
-  * `headers` {Object} A map of header name to value.
-  * Returns: {MockInterceptor}
-* `defaultReplyTrailers(trailers)` {Function} Sets default trailers included on
-  every subsequent reply defined on this interceptor, in addition to any
-  trailers set on a specific reply.
-  * `trailers` {Object} A map of trailer name to value.
-  * Returns: {MockInterceptor}
-* `replyContentLength()` {Function} Sets an automatically calculated
-  `content-length` header on every subsequent reply defined on this interceptor.
-  * Returns: {MockInterceptor}
-
-By default, `reply()` and `replyWithError()` define the behaviour for the first
-matching request only; subsequent requests are not affected unless `persist()`
-or `times()` is used on the returned [`MockScope`][].
-
-#### Parameter: `MockResponseCallbackOptions`
-
-The argument passed to the `reply()` data and options callbacks.
-
-* `path` {string} The path of the intercepted request.
-* `method` {string} The method of the intercepted request.
-* `headers` {Object|Headers} The headers of the intercepted request.
-* `origin` {string} The origin of the intercepted request.
-* `body` {string|null} The body of the intercepted request.
-
-#### Parameter: `MockResponseOptions`
-
-* `headers` {Object} Headers to include on the mocked reply.
-* `trailers` {Object} Trailers to include on the mocked reply.
-
-#### Return: `MockScope`
-
-A `MockScope` is associated with a single [`MockInterceptor`][] and configures
-how many times the defined reply is used.
-
-* `delay(waitInMs)` {Function} Delays the associated reply by a set amount of
-  time.
-  * `waitInMs` {number} The delay in milliseconds.
-  * Returns: {MockScope}
-* `persist()` {Function} Makes the associated reply match indefinitely, so every
-  matching request receives the defined response.
-  * Returns: {MockScope}
-* `times(repeatTimes)` {Function} Makes the associated reply match a fixed number
-  of times. This is overridden by `persist()`.
-  * `repeatTimes` {number} The number of matching requests the reply applies to.
-  * Returns: {MockScope}
-
-The following examples show common interception patterns.
-
-```mjs displayName="Basic mocked request"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-
-const { statusCode, body } = await request('http://localhost:3000/foo')
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-```mjs displayName="Reply with a data callback"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/echo',
-  method: 'GET'
-}).reply(200, ({ headers }) => ({ message: headers.message }))
-
-const { statusCode, body } = await request('http://localhost:3000/echo', {
-  headers: { message: 'hello world!' }
-})
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
-}
-```
-
-```mjs displayName="Reply with an options callback"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/echo',
-  method: 'GET'
-}).reply(({ headers }) => ({
-  statusCode: 200,
-  data: { message: headers.message }
-}))
-
-const { statusCode, body } = await request('http://localhost:3000/echo', {
-  headers: { message: 'hello world!' }
-})
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
-}
-```
-
-```mjs displayName="Reply with an asynchronous options callback"
-import { readFile } from 'node:fs/promises'
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/fixture',
-  method: 'GET'
-}).reply(async ({ path }) => ({
-  statusCode: 200,
-  data: await readFile(new URL('./fixture.json', import.meta.url))
-}))
-
-const { statusCode, body } = await request('http://localhost:3000/fixture')
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // contents of fixture.json
-}
-```
-
-```mjs displayName="Multiple intercepts"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
-mockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')
-
-const fooResult = await request('http://localhost:3000/foo')
-for await (const data of fooResult.body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-
-const helloResult = await request('http://localhost:3000/hello')
-for await (const data of helloResult.body) {
-  console.log('data', data.toString('utf8')) // data hello
-}
-```
-
-```mjs displayName="Match query, body, request headers; reply with headers and trailers"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/foo?hello=there&see=ya',
-  method: 'POST',
-  body: 'form1=data1&form2=data2',
-  headers: {
-    'User-Agent': 'undici',
-    Host: 'example.com'
-  }
-}).reply(200, { foo: 'bar' }, {
-  headers: { 'content-type': 'application/json' },
-  trailers: { 'Content-MD5': 'test' }
-})
-
-const { statusCode, headers, trailers, body } = await request(
-  'http://localhost:3000/foo?hello=there&see=ya',
-  {
-    method: 'POST',
-    body: 'form1=data1&form2=data2',
-    headers: {
-      foo: 'bar',
-      'User-Agent': 'undici',
-      Host: 'example.com'
-    }
-  }
-)
-
-console.log('response received', statusCode) // response received 200
-console.log('headers', headers) // { 'content-type': 'application/json' }
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // {"foo":"bar"}
-}
-
-console.log('trailers', trailers) // { 'content-md5': 'test' }
-```
-
-```mjs displayName="Different matcher forms"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/foo',
-  method: /^GET$/,
-  body: (value) => value === 'form=data',
-  headers: {
-    'User-Agent': 'undici',
-    Host: /^example\.com$/
-  }
-}).reply(200, 'foo')
-
-const { statusCode, body } = await request('http://localhost:3000/foo', {
-  method: 'GET',
-  body: 'form=data',
-  headers: {
-    foo: 'bar',
-    'User-Agent': 'undici',
-    Host: 'example.com'
-  }
-})
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-```mjs displayName="Reply with an error"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).replyWithError(new Error('kaboom'))
-
-try {
-  await request('http://localhost:3000/foo', { method: 'GET' })
-} catch (error) {
-  console.error(error.message) // kaboom
-}
-```
-
-```mjs displayName="Default reply headers"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' })
-  .defaultReplyHeaders({ foo: 'bar' })
-  .reply(200, 'foo')
-
-const { headers } = await request('http://localhost:3000/foo')
-
-console.log('headers', headers) // headers { foo: 'bar' }
-```
-
-```mjs displayName="Default reply trailers"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' })
-  .defaultReplyTrailers({ foo: 'bar' })
-  .reply(200, 'foo')
-
-const { trailers } = await request('http://localhost:3000/foo')
-
-console.log('trailers', trailers) // trailers { foo: 'bar' }
-```
-
-```mjs displayName="Automatic content-length"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' })
-  .replyContentLength()
-  .reply(200, 'foo')
-
-const { headers } = await request('http://localhost:3000/foo')
-
-console.log('headers', headers) // headers { 'content-length': '3' }
-```
-
-```mjs displayName="Persisted reply"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()
-
-await request('http://localhost:3000/foo') // Matches and returns the mock
-await request('http://localhost:3000/foo') // Matches again, indefinitely
-```
-
-```mjs displayName="Reply a fixed number of times"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)
-
-await request('http://localhost:3000/foo') // Matches and returns the mock
-await request('http://localhost:3000/foo') // Matches and returns the mock
-await request('http://localhost:3000/foo') // No match; a real request is attempted
-```
-
-```mjs displayName="Match the path with a function"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
-import querystring from 'node:querystring'
-
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
-
-const mockPool = mockAgent.get('http://localhost:3000')
-
-const matchPath = (requestPath) => {
-  const [pathname, search] = requestPath.split('?')
-  const requestQuery = querystring.parse(search)
-
-  if (!pathname.startsWith('/foo')) {
-    return false
-  }
-
-  return requestQuery.foo === 'bar'
-}
-
-mockPool.intercept({ path: matchPath, method: 'GET' }).reply(200, 'foo')
-
-await request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock
-```
-
-### `mockPool.close()`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* Returns: {Promise} Fulfills with `undefined` once the mock pool is closed.
-
-Closes the mock pool, gracefully waiting for any enqueued requests to complete,
-and removes it from the associated [`MockAgent`][].
-
-```mjs
-import { MockAgent } from 'undici'
-
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-
-await mockPool.close()
-```
-
-### `mockPool.dispatch(options, handlers)`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* `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`.
-
-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`.
-
-### `mockPool.request(options[, callback])`
-
-<!-- YAML
-added: v4.0.0
--->
-
-* `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
-[`Pool`][]; see [`dispatcher.request(options[, callback])`][] for the full
-parameter and return value documentation.
-
-```mjs
-import { MockAgent } from 'undici'
-
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
-
-const { statusCode, body } = await mockPool.request({
-  origin: 'http://localhost:3000',
-  path: '/foo',
-  method: 'GET'
-})
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-### `mockPool.cleanMocks()`
-
-<!-- YAML
-added: v7.11.0
--->
-
-* Returns: {undefined}
-
-Removes all registered interceptors from the mock pool. Pending mocks defined
-before this call no longer match incoming requests.
-
-```mjs
-import { MockAgent } from 'undici'
-
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-
-mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
-mockPool.cleanMocks()
-```
-
-[`MockAgent`]: MockAgent.md#class-mockagent
-[`MockClient`]: MockClient.md#class-mockclient
-[`MockInterceptor`]: MockPool.md#return-mockinterceptor
-[`MockScope`]: MockPool.md#return-mockscope
-[`Pool`]: Pool.md#class-pool
-[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
-[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
-[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin