Socket
Socket
Sign inDemoInstall

lightning-pool

Package Overview
Dependencies
Maintainers
1
Versions
59
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

lightning-pool

Fastest generic Pool written with TypeScript


Version published
Weekly downloads
80K
decreased by-0.68%
Maintainers
1
Weekly downloads
 
Created
Source

lightning-pool

NPM Version NPM Downloads CircleCI Test Coverage

About

High performance resource pool written with TypeScript.

  • The fastest Resource Pool implementation for JavaScript ever! Check out benchmark results
  • Advanced configuration options, suits for enterprise level applications
  • Configuration can be changed while pool running
  • Promise based factory supported
  • Supports validation and resource reset
  • Fully tested. (%100 coverage)

Installation

  • npm install lightning-pool --save

Example

import {Pool} from 'lightning-pool';
import dbDriver from 'some-db-driver';

/**
 * Step 1 - Create a factory object
 */
const factory = {
    create: async function(opts) {
        const client = await DbDriver.createClient();
        return client;
    },
    destroy: async function(client) {  
       await client.close();       
    },
    reset: async function(client){   
       await client.rollback();       
    },
    validate: async function(client) {
       await client.query('select 1');       
    }    
};

/**
 * Step 2 - Create a the pool object
 */
const pool = new Pool(factory, {  
    max: 10,    // maximum size of the pool
    min: 2,     // minimum size of the pool
    minIdle: 2  // minimum idle resources
});

/**
 * Step 3 - Use pool in your code to acquire/release resources
 */
// acquire connection - Promise is resolved
const client = await pool.acquire();
// once a resource becomes available
// Use resource
await client.query("select * from foo");
// return object back to pool
await pool.release(client);

/**
 * Step 4 - Shutdown pool (optional)
 * Call close(force) when you need to shutdown the pool
 */

// Wait for active resource for 5 sec than force shutdown
await pool.close(5000);

Documentation

Creating a Pool instance

lightning-pool module exports createPool() method and Pool class. Both can be used to instantiate a Pool.

import {createPool} from 'lightning-pool';
const pool = createPool(factory, options);
import {Pool} from 'lightning-pool';
const pool = new Pool(factory, options);
factory

Can be any object/instance with the following properties:

  • create : The function that the Pool will call when it needs a new resource. It should return a Promise<resouce>.
  • 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<>.
  • 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<>. Pool will destroy and remove the resource from the Pool on any error.
  • 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<>. Pool will destroy and remove the resource from the Pool on any error.
options
  • acquireMaxRetries: Maximum number that Pool will try to create a resource before returning the error. (Default 0)
  • acquireRetryWait: Time in millis that Pool will wait after each tries. (Default 2000)
  • acquireTimeoutMillis: Time in millis an acquire call will wait for a resource before timing out. (Default 0 - no limit)
  • fifo: If true resources will be allocated first-in-first-out order. resources will be allocated last-in-first-out order. (Default true)
  • idleTimeoutMillis: The minimum amount of time in millis that an resource may sit idle in the Pool. (Default 30000)
  • houseKeepInterval: Time period in millis that Pool will make a cleanup. (Default 1000)
  • min: Minimum number of resources that Pool will keep. (Default 0)
  • minIdle: Minimum number of resources that Pool will keep in idle state. (Default 0)
  • max: Maximum number of resources that Pool will create. (Default 10)
  • maxQueue: Maximum number of request that Pool will accept. (Default 1000)
  • resetOnReturn: If true Pool will call reset() function of factory before moving it idle state. (Default true)
  • validation: If true Pool will call validation() function of factory when it needs it. If false, validation() never been called. (Default true)

Methods

Pool.prototype.acquire()

Acquires a resource from the Pool or create a new one.

Usage

pool.acquire(): Promise<any>

pool.acquire(factoryCreateOptions: any): Promise<any>

pool.acquire(callback:Callback): Promise<any>

pool.acquire(factoryCreateOptions?: any, callback:Callback): Promise<any>

  • Returns: A Promise
var promise = pool.acquire();
promise.then(resource => {
  // Do what ever you want with resource
}).catch(err =>{
  // Handle Error  
});
Pool.prototype.isAcquired()

Returns if a resource has been acquired from the Pool and not yet released or destroyed.

Usage

pool.isAcquired(resource)

  • resource: A previously acquired resource
  • Returns: True if the resource is acquired, else False
if (pool.isAcquired(resource)) {
  // Do any thing
}
Pool.prototype.includes()

Returns if the Pool contains a resource

