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.