@noodleseed/one 0.22.0 → 0.23.0

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

@@ -1,87 +1,279 @@
-# Class: Pool
+# Pool
+
+<!--introduced_in=v1.0.0-->
+
+<!--type=module-->
+
+<!-- source_link=lib/dispatcher/pool.js -->
+
+> Stability: 2 - Stable
+
+A pool of [`Client`][] instances connected to the same upstream origin. A `Pool`
+spreads requests across several connections to the same host, which allows more
+than one request to be in flight at a time without enabling pipelining on a
+single connection.
+
+`Pool` extends [`Dispatcher`][]. Each [`Client`][] in the pool is created lazily
+through a configurable `factory` and shares the same options. Requests are not
+guaranteed to be dispatched in the order in which they are invoked.
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
+console.log(statusCode, await body.text())
+await pool.close()
+```
+
+## Class: `Pool`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
+
+* Extends: {Dispatcher}
+
+### `new Pool(url[, options])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `url` {URL|string} The upstream origin. It should only include the protocol,
+  hostname, and port.
+* `options` {PoolOptions} (optional) Extends {ClientOptions}, so every
+  [`Client`][] option is also accepted and forwarded to each pooled client.
+  * `factory` {Function} Creates the [`Client`][] (or other [`Dispatcher`][])
+    instances used by the pool.
+    **Default:** `(origin, opts) => new Client(origin, opts)`.
+    * `origin` {URL} The parsed upstream origin.
+    * `opts` {Object} The resolved client options.
+    * Returns: {Dispatcher}
+  * `connections` {number|null} The maximum number of [`Client`][] instances the
+    pool may create. When set to `null` the pool creates an unlimited number of
+    clients. **Default:** `null`.
+  * `clientTtl` {number|null} The amount of time, in milliseconds, before an idle
+    [`Client`][] is removed from the pool and closed. When set to `null` clients
+    are never removed based on age. **Default:** `null`.
+
+Creates a new `Pool` against `url`. If `connections` is provided it must be a
+finite, non-negative number, otherwise an [`InvalidArgumentError`][] is thrown.
+The `factory` must be a function, and `connect` (inherited from {ClientOptions})
+must be a function or an object when provided.
+
+The connection-related {ClientOptions} (`connect`, `connectTimeout`, `tls`,
+`maxCachedSessions`, `socketPath`, `autoSelectFamily`,
+`autoSelectFamilyAttemptTimeout`, `allowH2`, and `useH2c`) are used to build the
+connector shared by every pooled client.
 
-Extends: `undici.Dispatcher`
+> [!NOTE]
+> `Pool` inherits all {ClientOptions}, including `allowH2` and
+> `maxConcurrentStreams`. With the default unlimited `connections`, the pool
+> opens a new client - and therefore a new TCP/TLS socket - per concurrent
+> dispatch, which defeats HTTP/2 multiplexing over a shared session. To benefit
+> from h2 multiplexing on a single session, cap `connections` (for example
+> `connections: 1`) so that concurrent requests share a session up to
+> `maxConcurrentStreams`.
 
-A pool of [Client](/docs/docs/api/Client.md) instances connected to the same upstream target.
+```mjs
+import { Pool } from 'undici'
 
-Requests are not guaranteed to be dispatched in order of invocation.
+const pool = new Pool('http://localhost:3000', {
+  connections: 128,
+  pipelining: 1
+})
+```
 
-## `new Pool(url[, options])`
+### `pool.closed`
 
-Arguments:
+<!-- YAML
+added: v1.0.0
+-->
 
-* **url** `URL | string` - It should only include the **protocol, hostname, and port**.
-* **options** `PoolOptions` (optional)
+* Type: {boolean}
 
-### Parameter: `PoolOptions`
+`true` after [`pool.close()`][] has been called.
 
-Extends: [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions)
+### `pool.destroyed`
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
-* **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `Pool` instance will create an unlimited amount of `Client` instances.
-* **clientTtl** `number | null` (optional) - Default: `null` - The amount of time before a `Client` instance is removed from the `Pool` and closed.   When set to `null`, `Client` instances will not be removed or closed based on age.
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v2.0.0
+    pr-url: https://github.com/nodejs/undici/pull/384
+    description: Reflects the state set by `pool.close()`.
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
 
-> [!NOTE]
-> `Pool` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions), including `allowH2` (default `true`) and `maxConcurrentStreams` (default `100`). With the unlimited default of `connections`, `Pool` will open a new `Client` — and therefore a new TCP/TLS socket — per concurrent dispatch, which defeats HTTP/2 multiplexing on a shared session. To benefit from h2 multiplexing on a single session, cap `connections` (e.g. `connections: 1`) so that concurrent requests share a session up to `maxConcurrentStreams`.
+* Type: {boolean}
+
+`true` after [`pool.destroy()`][] has been called, or after [`pool.close()`][]
+has been called and the pool shutdown has completed.
+
+### `pool.stats`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {PoolStats}
 
-## Instance Properties
+Aggregate statistics for the pool. See [`PoolStats`][].
 
