monitor-transfer-dsh 0.0.0-stage → 0.1.2

package/skill/tools/node_modules/undici/docs/docs/api/MockCallHistory.md

@@ -0,0 +1,371 @@
+# MockCallHistory
+
+<!--introduced_in=v7.5.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-call-history.js -->
+
+> Stability: 2 - Stable
+
+A `MockCallHistory` records the configuration of every request intercepted by a
+[`MockAgent`][] for which call history is enabled. Each recorded request is
+stored as a [`MockCallHistoryLog`][], and the `MockCallHistory` exposes helpers
+to read and filter those logs in tests.
+
+Instances are not created directly. Enable call history on a [`MockAgent`][] and
+retrieve the history with `mockAgent.getCallHistory()`:
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+const callHistory = mockAgent.getCallHistory()
+```
+
+Call history can also be enabled after construction:
+
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent()
+mockAgent.enableCallHistory()
+const callHistory = mockAgent.getCallHistory()
+```
+
+## Class: `MockCallHistory`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+Tracks the configuration of intercepted requests as an ordered collection of
+[`MockCallHistoryLog`][] entries.
+
+A `MockCallHistory` is iterable. Use it with a `for...of` loop, the spread
+operator, or any constructor that accepts an iterable:
+
+```mjs
+for (const log of mockAgent.getCallHistory()) {
+  // ...
+}
+
+const logs = [...mockAgent.getCallHistory()]
+const logSet = new Set(mockAgent.getCallHistory())
+```
+
+### `mockCallHistory.calls()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockCallHistoryLog[]} All recorded logs, in the order the requests
+  were intercepted.
+
+Returns every recorded [`MockCallHistoryLog`][] as an array.
+
+```mjs
+mockAgent.getCallHistory()?.calls()
+```
+
+### `mockCallHistory.firstCall()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockCallHistoryLog|undefined} The first recorded log, or `undefined`
+  when no request has been recorded.
+
+Returns the first recorded [`MockCallHistoryLog`][].
+
+```mjs
+mockAgent.getCallHistory()?.firstCall()
+```
+
+### `mockCallHistory.lastCall()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {MockCallHistoryLog|undefined} The last recorded log, or `undefined`
+  when no request has been recorded.
+
+Returns the last recorded [`MockCallHistoryLog`][].
+
+```mjs
+mockAgent.getCallHistory()?.lastCall()
+```
+
+### `mockCallHistory.nthCall(position)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `position` {number} The 1-based position of the log to return. Must be a
+  positive integer.
+* Returns: {MockCallHistoryLog|undefined} The log at `position`, or `undefined`
+  when no log exists at that position.
+
+Returns the [`MockCallHistoryLog`][] at the given 1-based `position`. The index
+is 1-based for readability, so `nthCall(1)` is equivalent to `firstCall()`.
+
+Throws an [`InvalidArgumentError`][] when `position` is not a number, not an
+integer, or not positive. Use `firstCall()` or `lastCall()` instead of passing a
+non-positive value.
+
+```mjs
+mockAgent.getCallHistory()?.nthCall(3) // the third recorded log
+```
+
+### `mockCallHistory.filterCalls(criteria[, options])`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {Function|RegExp|Object} The filter to apply.
+  * When a {Function} is given, it is used as the predicate of
+    `Array.prototype.filter` and receives each [`MockCallHistoryLog`][]; logs for
+    which it returns a truthy value are kept.
+  * When a {RegExp} is given, a log is kept when the expression matches its
+    [`mockCallHistoryLog.toString()`][] representation.
+  * When an {Object} is given, each property is a request field to filter on and
+    each value is a [filter parameter](#filter-parameter). An empty object
+    returns every log.
+    * `protocol` {string|RegExp|null|undefined} Filters by request protocol.
+    * `host` {string|RegExp|null|undefined} Filters by request host.
+    * `port` {string|RegExp|null|undefined} Filters by request port.
+    * `origin` {string|RegExp|null|undefined} Filters by request origin.
+    * `path` {string|RegExp|null|undefined} Filters by request path.
+    * `hash` {string|RegExp|null|undefined} Filters by request hash.
+    * `fullUrl` {string|RegExp|null|undefined} Filters by request full URL.
+    * `method` {string|RegExp|null|undefined} Filters by request method.
+* `options` {Object} Adjusts the filtering behavior. Only applied when `criteria`
+  is an object. (optional)
+  * `operator` {string} How to combine multiple object properties. `'OR'` keeps
+    a log matching any criterion; `'AND'` keeps a log matching every criterion.
+    The value is case-insensitive. **Default:** `'OR'`.
+* Returns: {MockCallHistoryLog[]} The matching logs. Duplicates produced by an
+  `'OR'` combination are removed.
+
+A convenience method for applying one or several filters at once. It is a more
+expressive alternative to the per-field helpers below.
+
+Throws an [`InvalidArgumentError`][] when `criteria` is not a function, regular
+expression, or object, or when `options.operator` is neither `'OR'` nor `'AND'`.
+
+```mjs
+const callHistory = mockAgent.getCallHistory()
+
+callHistory?.filterCalls((log) =>
+  log.hash === '#hash' && log.headers?.authorization !== undefined)
+
+callHistory?.filterCalls(/"errors": "wrong body"/)
+
+// Logs with a hash containing `my-hash` OR a path equal to `/endpoint`.
+callHistory?.filterCalls({ hash: /my-hash/, path: '/endpoint' })
+
+// Logs with a hash containing `my-hash` AND a path equal to `/endpoint`.
+callHistory?.filterCalls(
+  { hash: /my-hash/, path: '/endpoint' },
+  { operator: 'AND' }
+)
+```
+
+### `mockCallHistory.filterCallsByProtocol(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose protocol matches `criteria`.
+
+Filters the recorded logs by request protocol.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
+mockAgent.getCallHistory()?.filterCallsByProtocol('https:')
+```
+
+### `mockCallHistory.filterCallsByHost(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose host matches `criteria`.
+
+Filters the recorded logs by request host.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
+mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')
+```
+
+### `mockCallHistory.filterCallsByPort(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose port matches `criteria`.
+
+Filters the recorded logs by request port.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
+mockAgent.getCallHistory()?.filterCallsByPort('3000')
+mockAgent.getCallHistory()?.filterCallsByPort('')
+```
+
+### `mockCallHistory.filterCallsByOrigin(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose origin matches `criteria`.
+
+Filters the recorded logs by request origin.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
+mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')
+```
+
+### `mockCallHistory.filterCallsByPath(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose path matches `criteria`.
+
+Filters the recorded logs by request path.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
+mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')
+```
+
+### `mockCallHistory.filterCallsByHash(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose hash matches `criteria`.
+
+Filters the recorded logs by request hash.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
+mockAgent.getCallHistory()?.filterCallsByHash('#hash')
+```
+
+### `mockCallHistory.filterCallsByFullUrl(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose full URL matches `criteria`.
+
+Filters the recorded logs by request full URL. The full URL contains the
+protocol, host, port, path, query parameters, and hash.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
+mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')
+```
+
+### `mockCallHistory.filterCallsByMethod(criteria)`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* `criteria` {string|RegExp|null|undefined} See
+  [filter parameter](#filter-parameter).
+* Returns: {MockCallHistoryLog[]} The logs whose method matches `criteria`.
+
+Filters the recorded logs by request method.
+
+```mjs
+mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
+mockAgent.getCallHistory()?.filterCallsByMethod('POST')
+```
+
+### `mockCallHistory.clear()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {undefined}
+
+Removes every recorded [`MockCallHistoryLog`][]. This is performed
+automatically when `mockAgent.close()` is called.
+
+```mjs
+mockAgent.clearCallHistory()
+// Equivalent to:
+mockAgent.getCallHistory()?.clear()
+```
+
+### `mockCallHistory[Symbol.iterator]()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* Returns: {Generator} A generator yielding each recorded
+  [`MockCallHistoryLog`][] in order.
+
+Makes a `MockCallHistory` iterable, yielding the same logs returned by
+`calls()`. This enables `for...of` iteration, the spread operator, and
+constructing other iterables from a history.
+
+```mjs
+const callHistory = mockAgent.getCallHistory()
+
+for (const log of callHistory) {
+  console.log(log.method, log.fullUrl)
+}
+
+const logs = [...callHistory]
+```
+
+## Filter parameter
+
+The per-field `filterCallsBy*` helpers and the object form of `filterCalls()`
+accept a filter parameter that is matched against the corresponding field of each
+[`MockCallHistoryLog`][]:
+
+* A {string} keeps a log only when the field is strictly equal to the value.
+* `null` keeps a log only when the field is strictly equal to `null`.
+* `undefined` keeps a log only when the field is strictly equal to `undefined`.
+* A {RegExp} keeps a log only when the expression matches the field.
+
+Any other value throws an [`InvalidArgumentError`][].
+
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockCallHistoryLog`]: MockCallHistoryLog.md#class-mockcallhistorylog
+[`mockCallHistoryLog.toString()`]: MockCallHistoryLog.md#mockcallhistorylogtostring

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

@@ -0,0 +1,206 @@
+# MockCallHistoryLog
+
+<!--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'
+
+const mockAgent = new MockAgent({ enableCallHistory: true })
+
+// after some requests have been intercepted:
+const log = mockAgent.getCallHistory()?.firstCall()
+```
+
+## 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
+-->
+
+* Type: {string}
+
+The origin of the intercepted request, comprising the protocol and host, for
+example `'https://localhost:4000'`.
+
+### `mockCallHistoryLog.path`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* 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'
+```
+
+### `mockCallHistoryLog.toString()`
+
+<!-- YAML
+added: v7.5.0
+-->
+
+* 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