poolee

1.0.1 verified Sat Apr 25 auth: no javascript maintenance

HTTP pool and load balancer for Node.js (v1.0.1, stable). Provides connection pooling, load balancing across multiple endpoints, automatic retries with exponential backoff, health checks via ping endpoints, and configurable timeouts. Differentiators: simple API, built-in retry filtering, and endpoint health management. Last release in 2017; maintenance mode.

Common errors

error TypeError: Cannot read property 'statusCode' of undefined ↓

cause Callback invoked with error but response is undefined on timeout/connection error.

fix

Check if (error) return before accessing response.

error Error: Max pending threshold reached ↓

cause Too many concurrent requests; pool.maxPending exceeded.

fix

Increase maxPending or slow down request rate.

error Error: All endpoints are unavailable ↓

cause All servers are marked unhealthy or unreachable.

fix

Check server health; ensure ping endpoint returns 200.

Warnings

deprecated The keepAlive option uses a non-standard internal agent; behavior may differ from Node's native keep-alive. ↓

fix Avoid using keepAlive: true unless you understand the internal implementation.

gotcha maxRetries is capped by pool size; if maxRetries >= number of servers, retries will not work as expected. ↓

fix Set maxRetries < number of endpoints in pool.

gotcha The ping option only works if resolution is set; endpoint health checks may not occur otherwise. ↓

fix Ensure resolution is defined (default 1000ms) for ping to function.

gotcha Timeout is approximate; actual timeout can be up to resolution ms later than specified timeout. ↓

fix Set resolution smaller than timeout for tighter accuracy.

Install

npm install poolee

yarn add poolee

pnpm add poolee

Imports

Pool

wrong

import Pool from 'poolee'

correct

const Pool = require('poolee')

CJS only; no ESM support.

Pool
```
const { Pool } = require('poolee')
```
Default export is the Pool constructor; named export also available.
Pool.prototype.request
wrong
```
pool.request(options, callback)
```
correct
```
pool.request(options, body, callback)
```
Body can be string/buffer; omit for GET.

Quickstart

Creates a pool with multiple servers, configures options including health checks and retry filter, then makes a GET request.

const Pool = require('poolee');
const http = require('http');

const servers = [
  '127.0.0.1:8886',
  '127.0.0.1:8887',
  '127.0.0.1:8888',
  '127.0.0.1:8889'
];

const pool = new Pool(http, servers, {
  maxPending: 1000,
  maxSockets: 20,
  timeout: 60000,
  resolution: 1000,
  keepAlive: true,
  ping: '/health',
  pingTimeout: 2000,
  retryFilter: function(options, response, body) {
    return response.statusCode === 500;
  },
  retryDelay: 20,
  maxRetries: 3
});

pool.request(
  { method: 'GET', path: '/api/data' },
  null,
  function(error, response, body) {
    if (error) {
      console.error(error.message);
      return;
    }
    console.log(response.statusCode, body);
  }
);