@milpa/comal 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,159 @@
+# Class: EnvHttpProxyAgent
+
+Extends: `undici.Dispatcher`
+
+EnvHttpProxyAgent automatically reads the proxy configuration from the environment variables `http_proxy`, `https_proxy`, and `no_proxy` and sets up the proxy agents accordingly. When `http_proxy` and `https_proxy` are set, `http_proxy` is used for HTTP requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is set, `http_proxy` is used for both HTTP and HTTPS requests. If only `https_proxy` is set, it is only used for HTTPS requests.
+
+`no_proxy` is a comma or space-separated list of hostnames that should not be proxied. The list may contain leading wildcard characters (`*`). If `no_proxy` is set, the EnvHttpProxyAgent will bypass the proxy for requests to hosts that match the list. If `no_proxy` is set to `"*"`, the EnvHttpProxyAgent will bypass the proxy for all requests.
+
+Uppercase environment variables are also supported: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. However, if both the lowercase and uppercase environment variables are set, the uppercase environment variables will be ignored.
+
+## `new EnvHttpProxyAgent([options])`
+
+Arguments:
+
+* **options** `EnvHttpProxyAgentOptions` (optional) - extends the `Agent` options.
+
+Returns: `EnvHttpProxyAgent`
+
+### Parameter: `EnvHttpProxyAgentOptions`
+
+Extends: [`AgentOptions`](/docs/docs/api/Agent.md#parameter-agentoptions)
+
+* **httpProxy** `string` (optional) - When set, it will override the `HTTP_PROXY` environment variable.
+* **httpsProxy** `string` (optional) - When set, it will override the `HTTPS_PROXY` environment variable.
+* **noProxy** `string` (optional) - When set, it will override the `NO_PROXY` environment variable.
+
+Examples:
+
+```js
+import { EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+// or
+const envHttpProxyAgent = new EnvHttpProxyAgent({ httpProxy: 'my.proxy.server:8080', httpsProxy: 'my.proxy.server:8443', noProxy: 'localhost' })
+```
+
+#### Example - EnvHttpProxyAgent instantiation
+
+This will instantiate the EnvHttpProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
+import { EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+```
+
+#### Example - Basic Proxy Fetch with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+setGlobalDispatcher(envHttpProxyAgent)
+
+const { status, json } = await fetch('http://localhost:3000/foo')
+
+console.log('response received', status) // response received 200
+
+const data = await json() // data { foo: "bar" }
+```
+
+#### Example - Basic Proxy Request with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+setGlobalDispatcher(envHttpProxyAgent)
+
+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
+}
+```
+
+#### Example - Basic Proxy Request with local agent dispatcher
+
+```js
+import { EnvHttpProxyAgent, request } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Fetch with local agent dispatcher
+
+```js
+import { EnvHttpProxyAgent, fetch } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+
+const {
+  status,
+  json
+} = await fetch('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+
+console.log('response received', status) // response received 200
+
+const data = await json() // data { foo: "bar" }
+```
+
+## Instance Methods
+
+### `EnvHttpProxyAgent.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+
+### `EnvHttpProxyAgent.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.dispatch(options, handler: AgentDispatchOptions)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+
+#### Parameter: `AgentDispatchOptions`
+
+Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
+
+* **origin** `string | URL`
+
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+
+### `EnvHttpProxyAgent.dispatch(options, handler)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+
+### `EnvHttpProxyAgent.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+
+### `EnvHttpProxyAgent.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+
+### `EnvHttpProxyAgent.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+
+### `EnvHttpProxyAgent.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).

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

@@ -0,0 +1,49 @@
+# Errors
+
+Undici exposes a variety of error objects that you can use to enhance your error handling.
+You can find all the error objects inside the `errors` key.
+
+```js
+import { errors } from 'undici'
+```
+
+| Error                                | Error Codes                           | Description                                                               |
+| ------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------- |
+| `UndiciError`                        | `UND_ERR`                             | all errors below are extended from `UndiciError`.                         |
+| `ConnectTimeoutError`                | `UND_ERR_CONNECT_TIMEOUT`             | socket is destroyed due to connect timeout.                               |
+| `HeadersTimeoutError`                | `UND_ERR_HEADERS_TIMEOUT`             | socket is destroyed due to headers timeout.                               |
+| `HeadersOverflowError`               | `UND_ERR_HEADERS_OVERFLOW`            | socket is destroyed due to headers' max size being exceeded.              |
+| `BodyTimeoutError`                   | `UND_ERR_BODY_TIMEOUT`                | socket is destroyed due to body timeout.                                  |
+| `InvalidArgumentError`               | `UND_ERR_INVALID_ARG`                 | passed an invalid argument.                                               |
+| `InvalidReturnValueError`            | `UND_ERR_INVALID_RETURN_VALUE`        | returned an invalid value.                                                |
+| `RequestAbortedError`                | `UND_ERR_ABORTED`                     | the request has been aborted by the user                                  |
+| `ClientDestroyedError`               | `UND_ERR_DESTROYED`                   | trying to use a destroyed client.                                         |
+| `ClientClosedError`                  | `UND_ERR_CLOSED`                      | trying to use a closed client.                                            |
+| `SocketError`                        | `UND_ERR_SOCKET`                      | there is an error with the socket.                                        |
+| `NotSupportedError`                  | `UND_ERR_NOT_SUPPORTED`               | encountered unsupported functionality.                                    |
+| `RequestContentLengthMismatchError`  | `UND_ERR_REQ_CONTENT_LENGTH_MISMATCH` | request body does not match content-length header                         |
+| `ResponseContentLengthMismatchError` | `UND_ERR_RES_CONTENT_LENGTH_MISMATCH` | response body does not match content-length header                        |
+| `InformationalError`                 | `UND_ERR_INFO`                        | expected error with reason                                                |
+| `ResponseExceededMaxSizeError`       | `UND_ERR_RES_EXCEEDED_MAX_SIZE`       | response body exceed the max size allowed                                 |
+| `SecureProxyConnectionError`         | `UND_ERR_PRX_TLS`                     | tls connection to a proxy failed                                          |
+| `MessageSizeExceededError`           | `UND_ERR_WS_MESSAGE_SIZE_EXCEEDED`    | WebSocket decompressed message exceeded the maximum allowed size          |
+
+Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check `instanceof errors.UndiciError` and seek for the `error.code === '<error_code>'` instead to avoid inconsistencies.
+### `SocketError`
+
+The `SocketError` has a `.socket` property which holds socket metadata:
+
+```ts
+interface SocketInfo {
+  localAddress?: string
+  localPort?: number
+  remoteAddress?: string
+  remotePort?: number
+  remoteFamily?: string
+  timeout?: number
+  bytesWritten?: number
+  bytesRead?: number
+}
+```
+
+Be aware that in some cases the `.socket` property can be `null`.

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

@@ -0,0 +1,45 @@
+# EventSource
+
+> ⚠️ Warning: the EventSource API is experimental.
+
+Undici exposes a WHATWG spec-compliant implementation of [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
+for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
+
+## Instantiating EventSource
+
+Undici exports a EventSource class. You can instantiate the EventSource as
+follows:
+
+```mjs
+import { EventSource } from 'undici'
+
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.onmessage = (event) => {
+  console.log(event.data)
+}
+```
+
+## Using a custom Dispatcher
+
+undici allows you to set your own Dispatcher in the EventSource constructor.
+
+An example which allows you to modify the request headers is:
+
+```mjs
+import { EventSource, Agent } from 'undici'
+
+class CustomHeaderAgent extends Agent {
+  dispatch (opts) {
+    opts.headers['x-custom-header'] = 'hello world'
+    return super.dispatch(...arguments)
+  }
+}
+
+const eventSource = new EventSource('http://localhost:3000', {
+  dispatcher: new CustomHeaderAgent()
+})
+
+```
+
+More information about the EventSource API can be found on
+[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).

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

@@ -0,0 +1,60 @@
+# Fetch
+
+Undici exposes a fetch() method starts the process of fetching a resource from the network.
+
+Documentation and examples can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
+
+## FormData
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
+
+If any parameters are passed to the FormData constructor other than `undefined`, an error will be thrown. Other parameters are ignored.
+
+When you use `FormData` as a request body, keep `fetch` and `FormData` from the
+same implementation. Use the built-in global `FormData` with the built-in
+global `fetch()`, and use `undici`'s `FormData` with `undici.fetch()`.
+
+If you want the installed `undici` package to provide the globals, call
+[`install()`](/docs/api/GlobalInstallation.md) so `fetch`, `Headers`,
+`Response`, `Request`, and `FormData` are installed together as a matching set.
+
+## Response
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+
+## Request
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+
+## Header
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+
+# Body Mixins
+
+`Response` and `Request` body inherit body mixin methods. These methods include:
+
+- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
+- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
+- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
+- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata)
+- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
+- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
+
+There is an ongoing discussion regarding `.formData()` and its usefulness and performance in server environments. It is recommended to use a dedicated library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy).
+
+These libraries can be interfaced with fetch with the following example code:
+
+```mjs
+import { Busboy } from '@fastify/busboy'
+import { Readable } from 'node:stream'
+
+const response = await fetch('...')
+const busboy = new Busboy({
+  headers: {
+    'content-type': response.headers.get('content-type')
+  }
+})
+
+Readable.fromWeb(response.body).pipe(busboy)
+```

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

