{
  "type": "module",
  "source": "doc/api/api-balancedpool.md",
  "modules": [
    {
      "textRaw": "BalancedPool",
      "name": "balancedpool",
      "introduced_in": "v4.8.0",
      "type": "module",
      "stability": 2,
      "stabilityText": "Stable",
      "desc": "<p>A <code>BalancedPool</code> distributes requests across a set of <a href=\"Pool.md#class-pool\"><code>&#x3C;Pool></code></a> instances, each\nconnected to a different upstream. It uses a weighted round-robin algorithm:\nevery upstream starts with the same weight, and the weight is adjusted up on\nsuccessful connections and down on connection errors, so that healthy upstreams\nreceive a larger share of traffic.</p>\n<p>Requests are not guaranteed to be dispatched in the order they are issued.</p>\n<pre><code class=\"language-mjs\">import { BalancedPool } from 'undici'\n\nconst pool = new BalancedPool([\n  'http://localhost:3000',\n  'http://localhost:3001',\n  'http://localhost:3002',\n])\n\nconst { statusCode, body } = await pool.request({\n  path: '/',\n  method: 'GET',\n})\nconsole.log('response received', statusCode)\nfor await (const chunk of body) {\n  console.log('data', chunk.toString())\n}\n</code></pre>",
      "classes": [
        {
          "textRaw": "Class: `BalancedPool`",
          "name": "BalancedPool",
          "type": "class",
          "meta": {
            "added": [
              "v4.8.0"
            ],
            "changes": [
              {
                "version": "v4.10.4",
                "pr-url": "https://github.com/nodejs/undici/pull/1114",
                "description": "Introduced the `BalancedPool` class."
              }
            ]
          },
          "desc": "<ul>\n<li>Extends: <a href=\"Dispatcher.md#class-dispatcher\"><code>&#x3C;Dispatcher></code></a></li>\n</ul>\n<p>A pool of <a href=\"Pool.md#class-pool\"><code>&#x3C;Pool></code></a> instances connected to multiple upstreams.</p>",
          "signatures": [
            {
              "textRaw": "`new BalancedPool(upstreams[, options])`",
              "name": "BalancedPool",
              "type": "ctor",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.15.0",
                    "pr-url": "https://github.com/nodejs/undici/pull/1237",
                    "description": "Added the `factory` option."
                  }
                ]
              },
              "params": [
                {
                  "textRaw": "`upstreams` {URL|string|URL}[] | {string}[] One or more upstream origins. Each value should only include the **protocol, hostname, and port**. **Default:** `[]`.",
                  "name": "upstreams",
                  "type": "URL|string|URL",
                  "default": "`[]`",
                  "desc": "[] | {string}[] One or more upstream origins. Each value should only include the **protocol, hostname, and port**."
                },
                {
                  "textRaw": "`options` {BalancedPoolOptions} (optional)",
                  "name": "options",
                  "type": "BalancedPoolOptions",
                  "desc": "(optional)",
                  "optional": true
                }
              ],
              "desc": "<p>The options passed to the constructor are forwarded to every <a href=\"Pool.md#class-pool\"><code>&#x3C;Pool></code></a> instance\nthat is created for an upstream.</p>",
              "modules": [
                {
                  "textRaw": "Parameter: `BalancedPoolOptions`",
                  "name": "parameter:_`balancedpooloptions`",
                  "type": "module",
                  "desc": "<p>Extends: <a href=\"Pool.md#new-poolurl-options\"><code>&#x3C;PoolOptions></code></a></p>\n<p>In addition to all <a href=\"Pool.md#new-poolurl-options\"><code>&#x3C;PoolOptions></code></a>, the following options are supported:</p>\n<ul>\n<li><code>factory</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function\"><code>&#x3C;Function></code></a> A function used to create the <a href=\"Pool.md#class-pool\"><code>&#x3C;Pool></code></a> instance for each\nupstream. <strong>Default:</strong> <code>(origin, opts) => new Pool(origin, opts)</code>.\n<ul>\n<li><code>origin</code> <a href=\"https://developer.mozilla.org/docs/Web/API/URL\"><code>&#x3C;URL></code></a> | <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#string_type\"><code>&#x3C;string></code></a> The upstream origin.</li>\n<li><code>opts</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object\"><code>&#x3C;Object></code></a> The options object derived from the constructor options.</li>\n<li>Returns: <a href=\"Dispatcher.md#class-dispatcher\"><code>&#x3C;Dispatcher></code></a></li>\n</ul>\n</li>\n<li><code>maxWeightPerServer</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#number_type\"><code>&#x3C;number></code></a> The maximum weight any single upstream can\nreach. Successful connections increase an upstream's weight up to this value. <strong>Default:</strong> <code>100</code>.</li>\n<li><code>errorPenalty</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#number_type\"><code>&#x3C;number></code></a> The amount by which an upstream's weight is decreased\non a connection error and increased on a successful connection. <strong>Default:</strong>\n<code>15</code>.</li>\n</ul>",
                  "displayName": "Parameter: `BalancedPoolOptions`"
                }
              ]
            }
          ],
          "methods": [
            {
              "textRaw": "`balancedPool.addUpstream(upstream)`",
              "name": "addUpstream",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`upstream` {URL|string} The upstream origin to add. It should only include the **protocol, hostname, and port**.",
                      "name": "upstream",
                      "type": "URL|string",
                      "desc": "The upstream origin to add. It should only include the **protocol, hostname, and port**."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {BalancedPool} The `BalancedPool` instance, for chaining.",
                    "name": "return",
                    "type": "BalancedPool",
                    "desc": "The `BalancedPool` instance, for chaining."
                  }
                }
              ],
              "desc": "<p>Adds an upstream. If an open, non-destroyed upstream with the same origin is\nalready present, the call is a no-op.</p>"
            },
            {
              "textRaw": "`balancedPool.removeUpstream(upstream)`",
              "name": "removeUpstream",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`upstream` {URL|string} The upstream origin to remove. It should only include the **protocol, hostname, and port**.",
                      "name": "upstream",
                      "type": "URL|string",
                      "desc": "The upstream origin to remove. It should only include the **protocol, hostname, and port**."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {BalancedPool} The `BalancedPool` instance, for chaining.",
                    "name": "return",
                    "type": "BalancedPool",
                    "desc": "The `BalancedPool` instance, for chaining."
                  }
                }
              ],
              "desc": "<p>Removes an upstream that was previously added. If no matching upstream is found,\nthe call is a no-op.</p>"
            },
            {
              "textRaw": "`balancedPool.getUpstream(upstream)`",
              "name": "getUpstream",
              "type": "method",
              "meta": {
                "added": [
                  "v7.17.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`upstream` {URL|string} The upstream origin to look up. It should only include the **protocol, hostname, and port**.",
                      "name": "upstream",
                      "type": "URL|string",
                      "desc": "The upstream origin to look up. It should only include the **protocol, hostname, and port**."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {Pool|undefined} The {Pool} instance managing the given upstream, or `undefined` if it is not present.",
                    "name": "return",
                    "type": "Pool|undefined",
                    "desc": "The {Pool} instance managing the given upstream, or `undefined` if it is not present."
                  }
                }
              ],
              "desc": "<p>Returns the <a href=\"Pool.md#class-pool\"><code>&#x3C;Pool></code></a> instance for the given upstream origin, if it is open and not\ndestroyed.</p>"
            },
            {
              "textRaw": "`balancedPool.close([callback])`",
              "name": "close",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>Dispatcher.close([callback])</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.destroy([error[, callback]])`",
              "name": "destroy",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "error",
                      "optional": true
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>Dispatcher.destroy([error, callback])</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.connect(options[, callback])`",
              "name": "connect",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>Dispatcher.connect(options[, callback])</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.dispatch(options, handlers)`",
              "name": "dispatch",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  }
                ]
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handlers"
                    }
                  ]
                }
              ],
              "desc": "<p>Implements [<code>Dispatcher.dispatch(options, handler)</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.pipeline(options, handler)`",
              "name": "pipeline",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handler"
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>Dispatcher.pipeline(options, handler)</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.request(options[, callback])`",
              "name": "request",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>Dispatcher.request(options[, callback])</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.stream(options, factory[, callback])`",
              "name": "stream",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "factory"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>Dispatcher.stream(options, factory[, callback])</code>][].</p>"
            },
            {
              "textRaw": "`balancedPool.upgrade(options[, callback])`",
              "name": "upgrade",
              "type": "method",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See [<code>Dispatcher.upgrade(options[, callback])</code>][].</p>"
            }
          ],
          "properties": [
            {
              "textRaw": "Type: {string}[] The origins of the upstreams that are currently open and not destroyed.",
              "name": "upstreams",
              "type": "string",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "desc": "[] The origins of the upstreams that are currently open and not destroyed."
            },
            {
              "textRaw": "Type: {boolean} `true` after `balancedPool.close()` has been called.",
              "name": "closed",
              "type": "boolean",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  }
                ]
              },
              "desc": "<p>Implements [<code>client.closed</code>][].</p>",
              "shortDesc": "`true` after `balancedPool.close()` has been called."
            },
            {
              "textRaw": "Type: {boolean} `true` after `balancedPool.destroy()` has been called, or after `balancedPool.close()` has been called and the shutdown has completed.",
              "name": "destroyed",
              "type": "boolean",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  }
                ]
              },
              "desc": "<p>Implements [<code>client.destroyed</code>][].</p>",
              "shortDesc": "`true` after `balancedPool.destroy()` has been called, or after `balancedPool.close()` has been called and the shutdown has completed."
            },
            {
              "textRaw": "Type: {PoolStats}",
              "name": "stats",
              "type": "PoolStats",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": []
              },
              "desc": "<p>Returns a <a href=\"PoolStats.md#class-poolstats\"><code>&#x3C;PoolStats></code></a> instance aggregating the statistics of the underlying\npools.</p>"
            }
          ],
          "events": [
            {
              "textRaw": "Event: `'connect'`",
              "name": "connect",
              "type": "event",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  },
                  {
                    "version": "v5.8.0",
                    "pr-url": "https://github.com/nodejs/undici/pull/1069",
                    "description": "Adopted weighted round-robin selection across upstreams."
                  }
                ]
              },
              "params": [],
              "desc": "<p>See <a href=\"Dispatcher.html#event-connect\">Dispatcher Event: <code>'connect'</code></a>.</p>"
            },
            {
              "textRaw": "Event: `'disconnect'`",
              "name": "disconnect",
              "type": "event",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  },
                  {
                    "version": "v5.8.0",
                    "pr-url": "https://github.com/nodejs/undici/pull/1069",
                    "description": "Adopted weighted round-robin selection across upstreams."
                  }
                ]
              },
              "params": [],
              "desc": "<p>See <a href=\"Dispatcher.html#event-disconnect\">Dispatcher Event: <code>'disconnect'</code></a>.</p>"
            },
            {
              "textRaw": "Event: `'drain'`",
              "name": "drain",
              "type": "event",
              "meta": {
                "added": [
                  "v4.8.0"
                ],
                "changes": [
                  {
                    "version": "v4.10.4",
                    "pr-url": "https://github.com/nodejs/undici/pull/1114",
                    "description": "Introduced the `BalancedPool` class."
                  }
                ]
              },
              "params": [],
              "desc": "<p>See <a href=\"Dispatcher.html#event-drain\">Dispatcher Event: <code>'drain'</code></a>.</p>\n<p>[<code>Dispatcher.close([callback])</code>]: Dispatcher.md#dispatcherclosecallback-promise\n[<code>Dispatcher.connect(options[, callback])</code>]: Dispatcher.md#dispatcherconnectoptions-callback\n[<code>Dispatcher.destroy([error, callback])</code>]: Dispatcher.md#dispatcherdestroyerror-callback-promise\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>client.closed</code>]: Client.md#clientclosed\n[<code>client.destroyed</code>]: Client.md#clientdestroyed</p>"
            }
          ]
        }
      ]
    }
  ]
}