{"id":15011271,"url":"https://github.com/panates/lightning-pool","last_synced_at":"2025-04-06T15:12:26.164Z","repository":{"id":26854490,"uuid":"108646632","full_name":"panates/lightning-pool","owner":"panates","description":"High performance resource pool written with TypeScript","archived":false,"fork":false,"pushed_at":"2025-01-28T10:33:56.000Z","size":1062,"stargazers_count":28,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T14:11:27.910Z","etag":null,"topics":["fast","javascript","node-js","pool","resource-pool","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/panates.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/package.cjs.json","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-28T12:18:50.000Z","updated_at":"2025-02-20T10:38:29.000Z","dependencies_parsed_at":"2024-01-08T07:28:05.079Z","dependency_job_id":"164c9eeb-24d4-4f5f-be91-60b45d7a3849","html_url":"https://github.com/panates/lightning-pool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panates%2Flightning-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panates%2Flightning-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panates%2Flightning-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panates%2Flightning-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/panates","download_url":"https://codeload.github.com/panates/lightning-pool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247500468,"owners_count":20948880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fast","javascript","node-js","pool","resource-pool","typescript"],"created_at":"2024-09-24T19:40:05.311Z","updated_at":"2025-04-06T15:12:26.140Z","avatar_url":"https://github.com/panates.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lightning-pool\n\n[![NPM Version][npm-image]][npm-url]\n[![NPM Downloads][downloads-image]][downloads-url]\n[![CircleCI][circleci-image]][circleci-url]\n[![Test Coverage][coveralls-image]][coveralls-url]\n\n## About\n\nHigh performance resource pool written with TypeScript.\n\n - The fastest Resource Pool implementation for JavaScript ever! Check out [benchmark](BANCHMARK.md) results\n - Advanced configuration options, suits for enterprise level applications\n - Configuration can be changed while pool running\n - Promise based factory supported\n - Supports validation and resource reset\n - Fully tested. (%100 coverage)\n\n## Installation\n\n  - `npm install lightning-pool --save`\n\n## Example\n\n```ts\nimport {Pool} from 'lightning-pool';\nimport dbDriver from 'some-db-driver';\n\n/**\n * Step 1 - Create a factory object\n */\nconst factory = {\n    create: async function(opts) {\n        const client = await DbDriver.createClient();\n        return client;\n    },\n    destroy: async function(client) {  \n       await client.close();       \n    },\n    reset: async function(client){   \n       await client.rollback();       \n    },\n    validate: async function(client) {\n       await client.query('select 1');       \n    }    \n};\n\n/**\n * Step 2 - Create a the pool object\n */\nconst pool = new Pool(factory, {  \n    max: 10,    // maximum size of the pool\n    min: 2,     // minimum size of the pool\n    minIdle: 2  // minimum idle resources\n});\n\npool.start();\n\n/**\n * Step 3 - Use pool in your code to acquire/release resources\n */\n// acquire connection - Promise is resolved\nconst client = await pool.acquire();\n// once a resource becomes available\n// Use resource\nawait client.query(\"select * from foo\");\n// return object back to pool\nawait pool.release(client);\n\n/**\n * Step 4 - Shutdown pool (optional)\n * Call close(force) when you need to shutdown the pool\n */\n\n// Wait for active resource for 5 sec than force shutdown\nawait pool.close(5000);\n```\n\n## Documentation\n\n### Creating a `Pool` instance\n\nlightning-pool module exports createPool() method and Pool class. Both can be used to instantiate a Pool. \n\n```ts\nimport {createPool} from 'lightning-pool';\nconst pool = createPool(factory, options);\n```\n\n```ts\nimport {Pool} from 'lightning-pool';\nconst pool = new Pool(factory, options);\n```\n\n#### factory\n\nCan be any object/instance with the following properties:\n\n- `create` : The function that the `Pool` will call when it needs a new resource. It should return a `Promise\u003cresouce\u003e`.\n- `destroy` : The function that the `Pool` will call when it wants to destroy a `resource`. It should accept first argument as `resource`,  where `resource` is whatever factory.create made. It should return a `Promise\u003c\u003e`.    \n- `reset` (optional) : The function that the `Pool` will call before any `resource` back to the `Pool`. It should accept first argument as `resource`,  where `resource` is whatever factory.create made. It should return a `Promise\u003c\u003e`. `Pool` will destroy and remove the resource from the `Pool` on any error.\n- `validate` (optional) : The function that the `Pool` will call when any resource needs to be validated. It should accept first argument as `resource`,  where `resource` is whatever factory.create made. It should return a `Promise\u003c\u003e`. `Pool` will destroy and remove the resource from the `Pool` on any error.\n\n#### options\n- `acquireMaxRetries`: Maximum number that `Pool` will try to create a resource before returning the error. (Default 0)\n- `acquireRetryWait`: Time in millis that `Pool` will wait after each tries. (Default 2000) \n- `acquireTimeoutMillis`: Time in millis an acquire call will wait for a resource before timing out. (Default 0 - no limit) \n- `fifo`: If true resources will be allocated first-in-first-out order. resources will be allocated last-in-first-out order. (Default true)\n- `idleTimeoutMillis`: The minimum amount of time in millis that an `resource` may sit idle in the `Pool`. (Default 30000) \n- `houseKeepInterval`: Time period in millis that `Pool` will make a cleanup. (Default 1000) \n- `min`: Minimum number of resources that `Pool` will keep. (Default 0)\n- `minIdle`: Minimum number of resources that `Pool` will keep in idle state. (Default 0)\n- `max`: Maximum number of resources that `Pool` will create. (Default 10)\n- `maxQueue`: Maximum number of request that `Pool` will accept. (Default 1000)\n- `resetOnReturn`: If true `Pool` will call `reset()` function of factory before moving it idle state. (Default true)\n- `validation`: If true `Pool` will call `validation()` function of factory when it needs it. If false, `validation()` never been called. (Default true)\n\n### Methods\n\n#### Pool.prototype.acquire()\n\nAcquires a `resource` from the `Pool` or create a new one.\n\n##### Usage\n\n`pool.acquire(): Promise\u003cany\u003e`\n\n`pool.acquire(factoryCreateOptions: any): Promise\u003cany\u003e`\n\n`pool.acquire(callback:Callback): Promise\u003cany\u003e`\n\n`pool.acquire(factoryCreateOptions?: any, callback:Callback): Promise\u003cany\u003e`\n\n- *Returns*: A Promise\n\n\n```js\nvar promise = pool.acquire();\npromise.then(resource =\u003e {\n  // Do what ever you want with resource\n}).catch(err =\u003e{\n  // Handle Error  \n});\n```\n\n#### Pool.prototype.isAcquired()\n\nReturns if a resource has been acquired from the `Pool` and not yet released or destroyed.\n\n##### Usage\n\n`pool.isAcquired(resource)`\n\n- `resource`: A previously acquired resource\n- *Returns*: True if the resource is acquired, else False\n\n```js\nif (pool.isAcquired(resource)) {\n  // Do any thing\n}\n```\n\n\n\n#### Pool.prototype.includes()\n\nReturns if the `Pool` contains a resource\n\n##### Usage\n\n`pool.includes(resource)`\n\n- `resource`: A resource object\n- *Returns*: True if the resource is in the `Pool`, else False\n\n```js\nif (pool.includes(resource)) {\n  // Do any thing\n}\n```\n\n\n\n#### Pool.prototype.release()\n\nReleases an allocated `resource` and let it back to pool.\n\n##### Usage\n\n`pool.release(resource)`\n\n- `resource`: A previously acquired resource\n- *Returns*: undefined\n\n```js\npool.release(resource);\n```\n\n\n\n\n#### Pool.prototype.destroy()\n\nReleases, destroys and removes any `resource` from `Pool`.\n\n##### Usage\n\n`pool.destroy(resource)`\n\n- `resource`: A previously acquired resource\n- *Returns*: undefined\n\n```js\npool.destroy(resource);\n```\n\n\n\n\n#### Pool.prototype.start()\n\nStarts the `Pool` and begins creating of resources, starts house keeping and any other internal logic.\n\n*Note: This method is not need to be called. `Pool` instance will automatically be started when acquire() method is called*  \n\n##### Usage\n\n`pool.start()`\n\n- *Returns*: undefined\n\n\n```js\npool.start();\n```\n\n\n\n#### Pool.prototype.close()\n\nShuts down the `Pool` and destroys all resources.  \n\n##### Usage\n\n`close(callback: Callback): void;`\n`close(terminateWait: number, callback?: Callback): Promise\u003cvoid\u003e;`\n`close(force: boolean, callback?: Callback): void;`\n\n- `force`: If true, `Pool` will immediately destroy resources instead of waiting to be released\n- `terminateWait`: If specified, `Pool` will wait for active resources to release\n- `callback`: If specified, callback will be called after close. If not specified a promise returns.\n\n\n```js\nvar promise = pool.close();\npromise.then(() =\u003e {\n  console.log('Pool has been shut down') \n}).catch(err =\u003e {\n  console.error(err);  \n});\n```\n\n### Properties\n\n\n- `acquired` (Number): Returns number of acquired resources.\n- `available` (Number): Returns number of idle resources.\n- `creating` (Number): Returns number of resources currently been created.\n- `pending` (Number): Returns number of acquire request waits in the `Pool` queue.\n- `size` (Number): Returns number of total resources.\n- `state` (PoolState): Returns current state of the `Pool`.\n- `options` (PoolOptions): Returns object instance that holds configuration properties\n    - `acquireMaxRetries` (Get/Set): Maximum number that `Pool` will try to create a resource before returning the error. (Default 0)\n    - `acquireRetryWait` (Get/Set): Time in millis that `Pool` will wait after each tries. (Default 2000) \n    - `acquireTimeoutMillis` (Get/Set): Time in millis an acquire call will wait for a resource before timing out. (Default 0 - no limit) \n    - `fifo` (Get/Set): If true resources will be allocated first-in-first-out order. resources will be allocated last-in-first-out order. (Default true)\n    - `idleTimeoutMillis` (Get/Set): The minimum amount of time in millis that an `resource` may sit idle in the `Pool`. (Default 30000) \n    - `houseKeepInterval` (Get/Set): Time period in millis that `Pool` will make a cleanup. (Default 1000) \n    - `min` (Get/Set): Minimum number of resources that `Pool` will keep. (Default 0)\n    - `minIdle` (Get/Set): Minimum number of resources that `Pool` will keep in idle state. (Default 0)\n    - `max` (Get/Set): Maximum number of resources that `Pool` will create. (Default 10)\n    - `maxQueue` (Get/Set): Maximum number of request that `Pool` will acceps. (Default 1000)\n    - `resetOnReturn` (Get/Set): If true `Pool` will call `reset()` function of factory before moving it idle state. (Default true)\n    - `validation` (Get/Set): If true `Pool` will call `validation()` function of factory when it needs it. If false, `validation()` never been called. (Default true)    \n\n### Events\n\nPool derives from EventEmitter and produce the following events:\n\n- `acquire`: Emitted when a resource acquired.\n    \n```js\npool.on('acquire', function(resource){\n  //....\n})\n```    \n    \n- `create`: Emitted when a new resource is added to the `Pool`.\n```js\npool.on('create', function(resource){\n  //....\n})\n```    \n\n- `create-error`: Emitted when a factory.create informs any error.\n```js\npool.on('create-error', function(error){\n  //Log stuff maybe\n})\n```    \n\n- `destroy`: Emitted when a resource is destroyed and removed from the `Pool`.\n- `destroy-error`: Emitted when a factory.destroy informs any error.\n```js\npool.on('destroy-error', function(error, resource){\n  //Log stuff maybe\n})\n```    \n\n- `return`: Emitted when an acquired resource returns to the `Pool`.\n```js\npool.on('start', function(resource){\n  //...\n})\n```    \n\n\n- `start`: Emitted when the `Pool` started.\n```js\npool.on('start', function(){\n  //...\n})\n```    \n\n- `closing`: Emitted when before closing the `Pool`.\n```js\npool.on('closing', function(){\n  //...\n})\n```    \n\n\n- `close`: Emitted when after closing the `Pool`.\n```js\npool.on('close', function(){\n  //...\n})\n```    \n\n- `validate-error`: Emitted when a factory.validate informs any error.\n```js\npool.on('validate-error', function(error, resource){\n  //Log stuff maybe\n})\n```    \n\n## PoolState enum\n\nPool.PoolState (Number): \n\n- IDLE: 0,     // Pool has not been started\n  \n- STARTED: 1,  // Pool has been started\n  \n- CLOSING: 2, // Pool shutdown in progress\n  \n- CLOSED: 3   // Pool has been shut down\n  \n\n\n## Node Compatibility\n\n  - node `\u003e= 16.0`;\n  \n### License\n[MIT](LICENSE)\n\n[npm-image]: https://img.shields.io/npm/v/lightning-pool.svg\n[npm-url]: https://npmjs.org/package/lightning-pool\n[circleci-image]: https://circleci.com/gh/panates/lightning-pool/tree/master.svg?style=shield\n[circleci-url]: https://circleci.com/gh/panates/lightning-pool/tree/master\n[coveralls-image]: https://img.shields.io/coveralls/panates/lightning-pool/master.svg\n[coveralls-url]: https://coveralls.io/r/panates/lightning-pool\n[downloads-image]: https://img.shields.io/npm/dm/lightning-pool.svg\n[downloads-url]: https://npmjs.org/package/lightning-pool\n[gitter-image]: https://badges.gitter.im/panates/lightning-pool.svg\n[gitter-url]: https://gitter.im/panates/lightning-pool?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\n[dependencies-image]: https://david-dm.org/panates/lightning-pool/status.svg\n[dependencies-url]:https://david-dm.org/panates/lightning-pool\n[devdependencies-image]: https://david-dm.org/panates/lightning-pool/dev-status.svg\n[devdependencies-url]:https://david-dm.org/panates/lightning-pool?type=dev\n[quality-image]: http://npm.packagequality.com/shield/lightning-pool.png\n[quality-url]: http://packagequality.com/#?package=lightning-pool\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanates%2Flightning-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpanates%2Flightning-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanates%2Flightning-pool/lists"}