@alius/pool

Resource pool.

Installation

npm install @alius/pool

Usage

import { Pool, ResourceFactory } from "@alius/pool";

// create resource factory class
class MyResourceFactory extends ResourceFactory {
  // used for creating new resource
  async create() {
    // for example database connection
    const res = {};
    return res;
  }

  // used for destroying resource
  async destroy(resource) {
    // for example disconnect from database
  }

  // used for validating existing resource
  async validate(resource) {
    // validate resource
    if (resourceIsNotValid) {
      throw new Error();
    }
  }
}

// create resource factory
const resourceFactory = new MyResourceFactory();

const poolOptions = {
  max: 10,
  min: 3,
  validate: true
};

// create and start pool
const pool = new Pool(resourceFactory, poolOptions);
pool.start();

// acquire and use resource
let resource;
try {
  resource = await pool.acquire();
  // use resource
} catch(err) {
  console.error("got error", err);
} finally {
  if (resource) {
    pool.release(resource);
  }
}

// shut down pool
await pool.shutDown();

API

Constructors

Pool(resourceFactory)

Creates new pool with specified resource factory.

Pool(resourceFactory, poolOptions)

Creates new pool with specified resource factory and options.

Properties

state

• CREATED - pool is just created
• STARTED - pool is started
• DOWN - pool is shutting down
• STOPPED - pool is stopped

stats

Returns current pool statistics: requests, creators, destroyers, resources(total, idle, inUse, testing)

Methods

acquire()

Acquires new resource from pool. This method creates and queues new request (Promise) for resource. Request (Promise) will be resolved with resource as soon as it becomes available. If pool is not started or is shutting down or request queue is full - returns immediately with rejected request (Promise).

release(resource)

Returns resource to pool.

start()

Starts pool. Pool will start only if it's state is either CREATED or STOPPED. Trying to start already running pool will be siletly discarded.

shutDown()

Shuts down pool. New requests for resource acquisition will be immediately rejected. All outstanding requests are rejected. Returns promise which will be resolved after all acquired resources are released and destroyed.

Events emitted

• started - pool has been started
• stopping - pool is stopping
• stopped - pool has been stopped
• created - new resource created
• createFailed - failed to create new resource; error passed as event argument
• destroyed - resource destroyed
• destroyFailed - failed to destroy resource; error passed as event argument
• acquired - resource acquired
• validationFailed - failed to validate resource; error passed as event argument
• released - resource released back to pool

Pool options (passed to constructor)

• createTimeout = 0 number of milliseconds to wait for creating resource; 0 - waits indefinitely.
• destroyTimeout = 0 number of milliseconds to wait for destroying resource; 0 - waits indefinitely.
• max = 1 maximum number of resources in this pool
• min = 0 minimum number of resources in this pool
• validate = false should resource be tested before releasing it
• validateTimeout = 0 number of milliseconds to wait for testing resource; 0 - waits indefinitely.
• acquireTimeout = 0 number of milliseconds to wait for acquiring resource; 0 - waits indefinitely.
• maxTries = 0 maximum number of failed tries to create resource before rejecting request; 0 - tries indefinitely.
• maxQueue = 0 maximum number of requests in queue. Incomming requests overflowing max queue wil be immediately rejected; 0 - queue size is not restricted.
• evictionInterval = 0 how often to run eviction checks; 0 - will not run.
• evictionAge = 0 minimum number of milliseconds before resource becomes eligible for evition. Resource can be evicted only if pool size greater than minimum number of reources; 0 - no resource will be evicted.