@orkestrel/pool 0.0.3 → 0.0.5

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

@@ -3,24 +3,20 @@ 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.
+ * Create a resource pool with optional bounded capacity, unique ownership, and FIFO settlement.
  *
  * @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`.
+ * Concurrent create and validation hooks may overlap, while acquire promises settle in
+ * request order. `clear` owns its idle snapshot; `destroy` returns one stable barrier and
+ * waits for every in-flight hook and cleanup before destroying the emitter last.
  *
  * @typeParam T - The pooled resource type
- * @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+ * @param options - Lifecycle hooks, optional positive safe `max`, and observation hooks
  * @returns A working {@link PoolInterface}
  *
  * @example
  * ```ts
- * import { createPool } from '@src/core'
+ * import { createPool } from '@orkestrel/pool'
  *
  * const pool = createPool<Connection>({
  * 	create: () => connect(),
@@ -40,120 +36,206 @@ import { EmitterInterface } from '@orkestrel/emitter';
 export declare function createPool<T>(options: PoolOptions<T>): PoolInterface<T>;
 
 /**
- * A bounded resource pool with idle reuse + FIFO waiting.
+ * Test whether an unknown value is a {@link PoolError}, returning `false` for hostile proxies.
  *
- * @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.
+ * @param value - The unknown boundary value
+ * @returns Whether the value is a real `PoolError` instance
+ *
+ * @example
+ * ```ts
+ * isPoolError(new PoolError({ code: 'destroyed' })) // true
+ * isPoolError(new Error('other')) // false
+ * ```
+ */
+export declare function isPoolError(value: unknown): value is PoolError;
+
+/**
+ * Test whether a value is a valid finite pool maximum.
+ *
+ * @param value - The unknown maximum candidate
+ * @returns Whether the value is a positive safe integer
+ *
+ * @example
+ * ```ts
+ * isPoolMax(8) // true
+ * isPoolMax(Infinity) // false
+ * ```
+ */
+export declare function isPoolMax(value: unknown): value is number;
+
+/**
+ * Test whether a value is a native `AbortSignal`, returning `false` for hostile proxies.
+ *
+ * @param value - The unknown signal candidate
+ * @returns Whether the value is a native `AbortSignal`
+ *
+ * @example
+ * ```ts
+ * isPoolSignal(new AbortController().signal) // true
+ * isPoolSignal({ aborted: false }) // false
+ * ```
+ */
+export declare function isPoolSignal(value: unknown): value is AbortSignal;
+
+/**
+ * A capacity-aware resource pool whose opaque ownership records preserve FIFO settlement,
+ * cancellation, exact lease release, and deterministic teardown under concurrent hooks.
+ *
+ * @typeParam T - The pooled resource value
+ *
+ * @example
+ * ```ts
+ * import { Pool } from '@orkestrel/pool'
+ *
+ * const pool = new Pool({ create: () => new Uint8Array(64), max: 2 })
+ * const token = await pool.acquire()
+ * try {
+ * 	consume(token.value)
+ * } finally {
+ * 	token.release()
+ * }
+ * await pool.destroy()
+ * ```
  */
 export declare class Pool<T> implements PoolInterface<T> {
     #private;
+    /**
+     * Construct a pool and synchronously validate its capacity contract.
+     *
+     * @param options - Resource hooks, observation hooks, and optional positive safe `max`
+     */
     constructor(options: PoolOptions<T>);
+    /** The typed synchronous lifecycle observation surface. */
     get emitter(): EmitterInterface<PoolEventMap>;
+    /** All owned records, including records validating or destroying. */
     get size(): number;
+    /** Records immediately available without validation work. */
     get idle(): number;
+    /** Records represented by unsettled released-once lease tokens. */
     get active(): number;
+    /**
+     * Queue and lease one resource in FIFO settlement order.
+     *
+     * @param signal - Optional native cancellation signal
+     * @returns A promise for the unique resource lease
+     */
     acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    /**
+     * Destroy the records that are idle at this call's synchronous snapshot.
+     *
+     * @returns A promise that settles after every snapshot cleanup attempt
+     */
     clear(): Promise<void>;
+    /**
+     * Permanently tear down the pool and return its stable completion barrier.
+     *
+     * @returns The exact promise shared by every destroy call
+     */
     destroy(): Promise<void>;
 }
 
+/** Machine-readable failure codes produced by {@link PoolError}. */
+export declare type PoolCode = 'invalid' | 'destroyed' | 'create' | 'cleanup';
+
+/** Structured context attached to a {@link PoolError}. */
+export declare interface PoolContext {
+    /** The rejected public input, when the failure is an input-validation error. */
+    readonly value?: unknown;
+    /** Distinct cleanup failures collected by `clear()` or `destroy()`. */
+    readonly failures?: readonly unknown[];
+}
+
 /**
- * The push observation surface of a {@link PoolInterface} (AGENTS §13) — the resource
- * lifecycle moments a fire-and-forget observer subscribes to.
+ * A stable, machine-readable pool failure with the original cause and structured context.
  *
- * @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).
+ * @example
+ * ```ts
+ * import { PoolError, isPoolError } from '@orkestrel/pool'
+ *
+ * try {
+ * 	await pool.acquire()
+ * } catch (error: unknown) {
+ * 	if (isPoolError(error)) console.error(error.code, error.cause)
+ * }
+ * ```
  */
+export declare class PoolError extends Error {
+    /** Stable machine-readable failure category. */
+    readonly code: PoolCode;
+    /** Optional structured input or aggregate-cleanup details. */
+    readonly context: PoolContext | undefined;
+    /**
+     * Create a pool failure without coercing a hostile thrown value.
+     *
+     * @param options - Stable code plus optional cause and structured context
+     */
+    constructor(options: PoolErrorOptions);
+}
+
+/** Construction options for {@link PoolError}. */
+export declare interface PoolErrorOptions {
+    /** The stable machine-readable failure category. */
+    readonly code: PoolCode;
+    /** The original thrown value, retained without unsafe string coercion. */
+    readonly cause?: unknown;
+    /** Optional structured failure details. */
+    readonly context?: PoolContext;
+}
+
+/** Observable resource lifecycle events emitted by a {@link PoolInterface}. */
 export declare type PoolEventMap = {
-    /** A fresh resource was created (`create` resolved) and leased. */
+    /** A created resource entered pool ownership. */
     readonly create: readonly [];
-    /** A token was handed to a lessee (a reused idle one, a fresh one, or a served waiter). */
+    /** A token settled successfully and its exact resource became leased. */
     readonly acquire: readonly [];
-    /** A leased resource returned to idle (no waiter was parked). */
+    /** A released resource became immediately idle. */
     readonly release: readonly [];
-    /** A resource was destroyed (`clear` / `destroy`, or a failed `validate`). */
+    /** A resource cleanup hook completed or was attempted when absent. */
     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.
- */
+/** A FIFO resource pool with optional bounded capacity and deterministic teardown. */
 export declare interface PoolInterface<T> {
+    /** The typed synchronous lifecycle observation surface. */
     readonly emitter: EmitterInterface<PoolEventMap>;
+    /** All owned records, including records validating or destroying. */
     readonly size: number;
+    /** Records immediately available without validation work. */
     readonly idle: number;
+    /** Records represented by unsettled released-once lease tokens. */
     readonly active: number;
+    /**
+     * Queue and lease one resource in FIFO settlement order.
+     *
+     * @param signal - Optional native cancellation signal
+     * @returns A promise for the unique resource lease
+     */
     acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+    /**
+     * Destroy the records that are idle at this call's synchronous snapshot.
+     *
+     * @returns A promise that settles after every snapshot cleanup attempt
+     */
     clear(): Promise<void>;
+    /**
+     * Permanently tear down the pool and return its stable completion barrier.
+     *
+     * @returns The exact promise shared by every destroy call
+     */
     destroy(): Promise<void>;
 }
 
 /**
- * Options for `createPool` — the resource lifecycle hooks.
+ * Resource lifecycle options for {@link Pool} and `createPool`.
  *
  * @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() }`).
+ * `create` lazily produces resources. `destroy` tears down a claimed resource.
+ * `validate` checks a previously owned resource before reuse. `max` is a positive
+ * safe integer; omission is the only unbounded form. `on` installs initial emitter
+ * listeners and `error` receives isolated listener failures.
  */
 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;
@@ -161,34 +243,12 @@ export declare interface PoolOptions<T> {
     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).
- */
+/** A unique lease over one pool-owned resource record. */
 export declare interface PoolToken<T> {
-    /** The leased resource. */
+    /** The leased value. Duplicate values still belong to independent records. */
     readonly value: T;
-    /** Return the resource to the pool; calling more than once is a no-op. */
+    /** Return this exact lease once; subsequent calls are no-ops. */
     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 { }