npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lightning-pool

v4.10.0

Published

Fastest generic Pool written with TypeScript

Downloads

262,859

Readme

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