-### `Pool.closed`
+### `pool.close([callback])`
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Pool.destroyed`
+Implements [`dispatcher.close([callback])`][]. Gracefully closes the pool and
+all of its clients, waiting for in-flight requests to complete. Resolves once
+every pooled client has closed.
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+### `pool.destroy([error[, callback]])`
 
-### `Pool.stats`
+<!-- YAML
+added: v1.0.0
+-->
 
-Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
+Implements [`dispatcher.destroy([error[, callback]])`][]. Forcefully destroys
+the pool and all of its clients, aborting any in-flight requests with `error`.
 
-## Instance Methods
+### `pool.connect(options[, callback])`
 
-### `Pool.close([callback])`
+<!-- YAML
+added: v1.0.0
+-->
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+See [`dispatcher.connect(options[, callback])`][]. Performs an HTTP `CONNECT`
+request through one of the pooled clients.
 
-### `Pool.destroy([error, callback])`
+### `pool.dispatch(options, handler)`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v1.3.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
 
-### `Pool.connect(options[, callback])`
+Implements [`dispatcher.dispatch(options, handler)`][]. Selects an available
+client - creating a new one through `factory` when none is free and the
+`connections` limit has not been reached - and dispatches the request to it.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+### `pool.pipeline(options, handler)`
 
-### `Pool.dispatch(options, handler)`
+<!-- YAML
+added: v1.0.0
+-->
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
+{Duplex} stream that pipes the request body to the response body through
+`handler`.
 
-### `Pool.pipeline(options, handler)`
+### `pool.request(options[, callback])`
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+<!-- YAML
+added: v1.0.0
+-->
 
-### `Pool.request(options[, callback])`
+See [`dispatcher.request(options[, callback])`][]. Performs a request through one
+of the pooled clients.
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+```mjs
+import { Pool } from 'undici'
 
-### `Pool.stream(options, factory[, callback])`
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, headers, body } = await pool.request({
+  path: '/',
+  method: 'GET'
+})
+console.log(statusCode, headers)
+console.log(await body.text())
+await pool.close()
+```
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+### `pool.stream(options, factory[, callback])`
 
-### `Pool.upgrade(options[, callback])`
+<!-- YAML
+added: v1.0.0
+-->
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+See [`dispatcher.stream(options, factory[, callback])`][]. Performs a request and
+writes the response body into the {Writable} stream returned by `factory`.
 
-## Instance Events
+### `pool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection
+(for example to a WebSocket) through one of the pooled clients.
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that connected,
+  `[pool, ...targets]`.
+
+Emitted by a pooled client when a socket has connected. See
+[`Dispatcher` Event: `'connect'`][]. When `clientTtl` is set, the connecting
+client's time-to-live timer starts on this event.
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that disconnected,
+  `[pool, ...targets]`.
+* `error` {Error}
+
+Emitted by a pooled client when a socket has disconnected. See
+[`Dispatcher` Event: `'disconnect'`][].
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that drained,
+  `[pool, ...targets]`.
+
+Emitted when a pooled client is no longer busy and can accept more requests. See
+[`Dispatcher` Event: `'drain'`][].
+
+[`Client`]: Client.md#class-client
+[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
+[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`PoolStats`]: PoolStats.md
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`pool.close()`]: #poolclosecallback
+[`pool.destroy()`]: #pooldestroyerror-callback

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

@@ -1,35 +1,141 @@
-# Class: PoolStats
+# PoolStats
 
-Aggregate stats for a [Pool](/docs/docs/api/Pool.md) or [BalancedPool](/docs/docs/api/BalancedPool.md).
+<!--introduced_in=v4.15.0-->
+<!--type=module-->
+<!-- source_link=lib/util/stats.js -->
 
-## `new PoolStats(pool)`
+> Stability: 2 - Stable
 
-Arguments:
+`PoolStats` exposes a read-only snapshot of the aggregate connection and request
+counters for a [`Pool`][] or [`BalancedPool`][]. An instance is created lazily
+each time the `pool.stats` getter is accessed, so the values reflect the state of
+the pool at the moment of access.
 
-* **pool** `Pool` - Pool or BalancedPool from which to return stats.
+`PoolStats` is not constructed directly in normal use; obtain an instance from
+the `stats` property of a pool:
 
-## Instance Properties
+```mjs
+import { Pool } from 'undici'
 
-### `PoolStats.connected`
+const pool = new Pool('http://localhost:3000')
+const { stats } = pool
+
+console.log(stats.connected, stats.running, stats.size)
+```
+
+## Class: `PoolStats`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+Each property is a plain number computed from the pool's internal state when the
+instance is created. The instance is a snapshot; read `pool.stats` again to
+observe later changes.
+
+### `new PoolStats(pool)`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* `pool` {Pool|BalancedPool} The pool to read counters from.
+
+Creates a new `PoolStats` instance from the current state of `pool`. Prefer the
+`pool.stats` getter, which returns a fresh `PoolStats` on each access.
+
+### `poolStats.connected`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of open socket connections in this pool.
 
-### `PoolStats.free`
+### `poolStats.free`
 
-Number of open socket connections in this pool that do not have an active request.
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
 
-### `PoolStats.pending`
+* Type: {number}
+
+Number of open socket connections in this pool that do not have an active
+request.
+
+### `poolStats.pending`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of pending requests across all clients in this pool.
 
-### `PoolStats.queued`
+### `poolStats.queued`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of queued requests across all clients in this pool.
 
-### `PoolStats.running`
+### `poolStats.running`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of currently active requests across all clients in this pool.
 
-### `PoolStats.size`
+### `poolStats.size`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
 
 Number of active, pending, or queued requests across all clients in this pool.
+
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Pool`]: Pool.md#class-pool