@orkestrel/pool 0.0.9 → 0.0.11

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

@@ -1,254 +1,312 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * Create a resource pool with optional bounded capacity, unique ownership, and FIFO settlement.
+ * Creates a distinct {@link PoolInterface} from resource lifecycle hooks, with optional bounded
+ * capacity, unique ownership, and FIFO settlement.
  *
  * @remarks
  * 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.
+ * waits for every in-flight create, validation, and destroy attempt before destroying the
+ * emitter last.
  *
  * @typeParam T - The pooled resource type
  * @param options - Lifecycle hooks, optional positive safe `max`, and observation hooks
  * @returns A working {@link PoolInterface}
- *
- * @example
- * ```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()
- * }
- * ```
- */
-export declare function createPool<T>(options: PoolOptions<T>): PoolInterface<T>;
-
-/**
- * Test whether an unknown value is a {@link PoolError}, returning `false` for hostile proxies.
- *
- * @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.
+ * @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.
      *
-     * @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.
+     * @example Create a pool
+     * ```ts
+     * import { createPool } from '@orkestrel/pool'
      *
-     * @returns A promise that settles after every snapshot cleanup attempt
-     */
-    clear(): Promise<void>;
-    /**
-     * Permanently tear down the pool and return its stable completion barrier.
+     * const pool = createPool<Connection>({
+     * 	create: () => connect(),
+     * 	destroy: (connection) => connection.close(),
+     * 	validate: (connection) => connection.alive,
+     * 	max: 8,
+     * })
      *
-     * @returns The exact promise shared by every destroy call
+     * const token = await pool.acquire()
+     * try {
+     * 	await token.value.query('select 1')
+     * } finally {
+     * 	token.release()
+     * }
+     * ```
      */
-    destroy(): Promise<void>;
-}
+ export declare function createPool<T>(options: PoolOptions<T>): PoolInterface<T>;
 
-/** Machine-readable failure codes produced by {@link PoolError}. */
-export declare type PoolCode = 'invalid' | 'destroyed' | 'create' | 'cleanup';
+ /**
+  * Tests whether an unknown value is a {@link PoolError}, returning `false` for hostile proxies.
+  *
+  * @param value - The unknown boundary value
+  * @returns True if the value is a real `PoolError` instance; false otherwise
+  *
+  * @example
+  * ```ts
+  * isPoolError(new PoolError({ code: 'destroyed' })) // true
+  * isPoolError(new Error('other')) // false
+  * ```
+  */
+ export declare function isPoolError(value: unknown): value is PoolError;
 
-/** 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[];
-}
+ /**
+  * Tests whether a value is a positive safe integer, the only valid explicit pool maximum.
+  *
+  * @param value - The unknown maximum candidate
+  * @returns True if the value is a positive safe integer; false otherwise
+  *
+  * @example
+  * ```ts
+  * isPoolMax(8) // true
+  * isPoolMax(Infinity) // false
+  * ```
+  */
+ export declare function isPoolMax(value: unknown): value is number;
 
-/**
- * A stable, machine-readable pool failure with the original cause and structured context.
- *
- * @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);
-}
+ /**
+  * Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false`
+  * for hostile proxies.
+  *
+  * @param value - The unknown signal candidate
+  * @returns True if the value is a native `AbortSignal`; false otherwise
+  *
+  * @example
+  * ```ts
+  * isPoolSignal(new AbortController().signal) // true
+  * isPoolSignal({ aborted: false }) // false
+  * ```
+  */
+ export declare function isPoolSignal(value: unknown): value is AbortSignal;
 
-/** 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;
-}
+ /**
+  * Represents 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;
+     /**
+      * 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'`.
+          */
+      constructor(options: PoolOptions<T>);
+      /** Holds the typed synchronous lifecycle observation surface. */
+      get emitter(): EmitterInterface<PoolEventMap>;
+      /** Counts all owned records, including records validating or destroying. */
+      get size(): number;
+      /** Counts the records immediately available without validation work. */
+      get idle(): number;
+      /** Counts the records represented by unsettled released-once lease tokens. */
+      get active(): number;
+      /**
+       * Queues and leases one resource in FIFO settlement order.
+       *
+       * @param signal - Optional native cancellation signal
+       * @returns A promise for the unique resource lease
+       * @throws {@link PoolError} Thrown when `signal` is present and is not a native `AbortSignal`,
+           * 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.
+               */
+           acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+           /**
+            * Destroys the records that are idle at this call's synchronous snapshot.
+            *
+            * @returns A promise that settles after every snapshot cleanup attempt
+            * @throws {@link PoolError} Thrown when `destroy()` has already begun, with `code: 'destroyed'`.
+                * @throws {@link PoolError} Thrown when a claimed record's destroy hook fails, with
+                    * `code: 'cleanup'` and every distinct failure in `context.failures`. Each arrives as a rejected
+                    * promise rather than a synchronous throw.
+                    */
+                clear(): Promise<void>;
+                /**
+                 * 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
+                     * `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.
+                     */
+                 destroy(): Promise<void>;
+                }
 
-/** Observable resource lifecycle events emitted by a {@link PoolInterface}. */
-export declare type PoolEventMap = {
-    /** A created resource entered pool ownership. */
-    readonly create: readonly [];
-    /** A token settled successfully and its exact resource became leased. */
-    readonly acquire: readonly [];
-    /** A released resource became immediately idle. */
-    readonly release: readonly [];
-    /** A resource cleanup hook completed or was attempted when absent. */
-    readonly destroy: readonly [];
-};
+                /**
+                 * Names the machine-readable failure codes produced by {@link PoolError}.
+                 */
+                export declare type PoolCode = 'invalid' | 'destroyed' | 'create' | 'cleanup';
 