Usage

pool.includes(resource)

  • resource: A resource object
  • Returns: True if the resource is in the Pool, else False
if (pool.includes(resource)) {
  // Do any thing
}
Pool.prototype.release()

Releases an allocated resource and let it back to pool.

Usage

pool.release(resource)

  • resource: A previously acquired resource
  • Returns: undefined
pool.release(resource);
Pool.prototype.destroy()

Releases, destroys and removes any resource from Pool.

Usage

pool.destroy(resource)

  • resource: A previously acquired resource
  • Returns: undefined
pool.destroy(resource);
Pool.prototype.start()

Starts the Pool and begins creating of resources, starts house keeping and any other internal logic.

Note: This method is not need to be called. Pool instance will automatically be started when acquire() method is called

Usage

pool.start()

  • Returns: undefined
pool.start();
Pool.prototype.close()

Shuts down the Pool and destroys all resources.

Usage

close(callback: Callback): void; close(terminateWait: number, callback?: Callback): Promise<void>; close(force: boolean, callback?: Callback): void;

  • force: If true, Pool will immediately destroy resources instead of waiting to be released
  • terminateWait: If specified, Pool will wait for active resources to release
  • callback: If specified, callback will be called after close. If not specified a promise returns.
var promise = pool.close();
promise.then(() => {
  console.log('Pool has been shut down') 
}).catch(err => {
  console.error(err);  
});

Properties

  • acquired (Number): Returns number of acquired resources.
  • available (Number): Returns number of idle resources.
  • creating (Number): Returns number of resources currently been created.
  • pending (Number): Returns number of acquire request waits in the Pool queue.
  • size (Number): Returns number of total resources.
  • state (PoolState): Returns current state of the Pool.
  • options (PoolOptions): Returns object instance that holds configuration properties
    • acquireMaxRetries (Get/Set): Maximum number that Pool will try to create a resource before returning the error. (Default 0)
    • acquireRetryWait (Get/Set): Time in millis that Pool will wait after each tries. (Default 2000)
    • acquireTimeoutMillis (Get/Set): Time in millis an acquire call will wait for a resource before timing out. (Default 0 - no limit)
    • 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)
    • idleTimeoutMillis (Get/Set): The minimum amount of time in millis that an resource may sit idle in the Pool. (Default 30000)
    • houseKeepInterval (Get/Set): Time period in millis that Pool will make a cleanup. (Default 1000)
    • min (Get/Set): Minimum number of resources that Pool will keep. (Default 0)
    • minIdle (Get/Set): Minimum number of resources that Pool will keep in idle state. (Default 0)
    • max (Get/Set): Maximum number of resources that Pool will create. (Default 10)
    • maxQueue (Get/Set): Maximum number of request that Pool will acceps. (Default 1000)
    • resetOnReturn (Get/Set): If true Pool will call reset() function of factory before moving it idle state. (Default true)
    • validation (Get/Set): If true Pool will call validation() function of factory when it needs it. If false, validation() never been called. (Default true)

Events

Pool derives from EventEmitter and produce the following events:

  • acquire: Emitted when a resource acquired.
pool.on('acquire', function(resource){
  //....
})
  • create: Emitted when a new resource is added to the Pool.
pool.on('create', function(resource){
  //....
})
  • create-error: Emitted when a factory.create informs any error.
pool.on('create-error', function(error){
  //Log stuff maybe
})
  • destroy: Emitted when a resource is destroyed and removed from the Pool.
  • destroy-error: Emitted when a factory.destroy informs any error.
pool.on('destroy-error', function(error, resource){
  //Log stuff maybe
})
  • return: Emitted when an acquired resource returns to the Pool.
pool.on('start', function(resource){
  //...
})
  • start: Emitted when the Pool started.
pool.on('start', function(){
  //...
})
  • closing: Emitted when before closing the Pool.
pool.on('closing', function(){
  //...
})
  • close: Emitted when after closing the Pool.
pool.on('close', function(){
  //...
})
  • validate-error: Emitted when a factory.validate informs any error.
pool.on('validate-error', function(error, resource){
  //Log stuff maybe
})

PoolState enum

Pool.PoolState (Number):

  • IDLE: 0, // Pool has not been started

  • STARTED: 1, // Pool has been started

  • CLOSING: 2, // Pool shutdown in progress

  • CLOSED: 3 // Pool has been shut down

Node Compatibility

  • node >= 16.0;

License

MIT

Keywords

FAQs

Package last updated on 20 Aug 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc