@orkestrel/pool 0.0.13 → 0.0.15

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

@@ -11,12 +11,15 @@ import type { EmitterInterface } from '@orkestrel/emitter';
  * 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
@@ -83,9 +86,9 @@ import type { EmitterInterface } from '@orkestrel/emitter';
  export declare function isPoolSignal(value: unknown): value is AbortSignal;
 
  /**
-  * 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
   *
@@ -108,205 +111,250 @@ import type { EmitterInterface } from '@orkestrel/emitter';
      /**
       * 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: PoolOptions<T>);
       /** Holds the typed synchronous lifecycle observation surface. */
       get emitter(): EmitterInterface<PoolEventMap>;
-      /** Counts all owned records, including records validating or destroying. */
+      /** Counts all owned records, including records validating, destroying, or retained after failed cleanup. */
       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.
+       * Fills the warm floor and resets the strikes of a spent floor; without a floor, resolves immediately.
        *
-       * @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.
+       * @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(): Promise<void>;
+       /**
+        * 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
+        * @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 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?: AbortSignal): Promise<PoolToken<T>>;
+            /**
+             * 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'`.
+                 * @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.
                      */
-                 destroy(): Promise<void>;
-                }
+                 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 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.
+                      */
+                  destroy(): Promise<void>;
+                 }
 
-                /**
-                 * Names the machine-readable failure codes produced by {@link PoolError}.
-                 */
-                export declare type PoolCode = 'invalid' | 'destroyed' | 'create' | 'cleanup';
+                 /**
+                  * Names the machine-readable failure codes produced by {@link PoolError}.
+                  */
+                 export declare type PoolCode = 'invalid' | 'destroyed' | 'create' | 'cleanup';
 
-                /**
-                 * 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[];
-                }
+                 /**
+                  * 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[];
+                 }
 
-                /**
-                 * 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 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 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 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 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 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, orphaned, or refilled resource became immediately idle. */
+                     readonly release: readonly [];
+                     /** Signals that a resource destroy hook completed or was attempted when absent. */
+                     readonly destroy: readonly [];
+                 };
 
-                              /**
-                               * 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.
+                 /**
+                  * Represents a FIFO resource pool with optional bounded capacity, a warm floor, loss recovery,
+                  * 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, destroying, or retained after failed cleanup. */
+                     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;
+                     /**
+                      * 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(): Promise<void>;
+                      /**
+                       * 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
+                       * @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 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.
                                */
-                              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;
-                              }
+                           acquire(signal?: AbortSignal): Promise<PoolToken<T>>;
+                           /**
+                            * 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'`.
+                                * @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 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.
+                                     */
+                                 destroy(): Promise<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;
-                              }
+                                /**
+                                 * Represents the resource lifecycle options for {@link Pool} and `createPool`: creation,
+                                 * destruction, validation, capacity, a bounded warm floor, and loss observation.
+                                 *
+                                 * @remarks
+                                 * `create` produces resources on demand, or only to restore `min` after `start()`.
+                                 * `destroy` tears down a claimed resource. `validate` checks an owned resource before reuse.
+                                 * `min` and `max` are positive safe integers and must be equal when both are set; `max`
+                                 * defaults to `min`. Omitting both leaves capacity unbounded. `restarts` is required with
+                                 * `min`, is refused without `min`, has no default, and is a non-negative safe integer.
+                                 * A failed refill or loss of a never-leased record adds a strike. A lease grant resets the
+                                 * strikes only when its record was created after the last strike; creation alone does not.
+                                 * Exceeding `restarts` stops ordinary refills until `start()` or a qualifying grant.
+                                 * Each lost leased record earns one refill attempt after successful disposal, even when
+                                 * the bound is spent. That credit does not reset strikes; a failed attempt adds a strike.
+                                 * `watch` settles on loss and receives a signal aborted when disposal begins. Its rejection
+                                 * reaches `error` with event `watch` only while the record is live. Any settlement after
+                                 * the signal aborts is ignored. `on` installs initial emitter listeners; `error`
+                                 * also 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 watch?: (value: T, signal: AbortSignal) => Promise<unknown>;
+                                    readonly max?: number;
+                                    readonly min?: number;
+                                    readonly restarts?: number;
+                                }
+
+                                /**
+                                 * Represents a unique lease over one pool-owned resource record, exposing that record as a readonly
+                                 * `value` and ending it through an idempotent `release` or `destroy`.
+                                 */
+                                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 loss or teardown
+                                     * took ownership, are no-ops.
+                                     */
+                                    release(): void;
+                                    /**
+                                     * Destroys this exact record instead of returning it; a repeat call, and a call after release,
+                                     * are no-ops.
+                                     *
+                                     * @returns A promise for this record's cleanup attempt, including an attempt already in progress
+                                     * @throws {@link PoolError} Thrown as a rejection with `code: 'cleanup'` when disposal fails.
+                                         */
+                                     destroy(): Promise<void>;
+                                    }
 
-                              export { }
+                                    export { }