-/** 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>;
-}
+                /**
+                 * Represents the structured context attached to a {@link PoolError}: the rejected input, or the
+                 * distinct destroy-hook failures an aggregate cleanup collected.
+                 */
+                export declare interface PoolContext {
+                    /** Holds the rejected public input, when the failure is an input-validation error. */
+                    readonly value?: unknown;
+                    /** Holds distinct destroy-hook failures collected by `clear()` or `destroy()`. */
+                    readonly failures?: readonly unknown[];
+                }
 
-/**
- * Resource lifecycle options for {@link Pool} and `createPool`.
- *
- * @remarks
- * `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>;
-    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;
-}
+                /**
+                 * Represents a stable, machine-readable pool failure that retains the original thrown value as
+                 * its cause without unsafe coercion, alongside structured context.
+                 *
+                 * @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 {
+                    /** Holds the stable machine-readable failure category. */
+                    readonly code: PoolCode;
+                    /** Holds optional structured input or aggregate destroy-hook failure details. */
+                    readonly context: PoolContext | undefined;
+                    /**
+                     * Creates a pool failure without coercing a hostile thrown value.
+                     *
+                     * @param options - Stable code plus optional cause and structured context
+                     */
+                    constructor(options: PoolErrorOptions);
+                }
+
+                /**
+                 * Represents the construction options for {@link PoolError}: the stable code, an optional cause,
+                 * and optional structured context.
+                 */
+                export declare interface PoolErrorOptions {
+                    /** Holds the stable machine-readable failure category. */
+                    readonly code: PoolCode;
+                    /** Holds the original thrown value, retained without unsafe string coercion. */
+                    readonly cause?: unknown;
+                    /** Holds optional structured failure details. */
+                    readonly context?: PoolContext;
+                }
+
+                /**
+                 * Represents the observable resource lifecycle events emitted by a {@link PoolInterface}.
+                 */
+                export declare type PoolEventMap = {
+                    /** Signals that a created resource entered pool ownership. */
+                    readonly create: readonly [];
+                    /** Signals that a token settled successfully and its exact resource became leased. */
+                    readonly acquire: readonly [];
+                    /** Signals that a released resource became immediately idle. */
+                    readonly release: readonly [];
+                    /** Signals that a resource destroy hook completed or was attempted when absent. */
+                    readonly destroy: readonly [];
+                };
+
+                /**
+                 * Represents a FIFO resource pool with optional bounded capacity and deterministic teardown,
+                 * exposing its record counts and a typed lifecycle emitter.
+                 */
+                export declare interface PoolInterface<T> {
+                    /** Holds the typed synchronous lifecycle observation surface. */
+                    readonly emitter: EmitterInterface<PoolEventMap>;
+                    /** Counts all owned records, including records validating or destroying. */
+                    readonly size: number;
+                    /** Counts the records immediately available without validation work. */
+                    readonly idle: number;
+                    /** Counts the records represented by unsettled released-once lease tokens. */
+                    readonly active: number;
+                    /**
+                     * Queues the caller in FIFO order, validates an idle record or creates one, and settles queued
+                     * acquires in that same order.
+                     *
+                     * @param signal - Optional native cancellation signal
+                     * @returns A promise for the unique resource lease
+                     * @throws {@link PoolError} Thrown when `signal` is present and is not a native `AbortSignal`,
+                         * 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.
+                             */
+                         acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+                         /**
+                          * Destroys the records that are idle at this call's synchronous snapshot.
+                          *
+                          * @returns A promise that settles after every snapshot cleanup attempt
+                          * @throws {@link PoolError} Thrown when `destroy()` has already begun, with `code: 'destroyed'`.
+                              * @throws {@link PoolError} Thrown when a claimed record's destroy hook fails, with
+                                  * `code: 'cleanup'` and every distinct failure in `context.failures`. Each arrives as a rejected
+                                  * promise rather than a synchronous throw.
+                                  */
+                              clear(): Promise<void>;
+                              /**
+                               * 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
+                                   * `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.
+                                   */
+                               destroy(): Promise<void>;
+                              }
+
+                              /**
+                               * Represents the resource lifecycle options for {@link Pool} and `createPool`: creation,
+                               * destruction, validation, capacity, and observation.
+                               *
+                               * @remarks
+                               * `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>;
+                                  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 unique lease over one pool-owned resource record. */
-export declare interface PoolToken<T> {
-    /** The leased value. Duplicate values still belong to independent records. */
-    readonly value: T;
-    /** Return this exact lease once; subsequent calls are no-ops. */
-    release(): void;
-}
+                              /**
+                               * Represents a unique lease over one pool-owned resource record, exposing that record as a readonly
+                               * `value` and returning it through an idempotent `release`.
+                               */
+                              export declare interface PoolToken<T> {
+                                  /** Holds the leased value. Duplicate values still belong to independent records. */
+                                  readonly value: T;
+                                  /**
+                                   * Gives this exact record back to the pool once; a repeat call, and a call after teardown took
+                                   * ownership, are no-ops.
+                                   */
+                                  release(): void;
+                              }
 
-export { }
+                              export { }