@noodleseed/one 0.22.0 → 0.24.0

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

@@ -1,27 +1,93 @@
-# Class: ClientStats
+# ClientStats
 
-Stats for a [Client](/docs/docs/api/Client.md).
+<!--introduced_in=v7.9.0-->
+<!--type=module-->
+<!-- source_link=lib/util/stats.js -->
 
-## `new ClientStats(client)`
+> Stability: 2 - Stable
 
-Arguments:
+A `ClientStats` is a point-in-time snapshot of the connection and request
+state of a single [`Client`][]. Instances are not created directly; a fresh
+snapshot is produced each time the [`client.stats`][] getter is read.
 
-* **client** `Client` - Client from which to return stats.
+```mjs
+import { Client } from 'undici'
 
-## Instance Properties
+const client = new Client('http://localhost:3000')
+const stats = client.stats
+console.log(stats.connected, stats.running)
+```
 
-### `ClientStats.connected`
+```cjs
+const { Client } = require('undici')
 
-Boolean if socket as open connection by this client.
+const client = new Client('http://localhost:3000')
+const stats = client.stats
+console.log(stats.connected, stats.running)
+```
 
-### `ClientStats.pending`
+## Class: `ClientStats`
 
-Number of pending requests of this client.
+<!-- YAML
+added: v7.9.0
+-->
 
-### `ClientStats.running`
+Captures the connection and request counters of a [`Client`][] at the moment
+the snapshot is taken. The values are read from the client at construction time
+and do not update afterwards; read [`client.stats`][] again for current values.
 
-Number of currently active requests across this client.
+### `new ClientStats(client)`
 
-### `ClientStats.size`
+<!-- YAML
+added: v7.9.0
+-->
 
-Number of active, pending, or queued requests of this clients.
+* `client` {Client} The client to read the statistics from.
+
+Creates a snapshot from the supplied `client`. This constructor is used
+internally by the [`client.stats`][] getter and is not normally invoked by
+application code.
+
+### `clientStats.connected`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {boolean}
+
+`true` when the client currently has an open socket connection.
+
+### `clientStats.pending`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of open socket connections of this client that do not have an active
+request.
+
+### `clientStats.running`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of currently active requests of this client.
+
+### `clientStats.size`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {number}
+
+Number of active, pending, or queued requests of this client.
+
+[`Client`]: Client.md#class-client
+[`client.stats`]: Client.md#clientstats

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

@@ -1,49 +1,87 @@
 # Connector
 
-Undici creates the underlying socket via the connector builder.
-Normally, this happens automatically and you don't need to care about this,
-but if you need to perform some additional check over the currently used socket,
-this is the right place.
+<!--introduced_in=v4.3.0-->
+<!--type=module-->
+<!-- source_link=lib/core/connect.js -->
 
-If you want to create a custom connector, you must import the `buildConnector` utility.
+> Stability: 2 - Stable
 
-#### Parameter: `buildConnector.BuildOptions`
+undici opens the underlying socket for every request through a *connector*. By
+default this is handled internally, so most applications never interact with the
+connector directly. When a request needs additional control over the socket —
+for example to inspect a TLS certificate, pin a CA fingerprint, or tunnel the
+connection — a custom connector can be supplied through the `connect` option of
+a [`Dispatcher`][].
 
-Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
-Furthermore, the following options can be passed:
+Use the `buildConnector` helper to construct a connector with sensible defaults
+and then wrap it:
 
