Skip to content

Instantly share code, notes, and snippets.

@sandfox
Last active November 30, 2022 00:09
Show Gist options
  • Save sandfox/5ca20648b60a0cb959638c0cd6fcd02d to your computer and use it in GitHub Desktop.
Save sandfox/5ca20648b60a0cb959638c0cd6fcd02d to your computer and use it in GitHub Desktop.
node-pool / generic-pool v2 -> v3 migration guide

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.
@bitsofinfo
Copy link

@jinzlin
Copy link

jinzlin commented Jul 31, 2018

nice

@apmcodes
Copy link

@sandfox You should probably document that pool.destroyAllNow() is no longer available and what to use instead

As per the doc

myPool.drain().then(function() {
  myPool.clear();
});

@msimerson
Copy link

And note that getPoolSize() no longer exists (the test name lives on, but the function is gone).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment