@orkestrel/pool 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @orkestrel/pool
+
+A bounded, typed **resource pool**: idle reuse + FIFO waiting. `acquire` leases
+a resource — reusing a validated idle one, growing up to `max`, or parking on
+a FIFO waiter list until a `release` frees one — and the returned token's
+`release()` returns it for reuse (or hands it straight to the next waiter).
+The FIFO handoff is validated, so a resource that goes bad while leased is
+never handed to the next lessee, and a parked `acquire` given an `AbortSignal`
+rejects and de-queues itself when the signal fires — no leaked waiter. The
+pool is observable (a typed `emitter` surfaces `create` / `acquire` /
+`release` / `destroy`) and deliberately de-bloated — no warm-floor, no
+eviction timers. Environment-agnostic — no I/O, no browser or server
+assumptions. Part of the `@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/pool
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM-only (no CommonJS build)
+
+## Usage
+
+```ts
+import { createPool } from '@orkestrel/pool'
+
+const pool = createPool<Connection>({
+	create: () => connect(),
+	destroy: (connection) => connection.close(),
+	validate: (connection) => connection.alive,
+	max: 8,
+})
+
+const token = await pool.acquire()
+try {
+	await token.value.query('select 1')
+} finally {
+	token.release()
+}
+```
+
+## Guide
+
+For the full surface — the `Pool` engine, options, the observable `emitter`,
+and usage patterns — see [`guides/src/pool.md`](guides/src/pool.md).
+
+## Package
+
+Published as a single typed entry point per the `exports` field in
+`package.json`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

package/dist/src/core/index.cjs

@@ -0,0 +1,276 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/Pool.ts
+/**
+* A bounded resource pool with idle reuse + FIFO waiting.
+*
+* @remarks
+* - **Idle reuse.** `acquire` first takes an idle resource (validating it when a
+*   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh
+*   one is tried). When no usable idle resource exists and the pool is below `max`, it
+*   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter
+*   list until a `release` hands it a resource.
+* - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next
+*   parked waiter (oldest first) — the resource stays leased, the lessee just changes —
+*   or returns it to idle when no one is waiting. With a waiter parked the resource is
+*   re-validated first (the same `validate` hook the idle path uses), so a resource that
+*   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the
+*   waiter is served a fresh/valid one instead — a dead resource is never handed on. The
+*   no-waiter path stays synchronous; releasing the same token twice is a no-op (an
+*   idempotent token guard).
+* - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one
+*   returning `false` — the resource is "not usable", so it is destroyed and replaced —
+*   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so
+*   a throwing validator can never strand a parked waiter on an unhandled rejection.
+* - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects
+*   when that signal fires and removes its waiter from the queue — no leaked waiter, so
+*   a later `release` still serves the next live waiter. The signal is supplied by the
+*   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort
+*   of its own.
+* - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.
+* - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);
+*   `destroy` destroys ALL resources and rejects any parked waiters. Both await the
+*   `destroy` hook.
+* - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the
+*   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget
+*   observers. Every event is emitted directly, strictly AFTER the relevant transition —
+*   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the
+*   emitter isolates a listener throw and routes it to its `error` handler (the `error`
+*   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction
+*   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is
+*   purely a side-channel.
+* - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.
+*/
+var Pool = class {
+	#create;
+	#destroy;
+	#validate;
+	#max;
+	#emitter;
+	#idle = [];
+	#waiters = [];
+	#active = 0;
+	#destroyed = false;
+	constructor(options) {
+		this.#create = options.create;
+		this.#destroy = options.destroy;
+		this.#validate = options.validate;
+		this.#max = Math.max(1, options.max ?? Number.POSITIVE_INFINITY);
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		return this.#idle.length + this.#active;
+	}
+	get idle() {
+		return this.#idle.length;
+	}
+	get active() {
+		return this.#active;
+	}
+	async acquire(signal) {
+		if (this.#destroyed) throw new Error("pool is destroyed");
+		if (signal?.aborted === true) throw signal.reason;
+		const reused = await this.#reuse();
+		if (reused !== void 0) {
+			this.#emitter.emit("acquire");
+			return reused;
+		}
+		if (this.size < this.#max) {
+			const grown = await this.#grow();
+			this.#emitter.emit("acquire");
+			return grown;
+		}
+		return await this.#wait(signal);
+	}
+	async clear() {
+		const resources = this.#idle.splice(0);
+		await Promise.all(resources.map((resource) => this.#release(resource)));
+	}
+	async destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		const waiters = this.#waiters.splice(0);
+		const error = /* @__PURE__ */ new Error("pool is destroyed");
+		for (const waiter of waiters) {
+			waiter.clear();
+			waiter.reject(error);
+		}
+		const resources = this.#idle.splice(0);
+		await Promise.all(resources.map((resource) => this.#release(resource)));
+	}
+	async #reuse() {
+		while (this.#idle.length > 0) {
+			const resource = this.#idle.shift();
+			if (resource === void 0) continue;
+			if (await this.#valid(resource)) {
+				this.#active += 1;
+				return this.#token(resource);
+			}
+			await this.#release(resource);
+		}
+	}
+	async #grow() {
+		this.#active += 1;
+		let resource;
+		try {
+			resource = await this.#create();
+		} catch (error) {
+			this.#active -= 1;
+			throw error instanceof Error ? error : new Error(String(error));
+		}
+		if (this.#destroyed) {
+			this.#active -= 1;
+			await this.#release(resource);
+			throw new Error("pool is destroyed");
+		}
+		this.#emitter.emit("create");
+		return this.#token(resource);
+	}
+	#wait(signal) {
+		return new Promise((resolve, reject) => {
+			const waiter = {
+				resolve,
+				reject,
+				clear: () => {}
+			};
+			this.#waiters.push(waiter);
+			if (signal !== void 0) {
+				const onAbort = () => {
+					const index = this.#waiters.indexOf(waiter);
+					if (index >= 0) this.#waiters.splice(index, 1);
+					reject(signal.reason);
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+				waiter.clear = () => signal.removeEventListener("abort", onAbort);
+			}
+		});
+	}
+	#token(resource) {
+		let released = false;
+		return {
+			value: resource,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.#return(resource);
+			}
+		};
+	}
+	#return(resource) {
+		if (this.#waiters.length === 0) {
+			this.#active -= 1;
+			if (this.#destroyed) {
+				this.#release(resource);
+				return;
+			}
+			this.#idle.push(resource);
+			this.#emitter.emit("release");
+			return;
+		}
+		this.#handoff(resource);
+	}
+	async #handoff(resource) {
+		if (await this.#valid(resource)) {
+			this.#serve(resource);
+			return;
+		}
+		this.#release(resource);
+		let replacement;
+		try {
+			replacement = await this.#create();
+		} catch (error) {
+			this.#active -= 1;
+			const waiter = this.#waiters.shift();
+			waiter?.clear();
+			waiter?.reject(error instanceof Error ? error : new Error(String(error)));
+			return;
+		}
+		this.#emitter.emit("create");
+		this.#serve(replacement);
+	}
+	#serve(resource) {
+		const waiter = this.#destroyed ? void 0 : this.#waiters.shift();
+		if (waiter !== void 0) {
+			waiter.clear();
+			waiter.resolve(this.#token(resource));
+			this.#emitter.emit("acquire");
+			return;
+		}
+		this.#active -= 1;
+		if (this.#destroyed) {
+			this.#release(resource);
+			return;
+		}
+		this.#idle.push(resource);
+		this.#emitter.emit("release");
+	}
+	async #valid(resource) {
+		if (this.#validate === void 0) return true;
+		try {
+			return await this.#validate(resource);
+		} catch {
+			return false;
+		}
+	}
+	async #release(resource) {
+		if (this.#destroy === void 0) {
+			this.#emitter.emit("destroy");
+			return;
+		}
+		try {
+			await this.#destroy(resource);
+		} catch {}
+		this.#emitter.emit("destroy");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a
+* resource (reusing a validated idle one, growing up to `max`, or parking until a
+* `release` frees one) and the returned token's `release` returns it for reuse.
+*
+* @remarks
+* A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal
+* fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);
+* `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),
+* no eviction timers — and observable (§13): a typed `emitter` surfaces
+* `create` / `acquire` / `release` / `destroy`.
+*
+* @typeParam T - The pooled resource type
+* @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+* @returns A working {@link PoolInterface}
+*
+* @example
+* ```ts
+* import { createPool } from '@src/core'
+*
+* const pool = createPool<Connection>({
+* 	create: () => connect(),
+* 	destroy: (connection) => connection.close(),
+* 	validate: (connection) => connection.alive,
+* 	max: 8,
+* })
+*
+* const token = await pool.acquire()
+* try {
+* 	await token.value.query('select 1')
+* } finally {
+* 	token.release()
+* }
+* ```
+*/
+function createPool(options) {
+	return new Pool(options);
+}
+//#endregion
+exports.Pool = Pool;
+exports.createPool = createPool;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["#create","#destroy","#validate","#max","#emitter","#idle","#waiters","#active","#destroyed","#reuse","#grow","#wait","#release","#valid","#token","#return","#handoff","#serve"],"sources":["../../../src/core/Pool.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { PoolEventMap, PoolInterface, PoolOptions, PoolToken, PoolWaiter } from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\n\n/**\n * A bounded resource pool with idle reuse + FIFO waiting.\n *\n * @remarks\n * - **Idle reuse.** `acquire` first takes an idle resource (validating it when a\n *   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh\n *   one is tried). When no usable idle resource exists and the pool is below `max`, it\n *   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter\n *   list until a `release` hands it a resource.\n * - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next\n *   parked waiter (oldest first) — the resource stays leased, the lessee just changes —\n *   or returns it to idle when no one is waiting. With a waiter parked the resource is\n *   re-validated first (the same `validate` hook the idle path uses), so a resource that\n *   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the\n *   waiter is served a fresh/valid one instead — a dead resource is never handed on. The\n *   no-waiter path stays synchronous; releasing the same token twice is a no-op (an\n *   idempotent token guard).\n * - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one\n *   returning `false` — the resource is \"not usable\", so it is destroyed and replaced —\n *   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so\n *   a throwing validator can never strand a parked waiter on an unhandled rejection.\n * - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects\n *   when that signal fires and removes its waiter from the queue — no leaked waiter, so\n *   a later `release` still serves the next live waiter. The signal is supplied by the\n *   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort\n *   of its own.\n * - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.\n * - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);\n *   `destroy` destroys ALL resources and rejects any parked waiters. Both await the\n *   `destroy` hook.\n * - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the\n *   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget\n *   observers. Every event is emitted directly, strictly AFTER the relevant transition —\n *   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the\n *   emitter isolates a listener throw and routes it to its `error` handler (the `error`\n *   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction\n *   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is\n *   purely a side-channel.\n * - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.\n */\nexport class Pool<T> implements PoolInterface<T> {\n\treadonly #create: () => Promise<T> | T\n\treadonly #destroy: ((value: T) => Promise<void> | void) | undefined\n\treadonly #validate: ((value: T) => Promise<boolean> | boolean) | undefined\n\treadonly #max: number\n\t// The PUSH observation surface (§13) — owned, never inherited. The emitter isolates a\n\t// listener throw (routing it to the `error` handler), so it can never escape into the\n\t// validated FIFO handoff-eviction path.\n\treadonly #emitter: Emitter<PoolEventMap>\n\n\treadonly #idle: T[] = []\n\treadonly #waiters: PoolWaiter<T>[] = []\n\t#active = 0\n\t#destroyed = false\n\n\tconstructor(options: PoolOptions<T>) {\n\t\tthis.#create = options.create\n\t\tthis.#destroy = options.destroy\n\t\tthis.#validate = options.validate\n\t\tthis.#max = Math.max(1, options.max ?? Number.POSITIVE_INFINITY)\n\t\tthis.#emitter = new Emitter<PoolEventMap>({ on: options?.on, error: options?.error })\n\t}\n\n\tget emitter(): EmitterInterface<PoolEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget size(): number {\n\t\treturn this.#idle.length + this.#active\n\t}\n\n\tget idle(): number {\n\t\treturn this.#idle.length\n\t}\n\n\tget active(): number {\n\t\treturn this.#active\n\t}\n\n\tasync acquire(signal?: AbortSignal): Promise<PoolToken<T>> {\n\t\tif (this.#destroyed) throw new Error('pool is destroyed')\n\t\tif (signal?.aborted === true) throw signal.reason\n\t\t// Reuse a validated idle resource if one is available.\n\t\tconst reused = await this.#reuse()\n\t\tif (reused !== undefined) {\n\t\t\t// Observe the lease — AFTER `#reuse` resolved the token (the resource is already\n\t\t\t// leased; emit only OBSERVES it).\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn reused\n\t\t}\n\t\t// Otherwise grow the pool when below the cap.\n\t\tif (this.size < this.#max) {\n\t\t\tconst grown = await this.#grow()\n\t\t\t// Observe the lease — AFTER `#grow` resolved the fresh token.\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn grown\n\t\t}\n\t\t// At capacity with nothing idle — park until a release hands us a resource. The\n\t\t// `acquire` for THIS lease is emitted by `#serve` once a `release` hands it a resource\n\t\t// (after `waiter.resolve`), NOT here — so a served waiter emits `acquire` exactly once.\n\t\treturn await this.#wait(signal)\n\t}\n\n\tasync clear(): Promise<void> {\n\t\tconst resources = this.#idle.splice(0)\n\t\tawait Promise.all(resources.map((resource) => this.#release(resource)))\n\t}\n\n\tasync destroy(): Promise<void> {\n\t\tif (this.#destroyed) return\n\t\tthis.#destroyed = true\n\t\tconst waiters = this.#waiters.splice(0)\n\t\tconst error = new Error('pool is destroyed')\n\t\tfor (const waiter of waiters) {\n\t\t\twaiter.clear()\n\t\t\twaiter.reject(error)\n\t\t}\n\t\tconst resources = this.#idle.splice(0)\n\t\tawait Promise.all(resources.map((resource) => this.#release(resource)))\n\t}\n\n\t// Take + validate the next idle resource; destroy + skip invalid ones. Returns a\n\t// token for the first valid idle resource, or `undefined` when none is usable.\n\tasync #reuse(): Promise<PoolToken<T> | undefined> {\n\t\twhile (this.#idle.length > 0) {\n\t\t\tconst resource = this.#idle.shift()\n\t\t\tif (resource === undefined) continue\n\t\t\tif (await this.#valid(resource)) {\n\t\t\t\tthis.#active += 1\n\t\t\t\treturn this.#token(resource)\n\t\t\t}\n\t\t\tawait this.#release(resource)\n\t\t}\n\t\treturn undefined\n\t}\n\n\t// Create a fresh resource and lease it. Reserve the active slot before awaiting\n\t// `create` so a concurrent acquire sees the pool at capacity (no overshoot of `max`).\n\tasync #grow(): Promise<PoolToken<T>> {\n\t\tthis.#active += 1\n\t\tlet resource: T\n\t\ttry {\n\t\t\tresource = await this.#create()\n\t\t} catch (error: unknown) {\n\t\t\tthis.#active -= 1\n\t\t\tthrow error instanceof Error ? error : new Error(String(error))\n\t\t}\n\t\t// The pool may have been destroyed during `create` — never hand a live resource into\n\t\t// a torn-down pool. Free the active slot, destroy the just-created resource, and throw.\n\t\tif (this.#destroyed) {\n\t\t\tthis.#active -= 1\n\t\t\tawait this.#release(resource)\n\t\t\tthrow new Error('pool is destroyed')\n\t\t}\n\t\t// Observe the fresh resource — AFTER `create` resolved and the not-destroyed re-check\n\t\t// passed (the resource is here to stay), BEFORE the token is built.\n\t\tthis.#emitter.emit('create')\n\t\treturn this.#token(resource)\n\t}\n\n\t// Park a resolver on the FIFO waiter list until a release hands it a resource; an\n\t// abort on `signal` rejects the acquire and removes its waiter (no leak).\n\t#wait(signal: AbortSignal | undefined): Promise<PoolToken<T>> {\n\t\treturn new Promise<PoolToken<T>>((resolve, reject) => {\n\t\t\tconst waiter: PoolWaiter<T> = { resolve, reject, clear: () => {} }\n\t\t\tthis.#waiters.push(waiter)\n\t\t\tif (signal !== undefined) {\n\t\t\t\tconst onAbort = (): void => {\n\t\t\t\t\tconst index = this.#waiters.indexOf(waiter)\n\t\t\t\t\tif (index >= 0) this.#waiters.splice(index, 1)\n\t\t\t\t\treject(signal.reason)\n\t\t\t\t}\n\t\t\t\tsignal.addEventListener('abort', onAbort, { once: true })\n\t\t\t\twaiter.clear = (): void => signal.removeEventListener('abort', onAbort)\n\t\t\t}\n\t\t})\n\t}\n\n\t// Build an idempotent token; its `release` returns the resource exactly once.\n\t#token(resource: T): PoolToken<T> {\n\t\tlet released = false\n\t\treturn {\n\t\t\tvalue: resource,\n\t\t\trelease: (): void => {\n\t\t\t\tif (released) return\n\t\t\t\treleased = true\n\t\t\t\tthis.#return(resource)\n\t\t\t},\n\t\t}\n\t}\n\n\t// Return a leased resource. No waiter parked → synchronously drop it to idle (or destroy\n\t// it if torn down), `#active -= 1`. A waiter IS parked → hand off asynchronously, after\n\t// re-validating the resource so an invalid one (e.g. a terminated thread) is never served.\n\t#return(resource: T): void {\n\t\tif (this.#waiters.length === 0) {\n\t\t\tthis.#active -= 1\n\t\t\tif (this.#destroyed) {\n\t\t\t\tvoid this.#release(resource)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tthis.#idle.push(resource)\n\t\t\t// Observe the resource dropping to idle — AFTER `#active` was balanced down and it\n\t\t\t// is back on the idle list (the synchronous no-waiter path). A waiter-handoff\n\t\t\t// instead keeps the resource LEASED, so it emits no `release` here.\n\t\t\tthis.#emitter.emit('release')\n\t\t\treturn\n\t\t}\n\t\tvoid this.#handoff(resource)\n\t}\n\n\t// Hand a released resource to the oldest parked waiter, re-validating it first. A VALID\n\t// resource is served as-is (it stays leased — `#active` unchanged). An INVALID one is\n\t// destroyed and the waiter is served a fresh resource that REUSES the dead one's `#active`\n\t// slot (the count never dips below the lease, so a concurrent acquire can't overshoot\n\t// `max`). The waiter is re-shifted after every `await` (the queue can change underneath\n\t// us), and the pool is re-checked for teardown — so no waiter is leaked or double-settled\n\t// and no resource is handed into a destroyed pool.\n\tasync #handoff(resource: T): Promise<void> {\n\t\t// VALID release → serve the released resource directly (the common, unchanged path).\n\t\tif (await this.#valid(resource)) {\n\t\t\tthis.#serve(resource)\n\t\t\treturn\n\t\t}\n\t\t// INVALID release → destroy it and replace it, holding its `#active` slot steady.\n\t\tvoid this.#release(resource)\n\t\tlet replacement: T\n\t\ttry {\n\t\t\treplacement = await this.#create()\n\t\t} catch (error: unknown) {\n\t\t\t// The dead resource cannot be replaced — free its slot and reject the oldest waiter\n\t\t\t// (it can't be served), or drop the error if the queue raced empty.\n\t\t\tthis.#active -= 1\n\t\t\tconst waiter = this.#waiters.shift()\n\t\t\twaiter?.clear()\n\t\t\twaiter?.reject(error instanceof Error ? error : new Error(String(error)))\n\t\t\treturn\n\t\t}\n\t\t// Observe the fresh replacement — AFTER `create` resolved, BEFORE it is served.\n\t\tthis.#emitter.emit('create')\n\t\tthis.#serve(replacement)\n\t}\n\n\t// Hand a validated resource (the released one, or its fresh replacement) to the oldest\n\t// live waiter, holding its `#active` slot. If the queue raced empty across the awaits, the\n\t// resource is idle (or destroyed when torn down) and its slot is freed.\n\t#serve(resource: T): void {\n\t\tconst waiter = this.#destroyed ? undefined : this.#waiters.shift()\n\t\tif (waiter !== undefined) {\n\t\t\twaiter.clear()\n\t\t\twaiter.resolve(this.#token(resource))\n\t\t\t// Observe the served-waiter lease — strictly AFTER `waiter.resolve(...)` (the token\n\t\t\t// is already handed off; the emit only OBSERVES it and cannot sit across the resolve\n\t\t\t// or perturb the served acquirer's continuation). This is the `acquire` for a parked\n\t\t\t// `acquire`, so the public `acquire` deliberately does NOT emit on its `#wait` branch.\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn\n\t\t}\n\t\tthis.#active -= 1\n\t\tif (this.#destroyed) {\n\t\t\tvoid this.#release(resource)\n\t\t\treturn\n\t\t}\n\t\tthis.#idle.push(resource)\n\t\t// The waiter queue raced empty across the handoff awaits — the resource lands back on\n\t\t// idle instead of being leased. Observe that as a `release` (the return-to-idle that\n\t\t// `#return` would have emitted had no waiter been parked when the token was released).\n\t\tthis.#emitter.emit('release')\n\t}\n\n\t// Is this resource usable? No validator trusts it; otherwise run the hook. A validator\n\t// that THROWS is treated exactly like one returning `false` — the resource is \"not\n\t// usable\", so it is destroyed + replaced rather than escaping as an unhandled rejection\n\t// that would strand a parked waiter on the handoff path (the same total-function spirit\n\t// as a guard, AGENTS §12 / §14). The single gate for both the idle (`#reuse`) and the\n\t// handoff (`#handoff`) validation, so the two paths can never diverge.\n\tasync #valid(resource: T): Promise<boolean> {\n\t\tif (this.#validate === undefined) return true\n\t\ttry {\n\t\t\treturn await this.#validate(resource)\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\t// Destroy one resource via the optional hook, swallowing destruction failures. Observe the\n\t// drop with a `destroy` event AFTER the hook ran (or after the no-hook drop) — the resource\n\t// is gone from the pool either way; a swallowed `destroy`-hook failure still emits (the pool\n\t// abandoned it). The emit is the LAST thing here, strictly after the teardown transition.\n\tasync #release(resource: T): Promise<void> {\n\t\tif (this.#destroy === undefined) {\n\t\t\tthis.#emitter.emit('destroy')\n\t\t\treturn\n\t\t}\n\t\ttry {\n\t\t\tawait this.#destroy(resource)\n\t\t} catch {\n\t\t\t// A destroy failure abandons the resource — there is nothing to recover.\n\t\t}\n\t\tthis.#emitter.emit('destroy')\n\t}\n}\n","import type { PoolInterface, PoolOptions } from './types.js'\nimport { Pool } from './Pool.js'\n\n/**\n * Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a\n * resource (reusing a validated idle one, growing up to `max`, or parking until a\n * `release` frees one) and the returned token's `release` returns it for reuse.\n *\n * @remarks\n * A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal\n * fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);\n * `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),\n * no eviction timers — and observable (§13): a typed `emitter` surfaces\n * `create` / `acquire` / `release` / `destroy`.\n *\n * @typeParam T - The pooled resource type\n * @param options - The `create` hook plus optional `destroy` / `validate` / `max`\n * @returns A working {@link PoolInterface}\n *\n * @example\n * ```ts\n * import { createPool } from '@src/core'\n *\n * const pool = createPool<Connection>({\n * \tcreate: () => connect(),\n * \tdestroy: (connection) => connection.close(),\n * \tvalidate: (connection) => connection.alive,\n * \tmax: 8,\n * })\n *\n * const token = await pool.acquire()\n * try {\n * \tawait token.value.query('select 1')\n * } finally {\n * \ttoken.release()\n * }\n * ```\n */\nexport function createPool<T>(options: PoolOptions<T>): PoolInterface<T> {\n\treturn new Pool(options)\n}\n"],"mappings":"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"}

