├── .eslintignore ├── .eslintrc.js ├── .gitignore ├── .npmignore ├── .travis.yml ├── CHANGELOG.md ├── Makefile ├── README.md ├── index.d.ts ├── index.js ├── lib ├── DefaultEvictor.js ├── Deferred.js ├── Deque.js ├── DequeIterator.js ├── DoublyLinkedList.js ├── DoublyLinkedListIterator.js ├── Pool.js ├── PoolDefaults.js ├── PoolOptions.js ├── PooledResource.js ├── PooledResourceStateEnum.js ├── PriorityQueue.js ├── Queue.js ├── ResourceLoan.js ├── ResourceRequest.js ├── errors.js ├── factoryValidator.js └── utils.js ├── package.json ├── test ├── GH-159-test.js ├── doubly-linked-list-iterator-test.js ├── doubly-linked-list-test.js ├── generic-pool-acquiretimeout-test.js ├── generic-pool-destroytimeout-test.js ├── generic-pool-test.js ├── resource-request-test.js └── utils.js └── tsconfig.json /.eslintignore: -------------------------------------------------------------------------------- 1 | !.eslintrc.js 2 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | parserOptions: { ecmaVersion: 6 }, 3 | plugins: ["prettier"], 4 | rules: { 5 | "prettier/prettier": "error" 6 | }, 7 | extends: ["prettier"] 8 | }; 9 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | fabfile.pyc 2 | node-pool.iml 3 | node-pool.tmproj 4 | node_modules 5 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | .eslintignore 2 | .eslintrc.js 3 | .travis.yml 4 | Makefile 5 | tsconfig.json 6 | test/* 7 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | arch: 3 | - amd64 4 | - ppc64le 5 | node_js: 6 | - "6" 7 | - "8" 8 | - "10" 9 | - "11" 10 | 11 | install: 12 | - make install 13 | 14 | script: 15 | - make lint 16 | - make test 17 | 18 | sudo: false 19 | 20 | matrix: 21 | fast_finish: true 22 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. 4 | 5 | ## [3.9.0](https://github.com/coopernurse/node-pool/compare/v3.8.2...v3.9.0) (2022-09-10) 6 | 7 | 8 | ### Bug Fixes 9 | 10 | * add ready function to index.d.ts ([0a5ef1d](https://github.com/coopernurse/node-pool/commit/0a5ef1dd9124ea7d56626c7cc295e181c15ad4e2)) 11 | * unref setTimeout in pool ([e94fd37](https://github.com/coopernurse/node-pool/commit/e94fd374266acb1531b986050ba7486b03b18250)) 12 | 13 | ## [3.7.1] - March 28 2019 14 | - fix #257 - `pool.use` now destroys resources on rejection, matching the docs. 15 | 16 | ## [3.6.1] - Febuary 6 2019 17 | - fix #251 - silence bluebird warning about side-effect only handler (@sandfox) 18 | - Pool.clear no longer resolves to pointless array on undefineds (@restjohn) 19 | 20 | ## [3.6.0] - Febuary 4 2019 21 | - update docs (@chdh) 22 | - fix #159 - pool.clear can no longer "skip" clearing up resources when called early in pool lifecycle (@sandfox) 23 | 24 | ## [3.5.0] - January 17 2019 25 | - update nodejs versions tested by travis 26 | - eviction iterator no longer stops when reaching end of object list #243 (@DiegoRBaquero) 27 | - fix #192 softIdleTimeoutMillis = -1 no longer triggers evictor to run #242 (@DiegoRBaquero) 28 | - fix #234 maxWaitingClients = 0 is no longer ignored #247 (@anupbaldawa) 29 | 30 | ## [3.4.2] - Febuary 16 2018 31 | - fix `pool.use` to resolve after user supplied function has finished. (@asannes) 32 | 33 | ## [3.4.1] - Febuary 1 2018 34 | - prevent timed-out resource requests from being issued resources (@rebareba) 35 | 36 | ## [3.4.0] - December 27 2017 37 | - #218 fix numerous docblock annotations and minor errors in internal classes (@geovanisouza92) 38 | 39 | ## [3.3.0] - December 27 2017 40 | - add `use` method to simplify basic pool usage (@san00) 41 | 42 | ## [3.2.0] - October 15 2017 43 | - add `isBorrowedResource` method to check if objects are currently on loan from pool (@C-h-e-r-r-y) 44 | 45 | ## [3.1.8] - September 14 2017 46 | - fix undefined and annoying `autostart=false` behaviour (@sushantdhiman) 47 | - document `autostart` behaviour (@sandfox) 48 | - fix typos (@wvanderdeijl @AlexTes) 49 | 50 | ## [3.1.7] - Febuary 9 2017 51 | - fix warning when using bluebird promise impl (@benny-medflyt) 52 | 53 | ## [3.1.6] - December 28 2016 54 | - fix #173 where pool would not attempt to dispense reources upon `pool.destroy` 55 | - fix some out of date readme section 56 | - fix test warning for unhandled rejection on dispense 57 | 58 | ## [3.1.5] - December 20 2016 59 | - fix drain code to correctly wait on borrowed resources (@drew-r) 60 | - fix drain example in readme (@watson) 61 | 62 | ## [3.1.4] - November 28 2016 63 | - fix faulty Promise detection where user supplied promise lib would be ignored 64 | 65 | ## [3.1.3] - November 26 2016 66 | - internal refactoring and comment improvements 67 | - fix #159 so draining and closing don't leave resources behind 68 | - stop the evictor from keeping the event loop open after draining 69 | 70 | ## [3.1.2] - November 22 2016 71 | - Readme tidy up 72 | - Add missing changelog entry 73 | 74 | ## [3.1.1] - November 18 2016 75 | - Add Readme link for legacy branch 76 | 77 | ## [3.1.0] - November 6 2016 78 | - Inject dependencies into Pool to allow easier user extension 79 | 80 | ## [3.0.1] - November 1 2016 81 | - Passthrough Pool's promise impl to deferreds so they are used internally and exposed correctly on pool.acquire (@eide) 82 | 83 | ## [3.0.0] - October 30 2016 84 | - This is pretty big and the migration guide in the README has more detailed set of changes! 85 | - switch support to nodejs v4 and above 86 | - change external interfaces to use promises instead of callbacks 87 | - remove logging 88 | - decouple create/destroy operations from acquire/release operations 89 | - pool should now be created via `poolCreate` factory method instead of constructor. 90 | - huge internal rewrite and flow control changes 91 | - Pool is now an eventEmitter 92 | 93 | ## [2.4.3] - October 15 2016 94 | - Use domain.bind to preserve domain context (@LewisJEllis) 95 | 96 | ## [2.4.2] - March 26 2016 97 | - Travis now runs and fails lint checks (@kevinburke) 98 | - fixed bug #128 where using async validation incorrectly tracked resource state (@johnjdooley and @robfyfe) 99 | - fixed broken readme example that had aged badly 100 | 101 | ## [2.4.1] - February 20 2016 102 | - Documented previously created/fixed bug #122 (thanks @jasonrhodes) 103 | - Improved Makefile and test runner docs thanks (@kevinburke) 104 | - fixed bug documented in #121 where pool could make incorrect decisions about which resources were eligible for removal. (thanks @mikemorris) 105 | 106 | ## [2.4.0] - January 18 2016 107 | - Merged #118 - closes #110 - optional eslinting for test and lib using "standard" ruleset 108 | - Merged #114 - closes #113 - "classes" now used internally instead of object literals and exports support being called as a constructor (along with old factory behaviour) (contributed by @felixfbecker) 109 | - Move history from README.md to CHANGELOG.md and reformat 110 | - Closes #122 - fixes trapped connection bug when destroying a connection while others are in use 111 | 112 | ## [2.3.1] - January 7 2016 113 | - Documentation fixes and widened number of nodejs versions tested on travis 114 | 115 | ## [2.3.0] - January 1 2016 116 | - Merged #105 - allow asynchronous validate functions (contributed by @felipou) 117 | 118 | ## [2.2.2] - December 13 2015 119 | - Merged #106 - fix condition where non "resource pool" created objects could be returned to the pool. (contributed by @devzer01) 120 | 121 | ## [2.2.1] - October 30 2015 122 | - Merged #104 - fix #103 - condition where pool can create > specified max number of connections (contributed by @devzer01) 123 | 124 | ## [2.2.0] - March 26 2015 125 | - Merged #92 - add getMaxPoolSize function (contributed by platypusMaximus) 126 | 127 | ## [2.1.1] - July 5 2015 128 | - fix README error about priority queueing (spotted by @kmdm) 129 | 130 | ## [2.1.0] - June 19 2014 131 | - Merged #72 - Add optional returnToHead flag, if true, resources are returned to head of queue (stack like behaviour) upon release (contributed by calibr), also see #68 for further discussion. 132 | 133 | ## [2.0.4] - July 27 2013 134 | - Merged #64 - Fix for not removing idle objects (contributed by PiotrWpl) 135 | 136 | ## [2.0.3] - January 16 2013 137 | - Merged #56/#57 - Add optional refreshIdle flag. If false, idle resources at the pool minimum will not be destroyed/re-created. (contributed by wshaver) 138 | - Merged #54 - Factory can be asked to validate pooled objects (contributed by tikonen) 139 | 140 | ## [2.0.2] - October 22 2012 141 | - Fix #51, #48 - createResource() should check for null clientCb in err case (contributed by pooyasencha) 142 | - Merged #52 - fix bug of infinite wait when create object aync error (contributed by windyrobin) 143 | - Merged #53 - change the position of dispense and callback to ensure the time order (contributed by windyrobin) 144 | 145 | ## [2.0.1] - August 29 2012 146 | - Fix #44 - leak of 'err' and 'obj' in createResource() 147 | - Add devDependencies block to package.json 148 | - Add travis-ci.org integration 149 | 150 | ## [2.0.0] - July 31 2012 151 | - Non-backwards compatible change: remove adjustCallback 152 | - acquire() callback must accept two params: (err, obj) 153 | - Add optional 'min' param to factory object that specifies minimum number of resources to keep in pool 154 | - Merged #38 (package.json/Makefile changes - contributed by strk) 155 | 156 | ## [1.0.12] - June 27 2012 157 | - Merged #37 (Clear remove idle timer after destroyAllNow - contributed by dougwilson) 158 | 159 | ## [1.0.11] - June 17 2012 160 | - Merged #36 ("pooled" method to perform function decoration for pooled methods - contributed by cosbynator) 161 | 162 | ## [1.0.10] - May 3 2012 163 | - Merged #35 (Remove client from availbleObjects on destroy(client) - contributed by blax) 164 | 165 | ## [1.0.9] - Dec 18 2011 166 | - Merged #25 (add getName() - contributed by BryanDonovan) 167 | - Merged #27 (remove sys import - contributed by botker) 168 | - Merged #26 (log levels - contributed by JoeZ99) 169 | 170 | ## [1.0.8] - Nov 16 2011 171 | - Merged #21 (add getter methods to see pool size, etc. - contributed by BryanDonovan) 172 | 173 | ## [1.0.7] - Oct 17 2011 174 | - Merged #19 (prevent release on the same obj twice - contributed by tkrynski) 175 | - Merged #20 (acquire() returns boolean indicating whether pool is full - contributed by tilgovi) 176 | 177 | ## [1.0.6] - May 23 2011 178 | - Merged #13 (support error variable in acquire callback - contributed by tmcw) 179 | - Note: This change is backwards compatible. But new code should use the two parameter callback format in pool.create() functions from now on. 180 | - Merged #15 (variable scope issue in dispense() - contributed by eevans) 181 | 182 | ## [1.0.5] - Apr 20 2011 183 | - Merged #12 (ability to drain pool - contributed by gdusbabek) 184 | 185 | ## [1.0.4] - Jan 25 2011 186 | - Fixed #6 (objects reaped with undefined timeouts) 187 | - Fixed #7 (objectTimeout issue) 188 | 189 | ## [1.0.3] - Dec 9 2010 190 | - Added priority queueing (thanks to sylvinus) 191 | - Contributions from Poetro 192 | - Name changes to match conventions described here: http://en.wikipedia.org/wiki/Object_pool_pattern 193 | - borrow() renamed to acquire() 194 | - returnToPool() renamed to release() 195 | - destroy() removed from public interface 196 | - added JsDoc comments 197 | - Priority queueing enhancements 198 | 199 | ## [1.0.2] - Nov 9 2010 200 | - First NPM release 201 | 202 | ======= 203 | 204 | [unreleased]: https://github.com/coopernurse/node-pool/compare/v3.7.1...HEAD 205 | [3.7.1]: https://github.com/coopernurse/node-pool/compare/v3.6.1...v3.7.1 206 | [3.6.1]: https://github.com/coopernurse/node-pool/compare/v3.6.0...v3.6.1 207 | [3.6.0]: https://github.com/coopernurse/node-pool/compare/v3.5.0...v3.6.0 208 | [3.5.0]: https://github.com/coopernurse/node-pool/compare/v3.4.2...v3.5.0 209 | [3.4.2]: https://github.com/coopernurse/node-pool/compare/v3.4.1...v3.4.2 210 | [3.4.1]: https://github.com/coopernurse/node-pool/compare/v3.4.0...v3.4.1 211 | [3.4.0]: https://github.com/coopernurse/node-pool/compare/v3.3.0...v3.4.0 212 | [3.3.0]: https://github.com/coopernurse/node-pool/compare/v3.2.0...v3.3.0 213 | [3.2.0]: https://github.com/coopernurse/node-pool/compare/v3.1.8...v3.2.0 214 | [3.1.8]: https://github.com/coopernurse/node-pool/compare/v3.1.7...v3.1.8 215 | [3.1.7]: https://github.com/coopernurse/node-pool/compare/v3.1.6...v3.1.7 216 | [3.1.6]: https://github.com/coopernurse/node-pool/compare/v3.1.5...v3.1.6 217 | [3.1.5]: https://github.com/coopernurse/node-pool/compare/v3.1.4...v3.1.5 218 | [3.1.4]: https://github.com/coopernurse/node-pool/compare/v3.1.3...v3.1.4 219 | [3.1.3]: https://github.com/coopernurse/node-pool/compare/v3.1.2...v3.1.3 220 | [3.1.2]: https://github.com/coopernurse/node-pool/compare/v3.1.1...v3.1.2 221 | [3.1.1]: https://github.com/coopernurse/node-pool/compare/v3.1.0...v3.1.1 222 | [3.1.0]: https://github.com/coopernurse/node-pool/compare/v3.0.1...v3.1.0 223 | [3.0.1]: https://github.com/coopernurse/node-pool/compare/v3.0.0...v3.0.1 224 | [3.0.0]: https://github.com/coopernurse/node-pool/compare/v2.4.3...v3.0.0 225 | [2.4.3]: https://github.com/coopernurse/node-pool/compare/v2.4.2...v2.4.3 226 | [2.4.2]: https://github.com/coopernurse/node-pool/compare/v2.4.1...v2.4.2 227 | [2.4.1]: https://github.com/coopernurse/node-pool/compare/v2.4.0...v2.4.1 228 | [2.4.0]: https://github.com/coopernurse/node-pool/compare/v2.3.1...v2.4.0 229 | [2.3.1]: https://github.com/coopernurse/node-pool/compare/v2.3.0...v2.3.1 230 | [2.3.0]: https://github.com/coopernurse/node-pool/compare/v2.2.2...v2.3.0 231 | [2.2.2]: https://github.com/coopernurse/node-pool/compare/v2.2.1...v2.2.2 232 | [2.2.1]: https://github.com/coopernurse/node-pool/compare/v2.2.0...v2.2.1 233 | [2.2.0]: https://github.com/coopernurse/node-pool/compare/v2.1.1...v2.2.0 234 | [2.1.1]: https://github.com/coopernurse/node-pool/compare/v2.1.0...v2.1.1 235 | [2.1.0]: https://github.com/coopernurse/node-pool/compare/v2.0.4...v2.1.0 236 | [2.0.4]: https://github.com/coopernurse/node-pool/compare/v2.0.3...v2.0.4 237 | [2.0.3]: https://github.com/coopernurse/node-pool/compare/v2.0.2...v2.0.3 238 | [2.0.2]: https://github.com/coopernurse/node-pool/compare/v2.0.1...v2.0.2 239 | [2.0.1]: https://github.com/coopernurse/node-pool/compare/v2.0.0...v2.0.1 240 | [2.0.0]: https://github.com/coopernurse/node-pool/compare/v1.0.12...v2.0.0 241 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: all clean install check test lint 2 | 3 | all: 4 | 5 | clean: 6 | rm -rf node_modules 7 | 8 | install: 9 | npm install 10 | 11 | check: 12 | npm test 13 | 14 | test: 15 | npm test 16 | 17 | lint: 18 | npm run lint 19 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![build status](https://secure.travis-ci.org/coopernurse/node-pool.png)](http://travis-ci.org/coopernurse/node-pool) 2 | 3 | # Generic Pool 4 | 5 | ## About 6 | 7 | Generic resource pool with Promise based API. Can be used to reuse or throttle usage of expensive resources such as database connections. 8 | 9 | 10 | 11 | **V3 upgrade warning** 12 | 13 | Version 3 contains many breaking changes. The differences are mostly minor and I hope easy to accommodate. There is a very rough and basic [upgrade guide](https://gist.github.com/sandfox/5ca20648b60a0cb959638c0cd6fcd02d) I've written, improvements and other attempts most welcome. 14 | 15 | If you are after the older version 2 of this library you should look at the [current github branch](https://github.com/coopernurse/node-pool/tree/v2.5) for it. 16 | 17 | 18 | ## History 19 | 20 | The history has been moved to the [CHANGELOG](CHANGELOG.md) 21 | 22 | 23 | ## Installation 24 | 25 | ```sh 26 | $ npm install generic-pool [--save] 27 | ``` 28 | 29 | 30 | ## Example 31 | 32 | Here is an example using a fictional generic database driver that doesn't implement any pooling whatsoever itself. 33 | 34 | ```js 35 | const genericPool = require("generic-pool"); 36 | const DbDriver = require("some-db-driver"); 37 | 38 | /** 39 | * Step 1 - Create pool using a factory object 40 | */ 41 | const factory = { 42 | create: function() { 43 | return DbDriver.createClient(); 44 | }, 45 | destroy: function(client) { 46 | client.disconnect(); 47 | } 48 | }; 49 | 50 | const opts = { 51 | max: 10, // maximum size of the pool 52 | min: 2 // minimum size of the pool 53 | }; 54 | 55 | const myPool = genericPool.createPool(factory, opts); 56 | 57 | /** 58 | * Step 2 - Use pool in your code to acquire/release resources 59 | */ 60 | 61 | // acquire connection - Promise is resolved 62 | // once a resource becomes available 63 | const resourcePromise = myPool.acquire(); 64 | 65 | resourcePromise 66 | .then(function(client) { 67 | client.query("select * from foo", [], function() { 68 | // return object back to pool 69 | myPool.release(client); 70 | }); 71 | }) 72 | .catch(function(err) { 73 | // handle error - this is generally a timeout or maxWaitingClients 74 | // error 75 | }); 76 | 77 | /** 78 | * Step 3 - Drain pool during shutdown (optional) 79 | */ 80 | // Only call this once in your application -- at the point you want 81 | // to shutdown and stop using this pool. 82 | myPool.drain().then(function() { 83 | myPool.clear(); 84 | }); 85 | 86 | ``` 87 | 88 | 89 | ## Documentation 90 | 91 | 92 | 93 | ### Creating a pool 94 | 95 | Whilst it is possible to directly instantiate the Pool class directly, it is recommended to use the `createPool` function exported by module as the constructor method signature may change in the future. 96 | 97 | ### createPool 98 | 99 | The createPool function takes two arguments: 100 | 101 | - `factory` : an object containing functions to create/destroy/test resources for the `Pool` 102 | - `opts` : an optional object/dictonary to allow configuring/altering behaviour of the `Pool` 103 | 104 | ```js 105 | const genericPool = require('generic-pool') 106 | const pool = genericPool.createPool(factory, opts) 107 | ``` 108 | 109 | **factory** 110 | 111 | Can be any object/instance but must have the following properties: 112 | 113 | - `create` : a function that the pool will call when it wants a new resource. It should return a Promise that either resolves to a `resource` or rejects to an `Error` if it is unable to create a resource for whatever reason. 114 | - `destroy`: a function that the pool will call when it wants to destroy a resource. It should accept one argument `resource` where `resource` is whatever `factory.create` made. The `destroy` function should return a `Promise` that resolves once it has destroyed the resource. 115 | 116 | 117 | optionally it can also have the following property: 118 | 119 | - `validate`: a function that the pool will call if it wants to validate a resource. It should accept one argument `resource` where `resource` is whatever `factory.create` made. Should return a `Promise` that resolves a `boolean` where `true` indicates the resource is still valid or `false` if the resource is invalid. 120 | 121 | _Note: The values returned from `create`, `destroy`, and `validate` are all wrapped in a `Promise.resolve` by the pool before being used internally._ 122 | 123 | **opts** 124 | 125 | An optional object/dictionary with the any of the following properties: 126 | 127 | - `max`: maximum number of resources to create at any given time. (default=1) 128 | - `min`: minimum number of resources to keep in pool at any given time. If this is set >= max, the pool will silently set the min to equal `max`. (default=0) 129 | - `maxWaitingClients`: maximum number of queued requests allowed, additional `acquire` calls will be callback with an `err` in a future cycle of the event loop. 130 | - `testOnBorrow`: `boolean`: should the pool validate resources before giving them to clients. Requires that `factory.validate` is specified. 131 | - `acquireTimeoutMillis`: max milliseconds an `acquire` call will wait for a resource before timing out. (default no limit), if supplied should non-zero positive integer. 132 | - `destroyTimeoutMillis`: max milliseconds a `destroy` call will wait for a resource before timing out. (default no limit), if supplied should non-zero positive integer. 133 | - `fifo` : if true the oldest resources will be first to be allocated. If false the most recently released resources will be the first to be allocated. This in effect turns the pool's behaviour from a queue into a stack. `boolean`, (default true) 134 | - `priorityRange`: int between 1 and x - if set, borrowers can specify their relative priority in the queue if no resources are available. 135 | see example. (default 1) 136 | - `autostart`: boolean, should the pool start creating resources, initialize the evictor, etc once the constructor is called. If false, the pool can be started by calling `pool.start`, otherwise the first call to `acquire` will start the pool. (default true) 137 | - `evictionRunIntervalMillis`: How often to run eviction checks. Default: 0 (does not run). 138 | - `numTestsPerEvictionRun`: Number of resources to check each eviction run. Default: 3. 139 | - `softIdleTimeoutMillis`: amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any), with the extra condition that at least "min idle" object instances remain in the pool. Default -1 (nothing can get evicted) 140 | - `idleTimeoutMillis`: the minimum amount of time that an object may sit idle in the pool before it is eligible for eviction due to idle time. Supercedes `softIdleTimeoutMillis` Default: 30000 141 | - `Promise`: Promise lib, a Promises/A+ implementation that the pool should use. Defaults to whatever `global.Promise` is (usually native promises). 142 | 143 | ### pool.acquire 144 | 145 | ```js 146 | const onfulfilled = function(resource){ 147 | resource.doStuff() 148 | // release/destroy/etc 149 | } 150 | 151 | pool.acquire().then(onfulfilled) 152 | //or 153 | const priority = 2 154 | pool.acquire(priority).then(onfulfilled) 155 | ``` 156 | 157 | This function is for when you want to "borrow" a resource from the pool. 158 | 159 | `acquire` takes one optional argument: 160 | 161 | - `priority`: optional, number, see **Priority Queueing** below. 162 | 163 | and returns a `Promise` 164 | Once a resource in the pool is available, the promise will be resolved with a `resource` (whatever `factory.create` makes for you). If the Pool is unable to give a resource (e.g timeout) then the promise will be rejected with an `Error` 165 | 166 | ### pool.release 167 | 168 | ```js 169 | pool.release(resource) 170 | ``` 171 | 172 | This function is for when you want to return a resource to the pool. 173 | 174 | `release` takes one required argument: 175 | 176 | - `resource`: a previously borrowed resource 177 | 178 | and returns a `Promise`. This promise will resolve once the `resource` is accepted by the pool, or reject if the pool is unable to accept the `resource` for any reason (e.g `resource` is not a resource or object that came from the pool). If you do not care the outcome it is safe to ignore this promise. 179 | 180 | ### pool.isBorrowedResource 181 | 182 | ```js 183 | pool.isBorrowedResource(resource) 184 | ``` 185 | 186 | This function is for when you need to check if a resource has been acquired from the pool and not yet released/destroyed. 187 | 188 | `isBorrowedResource` takes one required argument: 189 | 190 | - `resource`: any object which you need to test 191 | 192 | and returns true (primitive, not Promise) if resource is currently borrowed from the pool, false otherwise. 193 | 194 | ### pool.destroy 195 | 196 | ```js 197 | pool.destroy(resource) 198 | ``` 199 | 200 | This function is for when you want to return a resource to the pool but want it destroyed rather than being made available to other resources. E.g you may know the resource has timed out or crashed. 201 | 202 | `destroy` takes one required argument: 203 | 204 | - `resource`: a previously borrowed resource 205 | 206 | and returns a `Promise`. This promise will resolve once the `resource` is accepted by the pool, or reject if the pool is unable to accept the `resource` for any reason (e.g `resource` is not a resource or object that came from the pool). If you do not care the outcome it is safe to ignore this promise. 207 | 208 | ### pool.on 209 | 210 | ```js 211 | pool.on('factoryCreateError', function(err){ 212 | //log stuff maybe 213 | }) 214 | 215 | pool.on('factoryDestroyError', function(err){ 216 | //log stuff maybe 217 | }) 218 | ``` 219 | 220 | The pool is an event emitter. Below are the events it emits and any args for those events 221 | 222 | - `factoryCreateError` : emitted when a promise returned by `factory.create` is rejected. If this event has no listeners then the `error` will be silently discarded 223 | - `error`: whatever `reason` the promise was rejected with. 224 | 225 | - `factoryDestroyError` : emitted when a promise returned by `factory.destroy` is rejected. If this event has no listeners then the `error` will be silently discarded 226 | - `error`: whatever `reason` the promise was rejected with. 227 | 228 | ### pool.start 229 | 230 | ```js 231 | pool.start() 232 | ``` 233 | 234 | If `autostart` is `false` then this method can be used to start the pool and therefore begin creation of resources, start the evictor, and any other internal logic. 235 | 236 | ### pool.ready 237 | 238 | ```js 239 | pool.ready() 240 | ``` 241 | 242 | Waits for the pool to fully start. 243 | 244 | ### pool.use 245 | 246 | ```js 247 | 248 | const myTask = dbClient => { 249 | return new Promise( (resolve, reject) => { 250 | // do something with the client and resolve/reject 251 | }) 252 | } 253 | 254 | pool.use(myTask).then(/* a promise that will run after myTask resolves */) 255 | ``` 256 | 257 | This method handles acquiring a `resource` from the pool, handing it to your function and then calling `pool.release` or `pool.destroy` with resource after your function has finished. 258 | 259 | `use` takes one required argument: 260 | 261 | - `fn`: a function that accepts a `resource` and returns a `Promise`. Once that promise `resolve`s the `resource` is returned to the pool, else if it `reject`s then the resource is destroyed. 262 | - `priority`: Optionally, you can specify the priority as number. See [Priority Queueing](#priority-queueing) section. 263 | 264 | and returns a `Promise` that either `resolve`s with the value from the user supplied `fn` or `reject`s with an error. 265 | 266 | ## Idle Object Eviction 267 | 268 | The pool has an evictor (off by default) which will inspect idle items in the pool and `destroy` them if they are too old. 269 | 270 | By default the evictor does not run, to enable it you must set the `evictionRunIntervalMillis` option to a non-zero value. Once enable the evictor will check at most `numTestsPerEvictionRun` each time, this is to stop it blocking your application if you have lots of resources in the pool. 271 | 272 | 273 | ## Priority Queueing 274 | 275 | The pool supports optional priority queueing. This becomes relevant when no resources are available and the caller has to wait. `acquire()` accepts an optional priority int which 276 | specifies the caller's relative position in the queue. Each priority slot has it's own internal queue created for it. When a resource is available for borrowing, the first request in the highest priority queue will be given it. 277 | 278 | Specifying a `priority` to `acquire` that is outside the `priorityRange` set at `Pool` creation time will result in the `priority` being converted the lowest possible `priority` 279 | 280 | ```js 281 | // create pool with priorityRange of 3 282 | // borrowers can specify a priority 0 to 2 283 | const opts = { 284 | priorityRange : 3 285 | } 286 | const pool = genericPool.createPool(someFactory,opts); 287 | 288 | // acquire connection - no priority specified - will go onto lowest priority queue 289 | pool.acquire().then(function(client) { 290 | pool.release(client); 291 | }); 292 | 293 | // acquire connection - high priority - will go into highest priority queue 294 | pool.acquire(0).then(function(client) { 295 | pool.release(client); 296 | }); 297 | 298 | // acquire connection - medium priority - will go into 'mid' priority queue 299 | pool.acquire(1).then(function(client) { 300 | pool.release(client); 301 | }); 302 | 303 | // etc.. 304 | ``` 305 | 306 | ## Draining 307 | 308 | If you are shutting down a long-lived process, you may notice 309 | that node fails to exit for 30 seconds or so. This is a side 310 | effect of the idleTimeoutMillis behavior -- the pool has a 311 | setTimeout() call registered that is in the event loop queue, so 312 | node won't terminate until all resources have timed out, and the pool 313 | stops trying to manage them. 314 | 315 | This behavior will be more problematic when you set factory.min > 0, 316 | as the pool will never become empty, and the setTimeout calls will 317 | never end. 318 | 319 | In these cases, use the pool.drain() function. This sets the pool 320 | into a "draining" state which will gracefully wait until all 321 | idle resources have timed out. For example, you can call: 322 | 323 | If you do this, your node process will exit gracefully. 324 | 325 | If you know you would like to terminate all the available resources in your pool before any timeouts they might have are reached, you can use `clear()` in conjunction with `drain()`: 326 | 327 | ```js 328 | const p = pool.drain() 329 | .then(function() { 330 | return pool.clear(); 331 | }); 332 | ``` 333 | The `promise` returned will resolve once all waiting clients have acquired and return resources, and any available resources have been destroyed 334 | 335 | One side-effect of calling `drain()` is that subsequent calls to `acquire()` 336 | will throw an Error. 337 | 338 | ## Pooled function decoration 339 | 340 | This has now been extracted out it's own module [generic-pool-decorator](https://github.com/sandfox/generic-pool-decorator) 341 | 342 | ## Pool info 343 | 344 | The following properties will let you get information about the pool: 345 | 346 | ```js 347 | 348 | // How many many more resources can the pool manage/create 349 | pool.spareResourceCapacity 350 | 351 | // returns number of resources in the pool regardless of 352 | // whether they are free or in use 353 | pool.size 354 | 355 | // returns number of unused resources in the pool 356 | pool.available 357 | 358 | // number of resources that are currently acquired by userland code 359 | pool.borrowed 360 | 361 | // returns number of callers waiting to acquire a resource 362 | pool.pending 363 | 364 | // returns number of maxixmum number of resources allowed by pool 365 | pool.max 366 | 367 | // returns number of minimum number of resources allowed by pool 368 | pool.min 369 | 370 | ``` 371 | 372 | ## Run Tests 373 | 374 | $ npm install 375 | $ npm test 376 | 377 | The tests are run/written using Tap. Most are ports from the old espresso tests and are not in great condition. Most cases are inside `test/generic-pool-test.js` with newer cases in their own files (legacy reasons). 378 | 379 | ## Linting 380 | 381 | We use eslint combined with prettier 382 | 383 | 384 | ## License 385 | 386 | (The MIT License) 387 | 388 | Copyright (c) 2010-2016 James Cooper <james@bitmechanic.com> 389 | 390 | Permission is hereby granted, free of charge, to any person obtaining 391 | a copy of this software and associated documentation files (the 392 | 'Software'), to deal in the Software without restriction, including 393 | without limitation the rights to use, copy, modify, merge, publish, 394 | distribute, sublicense, and/or sell copies of the Software, and to 395 | permit persons to whom the Software is furnished to do so, subject to 396 | the following conditions: 397 | 398 | The above copyright notice and this permission notice shall be 399 | included in all copies or substantial portions of the Software. 400 | 401 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 402 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 403 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 404 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 405 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 406 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 407 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 408 | -------------------------------------------------------------------------------- /index.d.ts: -------------------------------------------------------------------------------- 1 | // Type definitions for node-pool 3.1 2 | // Derived from https://github.com/DefinitelyTyped/DefinitelyTyped 3 | // -> https://github.com/DefinitelyTyped/DefinitelyTyped/blob/454dcbcbe5e932010b128dca9793758dd28adb45/types/generic-pool/index.d.ts 4 | 5 | /// 6 | 7 | import { EventEmitter } from "events"; 8 | 9 | export class Deferred { 10 | get state(): 'PENDING' | 'FULFILLED' | 'REJECTED'; 11 | 12 | get promise(): Promise; 13 | 14 | reject(reason: any): void; 15 | 16 | resolve(value: T): void; 17 | } 18 | 19 | export class ResourceRequest extends Deferred { 20 | setTimeout(delay: number): void; 21 | 22 | removeTimeout(): void; 23 | } 24 | 25 | export enum PooledResourceStateEnum { 26 | ALLOCATED = 'ALLOCATED', 27 | IDLE = 'IDLE', 28 | INVALID = 'INVALID', 29 | RETURNING = 'RETURNING', 30 | VALIDATION = 'VALIDATION', 31 | } 32 | 33 | export class PooledResource { 34 | creationTime: number; 35 | lastReturnTime?: number; 36 | lastBorrowTime?: number; 37 | lastIdleTime?: number; 38 | obj: T; 39 | state: PooledResourceStateEnum; 40 | 41 | allocate(): void; 42 | 43 | deallocate(): void; 44 | 45 | invalidate(): void; 46 | 47 | test(): void; 48 | 49 | idle(): void; 50 | 51 | returning(): void; 52 | } 53 | 54 | export interface IDeque extends Iterable { 55 | shift(): T | undefined; 56 | 57 | unshift(element: T): void; 58 | 59 | push(element: T): void; 60 | 61 | pop(): T | undefined; 62 | 63 | get head(): T | undefined; 64 | 65 | get tail(): T | undefined; 66 | 67 | get length(): number; 68 | 69 | iterator(): Iterator; 70 | 71 | reverseIterator(): Iterator; 72 | } 73 | 74 | export class Deque implements IDeque { 75 | shift(): T | undefined; 76 | 77 | unshift(element: T): void; 78 | 79 | push(element: T): void; 80 | 81 | pop(): T | undefined; 82 | 83 | get head(): T | undefined; 84 | 85 | get tail(): T | undefined; 86 | 87 | get length(): number; 88 | 89 | iterator(): Iterator; 90 | 91 | reverseIterator(): Iterator; 92 | 93 | [Symbol.iterator](): Iterator; 94 | } 95 | 96 | export interface IPriorityQueue { 97 | get length(): number; 98 | 99 | enqueue(obj: T, priority?: number): void; 100 | 101 | dequeue(): T | undefined; 102 | 103 | get head(): T | undefined; 104 | 105 | get tail(): T | undefined; 106 | } 107 | 108 | export class PriorityQueue implements IPriorityQueue { 109 | constructor(priorityRange: number); 110 | 111 | get length(): number; 112 | 113 | enqueue(obj: T, priority?: number): void; 114 | 115 | dequeue(): T | undefined; 116 | 117 | get head(): T | undefined; 118 | 119 | get tail(): T | undefined; 120 | } 121 | 122 | export interface IEvictorConfig { 123 | softIdleTimeoutMillis: number; 124 | idleTimeoutMillis: number; 125 | min: number; 126 | } 127 | 128 | export interface IEvictor { 129 | evict(config: IEvictorConfig, pooledResource: PooledResource, availableObjectsCount: number): boolean; 130 | } 131 | 132 | export class DefaultEvictor implements IEvictor { 133 | evict(config: IEvictorConfig, pooledResource: PooledResource, availableObjectsCount: number): boolean; 134 | } 135 | 136 | export interface Factory { 137 | create(): Promise; 138 | 139 | destroy(client: T): Promise; 140 | 141 | validate?(client: T): Promise; 142 | } 143 | 144 | export interface Options { 145 | max?: number; 146 | min?: number; 147 | maxWaitingClients?: number; 148 | testOnBorrow?: boolean; 149 | acquireTimeoutMillis?: number; 150 | destroyTimeoutMillis?: number; 151 | fifo?: boolean; 152 | priorityRange?: number; 153 | autostart?: boolean; 154 | evictionRunIntervalMillis?: number; 155 | numTestsPerEvictionRun?: number; 156 | softIdleTimeoutMillis?: number; 157 | idleTimeoutMillis?: number; 158 | } 159 | 160 | export class Pool extends EventEmitter { 161 | spareResourceCapacity: number; 162 | size: number; 163 | available: number; 164 | borrowed: number; 165 | pending: number; 166 | max: number; 167 | min: number; 168 | 169 | constructor( 170 | Evictor: { new (): IEvictor }, 171 | Deque: { new (): IDeque> }, 172 | PriorityQueue: { new (priorityRange: number): IPriorityQueue> }, 173 | factory: Factory, 174 | options?: Options, 175 | ); 176 | 177 | start(): void; 178 | 179 | acquire(priority?: number): Promise; 180 | 181 | release(resource: T): Promise; 182 | 183 | destroy(resource: T): Promise; 184 | 185 | drain(): Promise; 186 | 187 | clear(): Promise; 188 | 189 | use(cb: (resource: T) => U | Promise): Promise; 190 | 191 | isBorrowedResource(resource: T): boolean; 192 | 193 | ready(): Promise; 194 | } 195 | 196 | export function createPool(factory: Factory, opts?: Options): Pool; 197 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | const Pool = require("./lib/Pool"); 2 | const Deque = require("./lib/Deque"); 3 | const PriorityQueue = require("./lib/PriorityQueue"); 4 | const DefaultEvictor = require("./lib/DefaultEvictor"); 5 | module.exports = { 6 | Pool: Pool, 7 | Deque: Deque, 8 | PriorityQueue: PriorityQueue, 9 | DefaultEvictor: DefaultEvictor, 10 | createPool: function(factory, config) { 11 | return new Pool(DefaultEvictor, Deque, PriorityQueue, factory, config); 12 | } 13 | }; 14 | -------------------------------------------------------------------------------- /lib/DefaultEvictor.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | class DefaultEvictor { 4 | evict(config, pooledResource, availableObjectsCount) { 5 | const idleTime = Date.now() - pooledResource.lastIdleTime; 6 | 7 | if ( 8 | config.softIdleTimeoutMillis > 0 && 9 | config.softIdleTimeoutMillis < idleTime && 10 | config.min < availableObjectsCount 11 | ) { 12 | return true; 13 | } 14 | 15 | if (config.idleTimeoutMillis < idleTime) { 16 | return true; 17 | } 18 | 19 | return false; 20 | } 21 | } 22 | 23 | module.exports = DefaultEvictor; 24 | -------------------------------------------------------------------------------- /lib/Deferred.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | /** 4 | * This is apparently a bit like a Jquery deferred, hence the name 5 | */ 6 | 7 | class Deferred { 8 | constructor(Promise) { 9 | this._state = Deferred.PENDING; 10 | this._resolve = undefined; 11 | this._reject = undefined; 12 | 13 | this._promise = new Promise((resolve, reject) => { 14 | this._resolve = resolve; 15 | this._reject = reject; 16 | }); 17 | } 18 | 19 | get state() { 20 | return this._state; 21 | } 22 | 23 | get promise() { 24 | return this._promise; 25 | } 26 | 27 | reject(reason) { 28 | if (this._state !== Deferred.PENDING) { 29 | return; 30 | } 31 | this._state = Deferred.REJECTED; 32 | this._reject(reason); 33 | } 34 | 35 | resolve(value) { 36 | if (this._state !== Deferred.PENDING) { 37 | return; 38 | } 39 | this._state = Deferred.FULFILLED; 40 | this._resolve(value); 41 | } 42 | } 43 | 44 | // TODO: should these really live here? or be a seperate 'state' enum 45 | Deferred.PENDING = "PENDING"; 46 | Deferred.FULFILLED = "FULFILLED"; 47 | Deferred.REJECTED = "REJECTED"; 48 | 49 | module.exports = Deferred; 50 | -------------------------------------------------------------------------------- /lib/Deque.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const DoublyLinkedList = require("./DoublyLinkedList"); 4 | const DequeIterator = require("./DequeIterator"); 5 | /** 6 | * DoublyLinkedList backed double ended queue 7 | * implements just enough to keep the Pool 8 | */ 9 | class Deque { 10 | constructor() { 11 | this._list = new DoublyLinkedList(); 12 | } 13 | 14 | /** 15 | * removes and returns the first element from the queue 16 | * @return {any} [description] 17 | */ 18 | shift() { 19 | if (this.length === 0) { 20 | return undefined; 21 | } 22 | 23 | const node = this._list.head; 24 | this._list.remove(node); 25 | 26 | return node.data; 27 | } 28 | 29 | /** 30 | * adds one elemts to the beginning of the queue 31 | * @param {any} element [description] 32 | * @return {any} [description] 33 | */ 34 | unshift(element) { 35 | const node = DoublyLinkedList.createNode(element); 36 | 37 | this._list.insertBeginning(node); 38 | } 39 | 40 | /** 41 | * adds one to the end of the queue 42 | * @param {any} element [description] 43 | * @return {any} [description] 44 | */ 45 | push(element) { 46 | const node = DoublyLinkedList.createNode(element); 47 | 48 | this._list.insertEnd(node); 49 | } 50 | 51 | /** 52 | * removes and returns the last element from the queue 53 | */ 54 | pop() { 55 | if (this.length === 0) { 56 | return undefined; 57 | } 58 | 59 | const node = this._list.tail; 60 | this._list.remove(node); 61 | 62 | return node.data; 63 | } 64 | 65 | [Symbol.iterator]() { 66 | return new DequeIterator(this._list); 67 | } 68 | 69 | iterator() { 70 | return new DequeIterator(this._list); 71 | } 72 | 73 | reverseIterator() { 74 | return new DequeIterator(this._list, true); 75 | } 76 | 77 | /** 78 | * get a reference to the item at the head of the queue 79 | * @return {any} [description] 80 | */ 81 | get head() { 82 | if (this.length === 0) { 83 | return undefined; 84 | } 85 | const node = this._list.head; 86 | return node.data; 87 | } 88 | 89 | /** 90 | * get a reference to the item at the tail of the queue 91 | * @return {any} [description] 92 | */ 93 | get tail() { 94 | if (this.length === 0) { 95 | return undefined; 96 | } 97 | const node = this._list.tail; 98 | return node.data; 99 | } 100 | 101 | get length() { 102 | return this._list.length; 103 | } 104 | } 105 | 106 | module.exports = Deque; 107 | -------------------------------------------------------------------------------- /lib/DequeIterator.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const DoublyLinkedListIterator = require("./DoublyLinkedListIterator"); 4 | /** 5 | * Thin wrapper around an underlying DDL iterator 6 | */ 7 | class DequeIterator extends DoublyLinkedListIterator { 8 | next() { 9 | const result = super.next(); 10 | 11 | // unwrap the node... 12 | if (result.value) { 13 | result.value = result.value.data; 14 | } 15 | 16 | return result; 17 | } 18 | } 19 | 20 | module.exports = DequeIterator; 21 | -------------------------------------------------------------------------------- /lib/DoublyLinkedList.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | /** 4 | * A Doubly Linked List, because there aren't enough in the world... 5 | * this is pretty much a direct JS port of the one wikipedia 6 | * https://en.wikipedia.org/wiki/Doubly_linked_list 7 | * 8 | * For most usage 'insertBeginning' and 'insertEnd' should be enough 9 | * 10 | * nodes are expected to something like a POJSO like 11 | * { 12 | * prev: null, 13 | * next: null, 14 | * something: 'whatever you like' 15 | * } 16 | */ 17 | class DoublyLinkedList { 18 | constructor() { 19 | this.head = null; 20 | this.tail = null; 21 | this.length = 0; 22 | } 23 | 24 | insertBeginning(node) { 25 | if (this.head === null) { 26 | this.head = node; 27 | this.tail = node; 28 | node.prev = null; 29 | node.next = null; 30 | this.length++; 31 | } else { 32 | this.insertBefore(this.head, node); 33 | } 34 | } 35 | 36 | insertEnd(node) { 37 | if (this.tail === null) { 38 | this.insertBeginning(node); 39 | } else { 40 | this.insertAfter(this.tail, node); 41 | } 42 | } 43 | 44 | insertAfter(node, newNode) { 45 | newNode.prev = node; 46 | newNode.next = node.next; 47 | if (node.next === null) { 48 | this.tail = newNode; 49 | } else { 50 | node.next.prev = newNode; 51 | } 52 | node.next = newNode; 53 | this.length++; 54 | } 55 | 56 | insertBefore(node, newNode) { 57 | newNode.prev = node.prev; 58 | newNode.next = node; 59 | if (node.prev === null) { 60 | this.head = newNode; 61 | } else { 62 | node.prev.next = newNode; 63 | } 64 | node.prev = newNode; 65 | this.length++; 66 | } 67 | 68 | remove(node) { 69 | if (node.prev === null) { 70 | this.head = node.next; 71 | } else { 72 | node.prev.next = node.next; 73 | } 74 | if (node.next === null) { 75 | this.tail = node.prev; 76 | } else { 77 | node.next.prev = node.prev; 78 | } 79 | node.prev = null; 80 | node.next = null; 81 | this.length--; 82 | } 83 | 84 | // FIXME: this should not live here and has become a dumping ground... 85 | static createNode(data) { 86 | return { 87 | prev: null, 88 | next: null, 89 | data: data 90 | }; 91 | } 92 | } 93 | 94 | module.exports = DoublyLinkedList; 95 | -------------------------------------------------------------------------------- /lib/DoublyLinkedListIterator.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | /** 4 | * Creates an interator for a DoublyLinkedList starting at the given node 5 | * It's internal cursor will remains relative to the last "iterated" node as that 6 | * node moves through the list until it either iterates to the end of the list, 7 | * or the the node it's tracking is removed from the list. Until the first 'next' 8 | * call it tracks the head/tail of the linked list. This means that one can create 9 | * an iterator on an empty list, then add nodes, and then the iterator will follow 10 | * those nodes. Because the DoublyLinkedList nodes don't track their owning "list" and 11 | * it's highly inefficient to walk the list for every iteration, the iterator won't know 12 | * if the node has been detached from one List and added to another list, or if the iterator 13 | * 14 | * The created object is an es6 compatible iterator 15 | */ 16 | class DoublyLinkedListIterator { 17 | /** 18 | * @param {Object} doublyLinkedList a node that is part of a doublyLinkedList 19 | * @param {Boolean} [reverse=false] is this a reverse iterator? default: false 20 | */ 21 | constructor(doublyLinkedList, reverse) { 22 | this._list = doublyLinkedList; 23 | // NOTE: these key names are tied to the DoublyLinkedListIterator 24 | this._direction = reverse === true ? "prev" : "next"; 25 | this._startPosition = reverse === true ? "tail" : "head"; 26 | this._started = false; 27 | this._cursor = null; 28 | this._done = false; 29 | } 30 | 31 | _start() { 32 | this._cursor = this._list[this._startPosition]; 33 | this._started = true; 34 | } 35 | 36 | _advanceCursor() { 37 | if (this._started === false) { 38 | this._started = true; 39 | this._cursor = this._list[this._startPosition]; 40 | return; 41 | } 42 | this._cursor = this._cursor[this._direction]; 43 | } 44 | 45 | reset() { 46 | this._done = false; 47 | this._started = false; 48 | this._cursor = null; 49 | } 50 | 51 | remove() { 52 | if ( 53 | this._started === false || 54 | this._done === true || 55 | this._isCursorDetached() 56 | ) { 57 | return false; 58 | } 59 | this._list.remove(this._cursor); 60 | } 61 | 62 | next() { 63 | if (this._done === true) { 64 | return { done: true }; 65 | } 66 | 67 | this._advanceCursor(); 68 | 69 | // if there is no node at the cursor or the node at the cursor is no longer part of 70 | // a doubly linked list then we are done/finished/kaput 71 | if (this._cursor === null || this._isCursorDetached()) { 72 | this._done = true; 73 | return { done: true }; 74 | } 75 | 76 | return { 77 | value: this._cursor, 78 | done: false 79 | }; 80 | } 81 | 82 | /** 83 | * Is the node detached from a list? 84 | * NOTE: you can trick/bypass/confuse this check by removing a node from one DoublyLinkedList 85 | * and adding it to another. 86 | * TODO: We can make this smarter by checking the direction of travel and only checking 87 | * the required next/prev/head/tail rather than all of them 88 | * @return {Boolean} [description] 89 | */ 90 | _isCursorDetached() { 91 | return ( 92 | this._cursor.prev === null && 93 | this._cursor.next === null && 94 | this._list.tail !== this._cursor && 95 | this._list.head !== this._cursor 96 | ); 97 | } 98 | } 99 | 100 | module.exports = DoublyLinkedListIterator; 101 | -------------------------------------------------------------------------------- /lib/Pool.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const EventEmitter = require("events").EventEmitter; 4 | 5 | const factoryValidator = require("./factoryValidator"); 6 | const PoolOptions = require("./PoolOptions"); 7 | const ResourceRequest = require("./ResourceRequest"); 8 | const ResourceLoan = require("./ResourceLoan"); 9 | const PooledResource = require("./PooledResource"); 10 | const DefaultEvictor = require("./DefaultEvictor"); 11 | const Deque = require("./Deque"); 12 | const Deferred = require("./Deferred"); 13 | const PriorityQueue = require("./PriorityQueue"); 14 | const DequeIterator = require("./DequeIterator"); 15 | 16 | const reflector = require("./utils").reflector; 17 | 18 | /** 19 | * TODO: move me 20 | */ 21 | const FACTORY_CREATE_ERROR = "factoryCreateError"; 22 | const FACTORY_DESTROY_ERROR = "factoryDestroyError"; 23 | 24 | class Pool extends EventEmitter { 25 | /** 26 | * Generate an Object pool with a specified `factory` and `config`. 27 | * 28 | * @param {typeof DefaultEvictor} Evictor 29 | * @param {typeof Deque} Deque 30 | * @param {typeof PriorityQueue} PriorityQueue 31 | * @param {Object} factory 32 | * Factory to be used for generating and destroying the items. 33 | * @param {Function} factory.create 34 | * Should create the item to be acquired, 35 | * and call it's first callback argument with the generated item as it's argument. 36 | * @param {Function} factory.destroy 37 | * Should gently close any resources that the item is using. 38 | * Called before the items is destroyed. 39 | * @param {Function} factory.validate 40 | * Test if a resource is still valid .Should return a promise that resolves to a boolean, true if resource is still valid and false 41 | * If it should be removed from pool. 42 | * @param {Object} options 43 | */ 44 | constructor(Evictor, Deque, PriorityQueue, factory, options) { 45 | super(); 46 | 47 | factoryValidator(factory); 48 | 49 | this._config = new PoolOptions(options); 50 | 51 | // TODO: fix up this ugly glue-ing 52 | this._Promise = this._config.Promise; 53 | 54 | this._factory = factory; 55 | this._draining = false; 56 | this._started = false; 57 | /** 58 | * Holds waiting clients 59 | * @type {PriorityQueue} 60 | */ 61 | this._waitingClientsQueue = new PriorityQueue(this._config.priorityRange); 62 | 63 | /** 64 | * Collection of promises for resource creation calls made by the pool to factory.create 65 | * @type {Set} 66 | */ 67 | this._factoryCreateOperations = new Set(); 68 | 69 | /** 70 | * Collection of promises for resource destruction calls made by the pool to factory.destroy 71 | * @type {Set} 72 | */ 73 | this._factoryDestroyOperations = new Set(); 74 | 75 | /** 76 | * A queue/stack of pooledResources awaiting acquisition 77 | * TODO: replace with LinkedList backed array 78 | * @type {Deque} 79 | */ 80 | this._availableObjects = new Deque(); 81 | 82 | /** 83 | * Collection of references for any resource that are undergoing validation before being acquired 84 | * @type {Set} 85 | */ 86 | this._testOnBorrowResources = new Set(); 87 | 88 | /** 89 | * Collection of references for any resource that are undergoing validation before being returned 90 | * @type {Set} 91 | */ 92 | this._testOnReturnResources = new Set(); 93 | 94 | /** 95 | * Collection of promises for any validations currently in process 96 | * @type {Set} 97 | */ 98 | this._validationOperations = new Set(); 99 | 100 | /** 101 | * All objects associated with this pool in any state (except destroyed) 102 | * @type {Set} 103 | */ 104 | this._allObjects = new Set(); 105 | 106 | /** 107 | * Loans keyed by the borrowed resource 108 | * @type {Map} 109 | */ 110 | this._resourceLoans = new Map(); 111 | 112 | /** 113 | * Infinitely looping iterator over available object 114 | * @type {DequeIterator} 115 | */ 116 | this._evictionIterator = this._availableObjects.iterator(); 117 | 118 | this._evictor = new Evictor(); 119 | 120 | /** 121 | * handle for setTimeout for next eviction run 122 | * @type {(number|null)} 123 | */ 124 | this._scheduledEviction = null; 125 | 126 | // create initial resources (if factory.min > 0) 127 | if (this._config.autostart === true) { 128 | this.start(); 129 | } 130 | } 131 | 132 | _destroy(pooledResource) { 133 | // FIXME: do we need another state for "in destruction"? 134 | pooledResource.invalidate(); 135 | this._allObjects.delete(pooledResource); 136 | // NOTE: this maybe very bad promise usage? 137 | const destroyPromise = this._factory.destroy(pooledResource.obj); 138 | const wrappedDestroyPromise = this._config.destroyTimeoutMillis 139 | ? this._Promise.resolve(this._applyDestroyTimeout(destroyPromise)) 140 | : this._Promise.resolve(destroyPromise); 141 | 142 | this._trackOperation( 143 | wrappedDestroyPromise, 144 | this._factoryDestroyOperations 145 | ).catch(reason => { 146 | this.emit(FACTORY_DESTROY_ERROR, reason); 147 | }); 148 | 149 | // TODO: maybe ensuring minimum pool size should live outside here 150 | this._ensureMinimum(); 151 | } 152 | 153 | _applyDestroyTimeout(promise) { 154 | const timeoutPromise = new this._Promise((resolve, reject) => { 155 | setTimeout(() => { 156 | reject(new Error("destroy timed out")); 157 | }, this._config.destroyTimeoutMillis).unref(); 158 | }); 159 | return this._Promise.race([timeoutPromise, promise]); 160 | } 161 | 162 | /** 163 | * Attempt to move an available resource into test and then onto a waiting client 164 | * @return {Boolean} could we move an available resource into test 165 | */ 166 | _testOnBorrow() { 167 | if (this._availableObjects.length < 1) { 168 | return false; 169 | } 170 | 171 | const pooledResource = this._availableObjects.shift(); 172 | // Mark the resource as in test 173 | pooledResource.test(); 174 | this._testOnBorrowResources.add(pooledResource); 175 | const validationPromise = this._factory.validate(pooledResource.obj); 176 | const wrappedValidationPromise = this._Promise.resolve(validationPromise); 177 | 178 | this._trackOperation( 179 | wrappedValidationPromise, 180 | this._validationOperations 181 | ).then(isValid => { 182 | this._testOnBorrowResources.delete(pooledResource); 183 | 184 | if (isValid === false) { 185 | pooledResource.invalidate(); 186 | this._destroy(pooledResource); 187 | this._dispense(); 188 | return; 189 | } 190 | this._dispatchPooledResourceToNextWaitingClient(pooledResource); 191 | }); 192 | 193 | return true; 194 | } 195 | 196 | /** 197 | * Attempt to move an available resource to a waiting client 198 | * @return {Boolean} [description] 199 | */ 200 | _dispatchResource() { 201 | if (this._availableObjects.length < 1) { 202 | return false; 203 | } 204 | 205 | const pooledResource = this._availableObjects.shift(); 206 | this._dispatchPooledResourceToNextWaitingClient(pooledResource); 207 | return false; 208 | } 209 | 210 | /** 211 | * Attempt to resolve an outstanding resource request using an available resource from 212 | * the pool, or creating new ones 213 | * 214 | * @private 215 | */ 216 | _dispense() { 217 | /** 218 | * Local variables for ease of reading/writing 219 | * these don't (shouldn't) change across the execution of this fn 220 | */ 221 | const numWaitingClients = this._waitingClientsQueue.length; 222 | 223 | // If there aren't any waiting requests then there is nothing to do 224 | // so lets short-circuit 225 | if (numWaitingClients < 1) { 226 | return; 227 | } 228 | 229 | const resourceShortfall = 230 | numWaitingClients - this._potentiallyAllocableResourceCount; 231 | 232 | const actualNumberOfResourcesToCreate = Math.min( 233 | this.spareResourceCapacity, 234 | resourceShortfall 235 | ); 236 | for (let i = 0; actualNumberOfResourcesToCreate > i; i++) { 237 | this._createResource(); 238 | } 239 | 240 | // If we are doing test-on-borrow see how many more resources need to be moved into test 241 | // to help satisfy waitingClients 242 | if (this._config.testOnBorrow === true) { 243 | // how many available resources do we need to shift into test 244 | const desiredNumberOfResourcesToMoveIntoTest = 245 | numWaitingClients - this._testOnBorrowResources.size; 246 | const actualNumberOfResourcesToMoveIntoTest = Math.min( 247 | this._availableObjects.length, 248 | desiredNumberOfResourcesToMoveIntoTest 249 | ); 250 | for (let i = 0; actualNumberOfResourcesToMoveIntoTest > i; i++) { 251 | this._testOnBorrow(); 252 | } 253 | } 254 | 255 | // if we aren't testing-on-borrow then lets try to allocate what we can 256 | if (this._config.testOnBorrow === false) { 257 | const actualNumberOfResourcesToDispatch = Math.min( 258 | this._availableObjects.length, 259 | numWaitingClients 260 | ); 261 | for (let i = 0; actualNumberOfResourcesToDispatch > i; i++) { 262 | this._dispatchResource(); 263 | } 264 | } 265 | } 266 | 267 | /** 268 | * Dispatches a pooledResource to the next waiting client (if any) else 269 | * puts the PooledResource back on the available list 270 | * @param {PooledResource} pooledResource [description] 271 | * @return {Boolean} [description] 272 | */ 273 | _dispatchPooledResourceToNextWaitingClient(pooledResource) { 274 | const clientResourceRequest = this._waitingClientsQueue.dequeue(); 275 | if ( 276 | clientResourceRequest === undefined || 277 | clientResourceRequest.state !== Deferred.PENDING 278 | ) { 279 | // While we were away either all the waiting clients timed out 280 | // or were somehow fulfilled. put our pooledResource back. 281 | this._addPooledResourceToAvailableObjects(pooledResource); 282 | // TODO: do need to trigger anything before we leave? 283 | return false; 284 | } 285 | const loan = new ResourceLoan(pooledResource, this._Promise); 286 | this._resourceLoans.set(pooledResource.obj, loan); 287 | pooledResource.allocate(); 288 | clientResourceRequest.resolve(pooledResource.obj); 289 | return true; 290 | } 291 | 292 | /** 293 | * tracks on operation using given set 294 | * handles adding/removing from the set and resolve/rejects the value/reason 295 | * @param {Promise} operation 296 | * @param {Set} set Set holding operations 297 | * @return {Promise} Promise that resolves once operation has been removed from set 298 | */ 299 | _trackOperation(operation, set) { 300 | set.add(operation); 301 | 302 | return operation.then( 303 | v => { 304 | set.delete(operation); 305 | return this._Promise.resolve(v); 306 | }, 307 | e => { 308 | set.delete(operation); 309 | return this._Promise.reject(e); 310 | } 311 | ); 312 | } 313 | 314 | /** 315 | * @private 316 | */ 317 | _createResource() { 318 | // An attempt to create a resource 319 | const factoryPromise = this._factory.create(); 320 | const wrappedFactoryPromise = this._Promise 321 | .resolve(factoryPromise) 322 | .then(resource => { 323 | const pooledResource = new PooledResource(resource); 324 | this._allObjects.add(pooledResource); 325 | this._addPooledResourceToAvailableObjects(pooledResource); 326 | }); 327 | 328 | this._trackOperation(wrappedFactoryPromise, this._factoryCreateOperations) 329 | .then(() => { 330 | this._dispense(); 331 | // Stop bluebird complaining about this side-effect only handler 332 | // - a promise was created in a handler but was not returned from it 333 | // https://goo.gl/rRqMUw 334 | return null; 335 | }) 336 | .catch(reason => { 337 | this.emit(FACTORY_CREATE_ERROR, reason); 338 | this._dispense(); 339 | }); 340 | } 341 | 342 | /** 343 | * @private 344 | */ 345 | _ensureMinimum() { 346 | if (this._draining === true) { 347 | return; 348 | } 349 | const minShortfall = this._config.min - this._count; 350 | for (let i = 0; i < minShortfall; i++) { 351 | this._createResource(); 352 | } 353 | } 354 | 355 | _evict() { 356 | const testsToRun = Math.min( 357 | this._config.numTestsPerEvictionRun, 358 | this._availableObjects.length 359 | ); 360 | const evictionConfig = { 361 | softIdleTimeoutMillis: this._config.softIdleTimeoutMillis, 362 | idleTimeoutMillis: this._config.idleTimeoutMillis, 363 | min: this._config.min 364 | }; 365 | for (let testsHaveRun = 0; testsHaveRun < testsToRun; ) { 366 | const iterationResult = this._evictionIterator.next(); 367 | 368 | // Safety check incase we could get stuck in infinite loop because we 369 | // somehow emptied the array after checking its length. 370 | if (iterationResult.done === true && this._availableObjects.length < 1) { 371 | this._evictionIterator.reset(); 372 | return; 373 | } 374 | // If this happens it should just mean we reached the end of the 375 | // list and can reset the cursor. 376 | if (iterationResult.done === true && this._availableObjects.length > 0) { 377 | this._evictionIterator.reset(); 378 | continue; 379 | } 380 | 381 | const resource = iterationResult.value; 382 | 383 | const shouldEvict = this._evictor.evict( 384 | evictionConfig, 385 | resource, 386 | this._availableObjects.length 387 | ); 388 | testsHaveRun++; 389 | 390 | if (shouldEvict === true) { 391 | // take it out of the _availableObjects list 392 | this._evictionIterator.remove(); 393 | this._destroy(resource); 394 | } 395 | } 396 | } 397 | 398 | _scheduleEvictorRun() { 399 | // Start eviction if set 400 | if (this._config.evictionRunIntervalMillis > 0) { 401 | // @ts-ignore 402 | this._scheduledEviction = setTimeout(() => { 403 | this._evict(); 404 | this._scheduleEvictorRun(); 405 | }, this._config.evictionRunIntervalMillis).unref(); 406 | } 407 | } 408 | 409 | _descheduleEvictorRun() { 410 | if (this._scheduledEviction) { 411 | clearTimeout(this._scheduledEviction); 412 | } 413 | this._scheduledEviction = null; 414 | } 415 | 416 | start() { 417 | if (this._draining === true) { 418 | return; 419 | } 420 | if (this._started === true) { 421 | return; 422 | } 423 | this._started = true; 424 | this._scheduleEvictorRun(); 425 | this._ensureMinimum(); 426 | } 427 | 428 | /** 429 | * Request a new resource. The callback will be called, 430 | * when a new resource is available, passing the resource to the callback. 431 | * TODO: should we add a seperate "acquireWithPriority" function 432 | * 433 | * @param {Number} [priority=0] 434 | * Optional. Integer between 0 and (priorityRange - 1). Specifies the priority 435 | * of the caller if there are no available resources. Lower numbers mean higher 436 | * priority. 437 | * 438 | * @returns {Promise} 439 | */ 440 | acquire(priority) { 441 | if (this._started === false && this._config.autostart === false) { 442 | this.start(); 443 | } 444 | 445 | if (this._draining) { 446 | return this._Promise.reject( 447 | new Error("pool is draining and cannot accept work") 448 | ); 449 | } 450 | 451 | // TODO: should we defer this check till after this event loop incase "the situation" changes in the meantime 452 | if ( 453 | this.spareResourceCapacity < 1 && 454 | this._availableObjects.length < 1 && 455 | this._config.maxWaitingClients !== undefined && 456 | this._waitingClientsQueue.length >= this._config.maxWaitingClients 457 | ) { 458 | return this._Promise.reject( 459 | new Error("max waitingClients count exceeded") 460 | ); 461 | } 462 | 463 | const resourceRequest = new ResourceRequest( 464 | this._config.acquireTimeoutMillis, 465 | this._Promise 466 | ); 467 | this._waitingClientsQueue.enqueue(resourceRequest, priority); 468 | this._dispense(); 469 | 470 | return resourceRequest.promise; 471 | } 472 | 473 | /** 474 | * [use method, aquires a resource, passes the resource to a user supplied function and releases it] 475 | * @param {Function} fn [a function that accepts a resource and returns a promise that resolves/rejects once it has finished using the resource] 476 | * @return {Promise} [resolves once the resource is released to the pool] 477 | */ 478 | use(fn, priority) { 479 | return this.acquire(priority).then(resource => { 480 | return fn(resource).then( 481 | result => { 482 | this.release(resource); 483 | return result; 484 | }, 485 | err => { 486 | this.destroy(resource); 487 | throw err; 488 | } 489 | ); 490 | }); 491 | } 492 | 493 | /** 494 | * Check if resource is currently on loan from the pool 495 | * 496 | * @param {Function} resource 497 | * Resource for checking. 498 | * 499 | * @returns {Boolean} 500 | * True if resource belongs to this pool and false otherwise 501 | */ 502 | isBorrowedResource(resource) { 503 | return this._resourceLoans.has(resource); 504 | } 505 | 506 | /** 507 | * Return the resource to the pool when it is no longer required. 508 | * 509 | * @param {Object} resource 510 | * The acquired object to be put back to the pool. 511 | */ 512 | release(resource) { 513 | // check for an outstanding loan 514 | const loan = this._resourceLoans.get(resource); 515 | 516 | if (loan === undefined) { 517 | return this._Promise.reject( 518 | new Error("Resource not currently part of this pool") 519 | ); 520 | } 521 | 522 | this._resourceLoans.delete(resource); 523 | loan.resolve(); 524 | const pooledResource = loan.pooledResource; 525 | 526 | pooledResource.deallocate(); 527 | this._addPooledResourceToAvailableObjects(pooledResource); 528 | 529 | this._dispense(); 530 | return this._Promise.resolve(); 531 | } 532 | 533 | /** 534 | * Request the resource to be destroyed. The factory's destroy handler 535 | * will also be called. 536 | * 537 | * This should be called within an acquire() block as an alternative to release(). 538 | * 539 | * @param {Object} resource 540 | * The acquired resource to be destoyed. 541 | */ 542 | destroy(resource) { 543 | // check for an outstanding loan 544 | const loan = this._resourceLoans.get(resource); 545 | 546 | if (loan === undefined) { 547 | return this._Promise.reject( 548 | new Error("Resource not currently part of this pool") 549 | ); 550 | } 551 | 552 | this._resourceLoans.delete(resource); 553 | loan.resolve(); 554 | const pooledResource = loan.pooledResource; 555 | 556 | pooledResource.deallocate(); 557 | this._destroy(pooledResource); 558 | 559 | this._dispense(); 560 | return this._Promise.resolve(); 561 | } 562 | 563 | _addPooledResourceToAvailableObjects(pooledResource) { 564 | pooledResource.idle(); 565 | if (this._config.fifo === true) { 566 | this._availableObjects.push(pooledResource); 567 | } else { 568 | this._availableObjects.unshift(pooledResource); 569 | } 570 | } 571 | 572 | /** 573 | * Disallow any new acquire calls and let the request backlog dissapate. 574 | * The Pool will no longer attempt to maintain a "min" number of resources 575 | * and will only make new resources on demand. 576 | * Resolves once all resource requests are fulfilled and all resources are returned to pool and available... 577 | * Should probably be called "drain work" 578 | * @returns {Promise} 579 | */ 580 | drain() { 581 | this._draining = true; 582 | return this.__allResourceRequestsSettled() 583 | .then(() => { 584 | return this.__allResourcesReturned(); 585 | }) 586 | .then(() => { 587 | this._descheduleEvictorRun(); 588 | }); 589 | } 590 | 591 | __allResourceRequestsSettled() { 592 | if (this._waitingClientsQueue.length > 0) { 593 | // wait for last waiting client to be settled 594 | // FIXME: what if they can "resolve" out of order....? 595 | return reflector(this._waitingClientsQueue.tail.promise); 596 | } 597 | return this._Promise.resolve(); 598 | } 599 | 600 | // FIXME: this is a horrific mess 601 | __allResourcesReturned() { 602 | const ps = Array.from(this._resourceLoans.values()) 603 | .map(loan => loan.promise) 604 | .map(reflector); 605 | return this._Promise.all(ps); 606 | } 607 | 608 | /** 609 | * Forcibly destroys all available resources regardless of timeout. Intended to be 610 | * invoked as part of a drain. Does not prevent the creation of new 611 | * resources as a result of subsequent calls to acquire. 612 | * 613 | * Note that if factory.min > 0 and the pool isn't "draining", the pool will destroy all idle resources 614 | * in the pool, but replace them with newly created resources up to the 615 | * specified factory.min value. If this is not desired, set factory.min 616 | * to zero before calling clear() 617 | * 618 | */ 619 | clear() { 620 | const reflectedCreatePromises = Array.from( 621 | this._factoryCreateOperations 622 | ).map(reflector); 623 | 624 | // wait for outstanding factory.create to complete 625 | return this._Promise.all(reflectedCreatePromises).then(() => { 626 | // Destroy existing resources 627 | // @ts-ignore 628 | for (const resource of this._availableObjects) { 629 | this._destroy(resource); 630 | } 631 | const reflectedDestroyPromises = Array.from( 632 | this._factoryDestroyOperations 633 | ).map(reflector); 634 | return reflector(this._Promise.all(reflectedDestroyPromises)); 635 | }); 636 | } 637 | 638 | /** 639 | * Waits until the pool is ready. 640 | * We define ready by checking if the current resource number is at least 641 | * the minimum number defined. 642 | * @returns {Promise} that resolves when the minimum number is ready. 643 | */ 644 | ready() { 645 | return new this._Promise(resolve => { 646 | const isReady = () => { 647 | if (this.available >= this.min) { 648 | resolve(); 649 | } else { 650 | setTimeout(isReady, 100); 651 | } 652 | }; 653 | 654 | isReady(); 655 | }); 656 | } 657 | 658 | /** 659 | * How many resources are available to allocated 660 | * (includes resources that have not been tested and may faul validation) 661 | * NOTE: internal for now as the name is awful and might not be useful to anyone 662 | * @return {Number} number of resources the pool has to allocate 663 | */ 664 | get _potentiallyAllocableResourceCount() { 665 | return ( 666 | this._availableObjects.length + 667 | this._testOnBorrowResources.size + 668 | this._testOnReturnResources.size + 669 | this._factoryCreateOperations.size 670 | ); 671 | } 672 | 673 | /** 674 | * The combined count of the currently created objects and those in the 675 | * process of being created 676 | * Does NOT include resources in the process of being destroyed 677 | * sort of legacy... 678 | * @return {Number} 679 | */ 680 | get _count() { 681 | return this._allObjects.size + this._factoryCreateOperations.size; 682 | } 683 | 684 | /** 685 | * How many more resources does the pool have room for 686 | * @return {Number} number of resources the pool could create before hitting any limits 687 | */ 688 | get spareResourceCapacity() { 689 | return ( 690 | this._config.max - 691 | (this._allObjects.size + this._factoryCreateOperations.size) 692 | ); 693 | } 694 | 695 | /** 696 | * see _count above 697 | * @return {Number} [description] 698 | */ 699 | get size() { 700 | return this._count; 701 | } 702 | 703 | /** 704 | * number of available resources 705 | * @return {Number} [description] 706 | */ 707 | get available() { 708 | return this._availableObjects.length; 709 | } 710 | 711 | /** 712 | * number of resources that are currently acquired 713 | * @return {Number} [description] 714 | */ 715 | get borrowed() { 716 | return this._resourceLoans.size; 717 | } 718 | 719 | /** 720 | * number of waiting acquire calls 721 | * @return {Number} [description] 722 | */ 723 | get pending() { 724 | return this._waitingClientsQueue.length; 725 | } 726 | 727 | /** 728 | * maximum size of the pool 729 | * @return {Number} [description] 730 | */ 731 | get max() { 732 | return this._config.max; 733 | } 734 | 735 | /** 736 | * minimum size of the pool 737 | * @return {Number} [description] 738 | */ 739 | get min() { 740 | return this._config.min; 741 | } 742 | } 743 | 744 | module.exports = Pool; 745 | -------------------------------------------------------------------------------- /lib/PoolDefaults.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | /** 3 | * Create the default settings used by the pool 4 | * 5 | * @class 6 | */ 7 | class PoolDefaults { 8 | constructor() { 9 | this.fifo = true; 10 | this.priorityRange = 1; 11 | 12 | this.testOnBorrow = false; 13 | this.testOnReturn = false; 14 | 15 | this.autostart = true; 16 | 17 | this.evictionRunIntervalMillis = 0; 18 | this.numTestsPerEvictionRun = 3; 19 | this.softIdleTimeoutMillis = -1; 20 | this.idleTimeoutMillis = 30000; 21 | 22 | // FIXME: no defaults! 23 | this.acquireTimeoutMillis = null; 24 | this.destroyTimeoutMillis = null; 25 | this.maxWaitingClients = null; 26 | 27 | this.min = null; 28 | this.max = null; 29 | // FIXME: this seems odd? 30 | this.Promise = Promise; 31 | } 32 | } 33 | 34 | module.exports = PoolDefaults; 35 | -------------------------------------------------------------------------------- /lib/PoolOptions.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const PoolDefaults = require("./PoolDefaults"); 4 | 5 | class PoolOptions { 6 | /** 7 | * @param {Object} opts 8 | * configuration for the pool 9 | * @param {Number} [opts.max=null] 10 | * Maximum number of items that can exist at the same time. Default: 1. 11 | * Any further acquire requests will be pushed to the waiting list. 12 | * @param {Number} [opts.min=null] 13 | * Minimum number of items in pool (including in-use). Default: 0. 14 | * When the pool is created, or a resource destroyed, this minimum will 15 | * be checked. If the pool resource count is below the minimum, a new 16 | * resource will be created and added to the pool. 17 | * @param {Number} [opts.maxWaitingClients=null] 18 | * maximum number of queued requests allowed after which acquire calls will be rejected 19 | * @param {Boolean} [opts.testOnBorrow=false] 20 | * should the pool validate resources before giving them to clients. Requires that 21 | * `factory.validate` is specified. 22 | * @param {Boolean} [opts.testOnReturn=false] 23 | * should the pool validate resources before returning them to the pool. 24 | * @param {Number} [opts.acquireTimeoutMillis=null] 25 | * Delay in milliseconds after which the an `acquire` call will fail. optional. 26 | * Default: undefined. Should be positive and non-zero 27 | * @param {Number} [opts.destroyTimeoutMillis=null] 28 | * Delay in milliseconds after which the an `destroy` call will fail, causing it to emit a factoryDestroyError event. optional. 29 | * Default: undefined. Should be positive and non-zero 30 | * @param {Number} [opts.priorityRange=1] 31 | * The range from 1 to be treated as a valid priority 32 | * @param {Boolean} [opts.fifo=true] 33 | * Sets whether the pool has LIFO (last in, first out) behaviour with respect to idle objects. 34 | * if false then pool has FIFO behaviour 35 | * @param {Boolean} [opts.autostart=true] 36 | * Should the pool start creating resources etc once the constructor is called 37 | * @param {Number} [opts.evictionRunIntervalMillis=0] 38 | * How often to run eviction checks. Default: 0 (does not run). 39 | * @param {Number} [opts.numTestsPerEvictionRun=3] 40 | * Number of resources to check each eviction run. Default: 3. 41 | * @param {Number} [opts.softIdleTimeoutMillis=-1] 42 | * amount of time an object may sit idle in the pool before it is eligible 43 | * for eviction by the idle object evictor (if any), with the extra condition 44 | * that at least "min idle" object instances remain in the pool. Default -1 (nothing can get evicted) 45 | * @param {Number} [opts.idleTimeoutMillis=30000] 46 | * the minimum amount of time that an object may sit idle in the pool before it is eligible for eviction 47 | * due to idle time. Supercedes "softIdleTimeoutMillis" Default: 30000 48 | * @param {typeof Promise} [opts.Promise=Promise] 49 | * What promise implementation should the pool use, defaults to native promises. 50 | */ 51 | constructor(opts) { 52 | const poolDefaults = new PoolDefaults(); 53 | 54 | opts = opts || {}; 55 | 56 | this.fifo = typeof opts.fifo === "boolean" ? opts.fifo : poolDefaults.fifo; 57 | this.priorityRange = opts.priorityRange || poolDefaults.priorityRange; 58 | 59 | this.testOnBorrow = 60 | typeof opts.testOnBorrow === "boolean" 61 | ? opts.testOnBorrow 62 | : poolDefaults.testOnBorrow; 63 | this.testOnReturn = 64 | typeof opts.testOnReturn === "boolean" 65 | ? opts.testOnReturn 66 | : poolDefaults.testOnReturn; 67 | 68 | this.autostart = 69 | typeof opts.autostart === "boolean" 70 | ? opts.autostart 71 | : poolDefaults.autostart; 72 | 73 | if (opts.acquireTimeoutMillis) { 74 | // @ts-ignore 75 | this.acquireTimeoutMillis = parseInt(opts.acquireTimeoutMillis, 10); 76 | } 77 | 78 | if (opts.destroyTimeoutMillis) { 79 | // @ts-ignore 80 | this.destroyTimeoutMillis = parseInt(opts.destroyTimeoutMillis, 10); 81 | } 82 | 83 | if (opts.maxWaitingClients !== undefined) { 84 | // @ts-ignore 85 | this.maxWaitingClients = parseInt(opts.maxWaitingClients, 10); 86 | } 87 | 88 | // @ts-ignore 89 | this.max = parseInt(opts.max, 10); 90 | // @ts-ignore 91 | this.min = parseInt(opts.min, 10); 92 | 93 | this.max = Math.max(isNaN(this.max) ? 1 : this.max, 1); 94 | this.min = Math.min(isNaN(this.min) ? 0 : this.min, this.max); 95 | 96 | this.evictionRunIntervalMillis = 97 | opts.evictionRunIntervalMillis || poolDefaults.evictionRunIntervalMillis; 98 | this.numTestsPerEvictionRun = 99 | opts.numTestsPerEvictionRun || poolDefaults.numTestsPerEvictionRun; 100 | this.softIdleTimeoutMillis = 101 | opts.softIdleTimeoutMillis || poolDefaults.softIdleTimeoutMillis; 102 | this.idleTimeoutMillis = 103 | opts.idleTimeoutMillis || poolDefaults.idleTimeoutMillis; 104 | 105 | this.Promise = opts.Promise != null ? opts.Promise : poolDefaults.Promise; 106 | } 107 | } 108 | 109 | module.exports = PoolOptions; 110 | -------------------------------------------------------------------------------- /lib/PooledResource.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const PooledResourceStateEnum = require("./PooledResourceStateEnum"); 4 | 5 | /** 6 | * @class 7 | * @private 8 | */ 9 | class PooledResource { 10 | constructor(resource) { 11 | this.creationTime = Date.now(); 12 | this.lastReturnTime = null; 13 | this.lastBorrowTime = null; 14 | this.lastIdleTime = null; 15 | this.obj = resource; 16 | this.state = PooledResourceStateEnum.IDLE; 17 | } 18 | 19 | // mark the resource as "allocated" 20 | allocate() { 21 | this.lastBorrowTime = Date.now(); 22 | this.state = PooledResourceStateEnum.ALLOCATED; 23 | } 24 | 25 | // mark the resource as "deallocated" 26 | deallocate() { 27 | this.lastReturnTime = Date.now(); 28 | this.state = PooledResourceStateEnum.IDLE; 29 | } 30 | 31 | invalidate() { 32 | this.state = PooledResourceStateEnum.INVALID; 33 | } 34 | 35 | test() { 36 | this.state = PooledResourceStateEnum.VALIDATION; 37 | } 38 | 39 | idle() { 40 | this.lastIdleTime = Date.now(); 41 | this.state = PooledResourceStateEnum.IDLE; 42 | } 43 | 44 | returning() { 45 | this.state = PooledResourceStateEnum.RETURNING; 46 | } 47 | } 48 | 49 | module.exports = PooledResource; 50 | -------------------------------------------------------------------------------- /lib/PooledResourceStateEnum.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const PooledResourceStateEnum = { 4 | ALLOCATED: "ALLOCATED", // In use 5 | IDLE: "IDLE", // In the queue, not in use. 6 | INVALID: "INVALID", // Failed validation 7 | RETURNING: "RETURNING", // Resource is in process of returning 8 | VALIDATION: "VALIDATION" // Currently being tested 9 | }; 10 | 11 | module.exports = PooledResourceStateEnum; 12 | -------------------------------------------------------------------------------- /lib/PriorityQueue.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const Queue = require("./Queue"); 4 | 5 | /** 6 | * @class 7 | * @private 8 | */ 9 | class PriorityQueue { 10 | constructor(size) { 11 | this._size = Math.max(+size | 0, 1); 12 | /** @type {Queue[]} */ 13 | this._slots = []; 14 | // initialize arrays to hold queue elements 15 | for (let i = 0; i < this._size; i++) { 16 | this._slots.push(new Queue()); 17 | } 18 | } 19 | 20 | get length() { 21 | let _length = 0; 22 | for (let i = 0, slots = this._slots.length; i < slots; i++) { 23 | _length += this._slots[i].length; 24 | } 25 | return _length; 26 | } 27 | 28 | enqueue(obj, priority) { 29 | // Convert to integer with a default value of 0. 30 | priority = (priority && +priority | 0) || 0; 31 | 32 | if (priority) { 33 | if (priority < 0 || priority >= this._size) { 34 | priority = this._size - 1; 35 | // put obj at the end of the line 36 | } 37 | } 38 | this._slots[priority].push(obj); 39 | } 40 | 41 | dequeue() { 42 | for (let i = 0, sl = this._slots.length; i < sl; i += 1) { 43 | if (this._slots[i].length) { 44 | return this._slots[i].shift(); 45 | } 46 | } 47 | return; 48 | } 49 | 50 | get head() { 51 | for (let i = 0, sl = this._slots.length; i < sl; i += 1) { 52 | if (this._slots[i].length > 0) { 53 | return this._slots[i].head; 54 | } 55 | } 56 | return; 57 | } 58 | 59 | get tail() { 60 | for (let i = this._slots.length - 1; i >= 0; i--) { 61 | if (this._slots[i].length > 0) { 62 | return this._slots[i].tail; 63 | } 64 | } 65 | return; 66 | } 67 | } 68 | 69 | module.exports = PriorityQueue; 70 | -------------------------------------------------------------------------------- /lib/Queue.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const DoublyLinkedList = require("./DoublyLinkedList"); 4 | const Deque = require("./Deque"); 5 | 6 | /** 7 | * Sort of a internal queue for holding the waiting 8 | * resource requets for a given "priority". 9 | * Also handles managing timeouts rejections on items (is this the best place for this?) 10 | * This is the last point where we know which queue a resourceRequest is in 11 | * 12 | */ 13 | class Queue extends Deque { 14 | /** 15 | * Adds the obj to the end of the list for this slot 16 | * we completely override the parent method because we need access to the 17 | * node for our rejection handler 18 | * @param {any} resourceRequest [description] 19 | */ 20 | push(resourceRequest) { 21 | const node = DoublyLinkedList.createNode(resourceRequest); 22 | resourceRequest.promise.catch(this._createTimeoutRejectionHandler(node)); 23 | this._list.insertEnd(node); 24 | } 25 | 26 | _createTimeoutRejectionHandler(node) { 27 | return reason => { 28 | if (reason.name === "TimeoutError") { 29 | this._list.remove(node); 30 | } 31 | }; 32 | } 33 | } 34 | 35 | module.exports = Queue; 36 | -------------------------------------------------------------------------------- /lib/ResourceLoan.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const Deferred = require("./Deferred"); 4 | 5 | /** 6 | * Plan is to maybe add tracking via Error objects 7 | * and other fun stuff! 8 | */ 9 | 10 | class ResourceLoan extends Deferred { 11 | /** 12 | * 13 | * @param {any} pooledResource the PooledResource this loan belongs to 14 | * @return {any} [description] 15 | */ 16 | constructor(pooledResource, Promise) { 17 | super(Promise); 18 | this._creationTimestamp = Date.now(); 19 | this.pooledResource = pooledResource; 20 | } 21 | 22 | reject() { 23 | /** 24 | * Loans can only be resolved at the moment 25 | */ 26 | } 27 | } 28 | 29 | module.exports = ResourceLoan; 30 | -------------------------------------------------------------------------------- /lib/ResourceRequest.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const Deferred = require("./Deferred"); 4 | const errors = require("./errors"); 5 | 6 | function fbind(fn, ctx) { 7 | return function bound() { 8 | return fn.apply(ctx, arguments); 9 | }; 10 | } 11 | 12 | /** 13 | * Wraps a users request for a resource 14 | * Basically a promise mashed in with a timeout 15 | * @private 16 | */ 17 | class ResourceRequest extends Deferred { 18 | /** 19 | * [constructor description] 20 | * @param {Number} ttl timeout 21 | */ 22 | constructor(ttl, Promise) { 23 | super(Promise); 24 | this._creationTimestamp = Date.now(); 25 | this._timeout = null; 26 | 27 | if (ttl !== undefined) { 28 | this.setTimeout(ttl); 29 | } 30 | } 31 | 32 | setTimeout(delay) { 33 | if (this._state !== ResourceRequest.PENDING) { 34 | return; 35 | } 36 | const ttl = parseInt(delay, 10); 37 | 38 | if (isNaN(ttl) || ttl <= 0) { 39 | throw new Error("delay must be a positive int"); 40 | } 41 | 42 | const age = Date.now() - this._creationTimestamp; 43 | 44 | if (this._timeout) { 45 | this.removeTimeout(); 46 | } 47 | 48 | this._timeout = setTimeout( 49 | fbind(this._fireTimeout, this), 50 | Math.max(ttl - age, 0) 51 | ); 52 | } 53 | 54 | removeTimeout() { 55 | if (this._timeout) { 56 | clearTimeout(this._timeout); 57 | } 58 | this._timeout = null; 59 | } 60 | 61 | _fireTimeout() { 62 | this.reject(new errors.TimeoutError("ResourceRequest timed out")); 63 | } 64 | 65 | reject(reason) { 66 | this.removeTimeout(); 67 | super.reject(reason); 68 | } 69 | 70 | resolve(value) { 71 | this.removeTimeout(); 72 | super.resolve(value); 73 | } 74 | } 75 | 76 | module.exports = ResourceRequest; 77 | -------------------------------------------------------------------------------- /lib/errors.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | class ExtendableError extends Error { 4 | constructor(message) { 5 | super(message); 6 | // @ts-ignore 7 | this.name = this.constructor.name; 8 | this.message = message; 9 | if (typeof Error.captureStackTrace === "function") { 10 | Error.captureStackTrace(this, this.constructor); 11 | } else { 12 | this.stack = new Error(message).stack; 13 | } 14 | } 15 | } 16 | 17 | /* eslint-disable no-useless-constructor */ 18 | class TimeoutError extends ExtendableError { 19 | constructor(m) { 20 | super(m); 21 | } 22 | } 23 | /* eslint-enable no-useless-constructor */ 24 | 25 | module.exports = { 26 | TimeoutError: TimeoutError 27 | }; 28 | -------------------------------------------------------------------------------- /lib/factoryValidator.js: -------------------------------------------------------------------------------- 1 | module.exports = function(factory) { 2 | if (typeof factory.create !== "function") { 3 | throw new TypeError("factory.create must be a function"); 4 | } 5 | 6 | if (typeof factory.destroy !== "function") { 7 | throw new TypeError("factory.destroy must be a function"); 8 | } 9 | 10 | if ( 11 | typeof factory.validate !== "undefined" && 12 | typeof factory.validate !== "function" 13 | ) { 14 | throw new TypeError("factory.validate must be a function"); 15 | } 16 | }; 17 | -------------------------------------------------------------------------------- /lib/utils.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | function noop() {} 4 | 5 | /** 6 | * Reflects a promise but does not expose any 7 | * underlying value or rejection from that promise. 8 | * @param {Promise} promise [description] 9 | * @return {Promise} [description] 10 | */ 11 | exports.reflector = function(promise) { 12 | return promise.then(noop, noop); 13 | }; 14 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "generic-pool", 3 | "description": "Generic resource pooling for Node.JS", 4 | "homepage": "https://github.com/coopernurse/node-pool#readme", 5 | "version": "3.9.0", 6 | "main": "index.js", 7 | "author": { 8 | "email": "james@bitmechanic.com", 9 | "name": "James Cooper" 10 | }, 11 | "contributors": [ 12 | { 13 | "name": "James Butler", 14 | "email": "james.butler@sandfox.co.uk" 15 | }, 16 | { 17 | "name": "Kiko Beats", 18 | "email": "josefrancisco.verdu@gmail.com" 19 | }, 20 | { 21 | "name": "Felipe Machado", 22 | "email": "felipou@gmail.com" 23 | }, 24 | { 25 | "name": "Idan Attias", 26 | "email": "idana@wix.com" 27 | }, 28 | { 29 | "name": "Bryan Donovan", 30 | "email": "bdondo@gmail.com" 31 | }, 32 | { 33 | "name": "C-h-e-r-r-y", 34 | "email": "C-h-e-r-r-y@users.noreply.github.com" 35 | }, 36 | { 37 | "name": "rebareba", 38 | "email": "forcdc1990@gmail.com" 39 | }, 40 | { 41 | "name": "t3hmrman", 42 | "email": "t3hmrman@gmail.com" 43 | }, 44 | { 45 | "name": "Thomas Dimson", 46 | "email": "tdimson@gmail.com" 47 | }, 48 | { 49 | "name": "Anup Baldawa", 50 | "email": "anup@joinhoney.com" 51 | }, 52 | { 53 | "name": "Kevin Burke", 54 | "email": "burke@shyp.com" 55 | }, 56 | { 57 | "name": "Teow Hua Jun", 58 | "email": "huajun@Teows-MacBook-Pro.local" 59 | }, 60 | { 61 | "name": "Joe Z", 62 | "email": "jzarate@gmail.com" 63 | }, 64 | { 65 | "name": "Peter Galiba", 66 | "email": "poetro@poetro.hu" 67 | }, 68 | { 69 | "name": "Asbjørn Sannes", 70 | "email": "asbjorn.sannes@interhost.no" 71 | }, 72 | { 73 | "name": "san00", 74 | "email": "c5d59d07@opayq.com" 75 | }, 76 | { 77 | "name": "Christian d'Heureuse", 78 | "email": "chdh@inventec.ch" 79 | }, 80 | { 81 | "name": "Ryan Dao", 82 | "email": "ddao@paypal.com" 83 | }, 84 | { 85 | "name": "Diego Rodríguez Baquero", 86 | "email": "diegorbaquero@gmail.com" 87 | }, 88 | { 89 | "name": "Felix Becker", 90 | "email": "felix.b@outlook.com" 91 | }, 92 | { 93 | "name": "Geovani de Souza", 94 | "email": "geovanisouza92@gmail.com" 95 | }, 96 | { 97 | "name": "Jemila", 98 | "email": "jemila.abulhawa@gmail.com" 99 | }, 100 | { 101 | "name": "Justin Robinson", 102 | "email": "jrobinson@redventures.com" 103 | }, 104 | { 105 | "name": "linchuang", 106 | "email": "linchuang@tencent.com" 107 | }, 108 | { 109 | "name": "Nayana Hettiarachchi", 110 | "email": "nayana@corp-gems.com" 111 | }, 112 | { 113 | "name": "restjohn", 114 | "email": "restjohn@users.noreply.github.com" 115 | }, 116 | { 117 | "name": "Sushant", 118 | "email": "sushantdhiman@outlook.com" 119 | }, 120 | { 121 | "name": "travis4all", 122 | "email": "travis4all@diamon.dz" 123 | }, 124 | { 125 | "name": "Will Shaver", 126 | "email": "will.shaver@emberex.com" 127 | }, 128 | { 129 | "name": "windyrobin", 130 | "email": "windyrobin@Gmail.com" 131 | }, 132 | { 133 | "name": "王秋石", 134 | "email": "12qiushi@163.com" 135 | }, 136 | { 137 | "name": "Stephen Cresswell", 138 | "email": "229672+cressie176@users.noreply.github.com" 139 | }, 140 | { 141 | "name": "Arek Flinik", 142 | "email": "aflinik@gmail.com" 143 | }, 144 | { 145 | "name": "Alexander Tesfamichael", 146 | "email": "Alex.Tesfamichael@gmail.com" 147 | }, 148 | { 149 | "name": "calibr", 150 | "email": "awcalibr@gmail.com" 151 | }, 152 | { 153 | "name": "benny-medflyt", 154 | "email": "benny@medflyt.com" 155 | }, 156 | { 157 | "name": "Bryan Kaplan", 158 | "email": "bryan@pinchit.com" 159 | }, 160 | { 161 | "name": "Dumitru Uzun", 162 | "email": "contact@duzun.me" 163 | }, 164 | { 165 | "name": "Douglas Christopher Wilson", 166 | "email": "doug@somethingdoug.com" 167 | }, 168 | { 169 | "name": "Drew R", 170 | "email": "drewrathbone@gmail.com" 171 | }, 172 | { 173 | "name": "Magnus Eide", 174 | "email": "eide@iterate.no" 175 | }, 176 | { 177 | "name": "gdusbabek", 178 | "email": "gdusbabek@gmail.com" 179 | }, 180 | { 181 | "name": "Jason Rhodes", 182 | "email": "jason.matthew.rhodes@gmail.com" 183 | }, 184 | { 185 | "name": "John Dooley", 186 | "email": "john.j.dooley@gmail.com" 187 | }, 188 | { 189 | "name": "Lewis Ellis", 190 | "email": "lewis@getsentry.com" 191 | }, 192 | { 193 | "name": "Tom MacWright", 194 | "email": "macwright@gmail.com" 195 | }, 196 | { 197 | "name": "Louis Roché", 198 | "email": "mail+github@louisroche.net" 199 | }, 200 | { 201 | "name": "Mike Morris", 202 | "email": "mikemorris@users.noreply.github.com" 203 | }, 204 | { 205 | "name": "molipet", 206 | "email": "molipet@gmail.com" 207 | }, 208 | { 209 | "name": "An Nguyen Le", 210 | "email": "nguyenan169@gmail.com" 211 | }, 212 | { 213 | "name": "Piotr", 214 | "email": "pwalc@agora.pl" 215 | }, 216 | { 217 | "name": "Randall Leeds", 218 | "email": "randall.leeds@gmail.com" 219 | }, 220 | { 221 | "name": "Roy Binux", 222 | "email": "root@binux.me" 223 | }, 224 | { 225 | "name": "Sandro Santilli", 226 | "email": "strk@keybit.net" 227 | }, 228 | { 229 | "name": "Teemu Ikonen", 230 | "email": "teemu.ikonen@iki.fi" 231 | }, 232 | { 233 | "name": "Tevye Krynski", 234 | "email": "tevye@mog.com" 235 | }, 236 | { 237 | "name": "Thom Seddon", 238 | "email": "thom@nightworld.com" 239 | }, 240 | { 241 | "name": "Thomas Watson Steen", 242 | "email": "w@tson.dk" 243 | }, 244 | { 245 | "name": "Wilfred van der Deijl", 246 | "email": "wilfred@vanderdeijl.com" 247 | }, 248 | { 249 | "name": "Yanlong Wang", 250 | "email": "yanlong.wang@naiver.org" 251 | }, 252 | { 253 | "name": "Young Hahn", 254 | "email": "young@developmentseed.org" 255 | }, 256 | { 257 | "name": "Rajesh kumar", 258 | "email": "zazzel.cvs@gmail.com" 259 | } 260 | ], 261 | "repository": { 262 | "type": "git", 263 | "url": "git+ssh://git@github.com/coopernurse/node-pool.git" 264 | }, 265 | "bugs": { 266 | "url": "https://github.com/coopernurse/node-pool/issues" 267 | }, 268 | "keywords": [ 269 | "pool", 270 | "pooling", 271 | "throttle" 272 | ], 273 | "devDependencies": { 274 | "@types/node": "^8.5.1", 275 | "eslint": "^4.9.0", 276 | "eslint-config-prettier": "^2.6.0", 277 | "eslint-plugin-prettier": "^2.3.1", 278 | "eslint-plugin-promise": "^3.3.0", 279 | "prettier": "^1.7.4", 280 | "tap": "^8.0.0", 281 | "typescript": "^2.6.2" 282 | }, 283 | "engines": { 284 | "node": ">= 4" 285 | }, 286 | "files": [ 287 | "index.d.ts", 288 | "index.js", 289 | "lib" 290 | ], 291 | "scripts": { 292 | "lint": "eslint lib test index.js .eslintrc.js", 293 | "lint-fix": "eslint --fix lib test index.js .eslintrc.js", 294 | "test": "tap test/*-test.js " 295 | }, 296 | "license": "MIT" 297 | } 298 | -------------------------------------------------------------------------------- /test/GH-159-test.js: -------------------------------------------------------------------------------- 1 | const tap = require("tap"); 2 | const createPool = require("../").createPool; 3 | const utils = require("./utils"); 4 | const ResourceFactory = utils.ResourceFactory; 5 | 6 | class ResourceFactoryDelayCreateEachSecond { 7 | constructor() { 8 | this.callCreate = 0; 9 | this.created = 0; 10 | this.destroyed = 0; 11 | this.bin = []; 12 | } 13 | 14 | create() { 15 | const that = this; 16 | console.log(`** create call ${that.callCreate}`); 17 | return new Promise(resolve => { 18 | if (that.callCreate % 2 === 0) { 19 | setTimeout(function() { 20 | console.log(`** created ${that.created}`); 21 | resolve({ id: that.created++ }); 22 | }, 10); 23 | } else { 24 | console.log(`** created ${that.created}`); 25 | resolve({ id: that.created++ }); 26 | } 27 | that.callCreate++; 28 | }); 29 | } 30 | 31 | validate() { 32 | return Promise.resolve(true); 33 | } 34 | 35 | destroy(resource) { 36 | console.log(`** destroying ${resource.id}`); 37 | this.destroyed++; 38 | this.bin.push(resource); 39 | return Promise.resolve(); 40 | } 41 | } 42 | 43 | tap.test("tests drain clear with autostart and min > 0", function(t) { 44 | const count = 5; 45 | let acquired = 0; 46 | 47 | const resourceFactory = new ResourceFactoryDelayCreateEachSecond(); 48 | const config = { 49 | max: 10, 50 | min: 1, 51 | evictionRunIntervalMillis: 500, 52 | idleTimeoutMillis: 30000, 53 | testOnBorrow: true, 54 | autostart: true 55 | }; 56 | const pool = createPool(resourceFactory, config); 57 | 58 | return pool 59 | .drain() 60 | .then(function() { 61 | console.log("** pool drained"); 62 | return pool.clear(); 63 | }) 64 | .then(function() { 65 | console.log("** pool cleared"); 66 | t.equal(resourceFactory.created, resourceFactory.destroyed); 67 | }) 68 | .then(function() { 69 | t.end(); 70 | }); 71 | }); 72 | -------------------------------------------------------------------------------- /test/doubly-linked-list-iterator-test.js: -------------------------------------------------------------------------------- 1 | const tap = require("tap"); 2 | const DLL = require("../lib/DoublyLinkedList"); 3 | const Iterator = require("../lib/DoublyLinkedListIterator"); 4 | 5 | tap.test("iterates forward", function(t) { 6 | const dll = new DLL(); 7 | 8 | const node1 = DLL.createNode({ id: 1 }); 9 | const node2 = DLL.createNode({ id: 2 }); 10 | const node3 = DLL.createNode({ id: 3 }); 11 | const node4 = DLL.createNode({ id: 4 }); 12 | 13 | dll.insertBeginning(node1); 14 | dll.insertBeginning(node2); 15 | dll.insertBeginning(node3); 16 | dll.insertBeginning(node4); 17 | 18 | const iterator = new Iterator(dll); 19 | 20 | const iterationResult1 = iterator.next(); 21 | t.notOk(iterationResult1.done); 22 | t.same(iterationResult1.value, node4); 23 | 24 | iterator.next(); 25 | iterator.next(); 26 | 27 | const iterationResult4 = iterator.next(); 28 | t.notOk(iterationResult4.done); 29 | t.same(iterationResult4.value, node1); 30 | 31 | const iterationResult5 = iterator.next(); 32 | t.ok(iterationResult5.done); 33 | 34 | t.end(); 35 | }); 36 | 37 | tap.test("iterates backwards", function(t) { 38 | const dll = new DLL(); 39 | 40 | const node1 = DLL.createNode({ id: 1 }); 41 | const node2 = DLL.createNode({ id: 2 }); 42 | const node3 = DLL.createNode({ id: 3 }); 43 | const node4 = DLL.createNode({ id: 4 }); 44 | 45 | dll.insertBeginning(node1); 46 | dll.insertBeginning(node2); 47 | dll.insertBeginning(node3); 48 | dll.insertBeginning(node4); 49 | 50 | const iterator = new Iterator(dll, true); 51 | 52 | const iterationResult1 = iterator.next(); 53 | t.notOk(iterationResult1.done); 54 | t.same(iterationResult1.value, node1); 55 | 56 | iterator.next(); 57 | iterator.next(); 58 | 59 | const iterationResult4 = iterator.next(); 60 | t.notOk(iterationResult4.done); 61 | t.same(iterationResult4.value, node4); 62 | 63 | const iterationResult5 = iterator.next(); 64 | t.ok(iterationResult5.done); 65 | 66 | t.end(); 67 | }); 68 | 69 | tap.test("iterates forward when adding nodes after creating iterator", function( 70 | t 71 | ) { 72 | const dll = new DLL(); 73 | 74 | const node1 = DLL.createNode({ id: 1 }); 75 | const node2 = DLL.createNode({ id: 2 }); 76 | 77 | const iterator = new Iterator(dll); 78 | 79 | dll.insertBeginning(node1); 80 | dll.insertBeginning(node2); 81 | 82 | const iterationResult1 = iterator.next(); 83 | t.notOk(iterationResult1.done); 84 | t.same(iterationResult1.value, node2); 85 | 86 | const iterationResult2 = iterator.next(); 87 | t.notOk(iterationResult2.done); 88 | t.same(iterationResult2.value, node1); 89 | 90 | const iterationResult3 = iterator.next(); 91 | t.ok(iterationResult3.done); 92 | 93 | t.end(); 94 | }); 95 | 96 | tap.test( 97 | "iterates backwards when adding nodes after creating iterator", 98 | function(t) { 99 | const dll = new DLL(); 100 | 101 | const node1 = DLL.createNode({ id: 1 }); 102 | const node2 = DLL.createNode({ id: 2 }); 103 | 104 | const iterator = new Iterator(dll, true); 105 | 106 | dll.insertBeginning(node1); 107 | dll.insertBeginning(node2); 108 | 109 | const iterationResult1 = iterator.next(); 110 | t.notOk(iterationResult1.done); 111 | t.same(iterationResult1.value, node1); 112 | 113 | const iterationResult2 = iterator.next(); 114 | t.notOk(iterationResult2.done); 115 | t.same(iterationResult2.value, node2); 116 | 117 | const iterationResult3 = iterator.next(); 118 | t.ok(iterationResult3.done); 119 | 120 | t.end(); 121 | } 122 | ); 123 | 124 | tap.test("stops iterating when node is detached", function(t) { 125 | const dll = new DLL(); 126 | const iterator = new Iterator(dll); 127 | 128 | const node1 = DLL.createNode({ id: 1 }); 129 | const node2 = DLL.createNode({ id: 2 }); 130 | 131 | dll.insertBeginning(node1); 132 | dll.insertBeginning(node2); 133 | 134 | const iterationResult1 = iterator.next(); 135 | t.notOk(iterationResult1.done); 136 | t.same(iterationResult1.value, node2); 137 | 138 | dll.remove(node1); 139 | 140 | const iterationResult3 = iterator.next(); 141 | t.ok(iterationResult3.done); 142 | 143 | t.end(); 144 | }); 145 | -------------------------------------------------------------------------------- /test/doubly-linked-list-test.js: -------------------------------------------------------------------------------- 1 | var tap = require("tap"); 2 | var DLL = require("../lib/DoublyLinkedList"); 3 | 4 | tap.test("operations", function(t) { 5 | var dll = new DLL(); 6 | 7 | var item1 = { id: 1 }; 8 | var item2 = { id: 2 }; 9 | var item3 = { id: 3 }; 10 | var item4 = { id: 4 }; 11 | 12 | dll.insertBeginning(DLL.createNode(item1)); 13 | t.equal(dll.head.data, item1); 14 | 15 | dll.insertEnd(DLL.createNode(item2)); 16 | t.equal(dll.tail.data, item2); 17 | 18 | dll.insertAfter(dll.tail, DLL.createNode(item3)); 19 | t.equal(dll.tail.data, item3); 20 | 21 | dll.insertBefore(dll.tail, DLL.createNode(item4)); 22 | t.equal(dll.tail.data, item3); 23 | 24 | dll.remove(dll.tail); 25 | t.equal(dll.tail.data, item4); 26 | 27 | t.end(); 28 | }); 29 | -------------------------------------------------------------------------------- /test/generic-pool-acquiretimeout-test.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const tap = require("tap"); 4 | const createPool = require("../").createPool; 5 | 6 | tap.test("acquireTimeout handles timed out acquire calls", function(t) { 7 | const factory = { 8 | create: function() { 9 | return new Promise(function(resolve) { 10 | setTimeout(function() { 11 | resolve({}); 12 | }, 100); 13 | }); 14 | }, 15 | destroy: function() { 16 | return Promise.resolve(); 17 | } 18 | }; 19 | const config = { 20 | acquireTimeoutMillis: 20, 21 | idleTimeoutMillis: 150, 22 | log: false 23 | }; 24 | 25 | const pool = createPool(factory, config); 26 | 27 | pool 28 | .acquire() 29 | .then(function(resource) { 30 | t.fail("wooops"); 31 | }) 32 | .catch(function(err) { 33 | t.match(err, /ResourceRequest timed out/); 34 | return pool.drain(); 35 | }) 36 | .then(function() { 37 | return pool.clear(); 38 | }) 39 | .then(function() {}) 40 | .then(t.end) 41 | .catch(t.error); 42 | }); 43 | 44 | tap.test("acquireTimeout handles non timed out acquire calls", function(t) { 45 | const myResource = {}; 46 | const factory = { 47 | create: function() { 48 | return new Promise(function(resolve) { 49 | setTimeout(function() { 50 | resolve(myResource); 51 | }, 10); 52 | }); 53 | }, 54 | destroy: function() { 55 | return Promise.resolve(); 56 | } 57 | }; 58 | 59 | const config = { 60 | acquireTimeoutMillis: 400 61 | }; 62 | 63 | const pool = createPool(factory, config); 64 | 65 | pool 66 | .acquire() 67 | .then(function(resource) { 68 | t.equal(resource, myResource); 69 | pool.release(resource); 70 | return pool.drain(); 71 | }) 72 | .then(function() { 73 | return pool.clear(); 74 | }) 75 | .then(t.end) 76 | .catch(t.error); 77 | }); 78 | -------------------------------------------------------------------------------- /test/generic-pool-destroytimeout-test.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const tap = require("tap"); 4 | const createPool = require("../").createPool; 5 | 6 | tap.test("destroyTimeout handles timed out destroy calls", function(t) { 7 | const factory = { 8 | create: function() { 9 | return Promise.resolve({}); 10 | }, 11 | destroy: function() { 12 | return new Promise(function(resolve) { 13 | setTimeout(function() { 14 | resolve(); 15 | }, 100); 16 | }); 17 | } 18 | }; 19 | const config = { 20 | destroyTimeoutMillis: 20 21 | }; 22 | 23 | const pool = createPool(factory, config); 24 | 25 | pool 26 | .acquire() 27 | .then(function(resource) { 28 | pool.destroy(resource); 29 | return new Promise(function(resolve, reject) { 30 | pool.on("factoryDestroyError", function(err) { 31 | t.match(err, /destroy timed out/); 32 | resolve(); 33 | }); 34 | }); 35 | }) 36 | .then(t.end) 37 | .catch(t.error); 38 | }); 39 | 40 | tap.test("destroyTimeout handles non timed out destroy calls", function(t) { 41 | const myResource = {}; 42 | const factory = { 43 | create: function() { 44 | return Promise.resolve({}); 45 | }, 46 | destroy: function() { 47 | return new Promise(function(resolve) { 48 | setTimeout(function() { 49 | resolve(); 50 | }, 10); 51 | }); 52 | } 53 | }; 54 | 55 | const config = { 56 | destroyTimeoutMillis: 400 57 | }; 58 | 59 | const pool = createPool(factory, config); 60 | 61 | pool 62 | .acquire() 63 | .then(function(resource) { 64 | pool.destroy(resource); 65 | return new Promise(function(resolve) { 66 | pool.on("factoryDestroyError", function(err) { 67 | t.fail("wooops"); 68 | }); 69 | setTimeout(resolve, 20); 70 | }); 71 | }) 72 | .then(t.end) 73 | .catch(t.error); 74 | }); 75 | -------------------------------------------------------------------------------- /test/generic-pool-test.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const tap = require("tap"); 4 | const createPool = require("../").createPool; 5 | const utils = require("./utils"); 6 | const ResourceFactory = utils.ResourceFactory; 7 | 8 | // tap.test('Pool expands only to max limit', function (t) { 9 | // const resourceFactory = new ResourceFactory() 10 | 11 | // const config = { 12 | // max: 1 13 | // } 14 | 15 | // const pool = createPool(resourceFactory, config) 16 | 17 | // // NOTES: 18 | // // - request a resource 19 | // // - once we have it, request another and check the pool is fool 20 | // pool.acquire(function (err, obj) { 21 | // t.error(err) 22 | // const poolIsFull = !pool.acquire(function (err, obj) { 23 | // t.error(err) 24 | // t.equal(1, resourceFactory.created) 25 | // pool.release(obj) 26 | // utils.stopPool(pool) 27 | // t.end() 28 | // }) 29 | // t.ok(poolIsFull) 30 | // t.equal(1, resourceFactory.created) 31 | // pool.release(obj) 32 | // }) 33 | // }) 34 | 35 | // tap.test('Pool respects min limit', function (t) { 36 | // const resourceFactory = new ResourceFactory() 37 | 38 | // const config 39 | // min: 1, 40 | // max: 2 41 | // } 42 | 43 | // const pool = createPool(resourceFactory, config) 44 | 45 | // // FIXME: this logic only works because we know it takes ~1ms to create a resource 46 | // // we need better hooks into the pool probably to observe this... 47 | // setTimeout(function () { 48 | // t.equal(resourceFactory.created, 1) 49 | // utils.stopPool(pool) 50 | // t.end() 51 | // }, 10) 52 | // }) 53 | 54 | tap.test("min and max limit defaults", function(t) { 55 | const resourceFactory = new ResourceFactory(); 56 | 57 | const pool = createPool(resourceFactory); 58 | 59 | t.equal(1, pool.max); 60 | t.equal(0, pool.min); 61 | utils.stopPool(pool); 62 | t.end(); 63 | }); 64 | 65 | tap.test("malformed min and max limits are ignored", function(t) { 66 | const resourceFactory = new ResourceFactory(); 67 | 68 | const config = { 69 | min: "asf", 70 | max: [] 71 | }; 72 | const pool = createPool(resourceFactory, config); 73 | 74 | t.equal(1, pool.max); 75 | t.equal(0, pool.min); 76 | utils.stopPool(pool); 77 | t.end(); 78 | }); 79 | 80 | tap.test("min greater than max sets to max", function(t) { 81 | const resourceFactory = new ResourceFactory(); 82 | 83 | const config = { 84 | min: 5, 85 | max: 3 86 | }; 87 | const pool = createPool(resourceFactory, config); 88 | 89 | t.equal(3, pool.max); 90 | t.equal(3, pool.min); 91 | utils.stopPool(pool); 92 | t.end(); 93 | }); 94 | 95 | tap.test("supports priority on borrow", function(t) { 96 | // NOTE: this test is pretty opaque about what it's really testing/expecting... 97 | let borrowTimeLow = 0; 98 | let borrowTimeHigh = 0; 99 | let borrowCount = 0; 100 | 101 | const resourceFactory = new ResourceFactory(); 102 | 103 | const config = { 104 | max: 1, 105 | priorityRange: 2 106 | }; 107 | 108 | const pool = createPool(resourceFactory, config); 109 | 110 | function lowPriorityOnFulfilled(obj) { 111 | const time = Date.now(); 112 | if (time > borrowTimeLow) { 113 | borrowTimeLow = time; 114 | } 115 | borrowCount++; 116 | pool.release(obj); 117 | } 118 | 119 | function highPriorityOnFulfilled(obj) { 120 | const time = Date.now(); 121 | if (time > borrowTimeHigh) { 122 | borrowTimeHigh = time; 123 | } 124 | borrowCount++; 125 | pool.release(obj); 126 | } 127 | 128 | const operations = []; 129 | 130 | for (let i = 0; i < 10; i++) { 131 | const op = pool.acquire(1).then(lowPriorityOnFulfilled); 132 | operations.push(op); 133 | } 134 | 135 | for (let i = 0; i < 10; i++) { 136 | const op = pool.acquire(0).then(highPriorityOnFulfilled); 137 | operations.push(op); 138 | } 139 | 140 | Promise.all(operations) 141 | .then(function() { 142 | t.equal(20, borrowCount); 143 | t.equal(true, borrowTimeLow >= borrowTimeHigh); 144 | utils.stopPool(pool); 145 | t.end(); 146 | }) 147 | .catch(t.threw); 148 | }); 149 | 150 | // FIXME: bad test! 151 | // pool.destroy makes no obligations to user about when it will destroy the resource 152 | // we should test that "destroyed" objects are not acquired again instead 153 | // tap.test('removes correct object on reap', function (t) { 154 | // const resourceFactory = new ResourceFactory() 155 | 156 | // const config 157 | // max: 2 158 | // } 159 | 160 | // const pool = createPool(resourceFactory, config) 161 | 162 | // const op1 = pool.acquire() 163 | // .then(function (client) { 164 | // return new Promise(function (resolve, reject) { 165 | // // should be removed second 166 | // setTimeout(function () { 167 | // pool.destroy(client) 168 | // resolve() 169 | // }, 5) 170 | // }) 171 | // }) 172 | 173 | // const op2 = pool.acquire() 174 | // .then(function (client) { 175 | // pool.destroy(client) 176 | // }) 177 | 178 | // Promise.all([op1, op2]).then(function () { 179 | // t.equal(1, resourceFactory.bin[0].id) 180 | // t.equal(0, resourceFactory.bin[1].id) 181 | // utils.stopPool(pool) 182 | // t.end() 183 | // }) 184 | // .catch(t.threw) 185 | // }) 186 | 187 | tap.test("evictor removes instances on idletimeout", function(t) { 188 | const resourceFactory = new ResourceFactory(); 189 | const config = { 190 | min: 2, 191 | max: 2, 192 | idleTimeoutMillis: 50, 193 | evictionRunIntervalMillis: 10 194 | }; 195 | const pool = createPool(resourceFactory, config); 196 | 197 | setTimeout(function() { 198 | pool 199 | .acquire() 200 | .then(res => { 201 | t.ok(res.id > 1); 202 | return pool.release(res); 203 | }) 204 | .then(() => { 205 | utils.stopPool(pool); 206 | t.end(); 207 | }); 208 | }, 120); 209 | }); 210 | 211 | tap.test("tests drain", function(t) { 212 | const count = 5; 213 | let acquired = 0; 214 | 215 | const resourceFactory = new ResourceFactory(); 216 | const config = { 217 | max: 2, 218 | idletimeoutMillis: 300000 219 | }; 220 | const pool = createPool(resourceFactory, config); 221 | 222 | const operations = []; 223 | 224 | function onAcquire(client) { 225 | acquired += 1; 226 | t.equal(typeof client.id, "number"); 227 | setTimeout(function() { 228 | pool.release(client); 229 | }, 250); 230 | } 231 | 232 | // request 5 resources that release after 250ms 233 | for (let i = 0; i < count; i++) { 234 | const op = pool.acquire().then(onAcquire); 235 | operations.push(op); 236 | } 237 | // FIXME: what does this assertion prove? 238 | t.notEqual(count, acquired); 239 | 240 | Promise.all(operations) 241 | .then(function() { 242 | return pool.drain(); 243 | }) 244 | .then(function() { 245 | t.equal(count, acquired); 246 | // short circuit the absurdly long timeouts above. 247 | pool.clear(); 248 | }) 249 | .then(function() { 250 | // subsequent calls to acquire should resolve an error. 251 | return pool.acquire().then(t.fail, function(e) { 252 | t.type(e, Error); 253 | }); 254 | }) 255 | .then(function() { 256 | t.end(); 257 | }); 258 | }); 259 | 260 | tap.test("clear promise resolves with no value", function(t) { 261 | let resources = []; 262 | const factory = { 263 | create: function create() { 264 | return new Promise(function tryCreate(resolve, reject) { 265 | let resource = resources.shift(); 266 | if (resource) { 267 | resolve(resource); 268 | } else { 269 | process.nextTick(tryCreate.bind(this, resolve, reject)); 270 | } 271 | }); 272 | }, 273 | destroy: function() { 274 | return Promise.resolve(); 275 | } 276 | }; 277 | const pool = createPool(factory, { max: 3, min: 3 }); 278 | Promise.all([pool.acquire(), pool.acquire(), pool.acquire()]).then(all => { 279 | all.forEach(resource => { 280 | process.nextTick(pool.release.bind(pool), resource); 281 | }); 282 | }); 283 | 284 | t.equal(pool.pending, 3, "all acquisitions pending"); 285 | 286 | pool 287 | .drain() 288 | .then(() => pool.clear()) 289 | .then(resolved => { 290 | t.equal(resolved, undefined, "clear promise resolves with no value"); 291 | t.end(); 292 | }); 293 | 294 | process.nextTick(() => { 295 | resources.push("a"); 296 | resources.push("b"); 297 | resources.push("c"); 298 | }); 299 | }); 300 | 301 | tap.test("handle creation errors", function(t) { 302 | let created = 0; 303 | const resourceFactory = { 304 | create: function() { 305 | created++; 306 | if (created < 5) { 307 | return Promise.reject(new Error("Error occurred.")); 308 | } else { 309 | return Promise.resolve({ id: created }); 310 | } 311 | }, 312 | destroy: function(client) {} 313 | }; 314 | const config = { 315 | max: 1 316 | }; 317 | 318 | const pool = createPool(resourceFactory, config); 319 | 320 | // FIXME: this section no longer proves anything as factory 321 | // errors no longer bubble up through the acquire call 322 | // we need to make the Pool an Emitter 323 | 324 | // ensure that creation errors do not populate the pool. 325 | // for (const i = 0; i < 5; i++) { 326 | // pool.acquire(function (err, client) { 327 | // t.ok(err instanceof Error) 328 | // t.ok(client === null) 329 | // }) 330 | // } 331 | 332 | let called = false; 333 | pool 334 | .acquire() 335 | .then(function(client) { 336 | t.equal(typeof client.id, "number"); 337 | called = true; 338 | pool.release(client); 339 | }) 340 | .then(function() { 341 | t.ok(called); 342 | t.equal(pool.pending, 0); 343 | utils.stopPool(pool); 344 | t.end(); 345 | }) 346 | .catch(t.threw); 347 | }); 348 | 349 | tap.test("handle creation errors for delayed creates", function(t) { 350 | let attempts = 0; 351 | 352 | const resourceFactory = { 353 | create: function() { 354 | attempts++; 355 | if (attempts <= 5) { 356 | return Promise.reject(new Error("Error occurred.")); 357 | } else { 358 | return Promise.resolve({ id: attempts }); 359 | } 360 | }, 361 | destroy: function(client) { 362 | return Promise.resolve(); 363 | } 364 | }; 365 | 366 | const config = { 367 | max: 1 368 | }; 369 | 370 | const pool = createPool(resourceFactory, config); 371 | 372 | let errorCount = 0; 373 | pool.on("factoryCreateError", function(err) { 374 | t.ok(err instanceof Error); 375 | errorCount++; 376 | }); 377 | 378 | let called = false; 379 | pool 380 | .acquire() 381 | .then(function(client) { 382 | t.equal(typeof client.id, "number"); 383 | called = true; 384 | pool.release(client); 385 | }) 386 | .then(function() { 387 | t.ok(called); 388 | t.equal(errorCount, 5); 389 | t.equal(pool.pending, 0); 390 | utils.stopPool(pool); 391 | t.end(); 392 | }) 393 | .catch(t.threw); 394 | }); 395 | 396 | tap.test("getPoolSize", function(t) { 397 | let assertionCount = 0; 398 | const resourceFactory = new ResourceFactory(); 399 | const config = { 400 | max: 2 401 | }; 402 | 403 | const pool = createPool(resourceFactory, config); 404 | 405 | const borrowedResources = []; 406 | 407 | t.equal(pool.size, 0); 408 | assertionCount += 1; 409 | 410 | pool 411 | .acquire() 412 | .then(function(obj) { 413 | borrowedResources.push(obj); 414 | t.equal(pool.size, 1); 415 | assertionCount += 1; 416 | }) 417 | .then(function() { 418 | return pool.acquire(); 419 | }) 420 | .then(function(obj) { 421 | borrowedResources.push(obj); 422 | t.equal(pool.size, 2); 423 | assertionCount += 1; 424 | }) 425 | .then(function() { 426 | pool.release(borrowedResources.shift()); 427 | pool.release(borrowedResources.shift()); 428 | }) 429 | .then(function() { 430 | return pool.acquire(); 431 | }) 432 | .then(function(obj) { 433 | // should still be 2 434 | t.equal(pool.size, 2); 435 | assertionCount += 1; 436 | pool.release(obj); 437 | }) 438 | .then(function() { 439 | t.equal(assertionCount, 4); 440 | utils.stopPool(pool); 441 | t.end(); 442 | }) 443 | .catch(t.threw); 444 | }); 445 | 446 | tap.test("availableObjectsCount", function(t) { 447 | let assertionCount = 0; 448 | const resourceFactory = new ResourceFactory(); 449 | const config = { 450 | max: 2 451 | }; 452 | 453 | const pool = createPool(resourceFactory, config); 454 | 455 | const borrowedResources = []; 456 | 457 | t.equal(pool.available, 0); 458 | assertionCount += 1; 459 | 460 | pool 461 | .acquire() 462 | .then(function(obj) { 463 | borrowedResources.push(obj); 464 | t.equal(pool.available, 0); 465 | assertionCount += 1; 466 | }) 467 | .then(function() { 468 | return pool.acquire(); 469 | }) 470 | .then(function(obj) { 471 | borrowedResources.push(obj); 472 | t.equal(pool.available, 0); 473 | assertionCount += 1; 474 | }) 475 | .then(function() { 476 | pool.release(borrowedResources.shift()); 477 | t.equal(pool.available, 1); 478 | assertionCount += 1; 479 | 480 | pool.release(borrowedResources.shift()); 481 | t.equal(pool.available, 2); 482 | assertionCount += 1; 483 | }) 484 | .then(function() { 485 | return pool.acquire(); 486 | }) 487 | .then(function(obj) { 488 | t.equal(pool.available, 1); 489 | assertionCount += 1; 490 | pool.release(obj); 491 | 492 | t.equal(pool.available, 2); 493 | assertionCount += 1; 494 | }) 495 | .then(function() { 496 | t.equal(assertionCount, 7); 497 | utils.stopPool(pool); 498 | t.end(); 499 | }) 500 | .catch(t.threw); 501 | }); 502 | 503 | // FIXME: bad test! 504 | // pool.destroy makes no obligations to user about when it will destroy the resource 505 | // we should test that "destroyed" objects are not acquired again instead 506 | // tap.test('removes from available objects on destroy', function (t) { 507 | // let destroyCalled = false 508 | // const factory = { 509 | // create: function () { return Promise.resolve({}) }, 510 | // destroy: function (client) { destroyCalled = true; return Promise.resolve() } 511 | // } 512 | 513 | // const config 514 | // max: 2 515 | // } 516 | 517 | // const pool = createPool(factory, config) 518 | 519 | // pool.acquire().then(function (obj) { 520 | // pool.destroy(obj) 521 | // }) 522 | // .then(function () { 523 | // t.equal(destroyCalled, true) 524 | // t.equal(pool.available, 0) 525 | // utils.stopPool(pool) 526 | // t.end() 527 | // }) 528 | // .catch(t.threw) 529 | // }) 530 | 531 | // FIXME: bad test! 532 | // pool.destroy makes no obligations to user about when it will destroy the resource 533 | // we should test that "destroyed" objects are not acquired again instead 534 | // tap.test('removes from available objects on validation failure', function (t) { 535 | // const destroyCalled = false 536 | // const validateCalled = false 537 | // const count = 0 538 | // const factory = { 539 | // create: function () { return Promise.resolve({count: count++}) }, 540 | // destroy: function (client) { destroyCalled = client.count }, 541 | // validate: function (client) { 542 | // validateCalled = true 543 | // return Promise.resolve(client.count > 0) 544 | // } 545 | // } 546 | 547 | // const config 548 | // max: 2, 549 | // testOnBorrow: true 550 | // } 551 | 552 | // const pool = createPool(factory, config) 553 | 554 | // pool.acquire() 555 | // .then(function (obj) { 556 | // pool.release(obj) 557 | // t.equal(obj.count, 0) 558 | // }) 559 | // .then(function () { 560 | // return pool.acquire() 561 | // }) 562 | // .then(function (obj2) { 563 | // pool.release(obj2) 564 | // t.equal(obj2.count, 1) 565 | // }) 566 | // .then(function () { 567 | // t.equal(validateCalled, true) 568 | // t.equal(destroyCalled, 0) 569 | // t.equal(pool.available, 1) 570 | // utils.stopPool(pool) 571 | // t.end() 572 | // }) 573 | // .catch(t.threw) 574 | // }) 575 | 576 | tap.test( 577 | "do schedule again if error occured when creating new Objects async", 578 | function(t) { 579 | // NOTE: we're simulating the first few resource attempts failing 580 | let resourceCreationAttempts = 0; 581 | 582 | const factory = { 583 | create: function() { 584 | resourceCreationAttempts++; 585 | if (resourceCreationAttempts < 2) { 586 | return Promise.reject(new Error("Create Error")); 587 | } 588 | return Promise.resolve({}); 589 | }, 590 | destroy: function(client) {} 591 | }; 592 | 593 | const config = { 594 | max: 1 595 | }; 596 | 597 | const pool = createPool(factory, config); 598 | // pool.acquire(function () {}) 599 | pool 600 | .acquire() 601 | .then(function(obj) { 602 | t.equal(pool.available, 0); 603 | pool.release(obj); 604 | utils.stopPool(pool); 605 | t.end(); 606 | }) 607 | .catch(t.threw); 608 | } 609 | ); 610 | 611 | tap.test("returns only valid object to the pool", function(t) { 612 | const pool = createPool(new ResourceFactory(), { max: 1 }); 613 | 614 | pool 615 | .acquire() 616 | .then(function(obj) { 617 | t.equal(pool.available, 0); 618 | t.equal(pool.borrowed, 1); 619 | 620 | // Invalid release 621 | pool 622 | .release({}) 623 | .catch(function(err) { 624 | t.match(err.message, /Resource not currently part of this pool/); 625 | }) 626 | .then(function() { 627 | t.equal(pool.available, 0); 628 | t.equal(pool.borrowed, 1); 629 | 630 | // Valid release 631 | pool.release(obj).catch(t.error); 632 | t.equal(pool.available, 1); 633 | t.equal(pool.borrowed, 0); 634 | utils.stopPool(pool); 635 | t.end(); 636 | }); 637 | }) 638 | .catch(t.threw); 639 | }); 640 | 641 | tap.test("validate acquires object from the pool", function(t) { 642 | const pool = createPool(new ResourceFactory(), { max: 1 }); 643 | 644 | pool 645 | .acquire() 646 | .then(function(obj) { 647 | t.equal(pool.available, 0); 648 | t.equal(pool.borrowed, 1); 649 | pool.release(obj); 650 | utils.stopPool(pool); 651 | t.end(); 652 | }) 653 | .catch(t.threw); 654 | }); 655 | 656 | tap.test("release to pool should work", function(t) { 657 | const pool = createPool(new ResourceFactory(), { max: 1 }); 658 | 659 | pool 660 | .acquire() 661 | .then(function(obj) { 662 | t.equal(pool.available, 0); 663 | t.equal(pool.borrowed, 1); 664 | t.equal(pool.pending, 1); 665 | pool.release(obj); 666 | }) 667 | .catch(t.threw); 668 | 669 | pool 670 | .acquire() 671 | .then(function(obj) { 672 | t.equal(pool.available, 0); 673 | t.equal(pool.borrowed, 1); 674 | t.equal(pool.pending, 0); 675 | pool.release(obj); 676 | utils.stopPool(pool); 677 | t.end(); 678 | }) 679 | .catch(t.threw); 680 | }); 681 | 682 | tap.test( 683 | "isBorrowedResource should return true for borrowed resource", 684 | function(t) { 685 | const pool = createPool(new ResourceFactory(), { max: 1 }); 686 | 687 | pool 688 | .acquire() 689 | .then(function(obj) { 690 | t.equal(pool.isBorrowedResource(obj), true); 691 | pool.release(obj); 692 | utils.stopPool(pool); 693 | t.end(); 694 | }) 695 | .catch(t.threw); 696 | } 697 | ); 698 | 699 | tap.test( 700 | "isBorrowedResource should return false for released resource", 701 | function(t) { 702 | const pool = createPool(new ResourceFactory(), { max: 1 }); 703 | 704 | pool 705 | .acquire() 706 | .then(function(obj) { 707 | pool.release(obj); 708 | return obj; 709 | }) 710 | .then(function(obj) { 711 | t.equal(pool.isBorrowedResource(obj), false); 712 | utils.stopPool(pool); 713 | t.end(); 714 | }) 715 | .catch(t.threw); 716 | } 717 | ); 718 | 719 | tap.test("destroy should redispense", function(t) { 720 | const pool = createPool(new ResourceFactory(), { max: 1 }); 721 | 722 | pool 723 | .acquire() 724 | .then(function(obj) { 725 | t.equal(pool.available, 0); 726 | t.equal(pool.borrowed, 1); 727 | t.equal(pool.pending, 1); 728 | pool.destroy(obj); 729 | }) 730 | .catch(t.threw); 731 | 732 | pool 733 | .acquire() 734 | .then(function(obj) { 735 | t.equal(pool.available, 0); 736 | t.equal(pool.borrowed, 1); 737 | t.equal(pool.pending, 0); 738 | pool.release(obj); 739 | utils.stopPool(pool); 740 | t.end(); 741 | }) 742 | .catch(t.threw); 743 | }); 744 | 745 | tap.test("evictor start with acquire when autostart is false", function(t) { 746 | const pool = createPool(new ResourceFactory(), { 747 | evictionRunIntervalMillis: 10000, 748 | autostart: false 749 | }); 750 | 751 | t.equal(pool._scheduledEviction, null); 752 | 753 | pool 754 | .acquire() 755 | .then(function(obj) { 756 | t.notEqual(pool._scheduledEviction, null); 757 | pool.release(obj); 758 | utils.stopPool(pool); 759 | t.end(); 760 | }) 761 | .catch(t.threw); 762 | }); 763 | 764 | tap.test("use method", function(t) { 765 | const pool = createPool(new ResourceFactory()); 766 | const result = pool.use(function(resource) { 767 | t.equal(0, resource.id); 768 | return Promise.resolve(); 769 | }); 770 | result.then(function() { 771 | t.end(); 772 | }); 773 | }); 774 | 775 | tap.test("use method should resolve after fn promise is resolved", function(t) { 776 | const pool = createPool(new ResourceFactory()); 777 | let done_with_resource = false; 778 | const result = pool.use(function(resource) { 779 | return new Promise(function(resolve, reject) { 780 | setImmediate(function() { 781 | done_with_resource = true; 782 | resolve("value"); 783 | }); 784 | }); 785 | }); 786 | result.then(val => { 787 | t.equal(done_with_resource, true); 788 | t.equal(val, "value"); 789 | t.end(); 790 | }); 791 | }); 792 | 793 | tap.test("evictor should not run when softIdleTimeoutMillis is -1", function( 794 | t 795 | ) { 796 | const resourceFactory = new ResourceFactory(); 797 | const pool = createPool(resourceFactory, { 798 | evictionRunIntervalMillis: 10 799 | }); 800 | pool 801 | .acquire() 802 | .then(res => pool.release(res)) 803 | .then(() => { 804 | return new Promise(res => setTimeout(res, 30)); 805 | }) 806 | .then(() => t.equal(resourceFactory.destroyed, 0)) 807 | .then(() => { 808 | utils.stopPool(pool); 809 | t.end(); 810 | }); 811 | }); 812 | 813 | tap.test("should respect when maxWaitingClients is set to 0 ", function(t) { 814 | let assertionCount = 0; 815 | const resourceFactory = new ResourceFactory(); 816 | const config = { 817 | max: 2, 818 | maxWaitingClients: 0 819 | }; 820 | 821 | const pool = createPool(resourceFactory, config); 822 | 823 | const borrowedResources = []; 824 | 825 | t.equal(pool.size, 0); 826 | assertionCount += 1; 827 | 828 | pool 829 | .acquire() 830 | .then(function(obj) { 831 | borrowedResources.push(obj); 832 | t.equal(pool.size, 1); 833 | assertionCount += 1; 834 | }) 835 | .then(function() { 836 | return pool.acquire(); 837 | }) 838 | .then(function(obj) { 839 | borrowedResources.push(obj); 840 | t.equal(pool.size, 2); 841 | assertionCount += 1; 842 | }) 843 | .then(function() { 844 | return pool.acquire(); 845 | }) 846 | .then(function(obj) { 847 | // should not go in here 848 | t.equal(1, 2); 849 | }) 850 | .catch(error => { 851 | t.equal(error.message, "max waitingClients count exceeded"); 852 | t.end(); 853 | }); 854 | }); 855 | 856 | tap.test("should provide a way to wait until the pool is ready", function(t) { 857 | const resourceFactory = new ResourceFactory(); 858 | const config = { 859 | min: 2, 860 | max: 4 861 | }; 862 | 863 | const pool = createPool(resourceFactory, config); 864 | 865 | pool.ready().then(() => { 866 | t.ok( 867 | pool.available >= config.min, 868 | "expected available resources to be at least as the minimum" 869 | ); 870 | t.end(); 871 | }); 872 | }); 873 | -------------------------------------------------------------------------------- /test/resource-request-test.js: -------------------------------------------------------------------------------- 1 | var tap = require("tap"); 2 | var ResourceRequest = require("../lib/ResourceRequest"); 3 | 4 | tap.test("can be created", function(t) { 5 | var create = function() { 6 | var request = new ResourceRequest(undefined, Promise); // eslint-disable-line no-unused-vars 7 | }; 8 | t.doesNotThrow(create); 9 | t.end(); 10 | }); 11 | 12 | tap.test("times out when created with a ttl", function(t) { 13 | var reject = function(err) { 14 | t.match(err, /ResourceRequest timed out/); 15 | t.end(); 16 | }; 17 | var resolve = function(r) { 18 | t.fail("should not resolve"); 19 | }; 20 | var request = new ResourceRequest(10, Promise); // eslint-disable-line no-unused-vars 21 | 22 | request.promise.then(resolve, reject); 23 | }); 24 | 25 | tap.test("calls resolve when resolved", function(t) { 26 | var resource = {}; 27 | var resolve = function(r) { 28 | t.equal(r, resource); 29 | t.end(); 30 | }; 31 | var reject = function(err) { 32 | t.error(err); 33 | }; 34 | var request = new ResourceRequest(undefined, Promise); 35 | request.promise.then(resolve, reject); 36 | request.resolve(resource); 37 | }); 38 | 39 | tap.test("removeTimeout removes the timeout", function(t) { 40 | var reject = function(err) { 41 | t.error(err); 42 | }; 43 | var request = new ResourceRequest(10, Promise); 44 | request.promise.then(undefined, reject); 45 | request.removeTimeout(); 46 | setTimeout(function() { 47 | t.end(); 48 | }, 20); 49 | }); 50 | 51 | tap.test("does nothing if resolved more than once", function(t) { 52 | var request = new ResourceRequest(undefined, Promise); 53 | t.doesNotThrow(function() { 54 | request.resolve({}); 55 | }); 56 | t.doesNotThrow(function() { 57 | request.resolve({}); 58 | }); 59 | t.end(); 60 | }); 61 | -------------------------------------------------------------------------------- /test/utils.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | const Pool = require("../lib/Pool"); 4 | 5 | /** 6 | * Generic class for handling creation of resources 7 | * for testing 8 | */ 9 | class ResourceFactory { 10 | constructor() { 11 | this.created = 0; 12 | this.destroyed = 0; 13 | this.bin = []; 14 | } 15 | 16 | create() { 17 | return Promise.resolve({ id: this.created++ }); 18 | } 19 | 20 | validate() { 21 | return Promise.resolve(true); 22 | } 23 | 24 | destroy(resource) { 25 | this.destroyed++; 26 | this.bin.push(resource); 27 | return Promise.resolve(); 28 | } 29 | } 30 | exports.ResourceFactory = ResourceFactory; 31 | 32 | /** 33 | * drains and terminates the pool 34 | * 35 | * @param {Pool} pool [description] 36 | * @return {Promise} [description] 37 | */ 38 | exports.stopPool = function(pool) { 39 | return pool.drain().then(function() { 40 | return pool.clear(); 41 | }); 42 | }; 43 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es5", 4 | "module": "commonjs", 5 | "lib": ["es6", "dom"], 6 | "outDir": "dist/", 7 | "allowJs": true, 8 | "checkJs": true, 9 | "declaration": true, 10 | "noEmit": true, 11 | "strict": false 12 | } 13 | } --------------------------------------------------------------------------------