@node-core/utils 7.2.0 → 7.2.2

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

@@ -1,115 +0,0 @@
-# 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.
-
-If you want to create a custom connector, you must import the `buildConnector` utility.
-
-#### Parameter: `buildConnector.BuildOptions`
-
-Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
-Furthermore, the following options can be passed:
-
-* **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
-* **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)
-
-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'
-
-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 */) {
-        socket.destroy()
-        cb(new Error('kaboom'))
-      } else {
-        cb(null, socket)
-      }
-    })
-  }
-})
-```
-
-### Example: validate the CA fingerprint
-
-```js
-'use strict'
-
-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) => {
-      if (err) {
-        cb(err)
-      } else if (getIssuerCertificate(socket).fingerprint256 !== caFingerprint) {
-        socket.destroy()
-        cb(new Error('Fingerprint does not match or malformed certificate'))
-      } else {
-        cb(null, socket)
-      }
-    })
-  }
-})
-
-client.request({
-  path: '/',
-  method: 'GET'
-}, (err, data) => {
-  if (err) throw err
-
-  const bufs = []
-  data.body.on('data', (buf) => {
-    bufs.push(buf)
-  })
-  data.body.on('end', () => {
-    console.log(Buffer.concat(bufs).toString('utf8'))
-    client.close()
-  })
-})
-
-function getIssuerCertificate (socket) {
-  let certificate = socket.getPeerCertificate(true)
-  while (certificate && Object.keys(certificate).length > 0) {
-    // 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.
-    if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
-      break
-    }
-
-    // continue the loop
-    certificate = certificate.issuerCertificate
-  }
-  return certificate
-}
-```

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

@@ -1,57 +0,0 @@
-# MIME Type Parsing
-
-## `MIMEType` interface
-
-* **type** `string`
-* **subtype** `string`
-* **parameters** `Map<string, string>`
-* **essence** `string`
-
-## `parseMIMEType(input)`
-
-Implements [parse a MIME type](https://mimesniff.spec.whatwg.org/#parse-a-mime-type).
-
-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'`.
-
-```js
-import { parseMIMEType } from 'undici'
-
-parseMIMEType('text/html; charset=gbk')
-// {
-//   type: 'text',
-//   subtype: 'html',
-//   parameters: Map(1) { 'charset' => 'gbk' },
-//   essence: 'text/html'
-// }
-```
-
-Arguments:
-
-* **input** `string`
-
-Returns: `MIMEType|'failure'`
-
-## `serializeAMimeType(input)`
-
-Implements [serialize a MIME type](https://mimesniff.spec.whatwg.org/#serialize-a-mime-type).
-
-Serializes a MIMEType object.
-
-```js
-import { serializeAMimeType } from 'undici'
-
-serializeAMimeType({
-  type: 'text',
-  subtype: 'html',
-  parameters: new Map([['charset', 'gbk']]),
-  essence: 'text/html'
-})
-// text/html;charset=gbk
-
-```
-
-Arguments:
-
-* **mimeType** `MIMEType`
-
-Returns: `string`

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

@@ -1,101 +0,0 @@
-# Cookie Handling
-
-## `Cookie` interface
-
-* **name** `string`
-* **value** `string`
-* **expires** `Date|number` (optional)
-* **maxAge** `number` (optional)
-* **domain** `string` (optional)
-* **path** `string` (optional)
-* **secure** `boolean` (optional)
-* **httpOnly** `boolean` (optional)
-* **sameSite** `'String'|'Lax'|'None'` (optional)
-* **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
-
-## `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'
-
-const headers = new Headers()
-deleteCookie(headers, 'name')
-
-console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
-```
-
-Arguments:
-
-* **headers** `Headers`
-* **name** `string`
-* **attributes** `{ path?: string, domain?: string }` (optional)
-
-Returns: `void`
-
-## `getCookies(headers)`
-
-Parses the `Cookie` header and returns a list of attributes and values.
-
-```js
-import { getCookies, Headers } from 'undici'
-
-const headers = new Headers({
-  cookie: 'get=cookies; and=attributes'
-})
-
-console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
-```
-
-Arguments:
-
-* **headers** `Headers`
-
-Returns: `Record<string, string>`
-
-## `getSetCookies(headers)`
-
-Parses all `Set-Cookie` headers.
-
-```js
-import { getSetCookies, Headers } from 'undici'
-
-const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
-
-console.log(getSetCookies(headers))
-// [
-//   {
-//     name: 'undici',
-//     value: 'getSetCookies',
-//     secure: true
-//   }
-// ]
-
-```
-
-Arguments:
-
-* **headers** `Headers`
-
-Returns: `Cookie[]`
-
-## `setCookie(headers, cookie)`
-
-Appends a cookie to the `Set-Cookie` header.
-
-```js
-import { setCookie, Headers } from 'undici'
-
-const headers = new Headers()
-setCookie(headers, { name: 'undici', value: 'setCookie' })
-
-console.log(headers.get('Set-Cookie')) // undici=setCookie
-```
-
-Arguments:
-
-* **headers** `Headers`
-* **cookie** `Cookie`
-
-Returns: `void`

package/node_modules/cheerio/node_modules/undici/docs/docs/api/Debug.md

@@ -1,62 +0,0 @@
-# Debug
-
-Undici (and subsenquently `fetch` and `websocket`) exposes a debug statement that can be enabled by setting `NODE_DEBUG` within the environment.
-
-The flags available are:
-
-## `undici`
-
-This flag enables debug statements for the core undici library.
-
-```sh
-NODE_DEBUG=undici node script.js
-
-UNDICI 16241: connecting to nodejs.org using https:h1
-UNDICI 16241: connecting to nodejs.org using https:h1
-UNDICI 16241: connected to nodejs.org using https:h1
-UNDICI 16241: sending request to GET https://nodejs.org/
-UNDICI 16241: received response to GET https://nodejs.org/ - HTTP 307
-UNDICI 16241: connecting to nodejs.org using https:h1
-UNDICI 16241: trailers received from GET https://nodejs.org/
-UNDICI 16241: connected to nodejs.org using https:h1
-UNDICI 16241: sending request to GET https://nodejs.org/en
-UNDICI 16241: received response to GET https://nodejs.org/en - HTTP 200
-UNDICI 16241: trailers received from GET https://nodejs.org/en
-```
-
-## `fetch`
-
-This flag enables debug statements for the `fetch` API.
-
-> **Note**: statements are pretty similar to the ones in the `undici` flag, but scoped to `fetch`
-
-```sh
-NODE_DEBUG=fetch node script.js
-
-FETCH 16241: connecting to nodejs.org using https:h1
-FETCH 16241: connecting to nodejs.org using https:h1
-FETCH 16241: connected to nodejs.org using https:h1
-FETCH 16241: sending request to GET https://nodejs.org/
-FETCH 16241: received response to GET https://nodejs.org/ - HTTP 307
-FETCH 16241: connecting to nodejs.org using https:h1
-FETCH 16241: trailers received from GET https://nodejs.org/
-FETCH 16241: connected to nodejs.org using https:h1
-FETCH 16241: sending request to GET https://nodejs.org/en
-FETCH 16241: received response to GET https://nodejs.org/en - HTTP 200
-FETCH 16241: trailers received from GET https://nodejs.org/en
-```
-
-## `websocket`
-
-This flag enables debug statements for the `Websocket` API.
-
-> **Note**: statements can overlap with `UNDICI` ones if `undici` or `fetch` flag has been enabled as well.
-
-```sh
-NODE_DEBUG=websocket node script.js
-
-WEBSOCKET 18309: connecting to echo.websocket.org using https:h1
-WEBSOCKET 18309: connected to echo.websocket.org using https:h1
-WEBSOCKET 18309: sending request to GET https://echo.websocket.org/
-WEBSOCKET 18309: connection opened <ip_address>
-```

package/node_modules/cheerio/node_modules/undici/docs/docs/api/DiagnosticsChannel.md

@@ -1,315 +0,0 @@
-# Diagnostics Channel Support
-
-Stability: Experimental.
-
-Undici supports the [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) (currently available only on Node.js v16+).
-It is the preferred way to instrument Undici and retrieve internal information.
-
-The channels available are the following.
-
-## `undici:request:create`
-
-This message is published when a new outgoing request is created.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
-  console.log('origin', request.origin)
-  console.log('completed', request.completed)
-  console.log('method', request.method)
-  console.log('path', request.path)
-  console.log('headers', request.headers) // array of strings, e.g: ['foo', 'bar']
-  request.addHeader('hello', 'world')
-  console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']
-})
-```
-
-Note: a request is only loosely completed to a given socket.
-
-## `undici:request:bodyChunkSent`
-
-This message is published when a chunk of the request body is being sent.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
-  // request is the same object undici:request:create
-})
-```
-
-## `undici:request:bodySent`
-
-This message is published after the request body has been fully sent.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {
-  // request is the same object undici:request:create
-})
-```
-
-## `undici:request:headers`
-
-This message is published after the response headers have been received.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
-  // request is the same object undici:request:create
-  console.log('statusCode', response.statusCode)
-  console.log(response.statusText)
-  // response.headers are buffers.
-  console.log(response.headers.map((x) => x.toString()))
-})
-```
-
-## `undici:request:bodyChunkReceived`
-
-This message is published after a chunk of the response body has been received.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
-  // request is the same object undici:request:create
-})
-```
-
-## `undici:request:trailers`
-
-This message is published after the response body and trailers have been received, i.e. the response has been completed.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
-  // request is the same object undici:request:create
-  console.log('completed', request.completed)
-  // trailers are buffers.
-  console.log(trailers.map((x) => x.toString()))
-})
-```
-
-## `undici:request:error`
-
-This message is published if the request is going to error, but it has not errored yet.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
-  // request is the same object undici:request:create
-})
-```
-
-## `undici:client:sendHeaders`
-
-This message is published right before the first byte of the request is written to the socket.
-
-*Note*: It will publish the exact headers that will be sent to the server in raw format.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
-  // request is the same object undici:request:create
-  console.log(`Full headers list ${headers.split('\r\n')}`);
-})
-```
-
-## `undici:client:beforeConnect`
-
-This message is published before creating a new connection for **any** request.
-You can not assume that this event is related to any specific request.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
-  // connector is a function that creates the socket
-})
-```
-
-## `undici:client:connected`
-
-This message is published after a connection is established.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
- // connector is a function that creates the socket
-})
-```
-
-## `undici:client:connectError`
-
-This message is published if it did not succeed to create new connection
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
-  // const { host, hostname, protocol, port, servername, version } = connectParams
-  // connector is a function that creates the socket
-  console.log(`Connect failed with ${error.message}`)
-})
-```
-
-## `undici:websocket:open`
-
-This message is published after the client has successfully connected to a server.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:open').subscribe(({ 
-  address,           // { address: string, family: string, port: number }
-  protocol,          // string - negotiated subprotocol
-  extensions,        // string - negotiated extensions
-  websocket,         // WebSocket - the WebSocket instance
-  handshakeResponse  // object - HTTP response that upgraded the connection
-}) => {
-  console.log(address) // address, family, and port
-  console.log(protocol) // negotiated subprotocols
-  console.log(extensions) // negotiated extensions
-  console.log(websocket) // the WebSocket instance
-  
-  // Handshake response details
-  console.log(handshakeResponse.status) // 101 for HTTP/1.1, 200 for HTTP/2 extended CONNECT
-  console.log(handshakeResponse.statusText) // 'Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js
-  console.log(handshakeResponse.headers) // Object containing response headers
-})
-```
-
-### Handshake Response Object
-
-The `handshakeResponse` object contains the HTTP response that established the WebSocket connection:
-
-- `status` (number): The HTTP status code (`101` for HTTP/1.1 upgrade, `200` for HTTP/2 extended CONNECT)
-- `statusText` (string): The HTTP status message (`'Switching Protocols'` for HTTP/1.1, commonly `'OK'` for HTTP/2 in Node.js)
-- `headers` (object): The HTTP response headers from the server, including:
-  - `sec-websocket-accept` and other WebSocket-related headers
-  - `upgrade: 'websocket'`
-  - `connection: 'upgrade'`
-
-  The `upgrade` and `connection` headers are only present for HTTP/1.1 handshakes.
-
-This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.
-
-## `undici:websocket:close`
-
-This message is published after the connection has closed.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
-  console.log(websocket) // the WebSocket instance
-  console.log(code) // the closing status code
-  console.log(reason) // the closing reason
-})
-```
-
-## `undici:websocket:socket_error`
-
-This message is published if the socket experiences an error.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
-  console.log(error)
-})
-```
-
-## `undici:websocket:ping`
-
-This message is published after the client receives a ping frame, if the connection is not closing.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
-  // a Buffer or undefined, containing the optional application data of the frame
-  console.log(payload)
-  console.log(websocket) // the WebSocket instance
-})
-```
-
-## `undici:websocket:pong`
-
-This message is published after the client receives a pong frame.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
-  // a Buffer or undefined, containing the optional application data of the frame
-  console.log(payload)
-  console.log(websocket) // the WebSocket instance
-})
-```
-
-## `undici:proxy:connected`
-
-This message is published after the `ProxyAgent` establishes a connection to the proxy server.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
-  console.log(socket)
-  console.log(connectParams)
-  // const { origin, port, path, signal, headers, servername } = connectParams
-})
-```
-
-## `undici:request:pending-requests`
-
-This message is published when the deduplicate interceptor's pending request map changes. This is useful for monitoring and debugging request deduplication behavior.
-
-The deduplicate interceptor automatically deduplicates concurrent requests for the same resource. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response.
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
-  console.log(type)  // 'added' or 'removed'
-  console.log(size)  // current number of pending requests
-  console.log(key)   // the deduplication key for this request
-})
-```
-
-### Event Properties
-
-- `type` (`string`): Either `'added'` when a new pending request is registered, or `'removed'` when a pending request completes (successfully or with an error).
-- `size` (`number`): The current number of pending requests after the change.
-- `key` (`string`): The deduplication key for the request, composed of the origin, method, path, and request headers.
-
-### Example: Monitoring Request Deduplication
-
-```js
-import diagnosticsChannel from 'diagnostics_channel'
-
-const channel = diagnosticsChannel.channel('undici:request:pending-requests')
-
-channel.subscribe(({ type, size, key }) => {
-  if (type === 'added') {
-    console.log(`New pending request: ${key} (${size} total pending)`)
-  } else {
-    console.log(`Request completed: ${key} (${size} remaining)`)
-  }
-})
-```
-
-This can be useful for:
-- Verifying that request deduplication is working as expected
-- Monitoring the number of concurrent in-flight requests
-- Debugging deduplication behavior in production environments