sandfox/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Migration

This a (probably very bad) migration guide for users moving from generic-pool@2 to generic-pool@3. If there are any improvements you think should be made please let me know via email/twitter or the issue tracker as github issues don't have notifications for comments.
Prerequisites

This module requires nodejs v4 or above as it has dependencies on various es6 components such as Map, Set, Promise etc. I have some vague intetion to create another module that shims out those dependencies or allows user supplied implementations to allow people on node 0.10 to use this module.
Changes

Pool instantiation

Using the Pool class constructor directly is no longer recommended (and it's signature has changed too, see the factory method section below for details).
Instead the generic-pool library now exports a createPool function that acts as a factory for Pool instances.
e.g
var genericPool = require('generic-pool')
// old
var myPool = new genericPool.Pool(/* args */)

// new
const myPool = genericPool.createPool(/* args */)
The signature for the Pool constructor has changed and currently matches that of the new createFactory function. In v2 all the options/configuration were supplied as a single object/dictionary/hash, in v3 the factory stuff (the methods/functions that created/destroyed/validated resources) have been seperated into a seperate object/arguments, and then all the remaining configuration items are on a seperate object/argument
e.g
// old
var config = {
  max: 4,
  min: 2
}

var myPool = new Pool(config)

// new

const factory = {
  create: function(){/* stuff */},
  destroy: function(){/* stuff */}
}
const config = {
  max: 4,
  min: 2
}

const myPool = genericPool.createPool(factory, config)
Factory methods

v2 expected various factory methods to either accept callbacks or return synchronously, or in some cases had configuration to handle both situation for a method. v3 has moved to using Promises with factory methods, this is done to help simplify internal logic, aid in flow control, rate-limiting, and operation tracking.
create
Where create used to be passed a callback that would then called with (err, resource), it is now called with no arguments and instead should return a Promise. That promise shoul either resolve with a resource or reject with an Error
// OLD
var create = function(callback){
  /* stuff */
  callback(null, resource)
  // or
  callback(err)
}

// NEW
const create = function(){
  return new Promise(function(resolve, reject){
    /* stuff */
    resolve(resource)
    // or
    reject(err)
  })
}
destroy
Where destroy used to be passed a resource and then was then forgotten about , now it is still passed the resource but should return a Promise. That promise should either resolve with any value if the resource is destroyed successfully or reject with an Error if it could not.
// OLD
var destroy = function(resource){
  /* stuff */
}

// NEW
const destroy = function(resource){
  return new Promise(function(resolve, reject){
    /* stuff */
    resolve()
    // or
    reject(err)
  })
}
validate / asynValidate
v2 accepted one of either validate or asyncValidate. validate was passed a resource and expected to return a boolean representing the result of the validation test. asyncValidate was passed a resource and a callback, and expected to call the callback with a boolean representing the result of the validation test. v3 has only one validation method validate which is passed a resource to test and should return a promise that resolves to boolean representing the result of the validation test.
// OLD
var validate = function(resource){
  /* stuff */
  return result
}

var validateAsync = function(resource, callback){
  /* stuff */
  callback(result)
}

// NEW
const validate = function(){
  return new Promise(function(resolve, reject){
    /* stuff */
    resolve(result)
  })
}
Configuration

Various configation options have been renamed/removed/added
removed

name: this seemed a little pointless
log: (operational) logging is outside the scope of low level components like this and didn't give the user much of a useful interface.

changed

returnToHead: this has become fifo and now defaults to true. If you weren't setting this option previously then pools behaviour is unchanged.