V3 release stuff

[sandfox]

TODOs and DREAMS:

Release blockers

• [x] replace returnToHead with LIFO
• [x] stop using pool._count
• [x] make Pool an event-emitter and emit errors and stuff
  • [x] factory create error
  • [x] factory destroy error
• [x] replace "getThing()" with getters
• [x] rename destroyAllNow() to clear
• [x] make validate promise only and remove validate async option
• [x] make factories accept/return promises for create
• [x] make factories accept/return promises for destroy
• [x] change acquire to return a promise
• [x] make drain return a promise
• [x] make destroyAllNow return promise
• [x] track "inflight" factory.destroy calls/promises
• [x] track validation/test operations/promises
• [x] remove eventEmitters from resourceRequest and instead attach to promise resolution
• [x] track borrowing / borrows (make a promise thats resolved on release/destoy)
• [x] make destroy/release return promises to userland
• [x] migration doc/guide for v2 users
  • [x] moving to promises, and various ways to interop with existing code
  • [ ] option/arg changes
• [x] use doublylinkedlist arrays internally
• [x] replace idleTimeout etc with evictor

  Nice to do before release

• [ ] make and expose Error classes???
• [x] make promise library user changeable
• [ ] fix all the tests!!!
• [x] make a factory for pool
• [ ] make "classic" pool factory that accepts generic-pool@2 constructor args
• [ ] add some internal stats tracking for create/destroy counts etc
• [ ] expose internal stats/counts better
• [ ] add a pool.stop function that wraps pool.drain+pool.clear

  Can wait till after release

• make generic "collection" thing that supports indexes and use it power PooledResourceCollection (like Deferred does ResourceRequest)
• [ ] add support for testOnReturn
• [ ] add optional limit for max number of async-tests-before-borrow allowed in progress???
• [ ] better documenting of internals and general pool concepts

  Future thoughts/ideas

• [ ] add method to clear/drop all outstanding/pending requests in the waiting clients list?
• [ ] track usage using Error (it's stack) on acquire calls ?? (optional)
• [ ] can we make a "pooled" function that works with promises?
• make Pool an event-emitter and emit errors and stuff
  • [ ] minimum pool size reached?
• [ ] do some basic benchmarking (how tho?)
• [ ] allow cancelling acquire calls ???? (this probably depends on cancellable promises and factory.* functions becoming a thing!)
• [ ] look at remove-idle, can we replace the fixed time timer with a smarter one that works out when the next possible idle timeout is and sets to that instead. it will need work slightly differently for FIFO=true/false

[felixfbecker]

make a factory for pool

why this?

change acquire to return a promise make drain return a promise make destroyAllNow return promise

❤️

make and expose Error classes???

👍

Please consider a pre-release, I would be happy to use the promises in a new project atm :)

[felipou]

Awesome! How can I help?

[felixfbecker]

make generic "collection" thing that supports indexes and use it power PooledResourceCollection (like Deferred does ResourceRequest)

What do you mean by this? I always favor ES6 collections

[sandfox]

@felixfbecker

make a factory At some point I'd like to make the Pool class less responsible for instantiating it's own dependencies so that easier for people to replace various implementations of things, and also allows internal changes to be made more easily without breaking the external API.

make generic "collection" thing that supports indexes and use it power PooledResourceCollection (like Deferred does ResourceRequest)

I'm already using Set/Map etc but In some case I need to index the contents of a those collections by some other key. If you look at PooledResourceCollection you might see what I mean. (although I have just changed the internals a bit so exact use-case might have gone!)

Please consider a pre-release, I would be happy to use the promises in a new project atm :) the v3 branch v3-alpha is available on npm under the next tag

npm install [--save] generic-pool@next

I'll try to keep the npm next version up to date with the v3-alpha branch as much as possible. I'm also going to probably add/remove/re-arrange the todo list above a bit. it was just a brain dump.

There is one breaking change the current v3 api I'm going to make soon, and that is to have release/destroy return a promise. Other than that I think it's pretty fixed API wise, but open to suggestions.

[sandfox]

@felipou The biggest/most useful thing would be if you could try using this new version anywhere. I'd like to iron out the external API as much as possible so that v3 can be released, internals can be fixed/changed later.

In terms of work there the tests and the documentation is still patchy and a mess, and something does need to be done about examples and I want to write a migration guide somewhere to help people move from v2 - I know some people are going to dislike the promise change and I want to show them various ways they can adapt to it, or at least inter-op their callback code with it.

[sandfox]

this is now released... let the bugs roll in :-p