API Documentation
Overview
Pool.js is a lightweight resource pool scheduler built on ES2024 explicit resource management (Symbol.dispose / Symbol.asyncDispose). It provides an elegant way to manage limited resources (database connections, HTTP clients, Worker threads, etc.) allocation and recycling.
- Pool — Resource pool for managing resource creation, allocation, and recycling
- ResourceContainer — Resource holder that manages the actual resource and its release
- Scheduler — Task scheduler that automatically dispatches tasks to idle resources
- CoolDown — Callback to control the interval before a resource becomes available again
Installation
Quick Start
Pool
Pool<T> is the core class of the resource pool. It creates and manages resources, providing APIs for acquisition and scheduling.
PoolOptions
| Property | Type | Default | Description |
|---|---|---|---|
concurrency | number | — | Maximum concurrency, total number of resources the pool can manage |
create | (created: number) => T | PromiseLike<T> | (i) => i | Factory function to create resources, parameter is the current number of created resources |
resources | T[] | — | Pre-existing resource array, these resources are not destroyed when the pool is cleaned up |
coolDown | CoolDown | — | Cooldown callback after resource release, controls when it becomes available again |
shouldDispose | boolean | true | Whether to destroy created resources on pool cleanup (false when passing a resource array) |
acquire()
Acquire a resource from the pool, returns ResourceContainer<T>.
The returned ResourceContainer implements Symbol.dispose, it's recommended to use the using keyword for lifecycle management:
schedule()
Create a Scheduler instance for task-based resource scheduling.
enqueue()
Shortcut method, equivalent to pool.schedule().enqueue(). Directly enqueues a task.
Symbol.asyncDispose()
Clean up the entire resource pool. Waits for all borrowed resources to return, then destroys pool-created resources and resets state. Recommended to use the await using keyword for automatic cleanup.
ResourceContainer
ResourceContainer<T> is the return value of acquire(). It holds the actual resource and is responsible for releasing it when done.
| 属性/方法 | 类型 | 说明 |
|---|---|---|
value | T | The actual resource value (read-only) |
[Symbol.dispose]() | () => void | Release resource back to pool |
Without using Keyword
If your runtime does not support ES2024 explicit resource management, or you prefer manual control, you can manage resource lifecycle by directly calling [Symbol.dispose]() and [Symbol.asyncDispose]():
Using await using and using keywords ensures resources are properly released even when exceptions occur, preventing resource leaks. If your environment supports it (Node.js 22+), always use using keyword.
Scheduler
Scheduler<T> provides task-based resource scheduling. You don't need to manually acquire and release resources — the Scheduler automatically executes tasks when resources are available.
enqueue()
Enqueue a task. The task function receives pool resources via this.
enqueueAll()
Batch enqueue tasks, returns an array of all results. Accepts sync or async iterators.
wrap()
Wraps a task function, returning a new function. When the new function is called, it automatically enqueues the task. Useful when reusing task logic.
CoolDown
CoolDown is a callback executed after a resource is released. It receives resource scheduling timing information and returns a Promise to control when the resource can be allocated again.
Callback parameters:
| 参数 | 类型 | 说明 |
|---|---|---|
acquireAt | number | Timestamp when resource acquisition started |
deliverAt | number | Timestamp when resource was delivered to caller |
releaseAt | number | Timestamp when resource release started |
Error Handling
NoResourceAvailableError
Thrown when acquire({ wait: false }) is called and no resources are available.
Type Definitions