{
  "type": "module",
  "source": "doc/api/api-pool.md",
  "modules": [
    {
      "textRaw": "Pool",
      "name": "pool",
      "introduced_in": "v1.0.0",
      "type": "module",
      "stability": 2,
      "stabilityText": "Stable",
      "desc": "<p>A pool of <a href=\"Client.html#class-client\"><code>Client</code></a> instances connected to the same upstream origin. A <code>Pool</code>\nspreads requests across several connections to the same host, which allows more\nthan one request to be in flight at a time without enabling pipelining on a\nsingle connection.</p>\n<p><code>Pool</code> extends <a href=\"Dispatcher.html#class-dispatcher\"><code>Dispatcher</code></a>. Each <a href=\"Client.html#class-client\"><code>Client</code></a> in the pool is created lazily\nthrough a configurable <code>factory</code> and shares the same options. Requests are not\nguaranteed to be dispatched in the order in which they are invoked.</p>\n<pre><code class=\"language-mjs\">import { Pool } from 'undici'\n\nconst pool = new Pool('http://localhost:3000', { connections: 10 })\nconst { statusCode, body } = await pool.request({ path: '/', method: 'GET' })\nconsole.log(statusCode, await body.text())\nawait pool.close()\n</code></pre>",
      "classes": [
        {
          "textRaw": "Class: `Pool`",
          "name": "Pool",
          "type": "class",
          "meta": {
            "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."
              }
            ]
          },
          "desc": "<ul>\n<li>Extends: <a href=\"Dispatcher.md#class-dispatcher\"><code>&#x3C;Dispatcher></code></a></li>\n</ul>",
          "signatures": [
            {
              "textRaw": "`new Pool(url[, options])`",
              "name": "Pool",
              "type": "ctor",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`url` {URL|string} The upstream origin. It should only include the protocol, hostname, and port.",
                  "name": "url",
                  "type": "URL|string",
                  "desc": "The upstream origin. It should only include the protocol, hostname, and port."
                },
                {
                  "textRaw": "`options` {PoolOptions} (optional) Extends {ClientOptions}, so every `Client` option is also accepted and forwarded to each pooled client.",
                  "name": "options",
                  "type": "PoolOptions",
                  "desc": "(optional) Extends {ClientOptions}, so every `Client` option is also accepted and forwarded to each pooled client.",
                  "options": [
                    {
                      "textRaw": "`factory` {Function} Creates the `Client` (or other `Dispatcher`) instances used by the pool. **Default:** `(origin, opts) => new Client(origin, opts)`.",
                      "name": "factory",
                      "type": "Function",
                      "default": "`(origin, opts) => new Client(origin, opts)`",
                      "desc": "Creates the `Client` (or other `Dispatcher`) instances used by the pool.",
                      "options": [
                        {
                          "textRaw": "`origin` {URL} The parsed upstream origin.",
                          "name": "origin",
                          "type": "URL",
                          "desc": "The parsed upstream origin."
                        },
                        {
                          "textRaw": "`opts` {Object} The resolved client options.",
                          "name": "opts",
                          "type": "Object",
                          "desc": "The resolved client options."
                        },
                        {
                          "textRaw": "Returns: {Dispatcher}",
                          "name": "return",
                          "type": "Dispatcher"
                        }
                      ]
                    },
                    {
                      "textRaw": "`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`.",
                      "name": "connections",
                      "type": "number|null",
                      "default": "`null`",
                      "desc": "The maximum number of `Client` instances the pool may create. When set to `null` the pool creates an unlimited number of clients."
                    },
                    {
                      "textRaw": "`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`.",
                      "name": "clientTtl",
                      "type": "number|null",
                      "default": "`null`",
                      "desc": "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."
                    }
                  ],
                  "optional": true
                }
              ],
              "desc": "<p>Creates a new <code>Pool</code> against <code>url</code>. If <code>connections</code> is provided it must be a\nfinite, non-negative number, otherwise an <a href=\"Errors.html#class-invalidargumenterror\"><code>InvalidArgumentError</code></a> is thrown.\nThe <code>factory</code> must be a function, and <code>connect</code> (inherited from <a href=\"Client.md#new-clienturl-options\"><code>&#x3C;ClientOptions></code></a>)\nmust be a function or an object when provided.</p>\n<p>The connection-related <a href=\"Client.md#new-clienturl-options\"><code>&#x3C;ClientOptions></code></a> (<code>connect</code>, <code>connectTimeout</code>, <code>tls</code>,\n<code>maxCachedSessions</code>, <code>socketPath</code>, <code>autoSelectFamily</code>,\n<code>autoSelectFamilyAttemptTimeout</code>, <code>allowH2</code>, and <code>useH2c</code>) are used to build the\nconnector shared by every pooled client.</p>\n<blockquote>\n<p>[!NOTE]\n<code>Pool</code> inherits all <a href=\"Client.md#new-clienturl-options\"><code>&#x3C;ClientOptions></code></a>, including <code>allowH2</code> and\n<code>maxConcurrentStreams</code>. With the default unlimited <code>connections</code>, the pool\nopens a new client - and therefore a new TCP/TLS socket - per concurrent\ndispatch, which defeats HTTP/2 multiplexing over a shared session. To benefit\nfrom h2 multiplexing on a single session, cap <code>connections</code> (for example\n<code>connections: 1</code>) so that concurrent requests share a session up to\n<code>maxConcurrentStreams</code>.</p>\n</blockquote>\n<pre><code class=\"language-mjs\">import { Pool } from 'undici'\n\nconst pool = new Pool('http://localhost:3000', {\n  connections: 128,\n  pipelining: 1\n})\n</code></pre>"
            }
          ],
          "properties": [
            {
              "textRaw": "Type: {boolean}",
              "name": "closed",
              "type": "boolean",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "desc": "<p><code>true</code> after [<code>pool.close()</code>][] has been called.</p>"
            },
            {
              "textRaw": "Type: {boolean}",
              "name": "destroyed",
              "type": "boolean",
              "meta": {
                "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."
                  }
                ]
              },
              "desc": "<p><code>true</code> after [<code>pool.destroy()</code>][] has been called, or after [<code>pool.close()</code>][]\nhas been called and the pool shutdown has completed.</p>"
            },
            {
              "textRaw": "Type: {PoolStats}",
              "name": "stats",
              "type": "PoolStats",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "desc": "<p>Aggregate statistics for the pool. See <a href=\"PoolStats.html\"><code>PoolStats</code></a>.</p>"
            }
          ],
          "methods": [
            {
              "textRaw": "`pool.close([callback])`",
              "name": "close",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>dispatcher.close([callback])</code>][]. Gracefully closes the pool and\nall of its clients, waiting for in-flight requests to complete. Resolves once\nevery pooled client has closed.</p>"
            },
            {
              "textRaw": "`pool.destroy([error[, callback]])`",
              "name": "destroy",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "error",
                      "optional": true
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>dispatcher.destroy([error[, callback]])</code>][]. Forcefully destroys\nthe pool and all of its clients, aborting any in-flight requests with <code>error</code>.</p>"
            },
            {
              "textRaw": "`pool.connect(options[, callback])`",
              "name": "connect",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>dispatcher.connect(options[, callback])</code>][]. Performs an HTTP <code>CONNECT</code>\nrequest through one of the pooled clients.</p>"
            },
            {
              "textRaw": "`pool.dispatch(options, handler)`",
              "name": "dispatch",
              "type": "method",
              "meta": {
                "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."
                  }
                ]
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handler"
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>dispatcher.dispatch(options, handler)</code>][]. Selects an available\nclient - creating a new one through <code>factory</code> when none is free and the\n<code>connections</code> limit has not been reached - and dispatches the request to it.</p>"
            },
            {
              "textRaw": "`pool.pipeline(options, handler)`",
              "name": "pipeline",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handler"
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>dispatcher.pipeline(options, handler)</code>][]. Sends a request and returns a\n<a href=\"https://nodejs.org/api/stream.html#class-streamduplex\"><code>&#x3C;Duplex></code></a> stream that pipes the request body to the response body through <code>handler</code>.</p>"
            },
            {
              "textRaw": "`pool.request(options[, callback])`",
              "name": "request",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>dispatcher.request(options[, callback])</code>][]. Performs a request through one\nof the pooled clients.</p>\n<pre><code class=\"language-mjs\">import { Pool } from 'undici'\n\nconst pool = new Pool('http://localhost:3000', { connections: 10 })\nconst { statusCode, headers, body } = await pool.request({\n  path: '/',\n  method: 'GET'\n})\nconsole.log(statusCode, headers)\nconsole.log(await body.text())\nawait pool.close()\n</code></pre>"
            },
            {
              "textRaw": "`pool.stream(options, factory[, callback])`",
              "name": "stream",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "factory"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>dispatcher.stream(options, factory[, callback])</code>][]. Performs a request and\nwrites the response body into the <a href=\"https://nodejs.org/api/stream.html#class-streamwritable\"><code>&#x3C;Writable></code></a> stream returned by <code>factory</code>.</p>"
            },
            {
              "textRaw": "`pool.upgrade(options[, callback])`",
              "name": "upgrade",
              "type": "method",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>dispatcher.upgrade(options[, callback])</code>][]. Upgrades a connection\n(for example to a WebSocket) through one of the pooled clients.</p>"
            }
          ],
          "events": [
            {
              "textRaw": "Event: `'connect'`",
              "name": "connect",
              "type": "event",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`origin` {URL}",
                  "name": "origin",
                  "type": "URL"
                },
                {
                  "textRaw": "`targets` {Array} The pool followed by the client that connected, `[pool, ...targets]`.",
                  "name": "targets",
                  "type": "Array",
                  "desc": "The pool followed by the client that connected, `[pool, ...targets]`."
                }
              ],
              "desc": "<p>Emitted by a pooled client when a socket has connected. See\n<a href=\"Dispatcher.html#event-connect\"><code>Dispatcher</code> Event: <code>'connect'</code></a>. When <code>clientTtl</code> is set, the connecting\nclient's time-to-live timer starts on this event.</p>"
            },
            {
              "textRaw": "Event: `'disconnect'`",
              "name": "disconnect",
              "type": "event",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`origin` {URL}",
                  "name": "origin",
                  "type": "URL"
                },
                {
                  "textRaw": "`targets` {Array} The pool followed by the client that disconnected, `[pool, ...targets]`.",
                  "name": "targets",
                  "type": "Array",
                  "desc": "The pool followed by the client that disconnected, `[pool, ...targets]`."
                },
                {
                  "textRaw": "`error` {Error}",
                  "name": "error",
                  "type": "Error"
                }
              ],
              "desc": "<p>Emitted by a pooled client when a socket has disconnected. See\n<a href=\"Dispatcher.html#event-disconnect\"><code>Dispatcher</code> Event: <code>'disconnect'</code></a>.</p>"
            },
            {
              "textRaw": "Event: `'drain'`",
              "name": "drain",
              "type": "event",
              "meta": {
                "added": [
                  "v1.0.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`origin` {URL}",
                  "name": "origin",
                  "type": "URL"
                },
                {
                  "textRaw": "`targets` {Array} The pool followed by the client that drained, `[pool, ...targets]`.",
                  "name": "targets",
                  "type": "Array",
                  "desc": "The pool followed by the client that drained, `[pool, ...targets]`."
                }
              ],
              "desc": "<p>Emitted when a pooled client is no longer busy and can accept more requests. See\n<a href=\"Dispatcher.html#event-drain\"><code>Dispatcher</code> Event: <code>'drain'</code></a>.</p>\n<p>[<code>dispatcher.close([callback])</code>]: Dispatcher.md#dispatcherclosecallback\n[<code>dispatcher.connect(options[, callback])</code>]: Dispatcher.md#dispatcherconnectoptions-callback\n[<code>dispatcher.destroy([error[, callback]])</code>]: Dispatcher.md#dispatcherdestroyerror-callback\n[<code>dispatcher.dispatch(options, handler)</code>]: Dispatcher.md#dispatcherdispatchoptions-handler\n[<code>dispatcher.pipeline(options, handler)</code>]: Dispatcher.md#dispatcherpipelineoptions-handler\n[<code>dispatcher.request(options[, callback])</code>]: Dispatcher.md#dispatcherrequestoptions-callback\n[<code>dispatcher.stream(options, factory[, callback])</code>]: Dispatcher.md#dispatcherstreamoptions-factory-callback\n[<code>dispatcher.upgrade(options[, callback])</code>]: Dispatcher.md#dispatcherupgradeoptions-callback\n[<code>pool.close()</code>]: #poolclosecallback\n[<code>pool.destroy()</code>]: #pooldestroyerror-callback</p>"
            }
          ]
        }
      ]
    }
  ]
}