generic-promise-pool

Promise-based connection pooling library inspired by generic-pool.

Installation

$ npm install generic-promise-pool

Documentation

The full generated JSDoc documentation is hosted on GitHub here: https://NatalieWolfe.github.io/node-promise-pool/docs/. You can also find the documentation as a single markdown file at docs.md. All of the options used for configuring a pool are at the end of this README.

Examples

Creating a Pool

This example creates a pool that uses a hypothetical promise-based MySQL library.

var mysql = require('promise-mysql');
var pool = require('generic-promise-pool');

var mysqlPool = pool.create({
    name    : 'mysql',  // An optional name for the pool.
    max     : 10,       // Optional limit for how many connections to allow.
    min     : 2,        // Optional minimum connections to keep in the pool.
    create  : function(){
        var conn = mysql.createConnection(mysqlConnOptions);
        return conn.connect();
    },
    destroy : function(conn){
        return conn.end();
    }
});

For a full list of options that the PromisePool accepts, see the documentation on GitHub: https://NatalieWolfe.github.io/node-promise-pool/docs/PromisePool.Factory.html

Using the Pool

In this example we get a connection from the pool and use it to make a query.

mysqlPool.acquire(function(conn){
    // The connection remains acquired until the promise returned by this
    // function is resolved or rejected.
    return conn.query('SELECT * FROM books WHERE author = "Neal Stephenson"');
}).then(function(res){
    // The connection has been released back to the pool before we get here,
    // and the results from the acquire callback is propagated out.
    res.forEach(function(row){ console.dir(row); });
}, function(err){
    console.error(err);
});

Draining the Pool

When you want to shut down your application, it can be quite annoying to wait for idle connections to close naturally. To get past this, drain the pool before shutting down.

mysqlPool.drain()
    .then(function(){
        console.log('The pool has drained, and all connections destroyed.');
    });

Pool Factory Options

Properties
| Name | Type | Description | | --- | --- | --- | | name | string | Name of the pool. Used only for logging. | | create | create | Should create the item to be acquired, and return either a promise or the new client. | | destroy | destroy | Should gently close any resources that the item is using. Called to destroy resources. | | validate | validate | Optional. Should return true if the resource is still valid and false if it should be removed from the pool. Called before a resource is acquired from the pool. | | onRelease | onRelease | Optional. May return a promise to indicate when a client is ready to be added back to the pool after being released. | | max | number | Optional. Maximum number of items that can exist at the same time. Any further acquire requests will be pushed to the waiting list. Defaults to 1. | | min | number | Optional. Minimum number of items in pool (including in-use). When the pool is created, or a resource destroyed, this minimum will be checked. If the pool resource count is below the minimum a new resource will be created and added to the pool. Defaults to 0. | | idleTimeoutMillis | number | Optional. Maximum period for resources to be idle (e.g. not acquired) before they are destroyed. Defaults to 30000 (30 seconds). | | reapIntervalMillis | number | Optional. How frequently the pool will check for idle resources that need to be destroyed. Defaults to 1000 (1 second). | | drainCheckIntervalMillis | number | Optional. How frequently the pool will check the status of waiting clients and unreturned resources before destroying all the resources. Defaults to 100 (1/10th a second). | | log | bool | log | Optional. Whether the pool should log activity. If a function is provided, it will be called to log messages. If true is provided, messages are logged to console.log. Defaults to false. | | priorityRange | number | Optional. The range from 1 to be treated as a valid priority. Default is 1. | | refreshIdle | bool | Optional. Indicates if idle resources should be destroyed when left idle for idleTimeoutMillis milliseconds. Defaults to true. | | returnToHead | bool | Optional. Returns released object to the head of the available objects list. Default is false. |

Factory.create ⇒ Promise.<PromisePool.Client>

Kind: static typedef of Factory
Returns: Promise.<PromisePool.Client> - A promise for a new client.

Factory.destroy ⇒ Promise

Kind: static typedef of Factory
Returns: Promise - If destruction is asynchronous, a promise should be returned that will resolve after the client is destroyed.
| Param | Type | Description | | --- | --- | --- | | client | PromisePool.Client | A resource that had been created earlier. |

Factory.validate ⇒ bool

Kind: static typedef of Factory
Returns: bool - True if the resource is still valid, otherwise false should be returned.
| Param | Type | Description | | --- | --- | --- | | client | PromisePool.Client | A resource that had been created earlier. |

Factory.onRelease ⇒ Promise.<\*>

Kind: static typedef of Factory
Returns: Promise.<\*> - May return a promise, in which case the client wont join the pool until the promise resolves. If it is rejected, then the client will be destroyed instead.
| Param | Type | Description | | --- | --- | --- | | client | PromisePool.Client | A resource that has been released back to the pool. |

Factory.log : function

Kind: static typedef of Factory
| Param | Type | Description | | --- | --- | --- | | msg | string | The message to be logged. | | level | string | The importance of this log message. Possible values are: verbose, info, and error. |