@node-core/utils 7.2.1 → 7.2.3

package/node_modules/cheerio/node_modules/undici/docs/docs/best-practices/mocking-request.md

@@ -1,190 +0,0 @@
-# Mocking Request
-
-Undici has its own mocking [utility](/docs/docs/api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
-
-Example:
-
-```js
-// bank.mjs
-import { request } from 'undici'
-
-export async function bankTransfer(recipient, amount) {
-  const { body } = await request('http://localhost:3000/bank-transfer',
-    {
-      method: 'POST',
-      headers: {
-        'X-TOKEN-SECRET': 'SuperSecretToken',
-      },
-      body: JSON.stringify({
-        recipient,
-        amount
-      })
-    }
-  )
-  return await body.json()
-}
-```
-
-And this is what the test file looks like:
-
-```js
-// index.test.mjs
-import { strict as assert } from 'node:assert'
-import { MockAgent, setGlobalDispatcher, } from 'undici'
-import { bankTransfer } from './bank.mjs'
-
-const mockAgent = new MockAgent();
-
-setGlobalDispatcher(mockAgent);
-
-// Provide the base url to the request
-const mockPool = mockAgent.get('http://localhost:3000');
-
-// intercept the request
-mockPool.intercept({
-  path: '/bank-transfer',
-  method: 'POST',
-  headers: {
-    'X-TOKEN-SECRET': 'SuperSecretToken',
-  },
-  body: JSON.stringify({
-    recipient: '1234567890',
-    amount: '100'
-  })
-}).reply(200, {
-  message: 'transaction processed'
-})
-
-const success = await bankTransfer('1234567890', '100')
-
-assert.deepEqual(success, { message: 'transaction processed' })
-
-// if you dont want to check whether the body or the headers contain the same value
-// just remove it from interceptor
-mockPool.intercept({
-  path: '/bank-transfer',
-  method: 'POST',
-}).reply(400, {
-  message: 'bank account not found'
-})
-
-const badRequest = await bankTransfer('1234567890', '100')
-
-assert.deepEqual(badRequest, { message: 'bank account not found' })
-```
-
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
-
-## Access agent call history
-
-Using a MockAgent also allows you to make assertions on the configuration used to make your request in your application.
-
-Here is an example :
-
-```js
-// index.test.mjs
-import { strict as assert } from 'node:assert'
-import { MockAgent, setGlobalDispatcher, fetch } from 'undici'
-import { app } from './app.mjs'
-
-// given an application server running on http://localhost:3000
-await app.start()
-
-// enable call history at instantiation
-const mockAgent = new MockAgent({ enableCallHistory: true })
-// or after instantiation
-mockAgent.enableCallHistory()
-
-setGlobalDispatcher(mockAgent)
-
-// this call is made (not intercepted)
-await fetch(`http://localhost:3000/endpoint?query='hello'`, {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' }
-  body: JSON.stringify({ data: '' })
-})
-
-// access to the call history of the MockAgent (which register every call made intercepted or not)
-assert.ok(mockAgent.getCallHistory()?.calls().length === 1)
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.fullUrl, `http://localhost:3000/endpoint?query='hello'`)
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.body, JSON.stringify({ data: '' }))
-assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.searchParams, { query: 'hello' })
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.port, '3000')
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.host, 'localhost:3000')
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.method, 'POST')
-assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.path, '/endpoint')
-assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.headers, { 'content-type': 'application/json' })
-
-// clear all call history logs
-mockAgent.clearCallHistory()
-
-assert.ok(mockAgent.getCallHistory()?.calls().length === 0)
-```
-
-Calling `mockAgent.close()` will automatically clear and delete every call history for you.
-
-Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
-
-Explore other MockCallHistory functionality [here](/docs/docs/api/MockCallHistory.md)
-
-Explore other MockCallHistoryLog functionality [here](/docs/docs/api/MockCallHistoryLog.md)
-
-## Debug Mock Value
-
-When the interceptor and the request options are not the same, undici will automatically make a real HTTP request. To prevent real requests from being made, use `mockAgent.disableNetConnect()`:
-
-```js
-const mockAgent = new MockAgent();
-
-setGlobalDispatcher(mockAgent);
-mockAgent.disableNetConnect()
-
-// Provide the base url to the request
-const mockPool = mockAgent.get('http://localhost:3000');
-
-mockPool.intercept({
-  path: '/bank-transfer',
-  method: 'POST',
-}).reply(200, {
-  message: 'transaction processed'
-})
-
-const badRequest = await bankTransfer('1234567890', '100')
-// Will throw an error
-// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer':
-// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
-```
-
-## Reply with data based on request
-
-If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`:
-
-```js
-mockPool.intercept({
-  path: '/bank-transfer',
-  method: 'POST',
-  headers: {
-    'X-TOKEN-SECRET': 'SuperSecretToken',
-  },
-  body: JSON.stringify({
-    recipient: '1234567890',
-    amount: '100'
-  })
-}).reply(200, (opts) => {
-  // do something with opts
-
-  return { message: 'transaction processed' }
-})
-```
-
-in this case opts will be
-
-```
-{
-  method: 'POST',
-  headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
-  body: '{"recipient":"1234567890","amount":"100"}',
-  origin: 'http://localhost:3000',
-  path: '/bank-transfer'
-}
-```

