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.