package/dist/src/core/index.d.cts

@@ -0,0 +1,194 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a
+ * resource (reusing a validated idle one, growing up to `max`, or parking until a
+ * `release` frees one) and the returned token's `release` returns it for reuse.
+ *
+ * @remarks
+ * A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal
+ * fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);
+ * `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),
+ * no eviction timers — and observable (§13): a typed `emitter` surfaces
+ * `create` / `acquire` / `release` / `destroy`.
+ *
+ * @typeParam T - The pooled resource type
+ * @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+ * @returns A working {@link PoolInterface}
+ *
+ * @example
+ * ```ts
+ * import { createPool } from '@src/core'
+ *
+ * const pool = createPool<Connection>({
+ * 	create: () => connect(),
+ * 	destroy: (connection) => connection.close(),
+ * 	validate: (connection) => connection.alive,
+ * 	max: 8,
+ * })
+ *
+ * const token = await pool.acquire()
+ * try {
+ * 	await token.value.query('select 1')
+ * } finally {
+ * 	token.release()
+ * }
+ * ```
+ */
+export declare function createPool<T>(options: PoolOptions<T>): PoolInterface<T>;
+
+/**
+ * A bounded resource pool with idle reuse + FIFO waiting.
+ *
+ * @remarks
+ * - **Idle reuse.** `acquire` first takes an idle resource (validating it when a
+ *   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh
+ *   one is tried). When no usable idle resource exists and the pool is below `max`, it
+ *   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter
+ *   list until a `release` hands it a resource.
+ * - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next
+ *   parked waiter (oldest first) — the resource stays leased, the lessee just changes —
+ *   or returns it to idle when no one is waiting. With a waiter parked the resource is
+ *   re-validated first (the same `validate` hook the idle path uses), so a resource that
+ *   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the
+ *   waiter is served a fresh/valid one instead — a dead resource is never handed on. The
+ *   no-waiter path stays synchronous; releasing the same token twice is a no-op (an
+ *   idempotent token guard).
+ * - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one
+ *   returning `false` — the resource is "not usable", so it is destroyed and replaced —
+ *   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so
+ *   a throwing validator can never strand a parked waiter on an unhandled rejection.
+ * - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects
+ *   when that signal fires and removes its waiter from the queue — no leaked waiter, so
+ *   a later `release` still serves the next live waiter. The signal is supplied by the
+ *   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort
+ *   of its own.
+ * - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.
+ * - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);
+ *   `destroy` destroys ALL resources and rejects any parked waiters. Both await the
+ *   `destroy` hook.
+ * - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the
+ *   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget
+ *   observers. Every event is emitted directly, strictly AFTER the relevant transition —
+ *   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the
+ *   emitter isolates a listener throw and routes it to its `error` handler (the `error`
+ *   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction
+ *   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is
+ *   purely a side-channel.
+ * - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.
+ */
+export declare class Pool<T> implements PoolInterface<T> {
+    #private;
+    constructor(options: PoolOptions<T>);
+    get emitter(): EmitterInterface<PoolEventMap>;
+    get size(): number;
+    get idle(): number;
+    get active(): number;
+    acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * The push observation surface of a {@link PoolInterface} (AGENTS §13) — the resource
+ * lifecycle moments a fire-and-forget observer subscribes to.
+ *
+ * @remarks
+ * Pure signals (no `T` payload — `Pool<T>` carries no resource value on its events, so a
+ * non-generic map stays lean). Listener isolation is the emitter's (AGENTS §13): every event
+ * is emitted directly and a listener throw is routed to the emitter's `error` handler (the
+ * `error` option), never onto this map, and sits AFTER the relevant create / acquire /
+ * release / destroy transition — so a throwing observer can never corrupt the FIFO
+ * handoff-eviction machinery (it cannot strand a parked waiter or unbalance the lease count).
+ * Subscribe via `pool.emitter.on(...)`. Declared as a `type` alias (§4.5 — `EventMap` is a
+ * `type` kind).
+ */
+export declare type PoolEventMap = {
+    /** A fresh resource was created (`create` resolved) and leased. */
+    readonly create: readonly [];
+    /** A token was handed to a lessee (a reused idle one, a fresh one, or a served waiter). */
+    readonly acquire: readonly [];
+    /** A leased resource returned to idle (no waiter was parked). */
+    readonly release: readonly [];
+    /** A resource was destroyed (`clear` / `destroy`, or a failed `validate`). */
+    readonly destroy: readonly [];
+};
+
+/**
+ * A bounded resource pool with idle reuse + FIFO waiting.
+ *
+ * @remarks
+ * Exposes a typed {@link emitter} (AGENTS §13) carrying its resource lifecycle moments
+ * ({@link PoolEventMap}) for fire-and-forget observers. Emitting is observation-only —
+ * every event fires AFTER the relevant create / acquire / release / destroy transition, so a
+ * buggy observer can never corrupt the FIFO handoff-eviction machinery: the emitter isolates
+ * a listener throw and routes it to its `error` handler (the `error` option), never the pool.
+ */
+export declare interface PoolInterface<T> {
+    readonly emitter: EmitterInterface<PoolEventMap>;
+    readonly size: number;
+    readonly idle: number;
+    readonly active: number;
+    acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Options for `createPool` — the resource lifecycle hooks.
+ *
+ * @remarks
+ * - `create` — make a fresh resource; called when no idle resource is reusable and
+ *   the pool is below `max`. May be async.
+ * - `destroy` — tear a resource down when the pool drops it (`clear` / `destroy`, or
+ *   a failed `validate`); optional and awaited.
+ * - `validate` — check an idle resource is still usable before leasing it; an invalid
+ *   resource is destroyed and replaced. Optional (an absent validator trusts idle).
+ * - `max` — the most resources that may exist at once (idle + leased); defaults to
+ *   unbounded. A surplus `acquire` waits (FIFO) for a `release`.
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the pool's
+ *   {@link PoolEventMap}, wired at construction (e.g. `{ create: () => count() }`).
+ */
+export declare interface PoolOptions<T> {
+    readonly on?: EmitterHooks<PoolEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly create: () => Promise<T> | T;
+    readonly destroy?: (value: T) => Promise<void> | void;
+    readonly validate?: (value: T) => Promise<boolean> | boolean;
+    readonly max?: number;
+}
+
+/**
+ * A leased resource from a {@link PoolInterface} — `value` is the live resource and
+ * `release()` returns it to the pool for reuse (or hands it to the next waiter).
+ */
+export declare interface PoolToken<T> {
+    /** The leased resource. */
+    readonly value: T;
+    /** Return the resource to the pool; calling more than once is a no-op. */
+    release(): void;
+}
+
+/**
+ * A parked acquirer on a {@link PoolInterface}'s FIFO waiter list — its promise resolvers
+ * plus the cleanup that detaches its abort listener.
+ *
+ * @remarks
+ * Held only inside the {@link PoolInterface} engine (a resource at `max` parks the acquirer
+ * here until a `release` hands it a token); not part of the public call surface, but
+ * centralized here per AGENTS §5. `resolve` hands the waiter its leased {@link PoolToken};
+ * `reject` fails its `acquire` (a teardown or an aborted wait); `clear` detaches the abort
+ * listener so a settled waiter leaks nothing.
+ *
+ * @typeParam T - The resource the pool leases
+ */
+export declare interface PoolWaiter<T> {
+    readonly resolve: (token: PoolToken<T>) => void;
+    readonly reject: (error: unknown) => void;
+    clear(): void;
+}
+
+export { }

package/dist/src/core/index.d.ts

@@ -0,0 +1,194 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a
+ * resource (reusing a validated idle one, growing up to `max`, or parking until a
+ * `release` frees one) and the returned token's `release` returns it for reuse.
+ *
+ * @remarks
+ * A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal
+ * fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);
+ * `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),
+ * no eviction timers — and observable (§13): a typed `emitter` surfaces
+ * `create` / `acquire` / `release` / `destroy`.
+ *
+ * @typeParam T - The pooled resource type
+ * @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+ * @returns A working {@link PoolInterface}
+ *
+ * @example
+ * ```ts
+ * import { createPool } from '@src/core'
+ *
+ * const pool = createPool<Connection>({
+ * 	create: () => connect(),
+ * 	destroy: (connection) => connection.close(),
+ * 	validate: (connection) => connection.alive,
+ * 	max: 8,
+ * })
+ *
+ * const token = await pool.acquire()
+ * try {
+ * 	await token.value.query('select 1')
+ * } finally {
+ * 	token.release()
+ * }
+ * ```
+ */
+export declare function createPool<T>(options: PoolOptions<T>): PoolInterface<T>;
+
+/**
+ * A bounded resource pool with idle reuse + FIFO waiting.
+ *
+ * @remarks
+ * - **Idle reuse.** `acquire` first takes an idle resource (validating it when a
+ *   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh
+ *   one is tried). When no usable idle resource exists and the pool is below `max`, it
+ *   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter
+ *   list until a `release` hands it a resource.
+ * - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next
+ *   parked waiter (oldest first) — the resource stays leased, the lessee just changes —
+ *   or returns it to idle when no one is waiting. With a waiter parked the resource is
+ *   re-validated first (the same `validate` hook the idle path uses), so a resource that
+ *   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the
+ *   waiter is served a fresh/valid one instead — a dead resource is never handed on. The
+ *   no-waiter path stays synchronous; releasing the same token twice is a no-op (an
+ *   idempotent token guard).
+ * - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one
+ *   returning `false` — the resource is "not usable", so it is destroyed and replaced —
+ *   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so
+ *   a throwing validator can never strand a parked waiter on an unhandled rejection.
+ * - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects
+ *   when that signal fires and removes its waiter from the queue — no leaked waiter, so
+ *   a later `release` still serves the next live waiter. The signal is supplied by the
+ *   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort
+ *   of its own.
+ * - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.
+ * - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);
+ *   `destroy` destroys ALL resources and rejects any parked waiters. Both await the
+ *   `destroy` hook.
+ * - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the
+ *   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget
+ *   observers. Every event is emitted directly, strictly AFTER the relevant transition —
+ *   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the
+ *   emitter isolates a listener throw and routes it to its `error` handler (the `error`
+ *   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction
+ *   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is
+ *   purely a side-channel.
+ * - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.
+ */
+export declare class Pool<T> implements PoolInterface<T> {
+    #private;
+    constructor(options: PoolOptions<T>);
+    get emitter(): EmitterInterface<PoolEventMap>;
+    get size(): number;
+    get idle(): number;
+    get active(): number;
+    acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * The push observation surface of a {@link PoolInterface} (AGENTS §13) — the resource
+ * lifecycle moments a fire-and-forget observer subscribes to.
+ *
+ * @remarks
+ * Pure signals (no `T` payload — `Pool<T>` carries no resource value on its events, so a
+ * non-generic map stays lean). Listener isolation is the emitter's (AGENTS §13): every event
+ * is emitted directly and a listener throw is routed to the emitter's `error` handler (the
+ * `error` option), never onto this map, and sits AFTER the relevant create / acquire /
+ * release / destroy transition — so a throwing observer can never corrupt the FIFO
+ * handoff-eviction machinery (it cannot strand a parked waiter or unbalance the lease count).
+ * Subscribe via `pool.emitter.on(...)`. Declared as a `type` alias (§4.5 — `EventMap` is a
+ * `type` kind).
+ */
+export declare type PoolEventMap = {
+    /** A fresh resource was created (`create` resolved) and leased. */
+    readonly create: readonly [];
+    /** A token was handed to a lessee (a reused idle one, a fresh one, or a served waiter). */
+    readonly acquire: readonly [];
+    /** A leased resource returned to idle (no waiter was parked). */
+    readonly release: readonly [];
+    /** A resource was destroyed (`clear` / `destroy`, or a failed `validate`). */
+    readonly destroy: readonly [];
+};
+
+/**
+ * A bounded resource pool with idle reuse + FIFO waiting.
+ *
+ * @remarks
+ * Exposes a typed {@link emitter} (AGENTS §13) carrying its resource lifecycle moments
+ * ({@link PoolEventMap}) for fire-and-forget observers. Emitting is observation-only —
+ * every event fires AFTER the relevant create / acquire / release / destroy transition, so a
+ * buggy observer can never corrupt the FIFO handoff-eviction machinery: the emitter isolates
+ * a listener throw and routes it to its `error` handler (the `error` option), never the pool.
+ */
+export declare interface PoolInterface<T> {
+    readonly emitter: EmitterInterface<PoolEventMap>;
+    readonly size: number;
+    readonly idle: number;
+    readonly active: number;
+    acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Options for `createPool` — the resource lifecycle hooks.
+ *
+ * @remarks
+ * - `create` — make a fresh resource; called when no idle resource is reusable and
+ *   the pool is below `max`. May be async.
+ * - `destroy` — tear a resource down when the pool drops it (`clear` / `destroy`, or
+ *   a failed `validate`); optional and awaited.
+ * - `validate` — check an idle resource is still usable before leasing it; an invalid
+ *   resource is destroyed and replaced. Optional (an absent validator trusts idle).
+ * - `max` — the most resources that may exist at once (idle + leased); defaults to
+ *   unbounded. A surplus `acquire` waits (FIFO) for a `release`.
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the pool's
+ *   {@link PoolEventMap}, wired at construction (e.g. `{ create: () => count() }`).
+ */
+export declare interface PoolOptions<T> {
+    readonly on?: EmitterHooks<PoolEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly create: () => Promise<T> | T;
+    readonly destroy?: (value: T) => Promise<void> | void;
+    readonly validate?: (value: T) => Promise<boolean> | boolean;
+    readonly max?: number;
+}
+
+/**
+ * A leased resource from a {@link PoolInterface} — `value` is the live resource and
+ * `release()` returns it to the pool for reuse (or hands it to the next waiter).
+ */
+export declare interface PoolToken<T> {
+    /** The leased resource. */
+    readonly value: T;
+    /** Return the resource to the pool; calling more than once is a no-op. */
+    release(): void;
+}
+
+/**
+ * A parked acquirer on a {@link PoolInterface}'s FIFO waiter list — its promise resolvers
+ * plus the cleanup that detaches its abort listener.
+ *
+ * @remarks
+ * Held only inside the {@link PoolInterface} engine (a resource at `max` parks the acquirer
+ * here until a `release` hands it a token); not part of the public call surface, but
+ * centralized here per AGENTS §5. `resolve` hands the waiter its leased {@link PoolToken};
+ * `reject` fails its `acquire` (a teardown or an aborted wait); `clear` detaches the abort
+ * listener so a settled waiter leaks nothing.
+ *
+ * @typeParam T - The resource the pool leases
+ */
+export declare interface PoolWaiter<T> {
+    readonly resolve: (token: PoolToken<T>) => void;
+    readonly reject: (error: unknown) => void;
+    clear(): void;
+}
+
+export { }

package/dist/src/core/index.js

@@ -0,0 +1,274 @@
+import { Emitter } from "@orkestrel/emitter";
+//#region src/core/Pool.ts
+/**
+* A bounded resource pool with idle reuse + FIFO waiting.
+*
+* @remarks
+* - **Idle reuse.** `acquire` first takes an idle resource (validating it when a
+*   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh
+*   one is tried). When no usable idle resource exists and the pool is below `max`, it
+*   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter
+*   list until a `release` hands it a resource.
+* - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next
+*   parked waiter (oldest first) — the resource stays leased, the lessee just changes —
+*   or returns it to idle when no one is waiting. With a waiter parked the resource is
+*   re-validated first (the same `validate` hook the idle path uses), so a resource that
+*   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the
+*   waiter is served a fresh/valid one instead — a dead resource is never handed on. The
+*   no-waiter path stays synchronous; releasing the same token twice is a no-op (an
+*   idempotent token guard).
+* - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one
+*   returning `false` — the resource is "not usable", so it is destroyed and replaced —
+*   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so
+*   a throwing validator can never strand a parked waiter on an unhandled rejection.
+* - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects
+*   when that signal fires and removes its waiter from the queue — no leaked waiter, so
+*   a later `release` still serves the next live waiter. The signal is supplied by the
+*   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort
+*   of its own.
+* - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.
+* - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);
+*   `destroy` destroys ALL resources and rejects any parked waiters. Both await the
+*   `destroy` hook.
+* - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the
+*   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget
+*   observers. Every event is emitted directly, strictly AFTER the relevant transition —
+*   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the
+*   emitter isolates a listener throw and routes it to its `error` handler (the `error`
+*   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction
+*   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is
+*   purely a side-channel.
+* - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.
+*/
+var Pool = class {
+	#create;
+	#destroy;
+	#validate;
+	#max;
+	#emitter;
+	#idle = [];
+	#waiters = [];
+	#active = 0;
+	#destroyed = false;
+	constructor(options) {
+		this.#create = options.create;
+		this.#destroy = options.destroy;
+		this.#validate = options.validate;
+		this.#max = Math.max(1, options.max ?? Number.POSITIVE_INFINITY);
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		return this.#idle.length + this.#active;
+	}
+	get idle() {
+		return this.#idle.length;
+	}
+	get active() {
+		return this.#active;
+	}
+	async acquire(signal) {
+		if (this.#destroyed) throw new Error("pool is destroyed");
+		if (signal?.aborted === true) throw signal.reason;
+		const reused = await this.#reuse();
+		if (reused !== void 0) {
+			this.#emitter.emit("acquire");
+			return reused;
+		}
+		if (this.size < this.#max) {
+			const grown = await this.#grow();
+			this.#emitter.emit("acquire");
+			return grown;
+		}
+		return await this.#wait(signal);
+	}
+	async clear() {
+		const resources = this.#idle.splice(0);
+		await Promise.all(resources.map((resource) => this.#release(resource)));
+	}
+	async destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		const waiters = this.#waiters.splice(0);
+		const error = /* @__PURE__ */ new Error("pool is destroyed");
+		for (const waiter of waiters) {
+			waiter.clear();
+			waiter.reject(error);
+		}
+		const resources = this.#idle.splice(0);
+		await Promise.all(resources.map((resource) => this.#release(resource)));
+	}
+	async #reuse() {
+		while (this.#idle.length > 0) {
+			const resource = this.#idle.shift();
+			if (resource === void 0) continue;
+			if (await this.#valid(resource)) {
+				this.#active += 1;
+				return this.#token(resource);
+			}
+			await this.#release(resource);
+		}
+	}
+	async #grow() {
+		this.#active += 1;
+		let resource;
+		try {
+			resource = await this.#create();
+		} catch (error) {
+			this.#active -= 1;
+			throw error instanceof Error ? error : new Error(String(error));
+		}
+		if (this.#destroyed) {
+			this.#active -= 1;
+			await this.#release(resource);
+			throw new Error("pool is destroyed");
+		}
+		this.#emitter.emit("create");
+		return this.#token(resource);
+	}
+	#wait(signal) {
+		return new Promise((resolve, reject) => {
+			const waiter = {
+				resolve,
+				reject,
+				clear: () => {}
+			};
+			this.#waiters.push(waiter);
+			if (signal !== void 0) {
+				const onAbort = () => {
+					const index = this.#waiters.indexOf(waiter);
+					if (index >= 0) this.#waiters.splice(index, 1);
+					reject(signal.reason);
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+				waiter.clear = () => signal.removeEventListener("abort", onAbort);
+			}
+		});
+	}
+	#token(resource) {
+		let released = false;
+		return {
+			value: resource,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.#return(resource);
+			}
+		};
+	}
+	#return(resource) {
+		if (this.#waiters.length === 0) {
+			this.#active -= 1;
+			if (this.#destroyed) {
+				this.#release(resource);
+				return;
+			}
+			this.#idle.push(resource);
+			this.#emitter.emit("release");
+			return;
+		}
+		this.#handoff(resource);
+	}
+	async #handoff(resource) {
+		if (await this.#valid(resource)) {
+			this.#serve(resource);
+			return;
+		}
+		this.#release(resource);
+		let replacement;
+		try {
+			replacement = await this.#create();
+		} catch (error) {
+			this.#active -= 1;
+			const waiter = this.#waiters.shift();
+			waiter?.clear();
+			waiter?.reject(error instanceof Error ? error : new Error(String(error)));
+			return;
+		}
+		this.#emitter.emit("create");
+		this.#serve(replacement);
+	}
+	#serve(resource) {
+		const waiter = this.#destroyed ? void 0 : this.#waiters.shift();
+		if (waiter !== void 0) {
+			waiter.clear();
+			waiter.resolve(this.#token(resource));
+			this.#emitter.emit("acquire");
+			return;
+		}
+		this.#active -= 1;
+		if (this.#destroyed) {
+			this.#release(resource);
+			return;
+		}
+		this.#idle.push(resource);
+		this.#emitter.emit("release");
+	}
+	async #valid(resource) {
+		if (this.#validate === void 0) return true;
+		try {
+			return await this.#validate(resource);
+		} catch {
+			return false;
+		}
+	}
+	async #release(resource) {
+		if (this.#destroy === void 0) {
+			this.#emitter.emit("destroy");
+			return;
+		}
+		try {
+			await this.#destroy(resource);
+		} catch {}
+		this.#emitter.emit("destroy");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a
+* resource (reusing a validated idle one, growing up to `max`, or parking until a
+* `release` frees one) and the returned token's `release` returns it for reuse.
+*
+* @remarks
+* A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal
+* fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);
+* `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),
+* no eviction timers — and observable (§13): a typed `emitter` surfaces
+* `create` / `acquire` / `release` / `destroy`.
+*
+* @typeParam T - The pooled resource type
+* @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+* @returns A working {@link PoolInterface}
+*
+* @example
+* ```ts
+* import { createPool } from '@src/core'
+*
+* const pool = createPool<Connection>({
+* 	create: () => connect(),
+* 	destroy: (connection) => connection.close(),
+* 	validate: (connection) => connection.alive,
+* 	max: 8,
+* })
+*
+* const token = await pool.acquire()
+* try {
+* 	await token.value.query('select 1')
+* } finally {
+* 	token.release()
+* }
+* ```
+*/
+function createPool(options) {
+	return new Pool(options);
+}
+//#endregion
+export { Pool, createPool };
+
+//# sourceMappingURL=index.js.map

package/dist/src/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#create","#destroy","#validate","#max","#emitter","#idle","#waiters","#active","#destroyed","#reuse","#grow","#wait","#release","#valid","#token","#return","#handoff","#serve"],"sources":["../../../src/core/Pool.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { PoolEventMap, PoolInterface, PoolOptions, PoolToken, PoolWaiter } from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\n\n/**\n * A bounded resource pool with idle reuse + FIFO waiting.\n *\n * @remarks\n * - **Idle reuse.** `acquire` first takes an idle resource (validating it when a\n *   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh\n *   one is tried). When no usable idle resource exists and the pool is below `max`, it\n *   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter\n *   list until a `release` hands it a resource.\n * - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next\n *   parked waiter (oldest first) — the resource stays leased, the lessee just changes —\n *   or returns it to idle when no one is waiting. With a waiter parked the resource is\n *   re-validated first (the same `validate` hook the idle path uses), so a resource that\n *   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the\n *   waiter is served a fresh/valid one instead — a dead resource is never handed on. The\n *   no-waiter path stays synchronous; releasing the same token twice is a no-op (an\n *   idempotent token guard).\n * - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one\n *   returning `false` — the resource is \"not usable\", so it is destroyed and replaced —\n *   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so\n *   a throwing validator can never strand a parked waiter on an unhandled rejection.\n * - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects\n *   when that signal fires and removes its waiter from the queue — no leaked waiter, so\n *   a later `release` still serves the next live waiter. The signal is supplied by the\n *   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort\n *   of its own.\n * - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.\n * - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);\n *   `destroy` destroys ALL resources and rejects any parked waiters. Both await the\n *   `destroy` hook.\n * - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the\n *   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget\n *   observers. Every event is emitted directly, strictly AFTER the relevant transition —\n *   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the\n *   emitter isolates a listener throw and routes it to its `error` handler (the `error`\n *   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction\n *   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is\n *   purely a side-channel.\n * - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.\n */\nexport class Pool<T> implements PoolInterface<T> {\n\treadonly #create: () => Promise<T> | T\n\treadonly #destroy: ((value: T) => Promise<void> | void) | undefined\n\treadonly #validate: ((value: T) => Promise<boolean> | boolean) | undefined\n\treadonly #max: number\n\t// The PUSH observation surface (§13) — owned, never inherited. The emitter isolates a\n\t// listener throw (routing it to the `error` handler), so it can never escape into the\n\t// validated FIFO handoff-eviction path.\n\treadonly #emitter: Emitter<PoolEventMap>\n\n\treadonly #idle: T[] = []\n\treadonly #waiters: PoolWaiter<T>[] = []\n\t#active = 0\n\t#destroyed = false\n\n\tconstructor(options: PoolOptions<T>) {\n\t\tthis.#create = options.create\n\t\tthis.#destroy = options.destroy\n\t\tthis.#validate = options.validate\n\t\tthis.#max = Math.max(1, options.max ?? Number.POSITIVE_INFINITY)\n\t\tthis.#emitter = new Emitter<PoolEventMap>({ on: options?.on, error: options?.error })\n\t}\n\n\tget emitter(): EmitterInterface<PoolEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget size(): number {\n\t\treturn this.#idle.length + this.#active\n\t}\n\n\tget idle(): number {\n\t\treturn this.#idle.length\n\t}\n\n\tget active(): number {\n\t\treturn this.#active\n\t}\n\n\tasync acquire(signal?: AbortSignal): Promise<PoolToken<T>> {\n\t\tif (this.#destroyed) throw new Error('pool is destroyed')\n\t\tif (signal?.aborted === true) throw signal.reason\n\t\t// Reuse a validated idle resource if one is available.\n\t\tconst reused = await this.#reuse()\n\t\tif (reused !== undefined) {\n\t\t\t// Observe the lease — AFTER `#reuse` resolved the token (the resource is already\n\t\t\t// leased; emit only OBSERVES it).\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn reused\n\t\t}\n\t\t// Otherwise grow the pool when below the cap.\n\t\tif (this.size < this.#max) {\n\t\t\tconst grown = await this.#grow()\n\t\t\t// Observe the lease — AFTER `#grow` resolved the fresh token.\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn grown\n\t\t}\n\t\t// At capacity with nothing idle — park until a release hands us a resource. The\n\t\t// `acquire` for THIS lease is emitted by `#serve` once a `release` hands it a resource\n\t\t// (after `waiter.resolve`), NOT here — so a served waiter emits `acquire` exactly once.\n\t\treturn await this.#wait(signal)\n\t}\n\n\tasync clear(): Promise<void> {\n\t\tconst resources = this.#idle.splice(0)\n\t\tawait Promise.all(resources.map((resource) => this.#release(resource)))\n\t}\n\n\tasync destroy(): Promise<void> {\n\t\tif (this.#destroyed) return\n\t\tthis.#destroyed = true\n\t\tconst waiters = this.#waiters.splice(0)\n\t\tconst error = new Error('pool is destroyed')\n\t\tfor (const waiter of waiters) {\n\t\t\twaiter.clear()\n\t\t\twaiter.reject(error)\n\t\t}\n\t\tconst resources = this.#idle.splice(0)\n\t\tawait Promise.all(resources.map((resource) => this.#release(resource)))\n\t}\n\n\t// Take + validate the next idle resource; destroy + skip invalid ones. Returns a\n\t// token for the first valid idle resource, or `undefined` when none is usable.\n\tasync #reuse(): Promise<PoolToken<T> | undefined> {\n\t\twhile (this.#idle.length > 0) {\n\t\t\tconst resource = this.#idle.shift()\n\t\t\tif (resource === undefined) continue\n\t\t\tif (await this.#valid(resource)) {\n\t\t\t\tthis.#active += 1\n\t\t\t\treturn this.#token(resource)\n\t\t\t}\n\t\t\tawait this.#release(resource)\n\t\t}\n\t\treturn undefined\n\t}\n\n\t// Create a fresh resource and lease it. Reserve the active slot before awaiting\n\t// `create` so a concurrent acquire sees the pool at capacity (no overshoot of `max`).\n\tasync #grow(): Promise<PoolToken<T>> {\n\t\tthis.#active += 1\n\t\tlet resource: T\n\t\ttry {\n\t\t\tresource = await this.#create()\n\t\t} catch (error: unknown) {\n\t\t\tthis.#active -= 1\n\t\t\tthrow error instanceof Error ? error : new Error(String(error))\n\t\t}\n\t\t// The pool may have been destroyed during `create` — never hand a live resource into\n\t\t// a torn-down pool. Free the active slot, destroy the just-created resource, and throw.\n\t\tif (this.#destroyed) {\n\t\t\tthis.#active -= 1\n\t\t\tawait this.#release(resource)\n\t\t\tthrow new Error('pool is destroyed')\n\t\t}\n\t\t// Observe the fresh resource — AFTER `create` resolved and the not-destroyed re-check\n\t\t// passed (the resource is here to stay), BEFORE the token is built.\n\t\tthis.#emitter.emit('create')\n\t\treturn this.#token(resource)\n\t}\n\n\t// Park a resolver on the FIFO waiter list until a release hands it a resource; an\n\t// abort on `signal` rejects the acquire and removes its waiter (no leak).\n\t#wait(signal: AbortSignal | undefined): Promise<PoolToken<T>> {\n\t\treturn new Promise<PoolToken<T>>((resolve, reject) => {\n\t\t\tconst waiter: PoolWaiter<T> = { resolve, reject, clear: () => {} }\n\t\t\tthis.#waiters.push(waiter)\n\t\t\tif (signal !== undefined) {\n\t\t\t\tconst onAbort = (): void => {\n\t\t\t\t\tconst index = this.#waiters.indexOf(waiter)\n\t\t\t\t\tif (index >= 0) this.#waiters.splice(index, 1)\n\t\t\t\t\treject(signal.reason)\n\t\t\t\t}\n\t\t\t\tsignal.addEventListener('abort', onAbort, { once: true })\n\t\t\t\twaiter.clear = (): void => signal.removeEventListener('abort', onAbort)\n\t\t\t}\n\t\t})\n\t}\n\n\t// Build an idempotent token; its `release` returns the resource exactly once.\n\t#token(resource: T): PoolToken<T> {\n\t\tlet released = false\n\t\treturn {\n\t\t\tvalue: resource,\n\t\t\trelease: (): void => {\n\t\t\t\tif (released) return\n\t\t\t\treleased = true\n\t\t\t\tthis.#return(resource)\n\t\t\t},\n\t\t}\n\t}\n\n\t// Return a leased resource. No waiter parked → synchronously drop it to idle (or destroy\n\t// it if torn down), `#active -= 1`. A waiter IS parked → hand off asynchronously, after\n\t// re-validating the resource so an invalid one (e.g. a terminated thread) is never served.\n\t#return(resource: T): void {\n\t\tif (this.#waiters.length === 0) {\n\t\t\tthis.#active -= 1\n\t\t\tif (this.#destroyed) {\n\t\t\t\tvoid this.#release(resource)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tthis.#idle.push(resource)\n\t\t\t// Observe the resource dropping to idle — AFTER `#active` was balanced down and it\n\t\t\t// is back on the idle list (the synchronous no-waiter path). A waiter-handoff\n\t\t\t// instead keeps the resource LEASED, so it emits no `release` here.\n\t\t\tthis.#emitter.emit('release')\n\t\t\treturn\n\t\t}\n\t\tvoid this.#handoff(resource)\n\t}\n\n\t// Hand a released resource to the oldest parked waiter, re-validating it first. A VALID\n\t// resource is served as-is (it stays leased — `#active` unchanged). An INVALID one is\n\t// destroyed and the waiter is served a fresh resource that REUSES the dead one's `#active`\n\t// slot (the count never dips below the lease, so a concurrent acquire can't overshoot\n\t// `max`). The waiter is re-shifted after every `await` (the queue can change underneath\n\t// us), and the pool is re-checked for teardown — so no waiter is leaked or double-settled\n\t// and no resource is handed into a destroyed pool.\n\tasync #handoff(resource: T): Promise<void> {\n\t\t// VALID release → serve the released resource directly (the common, unchanged path).\n\t\tif (await this.#valid(resource)) {\n\t\t\tthis.#serve(resource)\n\t\t\treturn\n\t\t}\n\t\t// INVALID release → destroy it and replace it, holding its `#active` slot steady.\n\t\tvoid this.#release(resource)\n\t\tlet replacement: T\n\t\ttry {\n\t\t\treplacement = await this.#create()\n\t\t} catch (error: unknown) {\n\t\t\t// The dead resource cannot be replaced — free its slot and reject the oldest waiter\n\t\t\t// (it can't be served), or drop the error if the queue raced empty.\n\t\t\tthis.#active -= 1\n\t\t\tconst waiter = this.#waiters.shift()\n\t\t\twaiter?.clear()\n\t\t\twaiter?.reject(error instanceof Error ? error : new Error(String(error)))\n\t\t\treturn\n\t\t}\n\t\t// Observe the fresh replacement — AFTER `create` resolved, BEFORE it is served.\n\t\tthis.#emitter.emit('create')\n\t\tthis.#serve(replacement)\n\t}\n\n\t// Hand a validated resource (the released one, or its fresh replacement) to the oldest\n\t// live waiter, holding its `#active` slot. If the queue raced empty across the awaits, the\n\t// resource is idle (or destroyed when torn down) and its slot is freed.\n\t#serve(resource: T): void {\n\t\tconst waiter = this.#destroyed ? undefined : this.#waiters.shift()\n\t\tif (waiter !== undefined) {\n\t\t\twaiter.clear()\n\t\t\twaiter.resolve(this.#token(resource))\n\t\t\t// Observe the served-waiter lease — strictly AFTER `waiter.resolve(...)` (the token\n\t\t\t// is already handed off; the emit only OBSERVES it and cannot sit across the resolve\n\t\t\t// or perturb the served acquirer's continuation). This is the `acquire` for a parked\n\t\t\t// `acquire`, so the public `acquire` deliberately does NOT emit on its `#wait` branch.\n\t\t\tthis.#emitter.emit('acquire')\n\t\t\treturn\n\t\t}\n\t\tthis.#active -= 1\n\t\tif (this.#destroyed) {\n\t\t\tvoid this.#release(resource)\n\t\t\treturn\n\t\t}\n\t\tthis.#idle.push(resource)\n\t\t// The waiter queue raced empty across the handoff awaits — the resource lands back on\n\t\t// idle instead of being leased. Observe that as a `release` (the return-to-idle that\n\t\t// `#return` would have emitted had no waiter been parked when the token was released).\n\t\tthis.#emitter.emit('release')\n\t}\n\n\t// Is this resource usable? No validator trusts it; otherwise run the hook. A validator\n\t// that THROWS is treated exactly like one returning `false` — the resource is \"not\n\t// usable\", so it is destroyed + replaced rather than escaping as an unhandled rejection\n\t// that would strand a parked waiter on the handoff path (the same total-function spirit\n\t// as a guard, AGENTS §12 / §14). The single gate for both the idle (`#reuse`) and the\n\t// handoff (`#handoff`) validation, so the two paths can never diverge.\n\tasync #valid(resource: T): Promise<boolean> {\n\t\tif (this.#validate === undefined) return true\n\t\ttry {\n\t\t\treturn await this.#validate(resource)\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\t// Destroy one resource via the optional hook, swallowing destruction failures. Observe the\n\t// drop with a `destroy` event AFTER the hook ran (or after the no-hook drop) — the resource\n\t// is gone from the pool either way; a swallowed `destroy`-hook failure still emits (the pool\n\t// abandoned it). The emit is the LAST thing here, strictly after the teardown transition.\n\tasync #release(resource: T): Promise<void> {\n\t\tif (this.#destroy === undefined) {\n\t\t\tthis.#emitter.emit('destroy')\n\t\t\treturn\n\t\t}\n\t\ttry {\n\t\t\tawait this.#destroy(resource)\n\t\t} catch {\n\t\t\t// A destroy failure abandons the resource — there is nothing to recover.\n\t\t}\n\t\tthis.#emitter.emit('destroy')\n\t}\n}\n","import type { PoolInterface, PoolOptions } from './types.js'\nimport { Pool } from './Pool.js'\n\n/**\n * Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a\n * resource (reusing a validated idle one, growing up to `max`, or parking until a\n * `release` frees one) and the returned token's `release` returns it for reuse.\n *\n * @remarks\n * A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal\n * fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);\n * `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),\n * no eviction timers — and observable (§13): a typed `emitter` surfaces\n * `create` / `acquire` / `release` / `destroy`.\n *\n * @typeParam T - The pooled resource type\n * @param options - The `create` hook plus optional `destroy` / `validate` / `max`\n * @returns A working {@link PoolInterface}\n *\n * @example\n * ```ts\n * import { createPool } from '@src/core'\n *\n * const pool = createPool<Connection>({\n * \tcreate: () => connect(),\n * \tdestroy: (connection) => connection.close(),\n * \tvalidate: (connection) => connection.alive,\n * \tmax: 8,\n * })\n *\n * const token = await pool.acquire()\n * try {\n * \tawait token.value.query('select 1')\n * } finally {\n * \ttoken.release()\n * }\n * ```\n */\nexport function createPool<T>(options: PoolOptions<T>): PoolInterface<T> {\n\treturn new Pool(options)\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,81 @@
+{
+	"name": "@orkestrel/pool",
+	"version": "0.0.1",
+	"description": "A bounded, typed resource pool — idle reuse, max backpressure, FIFO abort-cancellable waiting, and an observable lifecycle emitter. Part of the @orkestrel line.",
+	"keywords": [
+		"connection-pool",
+		"fifo",
+		"pool",
+		"resource-pool",
+		"typescript"
+	],
+	"homepage": "https://github.com/orkestrel/pool#readme",
+	"bugs": "https://github.com/orkestrel/pool/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/orkestrel/pool.git"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/src/core/index.cjs",
+	"module": "./dist/src/core/index.js",
+	"types": "./dist/src/core/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/src/core/index.d.ts",
+				"default": "./dist/src/core/index.js"
+			},
+			"require": {
+				"types": "./dist/src/core/index.d.cts",
+				"default": "./dist/src/core/index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
+		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"check": "tsc --noEmit --project tsconfig.json",
+		"check:src": "npm run check:src:core",
+		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
+		"format": "oxfmt --config .oxfmtrc.json --write .",
+		"format:check": "oxfmt --config .oxfmtrc.json --check .",
+		"lint:check": "oxlint --config .oxlintrc.json .",
+		"test": "npm run test:src && npm run test:guides",
+		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
+		"build": "npm run clean && npm run build:src",
+		"build:src": "npm run build:src:core",
+		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check:src && npm run build && npm test"
+	},
+	"dependencies": {
+		"@orkestrel/emitter": "^0.0.1"
+	},
+	"devDependencies": {
+		"@microsoft/api-extractor": "^7.58.9",
+		"@orkestrel/guide": "^0.0.1",
+		"@types/node": "^26.1.1",
+		"oxfmt": "^0.58.0",
+		"oxlint": "^1.73.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.4",
+		"vite-plugin-dts": "^5.0.3",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=24"
+	}
+}