package/node_modules/cheerio/node_modules/undici/docs/docs/best-practices/proxy.md

@@ -1,127 +0,0 @@
-# Connecting through a proxy
-
-Connecting through a proxy is possible by:
-
-- Using [ProxyAgent](/docs/docs/api/ProxyAgent.md).
-- Configuring `Client` or `Pool` constructor.
-
-The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
-should be added to every request call in the `path`.
-For instance, if you need to send a request to the `/hello` route of your upstream server,
-the `path` should be `path: 'http://upstream.server:port/hello?foo=bar'`.
-
-If you proxy requires basic authentication, you can send it via the `proxy-authorization` header.
-
-### Connect without authentication
-
-```js
-import { Client } from 'undici'
-import { createServer } from 'http'
-import { createProxy } from 'proxy'
-
-const server = await buildServer()
-const proxyServer = await buildProxy()
-
-const serverUrl = `http://localhost:${server.address().port}`
-const proxyUrl = `http://localhost:${proxyServer.address().port}`
-
-server.on('request', (req, res) => {
-  console.log(req.url) // '/hello?foo=bar'
-  res.setHeader('content-type', 'application/json')
-  res.end(JSON.stringify({ hello: 'world' }))
-})
-
-const client = new Client(proxyUrl)
-
-const response = await client.request({
-  method: 'GET',
-  path: serverUrl + '/hello?foo=bar'
-})
-
-response.body.setEncoding('utf8')
-let data = ''
-for await (const chunk of response.body) {
-  data += chunk
-}
-console.log(response.statusCode) // 200
-console.log(JSON.parse(data)) // { hello: 'world' }
-
-server.close()
-proxyServer.close()
-client.close()
-
-function buildServer () {
-  return new Promise((resolve, reject) => {
-    const server = createServer()
-    server.listen(0, () => resolve(server))
-  })
-}
-
-function buildProxy () {
-  return new Promise((resolve, reject) => {
-    const server = createProxy(createServer())
-    server.listen(0, () => resolve(server))
-  })
-}
-```
-
-### Connect with authentication
-
-```js
-import { Client } from 'undici'
-import { createServer } from 'http'
-import { createProxy } from 'proxy'
-
-const server = await buildServer()
-const proxyServer = await buildProxy()
-
-const serverUrl = `http://localhost:${server.address().port}`
-const proxyUrl = `http://localhost:${proxyServer.address().port}`
-
-proxyServer.authenticate = function (req) {
-  return req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`
-}
-
-server.on('request', (req, res) => {
-  console.log(req.url) // '/hello?foo=bar'
-  res.setHeader('content-type', 'application/json')
-  res.end(JSON.stringify({ hello: 'world' }))
-})
-
-const client = new Client(proxyUrl)
-
-const response = await client.request({
-  method: 'GET',
-  path: serverUrl + '/hello?foo=bar',
-  headers: {
-    'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}`
-  }
-})
-
-response.body.setEncoding('utf8')
-let data = ''
-for await (const chunk of response.body) {
-  data += chunk
-}
-console.log(response.statusCode) // 200
-console.log(JSON.parse(data)) // { hello: 'world' }
-
-server.close()
-proxyServer.close()
-client.close()
-
-function buildServer () {
-  return new Promise((resolve, reject) => {
-    const server = createServer()
-    server.listen(0, () => resolve(server))
-  })
-}
-
-function buildProxy () {
-  return new Promise((resolve, reject) => {
-    const server = createProxy(createServer())
-    server.listen(0, () => resolve(server))
-  })
-}
-```
-

package/node_modules/cheerio/node_modules/undici/docs/docs/best-practices/undici-vs-builtin-fetch.md

@@ -1,224 +0,0 @@
-# Undici Module vs. Node.js Built-in Fetch
-
-Node.js has shipped a built-in `fetch()` implementation powered by undici since
-Node.js v18. This guide explains the relationship between the `undici` npm
-package and the built-in `fetch`, and when you should install one versus relying
-on the other.
-
-## Background
-
-The `fetch()`, `Request`, `Response`, `Headers`, and `FormData` globals in
-Node.js v18+ are provided by a version of undici that is bundled into Node.js
-itself. You can check which version is bundled with:
-
-```js
-console.log(process.versions.undici); // e.g., "7.5.0"
-```
-
-When you install undici from npm, you get the full library with all of its
-additional APIs, and potentially a newer release than what your Node.js version
-bundles.
-
-## Keep `fetch` and `FormData` from the same implementation
-
-When you send a `FormData` body, keep `fetch` and `FormData` together from the
-same implementation.
-
-Use one of these patterns:
-
-### Built-in globals
-
-```js
-const body = new FormData()
-body.set('name', 'some')
-body.set('someOtherProperty', '8000')
-
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-### `undici` module imports
-
-```js
-import { fetch, FormData } from 'undici'
-
-const body = new FormData()
-body.set('name', 'some')
-body.set('someOtherProperty', '8000')
-
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-### `undici.install()` globals
-
-If you want the installed `undici` package to provide the globals, call
-[`install()`](/docs/api/GlobalInstallation.md):
-
-```js
-import { install } from 'undici'
-
-install()
-
-const body = new FormData()
-body.set('name', 'some')
-body.set('someOtherProperty', '8000')
-
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
-`FormData` implementations with undici's versions, and also installs undici's
-`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
-globals.
-
-Avoid mixing implementations in the same request, for example:
-
-```js
-import { fetch } from 'undici'
-
-const body = new FormData()
-
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-```js
-import { FormData } from 'undici'
-
-const body = new FormData()
-
-await fetch('https://example.com', {
-  method: 'POST',
-  body
-})
-```
-
-Those combinations may behave differently across Node.js and undici versions.
-Using matching pairs keeps multipart handling predictable.
-
-## When you do NOT need to install undici
-
-If all of the following are true, you can rely on the built-in globals and skip
-adding undici to your dependencies:
-
-- You only need the standard Fetch API (`fetch`, `Request`, `Response`,
-  `Headers`, `FormData`).
-- You are running Node.js v18 or later.
-- You do not depend on features or bug fixes introduced in a version of undici
-  newer than the one bundled with your Node.js release.
-- You want zero additional runtime dependencies.
-- You want cross-platform interoperability with browsers and other runtimes
-  (Deno, Bun, Cloudflare Workers, etc.) using the same Fetch API surface.
-
-This is common in applications that make straightforward HTTP requests or in
-libraries that target multiple JavaScript runtimes.
-
-## When you SHOULD install undici
-
-Install undici from npm when you need capabilities beyond the standard Fetch API:
-
-### Advanced HTTP APIs
-
-undici exposes `request`, `stream`, `pipeline`, and `connect` methods that
-provide lower-level control and significantly better performance than `fetch`:
-
-```js
-import { request } from 'undici';
-
-const { statusCode, headers, body } = await request('https://example.com');
-const data = await body.json();
-```
-
-### Connection pooling and dispatchers
-
-`Client`, `Pool`, `BalancedPool`, `Agent`, and their configuration options
-let you manage connection lifecycle, keep-alive behavior, pipelining depth,
-and concurrency limits:
-
-```js
-import { Pool } from 'undici';
-
-const pool = new Pool('https://example.com', { connections: 10 });
-const { body } = await pool.request({ path: '/', method: 'GET' });
-```
-
-### Proxy support
-
-`ProxyAgent` and `EnvHttpProxyAgent` handle HTTP(S) proxying. Note that
-Node.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy
-configuration for the built-in `fetch` via the `--use-env-proxy` flag (or
-`NODE_USE_ENV_PROXY=1`). However, undici's `ProxyAgent` still provides
-programmatic control through the dispatcher API:
-
-```js
-import { ProxyAgent, fetch } from 'undici';
-
-const proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');
-const response = await fetch('https://example.com', { dispatcher: proxyAgent });
-```
-
-### Testing and mocking
-
-`MockAgent`, `MockClient`, and `MockPool` let you intercept and mock HTTP
-requests without patching globals or depending on external libraries:
-
-```js
-import { MockAgent, setGlobalDispatcher, fetch } from 'undici';
-
-const mockAgent = new MockAgent();
-setGlobalDispatcher(mockAgent);
-
-const pool = mockAgent.get('https://example.com');
-pool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });
-```
-
-### Interceptors and middleware
-
-Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you
-fine-grained control over how requests are processed.
-
-### Newer version than what Node.js bundles
-
-The npm package often includes features, performance improvements, and bug fixes
-that have not yet landed in a Node.js release. If you need a specific fix or
-feature, you can install a newer version directly.
-
-## Version compatibility
-
-| Node.js version | Bundled undici version | Notes |
-|---|---|---|
-| v18.x | ~5.x | `fetch` is experimental (behind `--experimental-fetch` in early v18) |
-| v20.x | ~6.x | `fetch` is stable |
-| v22.x | ~6.x / ~7.x | `fetch` is stable |
-| v24.x | ~7.x | `fetch` is stable; env-proxy support via `--use-env-proxy` |
-
-You can always check the exact bundled version at runtime with
-`process.versions.undici`.
-
-Installing undici from npm does not replace the built-in globals. If you want
-your installed version to replace the global `fetch` and related classes, use
-[`install()`](/docs/api/GlobalInstallation.md). Otherwise, import `fetch`
-directly from `'undici'`:
-
-```js
-import { fetch } from 'undici' // uses your installed version, not the built-in
-```
-
-## Further reading
-
-- [API Reference: Fetch](/docs/api/Fetch.md)
-- [API Reference: Client](/docs/api/Client.md)
-- [API Reference: Pool](/docs/api/Pool.md)
-- [API Reference: ProxyAgent](/docs/api/ProxyAgent.md)
-- [API Reference: MockAgent](/docs/api/MockAgent.md)
-- [API Reference: Global Installation](/docs/api/GlobalInstallation.md)

