API 文档
概述
Pool.js 是一个轻量级资源池调度器，基于 ES2024 显式资源管理（Symbol.dispose / Symbol.asyncDispose）实现。它提供了一种优雅的方式来管理有限资源（如数据库连接、HTTP 客户端、Worker 线程等）的分配与回收。
- Pool — 资源池，管理资源的创建、分配和回收
- ResourceContainer — 资源容器，持有实际资源并负责释放
- Scheduler — 任务调度器，将任务自动分配给空闲资源
- CoolDown — 冷却回调，控制资源释放后再次可用的时间间隔
安装
快速开始
Pool
Pool<T> 是资源池的核心类。它负责创建和管理资源，并提供获取、调度等 API。
PoolOptions 配置
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
concurrency | number | — | 最大并发数，池能管理的资源总数 |
create | (created: number) => T | PromiseLike<T> | (i) => i | 创建资源的工厂函数，参数为当前已创建的资源数量 |
resources | T[] | — | 预存在的资源数组，这些资源在清理池时不会被销毁 |
coolDown | CoolDown | — | 资源释放后的冷却回调，控制再次可用的时间 |
shouldDispose | boolean | true | 清理池时是否销毁已创建的资源（传入资源数组时为 false） |
acquire()
从池中获取一个资源，返回 ResourceContainer<T>。
返回的 ResourceContainer 实现了 Symbol.dispose，建议使用 using 关键字管理生命周期：
schedule()
创建一个 Scheduler 实例，用于基于任务的方式调度资源。
enqueue()
快捷方法，等价于 pool.schedule().enqueue()。直接将任务放入调度队列。
Symbol.asyncDispose()
清理整个资源池。等待所有已借出的资源归还后，销毁池创建的资源并重置状态。推荐使用 await using 关键字实现自动清理。
ResourceContainer
ResourceContainer<T> 是 acquire() 的返回值。它持有实际资源并负责在使用完毕后释放。
| 属性/方法 | 类型 | 说明 |
|---|---|---|
value | T | 实际的资源值（只读） |
[Symbol.dispose]() | () => void | 释放资源回池 |
不使用 using 关键字
如果你的运行时不支持 ES2024 显式资源管理，或者你更喜欢手动控制，可以通过直接调用 [Symbol.dispose]() 和 [Symbol.asyncDispose]() 来管理资源生命周期：
使用 await using 和 using 关键字可以确保即使发生异常资源也能被正确释放，避免资源泄漏。如果你的环境支持（Node.js 22+），建议始终使用 using 关键字。
Scheduler
Scheduler<T> 提供基于任务的资源调度方式。你不需要手动获取和释放资源，Scheduler 会在有资源可用时自动执行任务。
enqueue()
将一个任务放入队列。任务函数通过 this 接收池资源。
enqueueAll()
批量入队任务，返回所有结果的数组。接受同步或异步迭代器。
wrap()
包装一个任务函数，返回一个新函数。调用这个新函数时会自动将任务入队。适合需要复用任务逻辑的场景。
CoolDown
CoolDown 是一个回调函数，在资源被释放后执行。它接收资源调度的时间信息，返回一个 Promise 来控制资源何时可以再次被分配。
回调参数：
| 参数 | 类型 | 说明 |
|---|---|---|
acquireAt | number | 资源开始被获取的时间戳 |
deliverAt | number | 资源被交付给调用者的时间戳 |
releaseAt | number | 资源开始被释放的时间戳 |
错误处理
NoResourceAvailableError
当 acquire({ wait: false }) 且没有可用资源时抛出。
类型定义