@orkestrel/pool 0.0.13 → 0.0.14

package/README.md

@@ -1,8 +1,7 @@
 # @orkestrel/pool
 
-> A typed resource pool with optional bounded capacity, unique ownership, FIFO settlement,
-> validated reuse, caller-owned cancellation, explicit cleanup failures, and a stable
-> event-driven teardown barrier.
+> A typed resource pool with optional bounded capacity, a warm floor, bounded loss recovery,
+> unique ownership, FIFO settlement, validated reuse, caller-owned cancellation, and explicit cleanup.
 
 Create a pool with the `createPool` function, hand it the hooks that make, check, and tear
 down one resource, and `await pool.acquire()` wherever the work needs one. Release the token
@@ -10,6 +9,12 @@ in a `finally` block, and `await pool.destroy()` when the process is done with t
 Environment-agnostic — no I/O, no browser or server assumptions. Part of the `@orkestrel`
 line.
 
+For eager resources, set `min` and the required `restarts` bound on failed refills and losses
+of never-leased records between strike resets, then call `start()`.
+The `watch(value, signal)` hook reports loss; a holder can also call its token's `destroy()`.
+The pool disposes lost records before replacing them and keeps a record whose cleanup fails
+counted against `max`.
+
 ## Install
 
 ```sh

package/dist/src/core/index.cjs

@@ -95,9 +95,9 @@ function isPoolSignal(value) {
 //#endregion
 //#region src/core/Pool.ts
 /**
-* Represents a capacity-aware resource pool whose opaque ownership records preserve FIFO
-* settlement, cancellation, exact lease release, and deterministic teardown under concurrent
-* hooks.
+* Represents a resource pool with optional bounded capacity and a warm floor, whose opaque
+* ownership records preserve FIFO settlement, cancellation, exact lease release, and
+* deterministic teardown under concurrent hooks.
 *
 * @typeParam T - The pooled resource value
 *
@@ -120,6 +120,15 @@ var Pool = class {
 	#destroy;
 	#validate;
 	#max;
+	#min;
+	#restarts;
+	#watch;
+	#error;
+	#watches = /* @__PURE__ */ new Map();
+	#used = /* @__PURE__ */ new WeakSet();
+	#settled = /* @__PURE__ */ new WeakSet();
+	#survivors = /* @__PURE__ */ new Map();
+	#owing = /* @__PURE__ */ new Set();
 	#emitter;
 	#resources = /* @__PURE__ */ new Map();
 	#available = [];
@@ -137,25 +146,51 @@ var Pool = class {
 	#ending;
 	#pumping = false;
 	#repump = false;
+	#started = false;
+	#starting;
+	#refilling = false;
+	#strikes = 0;
+	#owed = 0;
+	#cause;
 	/**
 	* Constructs a pool and synchronously validates its capacity contract.
 	*
-	* @param options - Resource hooks, observation hooks, and optional positive safe `max`
-	* @throws {@link PoolError} Thrown when `options.max` is present and is not a positive safe
-	* integer, with `code: 'invalid'`.
+	* @param options - Resource hooks, observation hooks, capacity, and optional bounded warm floor
+	* @throws {@link PoolError} Thrown with `code: 'invalid'` when `min` or `max` is not a positive
+	* safe integer, their explicit values differ, `restarts` is absent with `min`, present without
+	* `min`, or not a non-negative safe integer, or `watch` is not callable.
 	*/
 	constructor(options) {
 		const max = options.max;
+		const min = options.min;
+		const restarts = options.restarts;
+		const watch = options.watch;
 		if (max !== void 0 && !isPoolMax(max)) throw new PoolError({
 			code: "invalid",
 			context: { value: max }
 		});
+		if (min !== void 0 && (!isPoolMax(min) || max !== void 0 && min !== max)) throw new PoolError({
+			code: "invalid",
+			context: { value: min }
+		});
+		if (min !== void 0 && restarts === void 0 || restarts !== void 0 && (min === void 0 || !(0, _orkestrel_contract.isNumber)(restarts) || !Number.isSafeInteger(restarts) || restarts < 0)) throw new PoolError({
+			code: "invalid",
+			context: { value: restarts }
+		});
+		if (watch !== void 0 && !(0, _orkestrel_contract.isFunction)(watch)) throw new PoolError({
+			code: "invalid",
+			context: { value: watch }
+		});
 		const on = options.on;
 		const error = options.error;
 		this.#create = options.create;
 		this.#destroy = options.destroy;
 		this.#validate = options.validate;
-		this.#max = max;
+		this.#max = max ?? min;
+		this.#min = min;
+		this.#restarts = restarts;
+		this.#watch = watch;
+		this.#error = error;
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			...on === void 0 ? {} : { on },
 			...error === void 0 ? {} : { error }
@@ -165,7 +200,7 @@ var Pool = class {
 	get emitter() {
 		return this.#emitter;
 	}
-	/** Counts all owned records, including records validating or destroying. */
+	/** Counts all owned records, including records validating, destroying, or retained after failed cleanup. */
 	get size() {
 		return this.#resources.size;
 	}
@@ -178,7 +213,27 @@ var Pool = class {
 		return this.#leased.size;
 	}
 	/**
-	* Queues and leases one resource in FIFO settlement order.
+	* Fills the warm floor and resets the strikes of a spent floor; without a floor, resolves immediately.
+	*
+	* @returns A promise that resolves when the floor owns `min` live records
+	* @throws {@link PoolError} Thrown as a rejection with `code: 'create'` and the last cause
+	* when the bound is spent, `code: 'cleanup'` when retained failed cleanup prevents filling,
+	* or `code: 'destroyed'` when teardown begins.
+	*/
+	start() {
+		if (this.#ending !== void 0) return Promise.reject(new PoolError({ code: "destroyed" }));
+		if (this.#min === void 0) return Promise.resolve();
+		if (this.#starting !== void 0) return this.#starting.promise;
+		const starting = Promise.withResolvers();
+		this.#starting = starting;
+		this.#started = true;
+		if (this.#spent()) this.#strikes = 0;
+		this.#pump();
+		return starting.promise;
+	}
+	/**
+	* Queues the caller in FIFO order, validates an idle record or waits for a floor refill, and
+	* creates on demand only without a floor.
 	*
 	* @param signal - Optional native cancellation signal
 	* @returns A promise for the unique resource lease
@@ -186,9 +241,11 @@ var Pool = class {
 	* with `code: 'invalid'`. This throw is synchronous rather than a rejected promise, so a caller
 	* that handles failures with `.catch()` alone misses it.
 	* @throws {@link PoolError} Thrown as a rejection when `destroy()` has already begun, with
-	* `code: 'destroyed'`; when the create hook fails, with `code: 'create'` and the hook's thrown
-	* value as `cause`; and when an invalid record's cleanup fails, with `code: 'cleanup'`. A
-	* `signal` that aborts rejects with the caller's exact `signal.reason` instead.
+	* `code: 'destroyed'`; when the create hook fails or the floor is spent without an idle record,
+	* with `code: 'create'` and the last cause; and when an invalid record's cleanup fails or
+	* a floor retains a record, owns `min` records, has nothing idle, and has no refill or disposal
+	* pending, even with live leases, with `code: 'cleanup'` and the retained cleanup failure as cause.
+	* A `signal` that aborts rejects with the caller's exact `signal.reason` instead.
 	*/
 	acquire(signal) {
 		if (signal !== void 0 && !isPoolSignal(signal)) throw new PoolError({
@@ -216,7 +273,7 @@ var Pool = class {
 		return waiter.promise;
 	}
 	/**
-	* Destroys the records that are idle at this call's synchronous snapshot.
+	* Destroys the records that are idle at this call's synchronous snapshot and restores a started floor.
 	*
 	* @returns A promise that settles after every snapshot cleanup attempt
 	* @throws {@link PoolError} Thrown when `destroy()` has already begun, with `code: 'destroyed'`.
@@ -239,7 +296,7 @@ var Pool = class {
 	* Tears down the pool permanently and returns its stable completion barrier.
 	*
 	* @returns The exact promise shared by every destroy call
-	* @throws {@link PoolError} Thrown when a destroy hook failed during teardown, with
+	* @throws {@link PoolError} Thrown when a destroy hook failure was retained or occurred during teardown, with
 	* `code: 'cleanup'` and every distinct failure in `context.failures`. The barrier rejects; it
 	* never throws synchronously, and a repeat call receives the same rejected promise.
 	*/
@@ -247,6 +304,8 @@ var Pool = class {
 		if (this.#ending !== void 0) return this.#ending.promise;
 		const ending = Promise.withResolvers();
 		this.#ending = ending;
+		this.#starting?.reject(new PoolError({ code: "destroyed" }));
+		this.#starting = void 0;
 		const waiters = this.#waiters.splice(0);
 		for (const waiter of waiters) {
 			this.#detach(waiter);
@@ -289,18 +348,31 @@ var Pool = class {
 			});
 		}
 	}
-	#createRelease(record) {
-		let released = false;
+	#token(record, value) {
+		const lease = {};
+		return {
+			value,
+			release: this.#createRelease(record, lease),
+			destroy: this.#createDestroy(record, lease)
+		};
+	}
+	#createRelease(record, lease) {
 		return () => {
-			if (released) return;
-			released = true;
+			if (this.#settled.has(lease)) return;
+			this.#settled.add(lease);
 			this.#release(record);
 		};
 	}
-	#token(record, value) {
-		return {
-			value,
-			release: this.#createRelease(record)
+	#createDestroy(record, lease) {
+		return () => {
+			if (this.#settled.has(lease)) return Promise.resolve();
+			this.#settled.add(lease);
+			return (this.#destroying.get(record) ?? this.#lose(record)).catch((error) => {
+				throw new PoolError({
+					code: "cleanup",
+					cause: error
+				});
+			});
 		};
 	}
 	#abort(waiter, reason) {
@@ -340,6 +412,30 @@ var Pool = class {
 					this.#startValidation(waiter, record);
 					continue;
 				}
+				if (this.#min !== void 0) {
+					if (!this.#refilling && this.#destroying.size === 0 && this.#resources.size >= this.#min && this.#survivors.size > 0) {
+						this.#ready.set(waiter, {
+							success: false,
+							error: new PoolError({
+								code: "cleanup",
+								cause: this.#survivors.values().next().value,
+								context: { failures: [...this.#failures] }
+							})
+						});
+						continue;
+					}
+					if (this.#spent() && !this.#refilling && this.#destroying.size === 0 && this.#owed === 0) {
+						this.#ready.set(waiter, {
+							success: false,
+							error: new PoolError({
+								code: "create",
+								cause: this.#cause
+							})
+						});
+						continue;
+					}
+					break;
+				}
 				if (this.#max === void 0 || this.#resources.size + this.#reservations.size < this.#max) {
 					this.#assigned.add(waiter);
 					this.#reservations.add(waiter);
@@ -348,8 +444,87 @@ var Pool = class {
 				}
 				break;
 			}
+			this.#commit();
 		} while (this.#repump);
 		this.#pumping = false;
+		this.#fill();
+	}
+	#spent() {
+		return this.#restarts !== void 0 && this.#strikes > this.#restarts;
+	}
+	#fill() {
+		if (this.#ending !== void 0 || !this.#started || this.#min === void 0) return;
+		if (this.#refilling) return;
+		if (this.#resources.size - this.#destroying.size - this.#survivors.size >= this.#min) {
+			this.#starting?.resolve();
+			this.#starting = void 0;
+		}
+		if (this.#resources.size < this.#min && (!this.#spent() || this.#owed > 0)) {
+			if (this.#owed > 0) this.#owed -= 1;
+			this.#refilling = true;
+			const operation = Promise.resolve().then(() => this.#refill());
+			this.#operations.add(operation);
+			operation.then(() => {
+				this.#refilling = false;
+				this.#completeOperation(operation);
+			});
+			return;
+		}
+		if (this.#destroying.size > 0) return;
+		if (this.#spent() || this.#survivors.size > 0) {
+			this.#starting?.reject(this.#spent() ? new PoolError({
+				code: "create",
+				cause: this.#cause
+			}) : this.#cleanupError(this.#failures));
+			this.#starting = void 0;
+		}
+	}
+	async #refill() {
+		if (this.#ending !== void 0) return;
+		let value;
+		try {
+			value = await this.#create();
+		} catch (error) {
+			this.#strikes += 1;
+			this.#cause = error;
+			return;
+		}
+		const record = this.#insert(value);
+		this.#recycle(record);
+	}
+	#insert(value) {
+		const record = {};
+		this.#resources.set(record, value);
+		if (this.#watch !== void 0) {
+			const controller = new AbortController();
+			this.#watches.set(record, controller);
+			const watching = (0, _orkestrel_contract.attempt)(() => this.#watch?.(value, controller.signal));
+			(watching.success ? Promise.resolve(watching.value) : Promise.reject(watching.error)).then(() => this.#own(this.#lose(record)), (error) => {
+				if (controller.signal.aborted) return;
+				this.#own(this.#lose(record, error));
+				(0, _orkestrel_contract.attempt)(() => this.#error?.(error, "watch"));
+			});
+		}
+		this.#emitter.emit("create");
+		return record;
+	}
+	async #lose(record, cause) {
+		if (this.#ending !== void 0 || !this.#resources.has(record) || this.#destroying.has(record) || this.#survivors.has(record)) return;
+		if (this.#leased.has(record) && this.#min !== void 0) this.#owing.add(record);
+		this.#strike(record, cause);
+		try {
+			await this.#dispose(record);
+		} catch (error) {
+			this.#pump();
+			throw error;
+		}
+		this.#pump();
+	}
+	#strike(record, cause) {
+		if (this.#min !== void 0 && !this.#used.has(record)) {
+			this.#strikes += 1;
+			this.#cause = cause;
+		}
 	}
 	#startCreate(waiter) {
 		const operation = Promise.resolve().then(() => this.#createResource(waiter));
@@ -391,9 +566,7 @@ var Pool = class {
 			return;
 		}
 		this.#reservations.delete(waiter);
-		const record = {};
-		this.#resources.set(record, value);
-		this.#emitter.emit("create");
+		const record = this.#insert(value);
 		if (this.#ending !== void 0) {
 			this.#assigned.delete(waiter);
 			try {
@@ -419,6 +592,11 @@ var Pool = class {
 			valid = await this.#validate?.(value) === true;
 		} catch {}
 		this.#validating.delete(record);
+		if (!this.#resources.has(record) || this.#destroying.has(record) || this.#survivors.has(record)) {
+			this.#assigned.delete(waiter);
+			this.#pump();
+			return;
+		}
 		if (this.#ending !== void 0) {
 			this.#assigned.delete(waiter);
 			try {
@@ -426,6 +604,7 @@ var Pool = class {
 			} catch {}
 			return;
 		}
+		if (!valid) this.#strike(record);
 		if (!this.#waiters.includes(waiter)) {
 			this.#assigned.delete(waiter);
 			if (valid) this.#recycle(record);
@@ -481,6 +660,12 @@ var Pool = class {
 			if (waiter === void 0) return;
 			const result = this.#ready.get(waiter);
 			if (result === void 0) return;
+			if (result.success && (!this.#resources.has(result.record) || this.#destroying.has(result.record) || this.#survivors.has(result.record))) {
+				this.#ready.delete(waiter);
+				this.#assigned.delete(waiter);
+				this.#repump = true;
+				return;
+			}
 			this.#waiters.shift();
 			this.#repump = true;
 			this.#ready.delete(waiter);
@@ -491,6 +676,8 @@ var Pool = class {
 				continue;
 			}
 			this.#leased.add(result.record);
+			this.#used.add(result.record);
+			this.#strikes = 0;
 			waiter.resolve(result.token);
 			this.#emitter.emit("acquire");
 		}
@@ -521,6 +708,7 @@ var Pool = class {
 		this.#recycle(record);
 	}
 	#recycle(record) {
+		if (!this.#resources.has(record) || this.#destroying.has(record) || this.#survivors.has(record)) return;
 		if (this.#ending !== void 0) {
 			this.#own(this.#dispose(record));
 			return;
@@ -530,6 +718,7 @@ var Pool = class {
 		if (this.#available.includes(record)) this.#emitter.emit("release");
 	}
 	#dispose(record) {
+		if (this.#survivors.has(record)) return Promise.resolve();
 		const existing = this.#destroying.get(record);
 		if (existing !== void 0) return existing;
 		for (const [owned, value] of this.#resources) {
@@ -540,6 +729,8 @@ var Pool = class {
 			if (index >= 0) this.#available.splice(index, 1);
 			this.#validating.delete(record);
 			this.#leased.delete(record);
+			this.#watches.get(record)?.abort();
+			this.#watches.delete(record);
 			if (this.#ending !== void 0) this.#own(cleanup.promise);
 			this.#clean(record, value, cleanup);
 			return cleanup.promise;
@@ -547,26 +738,34 @@ var Pool = class {
 		return Promise.resolve();
 	}
 	async #clean(record, value, cleanup) {
-		let attempt;
+		let disposal;
 		try {
-			attempt = Promise.resolve(this.#destroy?.(value));
+			disposal = Promise.resolve(this.#destroy?.(value));
 		} catch (error) {
-			attempt = Promise.reject(error);
+			disposal = Promise.reject(error);
 		}
 		let failure;
 		let failed = false;
 		try {
-			await attempt;
+			await disposal;
 		} catch (error) {
 			failure = error;
 			failed = true;
 		}
-		this.#resources.delete(record);
+		if (failed && this.#min !== void 0) {
+			this.#survivors.set(record, failure);
+			this.#record(failure);
+		} else {
+			this.#resources.delete(record);
+			if (this.#owing.has(record)) this.#owed += 1;
+		}
+		this.#owing.delete(record);
 		if (failed) cleanup.reject(failure);
 		else cleanup.resolve();
 		await Promise.resolve();
 		this.#emitter.emit("destroy");
 		this.#destroying.delete(record);
+		if (this.#min !== void 0) this.#pump();
 		this.#finish();
 	}
 	async #settleClear(cleanups) {
@@ -604,11 +803,11 @@ var Pool = class {
 		if (ending === void 0 || this.#operations.size > 0 || this.#owned.size > 0) return;
 		let claimed = false;
 		for (const record of this.#resources.keys()) {
-			if (this.#validating.has(record) || this.#destroying.has(record)) continue;
+			if (this.#validating.has(record) || this.#destroying.has(record) || this.#survivors.has(record)) continue;
 			claimed = true;
 			this.#own(this.#dispose(record));
 		}
-		if (claimed || this.#resources.size > 0 || this.#destroying.size > 0) return;
+		if (claimed || this.#resources.size > this.#survivors.size || this.#destroying.size > 0) return;
 		this.#emitter.destroy();
 		if (this.#failures.length > 0) ending.reject(this.#cleanupError(this.#failures));
 		else ending.resolve();
@@ -625,12 +824,15 @@ var Pool = class {
 * request order. `clear` owns its idle snapshot; `destroy` returns one stable barrier and
 * waits for every in-flight create, validation, and destroy attempt before destroying the
 * emitter last.
+* Set `min` with its required `restarts` bound and call `start()` to warm resources and
+* refill losses independently of queued acquires. `watch` observes loss and its signal
+* aborts at disposal; a token can declare loss through `destroy()`.
 *
 * @typeParam T - The pooled resource type
-* @param options - Lifecycle hooks, optional positive safe `max`, and observation hooks
+* @param options - Lifecycle hooks, capacity, optional bounded warm floor, and observation hooks
 * @returns A working {@link PoolInterface}
-* @throws {@link PoolError} Thrown when `options.max` is present and is not a positive safe
-* integer, with `code: 'invalid'`. Construction validates it synchronously, before the pool exists.
+* @throws {@link PoolError} Thrown with `code: 'invalid'` when capacity, restart bounds, or
+* the watch hook are invalid. Construction validates them synchronously, before the pool exists.
 *
 * @example Create a pool
 * ```ts