@depup/undici 8.0.2-depup.0 → 8.8.0-depup.0

package/README.md

@@ -13,8 +13,8 @@ npm install @depup/undici
 
 | Field | Value |
 |-------|-------|
-| Original | [undici](https://www.npmjs.com/package/undici) @ 8.0.2 |
-| Processed | 2026-04-04 |
+| Original | [undici](https://www.npmjs.com/package/undici) @ 8.8.0 |
+| Processed | 2026-07-21 |
 | Smoke test | passed |
 | Deps updated | 0 |
 

package/changes.json

@@ -1,5 +1,5 @@
 {
   "bumped": {},
-  "timestamp": "2026-04-04T12:15:52.479Z",
+  "timestamp": "2026-07-21T16:25:44.269Z",
   "totalUpdated": 0
 }

package/docs/docs/api/Agent.md

@@ -1,84 +1,291 @@
 # Agent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v3.2.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/agent.js -->
 
-Agent allows dispatching requests against multiple different origins.
+> Stability: 2 - Stable
 
-Requests are not guaranteed to be dispatched in order of invocation.
+An `Agent` dispatches requests against multiple different origins, creating and
+reusing a per-origin [`Pool`][] (or [`Client`][]) on demand. It is the default
+dispatcher used by [`request`][], [`stream`][], and [`fetch`][] when no explicit
+dispatcher is supplied.
 
-## `new undici.Agent([options])`
+Requests are not guaranteed to be dispatched in their order of invocation.
 
-Arguments:
+```mjs
+import { Agent, setGlobalDispatcher } from 'undici'
 
-* **options** `AgentOptions` (optional)
+const agent = new Agent({ connections: 10 })
+setGlobalDispatcher(agent)
+```
 
-Returns: `Agent`
+## Class: `Agent`
 
-### Parameter: `AgentOptions`
+<!-- YAML
+added: v3.2.0
+-->
 
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
+* Extends: {Dispatcher}
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
-* **maxOrigins** `number` (optional) - Default: `Infinity` - Limits the total number of origins that can receive requests at a time, throwing an `MaxOriginsReachedError` error when attempting to dispatch when the max is reached. If `Infinity`, no limit is enforced.
+`Agent` keeps an internal map of origins to dispatchers. The first request to a
+given origin lazily creates a dispatcher through the configured `factory`, and
+subsequent requests to the same origin reuse it. Idle dispatchers are closed
+automatically once they have no open connections and are no longer busy.
 
-## Instance Properties
+### `new Agent([options])`
 
-### `Agent.closed`
+<!-- YAML
+added: v3.2.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4365
+    description: Added the `maxOrigins` option to cap the number of origins.
+-->
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+* `options` {AgentOptions} (optional) Extends {PoolOptions}.
+  * `factory` {Function} Builds the dispatcher used for a given origin. When the
+    resolved options contain `connections: 1`, the default factory creates a
+    {Client}; otherwise it creates a {Pool}. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+    * `origin` {URL|string} The origin to create a dispatcher for.
+    * `opts` {Object} The resolved options for the new dispatcher.
+    * Returns: {Dispatcher}
+  * `maxOrigins` {number} Limits the total number of distinct origins that may
+    receive requests at the same time. A {MaxOriginsReachedError} is thrown when
+    a request targets a new origin once the limit is reached. When set to
+    `Infinity`, no limit is enforced. Must be a number greater than `0`.
+    **Default:** `Infinity`.
 
-### `Agent.destroyed`
+`Agent` inherits all {PoolOptions} (and therefore all {ClientOptions}). The
+per-origin {Pool} it creates uses the default unlimited `connections`, so
+concurrent requests to the same origin are spread across separate {Client}
+instances on separate sockets.
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+> [!NOTE]
+> Because each concurrent request to an origin may use a different {Client},
+> HTTP/2 multiplexing on a shared session does not apply unless `connections` is
+> set to a small value (for example `connections: 1`). See {PoolOptions} and
+> {ClientOptions} for the full set of inherited options such as `allowH2`
+> (default `true`) and `maxConcurrentStreams` (default `100`).
 
-## Instance Methods
+### `agent.closed`
 
-### `Agent.close([callback])`
+<!-- YAML
+added: v3.2.0
+-->
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+* Type: {boolean}
 
-### `Agent.destroy([error, callback])`
+`true` after [`agent.close()`][] has been called.
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+### `agent.destroyed`
 
-### `Agent.dispatch(options, handler: AgentDispatchOptions)`
+<!-- YAML
+added: v3.2.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+* Type: {boolean}
 
-#### Parameter: `AgentDispatchOptions`
+`true` after [`agent.destroy()`][] has been called, or after [`agent.close()`][]
+has been called and the shutdown has completed.
 
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
+### `agent.stats`
 
-* **origin** `string | URL`
+<!-- YAML
+added: v7.9.0
+-->
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+* Type: {Record<string, ClientStats|PoolStats>}
 
-### `Agent.connect(options[, callback])`
+Aggregate statistics for the agent, keyed by origin. Each value is the
+[`ClientStats`][] or [`PoolStats`][] object reported by the dispatcher currently
+serving that origin. Origins whose dispatcher does not expose `stats` are
+omitted.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+```mjs
+import { Agent } from 'undici'
 
-### `Agent.dispatch(options, handler)`
+const agent = new Agent()
+await agent.request({ origin: 'http://localhost:3000', path: '/', method: 'GET' })
+console.log(agent.stats)
+// { 'http://localhost:3000': PoolStats { ... } }
+```
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `agent.dispatch(options, handler)`
 
-### `Agent.pipeline(options, handler)`
+<!-- YAML
+added: v3.2.0
+-->
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+* `options` {AgentDispatchOptions} Extends {DispatchOptions}.
+  * `origin` {string|URL} The origin to dispatch the request against. Required.
+* `handler` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait for the [`'drain'`][] event before dispatching again.
 
-### `Agent.request(options[, callback])`
+Routes the request to the dispatcher for `options.origin`, creating one through
+the `factory` if needed. Throws an {InvalidArgumentError} when `options.origin`
+is not a non-empty string or {URL}, and a {MaxOriginsReachedError} when a new
+origin would exceed `maxOrigins`. Implements [`Dispatcher.dispatch()`][].
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+### `agent.close([callback])`
 
-### `Agent.stream(options, factory[, callback])`
+<!-- YAML
+added: v3.2.0
+-->
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  closed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
 
-### `Agent.upgrade(options[, callback])`
+Gracefully closes the agent and every dispatcher it owns, waiting for in-flight
+requests to complete. Implements [`Dispatcher.close()`][].
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+### `agent.destroy([error[, callback]])`
 
-### `Agent.stats()`
+<!-- YAML
+added: v3.2.0
+-->
 
-Returns an object of stats by origin in the format of `Record<string, TClientStats | TPoolStats>`
+* `error` {Error} (optional) The error to abort pending requests with.
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  been destroyed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
 
-See [`PoolStats`](/docs/docs/api/PoolStats.md) and [`ClientStats`](/docs/docs/api/ClientStats.md).
+Forcefully destroys the agent and every dispatcher it owns, aborting all pending
+requests. Implements [`Dispatcher.destroy()`][].
+
+### `agent.connect(options[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.connect()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### `agent.pipeline(options, handler)`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.pipeline()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### `agent.request(options[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.request()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+```mjs
+import { Agent } from 'undici'
+
+const agent = new Agent()
+const { statusCode, body } = await agent.request({
+  origin: 'http://localhost:3000',
+  path: '/',
+  method: 'GET',
+})
+
+console.log('response received', statusCode)
+console.log('data', await body.text())
+```
+
+### `agent.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.stream()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### `agent.upgrade(options[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.upgrade()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### Event: `'connect'`
+
+<!-- YAML
+added: v6.6.0
+-->
+
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent` followed by the per-origin dispatcher chain.
+
+Emitted when a socket has been created for an origin and is ready to receive
+requests. Forwarded from the underlying dispatcher's [`'connect'`][] event.
+
+### Event: `'disconnect'`
+
+<!-- YAML
+added: v6.6.0
+-->
+
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
+
+Emitted when a socket for an origin has disconnected. Forwarded from the
+underlying dispatcher's [`'disconnect'`][] event.
+
+### Event: `'connectionError'`
+
+<!-- YAML
+added: v6.6.0
+-->
+
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
+
+Emitted when a connection attempt for an origin fails. Forwarded from the
+underlying dispatcher's [`'connectionError'`][] event.
+
+### Event: `'drain'`
+
+<!-- YAML
+added: v6.6.0
+-->
+
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+
+Emitted when an origin's dispatcher is no longer busy and can accept more
+requests. Forwarded from the underlying dispatcher's [`'drain'`][] event.
+
+[`'connect'`]: Dispatcher.md#event-connect
+[`'connectionError'`]: Dispatcher.md#event-connectionerror
+[`'disconnect'`]: Dispatcher.md#event-disconnect
+[`'drain'`]: Dispatcher.md#event-drain
+[`Client`]: Client.md#class-client
+[`ClientStats`]: ClientStats.md
+[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.connect()`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`Dispatcher.destroy()`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.pipeline()`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Dispatcher.stream()`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`Dispatcher.upgrade()`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`Pool`]: Pool.md#class-pool
+[`PoolStats`]: PoolStats.md
+[`agent.close()`]: #agentclosecallback
+[`agent.destroy()`]: #agentdestroyerror-callback
+[`fetch`]: Fetch.md
+[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`stream`]: Dispatcher.md#dispatcherstreamoptions-factory-callback