package/node_modules/cheerio/node_modules/undici/docs/docs/best-practices/writing-tests.md

@@ -1,63 +0,0 @@
-# Writing tests
-
-Undici is tuned for a production use case and its default will keep
-a socket open for a few seconds after an HTTP request is completed to
-remove the overhead of opening up a new socket. These settings that makes
-Undici shine in production are not a good fit for using Undici in automated
-tests, as it will result in longer execution times.
-
-The following are good defaults that will keep the socket open for only 10ms:
-
-```js
-import { request, setGlobalDispatcher, Agent } from 'undici'
-
-const agent = new Agent({
-  keepAliveTimeout: 10, // milliseconds
-  keepAliveMaxTimeout: 10 // milliseconds
-})
-
-setGlobalDispatcher(agent)
-```
-
-## Guarding against unexpected disconnects
-
-Undici's `Client` automatically reconnects after a socket error. This means
-a test can silently disconnect, reconnect, and still pass. Unfortunately, 
-this could mask bugs like unexpected parser errors or protocol violations.
-To catch these silent reconnections, add a disconnect guard after creating 
-a `Client`:
-
-```js
-const { Client } = require('undici')
-const { test, after } = require('node:test')
-const { tspl } = require('@matteo.collina/tspl')
-
-test('example with disconnect guard', async (t) => {
-  t = tspl(t, { plan: 1 })
-
-  const client = new Client('http://localhost:3000')
-  after(() => client.close())
-
-  client.on('disconnect', () => {
-    if (!client.closed && !client.destroyed) {
-      t.fail('unexpected disconnect')
-    }
-  })
-
-  // ... test logic ...
-})
-```
-
-`client.close()` and `client.destroy()` both emit `'disconnect'` events, but
-those are expected. The guard only fails when a disconnect happens during the
-active test (i.e., `!client.closed && !client.destroyed` is true).
-
-Skip the guard for tests where a disconnect is expected behavior, such as:
-
-- Signal aborts (`signal.emit('abort')`, `ac.abort()`)
-- Server-side destruction (`res.destroy()`, `req.socket.destroy()`)
-- Client-side body destruction mid-stream (`data.body.destroy()`)
-- Timeout errors (`HeadersTimeoutError`, `BodyTimeoutError`)
-- Successful upgrades (the socket is detached from the `Client`)
-- Retry/reconnect tests where the disconnect triggers the retry
-- HTTP parser errors from malformed responses (`HTTPParserError`)