@@ -0,0 +1,139 @@
+# Global Installation
+
+Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally without requiring imports.
+
+## `install()`
+
+Install all WHATWG fetch classes globally on `globalThis`.
+
+**Example:**
+
+```js
+import { install } from 'undici'
+
+// Install all WHATWG fetch classes globally  
+install()
+
+// Now you can use fetch classes globally without importing
+const response = await fetch('https://api.example.com/data')
+const data = await response.json()
+
+// All classes are available globally:
+const headers = new Headers([['content-type', 'application/json']])
+const request = new Request('https://example.com')
+const formData = new FormData()
+const ws = new WebSocket('wss://example.com')
+const eventSource = new EventSource('https://example.com/events')
+```
+
+## Installed Classes
+
+The `install()` function adds the following classes to `globalThis`:
+
+| Class | Description |
+|-------|-------------|
+| `fetch` | The fetch function for making HTTP requests |
+| `Headers` | HTTP headers management |
+| `Response` | HTTP response representation |
+| `Request` | HTTP request representation |
+| `FormData` | Form data handling |
+| `WebSocket` | WebSocket client |
+| `CloseEvent` | WebSocket close event |
+| `ErrorEvent` | WebSocket error event |
+| `MessageEvent` | WebSocket message event |
+| `EventSource` | Server-sent events client |
+
+## Using `FormData` with `fetch`
+
+If you send a `FormData` body, use matching implementations for `fetch` and
+`FormData`.
+
+These two patterns are safe:
+
+```js
+// Built-in globals from Node.js
+const body = new FormData()
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+```js
+// Globals installed from the undici package
+import { install } from 'undici'
+
+install()
+
+const body = new FormData()
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`
+all come from the installed `undici` package, so they work as a matching set.
+
+If you do not want to install globals, import both from `undici` instead:
+
+```js
+import { fetch, FormData } from 'undici'
+
+const body = new FormData()
+await fetch('https://example.com', {
+  method: 'POST',
+  body
+})
+```
+
+Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`
+with the built-in global `fetch()`. Keeping them paired avoids surprising
+multipart behavior across Node.js and undici versions.
+
+## Use Cases
+
+Global installation is useful for:
+
+- **Polyfilling environments** that don't have native fetch support
+- **Ensuring consistent behavior** across different Node.js versions
+- **Library compatibility** when third-party libraries expect global fetch
+- **Migration scenarios** where you want to replace built-in implementations
+- **Testing environments** where you need predictable fetch behavior
+
+## Example: Polyfilling an Environment
+
+```js
+import { install } from 'undici'
+
+// Check if fetch is available and install if needed
+if (typeof globalThis.fetch === 'undefined') {
+  install()
+  console.log('Undici fetch installed globally')
+}
+
+// Now fetch is guaranteed to be available
+const response = await fetch('https://api.example.com')
+```
+
+## Example: Testing Environment
+
+```js
+import { install } from 'undici'
+
+// In test setup, ensure consistent fetch behavior
+install()
+
+// Now all tests use undici's implementations
+test('fetch API test', async () => {
+  const response = await fetch('https://example.com')
+  expect(response).toBeInstanceOf(Response)
+})
+```
+
+## Notes
+
+- The `install()` function overwrites any existing global implementations
+- Classes installed are undici's implementations, not Node.js built-ins
+- This provides access to undici's latest features and performance improvements
+- The global installation persists for the lifetime of the process