node package manager
Easy collaboration. Discover, share, and reuse code in your team. Create a free org »


Build Status


Node socket pool for persistent TCP/IPC connections


$ npm install socket-pool --save


import Pool from 'socket-pool'
const pool = new Pool({
  connect: {
    host: 'localhost',
    port: 2181
  // Defaults to `3000`
  connectTimeout: 3000,
  pool: {
    // the options of generic-pool
    max: 100,
    min: 10
  // other options of net.Socket
.then(socket => {
  socket.on('data', chunk => {
    // concat chunks
    // To re-use TCP connections, it is better NOT to end or destroy a socket
    // after data received.
    // Some mechanism could be used to tell the client if there is no more
    // chunks, such as:
    // - design a protocol to define the content-length of the incoming chunks.
    if (dataFinished) {
      // Release the socket resource,
      // then it can be required again.
// And then, the usage of `socket` is nearly the same as `new net.Socket`

new Pool({connect, pool, ...socketOptions})

  • pool Object the options of generic-pool, and the value is simply passed
  • connectTimeout Number=3000 the milliseconds socket pool will wait for a socket to connect to the server before timing out. Defaults to 3000 milliseconds.
  • socketOptions Object the options of new net.Socket(options) of the vanilla node.js. The only difference is that the option socketOptions.allowHalfOpen defaults to true. If half-opened TCP connections are not allowed, allowHalfOpen should be explicit set to false. But setting this to false is kind of silly, since that's the whole purpose of this lib.

connect Object

If connect.path is specified, then other socket options will be ignored, and it is only for IPC connections.

  • path String the same argument of socket.connect(path) of the vanilla node.js

Otherwise, it is for TCP connections, available options are:

  • port
  • host
  • localAddress
  • localPort
  • family
  • hints
  • lookup


Returns Promise.

  • Promise.resolve(socket) If the socket is successful connected
  • Promise.reject(error) If there are any errors
    • error SocketError|TimeoutError
import {
  // If connectTimeout is specified and timed out to connect to server
  // Socket error
} from 'socket-pool'
  socket => {
    // do something with socket
  error => {
    console.log(error instanceof SocketError || error instanceof TimeoutError)
    // true

The acquired socket is a wrapped net.Socket instance which will be destroyed when 'end' event occurs, and some additional methods are available:


The socket-pool-specified method to release the socket to the pool


Destroy the socket instance.