package/node_modules/cheerio/node_modules/undici/index-fetch.js

@@ -1,65 +0,0 @@
-'use strict'
-
-const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
-const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
-const fetchImpl = require('./lib/web/fetch').fetch
-
-// Capture __filename at module load time for stack trace augmentation.
-// This may be undefined when bundled in environments like Node.js internals.
-const currentFilename = typeof __filename !== 'undefined' ? __filename : undefined
-
-function appendFetchStackTrace (err, filename) {
-  if (!err || typeof err !== 'object') {
-    return
-  }
-
-  const stack = typeof err.stack === 'string' ? err.stack : ''
-  const normalizedFilename = filename.replace(/\\/g, '/')
-
-  if (stack && (stack.includes(filename) || stack.includes(normalizedFilename))) {
-    return
-  }
-
-  const capture = {}
-  Error.captureStackTrace(capture, appendFetchStackTrace)
-
-  if (!capture.stack) {
-    return
-  }
-
-  const captureLines = capture.stack.split('\n').slice(1).join('\n')
-
-  err.stack = stack ? `${stack}\n${captureLines}` : capture.stack
-}
-
-module.exports.fetch = function fetch (init, options = undefined) {
-  return fetchImpl(init, options).catch(err => {
-    if (currentFilename) {
-      appendFetchStackTrace(err, currentFilename)
-    } else if (err && typeof err === 'object') {
-      Error.captureStackTrace(err, module.exports.fetch)
-    }
-    throw err
-  })
-}
-module.exports.FormData = require('./lib/web/fetch/formdata').FormData
-module.exports.Headers = require('./lib/web/fetch/headers').Headers
-module.exports.Response = require('./lib/web/fetch/response').Response
-module.exports.Request = require('./lib/web/fetch/request').Request
-
-const { CloseEvent, ErrorEvent, MessageEvent, createFastMessageEvent } = require('./lib/web/websocket/events')
-module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
-module.exports.CloseEvent = CloseEvent
-module.exports.ErrorEvent = ErrorEvent
-module.exports.MessageEvent = MessageEvent
-module.exports.createFastMessageEvent = createFastMessageEvent
-
-module.exports.EventSource = require('./lib/web/eventsource/eventsource').EventSource
-
-const api = require('./lib/api')
-const Dispatcher = require('./lib/dispatcher/dispatcher')
-Object.assign(Dispatcher.prototype, api)
-// Expose the fetch implementation to be enabled in Node.js core via a flag
-module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
-module.exports.getGlobalDispatcher = getGlobalDispatcher
-module.exports.setGlobalDispatcher = setGlobalDispatcher

package/node_modules/cheerio/node_modules/undici/index.d.ts

@@ -1,3 +0,0 @@
-import Undici from './types/index'
-export default Undici
-export * from './types/index'