-* **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
-* **preferH2** `boolean` (optional) - Default: `false` - Only effective together with `allowH2`. When `true`, ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by *client* preference (e.g. some load balancers) so that HTTP/2 is negotiated whenever the server supports it. If the server does not support HTTP/2, ALPN transparently falls back to `http/1.1`.
-* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
-* **timeout** `number | null` (optional) -  In milliseconds. Default `10e3`.
-* **servername** `string | null` (optional)
+```mjs
+import { buildConnector } from 'undici'
 
-Once you call `buildConnector`, it will return a connector function, which takes the following parameters.
-
-#### Parameter: `connector.Options`
-
-* **hostname** `string` (required)
-* **host** `string` (optional)
-* **protocol** `string` (required)
-* **port** `string` (required)
-* **servername** `string` (optional)
-* **localAddress** `string | null` (optional) Local address the socket should connect from.
-* **httpSocket** `Socket` (optional) Establish secure connection on a given socket rather than creating a new socket. It can only be sent on TLS update.
-
-### Basic example
-
-```js
-'use strict'
+const connector = buildConnector({ rejectUnauthorized: false })
+```
 
+`buildConnector` accepts the same TLS options as
+[`tls.connect()`][tls.connect] in addition to the undici-specific options listed
+below, and returns a [`connector`](#connectoroptions-callback) function that
+undici invokes for each new connection.
+
+## `buildConnector([options])`
+
+<!-- YAML
+added: v5.23.4
+-->
+
+* `options` {buildConnector.BuildOptions} (optional) Connection options. In
+  addition to every [`tls.connect()`][tls.connect] option, the following fields
+  are supported:
+  * `allowH2` {boolean} Whether to offer HTTP/2 (`h2`) during TLS ALPN
+    negotiation. **Default:** `true`.
+  * `preferH2` {boolean} Only effective together with `allowH2`. When `true`,
+    ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default
+    `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by
+    *client* preference (for example, some load balancers) so that HTTP/2 is
+    negotiated whenever the server supports it. If the server does not support
+    HTTP/2, ALPN transparently falls back to `http/1.1`. **Default:** `false`.
+  * `maxCachedSessions` {number|null} Maximum number of TLS sessions to cache for
+    reuse. Use `0` to disable TLS session caching. Must be a non-negative
+    integer. **Default:** `100`.
+  * `socketPath` {string|null} An IPC endpoint, either a Unix domain socket or a
+    Windows named pipe. **Default:** `null`.
+  * `timeout` {number|null} The connection timeout in milliseconds. A
+    [`ConnectTimeoutError`][] is raised when the socket fails to connect within
+    this period. **Default:** `10e3`.
+  * `port` {number} The port to connect to when one is not provided to the
+    connector. Defaults to `443` for `https:` and `80` otherwise.
+  * `keepAlive` {boolean|null} Whether to enable TCP keep-alive on the socket.
+    **Default:** `true`.
+  * `keepAliveInitialDelay` {number|null} The delay in milliseconds before the
+    first TCP keep-alive probe is sent on an idle socket. **Default:** `60e3`.
+  * `typeOfService` {number|null} The IP Type of Service (ToS) value to set on
+    the socket. **Default:** `null`.
+* Returns: {buildConnector.connector} A
+  [`connector`](#connectoroptions-callback) function bound to the supplied
+  options.
+
+Builds a connector function. `maxCachedSessions` must be a non-negative integer
+or an [`InvalidArgumentError`][] is thrown.
+
+The returned function may be passed directly as the `connect` option of a
+[`Dispatcher`][], or wrapped to perform extra validation on each socket before it
+is handed back to undici.
+
+```mjs
 import { Client, buildConnector } from 'undici'
 
 const connector = buildConnector({ rejectUnauthorized: false })
+
 const client = new Client('https://localhost:3000', {
   connect (opts, cb) {
     connector(opts, (err, socket) => {
       if (err) {
         cb(err)
-      } else if (/* assertion */) {
+      } else if (/* assertion */ false) {
         socket.destroy()
         cb(new Error('kaboom'))
       } else {
@@ -54,15 +92,53 @@ const client = new Client('https://localhost:3000', {
 })
 ```
 
+## `connector(options, callback)`
+
+<!-- YAML
+added: v4.3.0
+-->
+
+* `options` {Object} Per-connection options provided by undici.
+  * `hostname` {string} The host to connect to.
+  * `host` {string} (optional) The value of the request `Host` header, used to
+    derive the TLS `servername` when one is not supplied.
+  * `protocol` {string} The request protocol, for example `'https:'` or
+    `'http:'`. A value of `'https:'` establishes a TLS connection.
+  * `port` {string} The port to connect to. Defaults to `443` for `https:` and
+    `80` otherwise.
+  * `servername` {string} (optional) The TLS Server Name Indication (SNI) value.
+    Derived from `host` when omitted.
+  * `localAddress` {string|null} (optional) The local address the socket should
+    connect from.
+  * `httpSocket` {Socket} (optional) An existing socket on which to establish the
+    secure connection rather than creating a new one. May only be supplied for a
+    TLS upgrade (`protocol` of `'https:'`).
+* `callback` {Function} Called once the socket has connected or failed.
+  * `err` {Error|null} The connection error, or `null` on success.
+  * `socket` {Socket|TLSSocket|null} The connected socket, or `null` on failure.
+* Returns: {Socket|TLSSocket} The socket being established.
+
+The function returned by [`buildConnector()`](#buildconnectoroptions). undici
+calls it for every new connection. It opens a [`net.Socket`][] for `http:`
+targets or a [`tls.TLSSocket`][] for `https:` targets, applies TCP keep-alive and
+the connect timeout, and invokes `callback` once the socket connects or errors.
+The socket is also returned synchronously.
+
+When connecting over TLS, established sessions are cached (subject to
+`maxCachedSessions`) and reused for subsequent connections to the same
+`servername` or `hostname`.
+
 ### Example: validate the CA fingerprint
 
-```js
-'use strict'
+A custom connector is a convenient place to verify the server certificate before
+any request is sent over the socket.
 
+```mjs
 import { Client, buildConnector } from 'undici'
 
 const caFingerprint = 'FO:OB:AR'
 const connector = buildConnector({ rejectUnauthorized: false })
+
 const client = new Client('https://localhost:3000', {
   connect (opts, cb) {
     connector(opts, (err, socket) => {
@@ -97,20 +173,26 @@ client.request({
 function getIssuerCertificate (socket) {
   let certificate = socket.getPeerCertificate(true)
   while (certificate && Object.keys(certificate).length > 0) {
-    // invalid certificate
+    // Invalid certificate.
     if (certificate.issuerCertificate == null) {
       return null
     }
 
-    // We have reached the root certificate.
-    // In case of self-signed certificates, `issuerCertificate` may be a circular reference.
+    // We have reached the root certificate. In case of self-signed
+    // certificates, `issuerCertificate` may be a circular reference.
     if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
       break
     }
 
-    // continue the loop
     certificate = certificate.issuerCertificate
   }
   return certificate
 }
 ```
+
+[`ConnectTimeoutError`]: Errors.md#class-connecttimeouterror
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`net.Socket`]: https://nodejs.org/api/net.html#class-netsocket
+[`tls.TLSSocket`]: https://nodejs.org/api/tls.html#class-tlstlssocket
+[tls.connect]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback

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

@@ -1,19 +1,51 @@
 # MIME Type Parsing
 
-## `MIMEType` interface
+<!--introduced_in=v4.13.0-->
+<!--type=module-->
+<!-- source_link=lib/web/fetch/data-url.js -->
 
-* **type** `string`
-* **subtype** `string`
-* **parameters** `Map<string, string>`
-* **essence** `string`
+> Stability: 2 - Stable
 
-## `parseMIMEType(input)`
+undici exposes helpers for parsing and serializing MIME types according to the
+WHATWG [MIME Sniffing Standard][]. These are the same primitives undici uses
+internally to interpret `Content-Type` headers and `data:` URLs.
+
+Import the functions from `'undici'`:
+
+```mjs
+import { parseMIMEType, serializeAMimeType } from 'undici'
+```
+
+A parsed MIME type is represented as a plain object with the following shape:
 
-Implements [parse a MIME type](https://mimesniff.spec.whatwg.org/#parse-a-mime-type).
+* `type` {string} The lowercased type, for example `'text'`.
+* `subtype` {string} The lowercased subtype, for example `'html'`.
+* `parameters` {Map<string, string>} The parameters, keyed by lowercased
+  parameter name.
+* `essence` {string} The concatenation of `type`, `'/'`, and `subtype`, for
+  example `'text/html'`.
 
-Parses a MIME type, returning its type, subtype, and any associated parameters. If the parser can't parse an input it returns the string literal `'failure'`.
+## `parseMIMEType(input)`
 
-```js
+<!-- YAML
+added: v4.13.0
+-->
+
+* `input` {string} The MIME type string to parse.
+* Returns: {Object|string} A parsed MIME type record, or the string literal
+  `'failure'` when `input` cannot be parsed.
+  * `type` {string} The lowercased type.
+  * `subtype` {string} The lowercased subtype.
+  * `parameters` {Map<string, string>} The parsed parameters, keyed by
+    lowercased parameter name.
+  * `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
+
+Implements the WHATWG [parse a MIME type][] algorithm. The `type` and `subtype`
+are lowercased, and only the first occurrence of a duplicate parameter name is
+retained. When `input` is empty, lacks a `/`, or otherwise violates the grammar,
+the string literal `'failure'` is returned instead of a record.
+
+```mjs
 import { parseMIMEType } from 'undici'
 
 parseMIMEType('text/html; charset=gbk')
@@ -23,21 +55,31 @@ parseMIMEType('text/html; charset=gbk')
 //   parameters: Map(1) { 'charset' => 'gbk' },
 //   essence: 'text/html'
 // }
-```
-
-Arguments:
 
-* **input** `string`
+parseMIMEType('not a mime type')
+// 'failure'
+```
 
-Returns: `MIMEType|'failure'`
+## `serializeAMimeType(mimeType)`
 
-## `serializeAMimeType(input)`
+<!-- YAML
+added: v5.11.0
+-->
 
-Implements [serialize a MIME type](https://mimesniff.spec.whatwg.org/#serialize-a-mime-type).
+* `mimeType` {Object} A MIME type record, as returned by [`parseMIMEType()`][].
+  * `type` {string} The type.
+  * `subtype` {string} The subtype.
+  * `parameters` {Map<string, string>} The parameters to serialize, in
+    insertion order.
+  * `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
+* Returns: {string} The serialized MIME type.
 
-Serializes a MIMEType object.
+Implements the WHATWG [serialize a MIME type][] algorithm. The essence is
+emitted followed by each parameter as `;name=value`. A parameter value that
+contains characters outside the HTTP token set is quoted, and any `"` or `\`
+characters within it are escaped.
 
-```js
+```mjs
 import { serializeAMimeType } from 'undici'
 
 serializeAMimeType({
@@ -46,12 +88,10 @@ serializeAMimeType({
   parameters: new Map([['charset', 'gbk']]),
   essence: 'text/html'
 })
-// text/html;charset=gbk
-
+// 'text/html;charset=gbk'
 ```
 
-Arguments:
-
-* **mimeType** `MIMEType`
-
-Returns: `string`
+[MIME Sniffing Standard]: https://mimesniff.spec.whatwg.org/
+[`parseMIMEType()`]: #parsemimetypeinput
+[parse a MIME type]: https://mimesniff.spec.whatwg.org/#parse-a-mime-type
+[serialize a MIME type]: https://mimesniff.spec.whatwg.org/#serialize-a-mime-type

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

@@ -1,44 +1,58 @@
-# Cookie Handling
+# Cookies
 
-## `Cookie` interface
+<!--introduced_in=v5.15.0-->
+<!--type=module-->
+<!-- source_link=lib/web/cookies/index.js -->
 
-* **name** `string`
-* **value** `string`
-* **expires** `Date|number` (optional)
-* **maxAge** `number` (optional)
-* **domain** `string` (optional)
-* **path** `string` (optional)
-* **secure** `boolean` (optional)
-* **httpOnly** `boolean` (optional)
-* **sameSite** `'Strict'|'Lax'|'None'` (optional)
-* **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
+> Stability: 2 - Stable
 
-## `deleteCookie(headers, name[, attributes])`
-
-Sets the expiry time of the cookie to the unix epoch, causing browsers to delete it when received.
-
-```js
-import { deleteCookie, Headers } from 'undici'
+A set of helpers for reading and writing HTTP cookies on a [`Headers`][]
+instance, following the [RFC 6265bis][] cookie parsing and serialization
+algorithm. They operate on the `Cookie` request header and the `Set-Cookie`
+response header.
 
-const headers = new Headers()
-deleteCookie(headers, 'name')
-
-console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```mjs
+import { getCookies, setCookie, deleteCookie, getSetCookies, parseCookie } from 'undici'
 ```
 
-Arguments:
+These functions do not manage a cookie jar or perform any network activity; they
+only read from and mutate the supplied `Headers` object.
+
+## `Cookie`
+
+The `Cookie` object describes a single cookie and its attributes. It is the
+return shape of [`parseCookie()`][] and [`getSetCookies()`][], and the input
+shape accepted by [`setCookie()`][].
+
+* `name` {string} The cookie name.
+* `value` {string} The cookie value.
+* `expires` {Date|number} The cookie expiry time, as a `Date` or a Unix
+  timestamp in seconds. (optional)
+* `maxAge` {number} The number of seconds until the cookie expires. (optional)
+* `domain` {string} The hosts the cookie is sent to. (optional)
+* `path` {string} The URL path that must exist for the cookie to be sent.
+  (optional)
+* `secure` {boolean} Whether the cookie is only sent over HTTPS. (optional)
+* `httpOnly` {boolean} Whether the cookie is inaccessible to client-side
+  JavaScript. (optional)
+* `sameSite` {string} Controls whether the cookie is sent with cross-site
+  requests. One of `'Strict'`, `'Lax'`, or `'None'`. (optional)
+* `unparsed` {string[]} Any attributes that were present in the `Set-Cookie`
+  header but not recognized, each formatted as `` `name=value` ``. (optional)
 
-* **headers** `Headers`
-* **name** `string`
-* **attributes** `{ path?: string, domain?: string }` (optional)
+## `getCookies(headers)`
 
-Returns: `void`
+<!-- YAML
+added: v5.15.0
+-->
 
-## `getCookies(headers)`
+* `headers` {Headers} The `Headers` to read the `Cookie` header from.
+* Returns: {Record<string, string>} A map of cookie names to values.
 
-Parses the `Cookie` header and returns a list of attributes and values.
+Parses the `Cookie` header of `headers` and returns its name/value pairs as a
+plain object. An empty object is returned when no `Cookie` header is present.
 
-```js
+```mjs
 import { getCookies, Headers } from 'undici'
 
 const headers = new Headers({
@@ -48,17 +62,48 @@ const headers = new Headers({
 console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
 ```
 
-Arguments:
+## `deleteCookie(headers, name[, attributes])`
+
+<!-- YAML
+added: v5.15.0
+-->
 
-* **headers** `Headers`
+* `headers` {Headers} The `Headers` to append the expiring cookie to.
+* `name` {string} The name of the cookie to delete.
+* `attributes` {Object} (optional)
+  * `path` {string} The path the cookie was scoped to. **Default:** `null`.
+  * `domain` {string} The domain the cookie was scoped to. **Default:** `null`.
+* Returns: {undefined}
 
-Returns: `Record<string, string>`
+Appends a `Set-Cookie` header to `headers` that expires the named cookie by
+setting its expiry time to the Unix epoch, causing a client to delete it on
+receipt. The optional `path` and `domain` must match those of the cookie being
+removed.
+
+```mjs
+import { deleteCookie, Headers } from 'undici'
+
+const headers = new Headers()
+deleteCookie(headers, 'name')
+
+console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```
 
 ## `getSetCookies(headers)`
 
-Parses all `Set-Cookie` headers.
+<!-- YAML
+added: v5.15.0
+-->
 
-```js
+* `headers` {Headers} The `Headers` to read the `Set-Cookie` headers from.
+* Returns: {Cookie[]} The parsed cookies, or an empty array when none are
+  present.
+
+Parses every `Set-Cookie` header of `headers` and returns the resulting
+[`Cookie`][] objects. A header that fails to parse yields a `null` entry at its
+position in the returned array.
+
+```mjs
 import { getSetCookies, Headers } from 'undici'
 
 const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
@@ -71,20 +116,23 @@ console.log(getSetCookies(headers))
 //     secure: true
 //   }
 // ]
-
 ```
 
-Arguments:
-
-* **headers** `Headers`
+## `setCookie(headers, cookie)`
 
-Returns: `Cookie[]`
+<!-- YAML
+added: v5.15.0
+-->
 
-## `setCookie(headers, cookie)`
+* `headers` {Headers} The `Headers` to append the `Set-Cookie` header to.
+* `cookie` {Cookie} The cookie to serialize. See [`Cookie`][].
+* Returns: {undefined}
 
-Appends a cookie to the `Set-Cookie` header.
+Serializes `cookie` and appends it to the `Set-Cookie` header of `headers`. When
+the cookie name is empty, serialization yields no value and no header is
+appended.
 
-```js
+```mjs
 import { setCookie, Headers } from 'undici'
 
 const headers = new Headers()
@@ -93,9 +141,39 @@ setCookie(headers, { name: 'undici', value: 'setCookie' })
 console.log(headers.get('Set-Cookie')) // undici=setCookie
 ```
 
-Arguments:
+## `parseCookie(cookie)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `cookie` {string} A `Set-Cookie` header value.
+* Returns: {Cookie|null} The parsed cookie, or `null` if `cookie` is invalid.
 
-* **headers** `Headers`
-* **cookie** `Cookie`
+Parses a single `Set-Cookie` header value into a [`Cookie`][] object. `null` is
+returned when the value contains control characters or otherwise cannot be
+parsed.
+
+```mjs
+import { parseCookie } from 'undici'
+
+console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
+// {
+//   name: 'undici',
+//   value: 'getSetCookies',
+//   secure: true,
+//   sameSite: 'Lax'
+// }
+```
 
-Returns: `void`
+The cookie value is returned exactly as it appears in the header; percent-encoded
+sequences such as `%20` or `%0D%0A` are not decoded. The `sameSite` attribute is
+only set when the value is a case-insensitive match for `Strict`, `Lax`, or
+`None`.
+
+[RFC 6265bis]: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis
+[`Cookie`]: #cookie
+[`Headers`]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
+[`getSetCookies()`]: #getsetcookiesheaders
+[`parseCookie()`]: #parsecookiecookie
+[`setCookie()`]: #setcookieheaders-cookie