@mnaoumov/typescript-lib 0.0.0 → 1.0.0

package/dist/lib/esm/disposable.d.mts

@@ -0,0 +1,387 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * Disposable utilities for `using` / `await using` declarations.
+ */
+import type { Promisable } from 'type-fest';
+/**
+ * Determines the error semantics of a {@link CombineDisposable} or {@link CombineAsyncDisposable} when
+ * one of its children throws while being disposed.
+ */
+export declare enum DisposeErrorBehavior {
+    /**
+     * Dispose every child even if some of them throw, collecting the thrown errors and re-throwing them
+     * as a single {@link AggregateError} once all children have been disposed.
+     */
+    Aggregate = 0,
+    /**
+     * Re-throw the first error a child throws immediately, leaving the remaining children undisposed.
+     */
+    FailFast = 1
+}
+/**
+ * Determines the order in which a {@link CombineDisposable} or {@link CombineAsyncDisposable} disposes
+ * its children.
+ */
+export declare enum DisposeOrder {
+    /**
+     * Dispose the last-registered child first (last-in, first-out), like nested `using` declarations
+     * unwinding in reverse.
+     */
+    Lifo = 0,
+    /**
+     * Dispose the first-registered child first (first-in, first-out).
+     */
+    Fifo = 1
+}
+/**
+ * Determines how a {@link CallbackDisposable} or {@link AsyncCallbackDisposable} behaves when it is
+ * disposed more than once.
+ */
+export declare enum MultipleDisposeBehavior {
+    /**
+     * Invoke the callback on every dispose.
+     */
+    Invoke = 0,
+    /**
+     * Invoke the callback on the first dispose only; subsequent disposes are no-ops.
+     */
+    Ignore = 1,
+    /**
+     * Invoke the callback on the first dispose only; subsequent disposes throw.
+     */
+    Throw = 2
+}
+/**
+ * The parameters for constructing an {@link AsyncCallbackDisposable}.
+ */
+export interface AsyncCallbackDisposableConstructorParams {
+    /**
+     * The callback to execute when disposed.
+     */
+    readonly callback: AsyncDisposeCallback;
+    /**
+     * How the disposable behaves when disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    readonly multipleDisposeBehavior?: MultipleDisposeBehavior;
+}
+/**
+ * An {@link AsyncDisposable} that additionally exposes a convenience {@link AsyncDisposableEx.asyncDispose}
+ * method, so a stored handle can be disposed as `handle.asyncDispose()` instead of the clunkier
+ * `handle[Symbol.asyncDispose]()`.
+ */
+export interface AsyncDisposableEx extends AsyncDisposable {
+    /**
+     * Disposes the object. Delegates to `this[Symbol.asyncDispose]()`.
+     *
+     * @returns A {@link Promise} that resolves once disposal completes.
+     */
+    asyncDispose: () => Promise<void>;
+}
+/**
+ * A callback invoked when an {@link AsyncCallbackDisposable} is disposed.
+ */
+export type AsyncDisposeCallback = () => Promisable<void>;
+/**
+ * The parameters for constructing a {@link CallbackDisposable}.
+ */
+export interface CallbackDisposableConstructorParams {
+    /**
+     * The callback to execute when disposed.
+     */
+    readonly callback: DisposeCallback;
+    /**
+     * How the disposable behaves when disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    readonly multipleDisposeBehavior?: MultipleDisposeBehavior;
+}
+/**
+ * The parameters for constructing a {@link CombineAsyncDisposable}.
+ */
+export interface CombineAsyncDisposableConstructorParams {
+    /**
+     * The async disposables to dispose when the combiner is disposed.
+     */
+    readonly asyncDisposables: Iterable<AsyncDisposable>;
+    /**
+     * The order in which the children are disposed.
+     *
+     * @default {@link DisposeOrder.Lifo}
+     */
+    readonly disposeOrder?: DisposeOrder;
+    /**
+     * How the combiner behaves when one of its children throws while being disposed.
+     *
+     * @default {@link DisposeErrorBehavior.Aggregate}
+     */
+    readonly errorBehavior?: DisposeErrorBehavior;
+    /**
+     * How the combiner behaves when it is disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    readonly multipleDisposeBehavior?: MultipleDisposeBehavior;
+}
+/**
+ * The parameters for constructing a {@link CombineDisposable}.
+ */
+export interface CombineDisposableConstructorParams {
+    /**
+     * The disposables to dispose when the combiner is disposed.
+     */
+    readonly disposables: Iterable<Disposable>;
+    /**
+     * The order in which the children are disposed.
+     *
+     * @default {@link DisposeOrder.Lifo}
+     */
+    readonly disposeOrder?: DisposeOrder;
+    /**
+     * How the combiner behaves when one of its children throws while being disposed.
+     *
+     * @default {@link DisposeErrorBehavior.Aggregate}
+     */
+    readonly errorBehavior?: DisposeErrorBehavior;
+    /**
+     * How the combiner behaves when it is disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    readonly multipleDisposeBehavior?: MultipleDisposeBehavior;
+}
+/**
+ * A {@link Disposable} that additionally exposes a convenience {@link DisposableEx.dispose} method, so a
+ * stored handle can be disposed as `handle.dispose()` instead of the clunkier `handle[Symbol.dispose]()`.
+ */
+export interface DisposableEx extends Disposable {
+    /**
+     * Disposes the object. Delegates to `this[Symbol.dispose]()`.
+     */
+    dispose: () => void;
+}
+/**
+ * A callback invoked when a {@link CallbackDisposable} is disposed.
+ */
+export type DisposeCallback = () => void;
+/**
+ * Abstract base for an {@link AsyncDisposableEx}: it carries the re-dispose guard (via
+ * {@link MultipleDisposeBehavior}) and the {@link AsyncDisposableEx.asyncDispose} alias; a subclass only
+ * implements {@link AsyncDisposableBase.performDisposeAsync}.
+ */
+export declare abstract class AsyncDisposableBase implements AsyncDisposableEx {
+    /**
+     * How the disposable behaves when disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    protected multipleDisposeBehavior: MultipleDisposeBehavior;
+    /**
+     * Whether this disposable has been disposed (its teardown has run at least once).
+     *
+     * @returns `true` once disposal has started.
+     */
+    protected get isDisposed(): boolean;
+    private _isDisposed;
+    /**
+     * Disposes the object. Convenience alias that delegates to `this[Symbol.asyncDispose]()`.
+     *
+     * @returns A {@link Promise} that resolves once teardown completes.
+     */
+    asyncDispose(): Promise<void>;
+    /**
+     * Disposes the object by running {@link AsyncDisposableBase.performDisposeAsync}, honoring the configured
+     * {@link MultipleDisposeBehavior} on a repeat dispose.
+     *
+     * @returns A {@link Promise} that resolves once teardown completes.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Performs the actual teardown. Called at most once unless {@link MultipleDisposeBehavior.Invoke} is set.
+     *
+     * @returns A {@link Promisable} that resolves once teardown completes.
+     */
+    protected abstract performDisposeAsync(): Promisable<void>;
+}
+/**
+ * An async disposable that executes a callback when disposed via `await using` (or a manual
+ * `await disposable[Symbol.asyncDispose]()`).
+ */
+export declare class AsyncCallbackDisposable extends AsyncDisposableBase {
+    private readonly callback;
+    /**
+     * Creates a new instance of {@link AsyncCallbackDisposable}.
+     *
+     * @param params - The parameters.
+     */
+    constructor(params: AsyncCallbackDisposableConstructorParams);
+    /**
+     * Runs the dispose callback.
+     *
+     * @returns A {@link Promise} that resolves once the callback completes.
+     */
+    protected performDisposeAsync(): Promise<void>;
+}
+/**
+ * Disposes a {@link Disposable}.
+ *
+ * Prefer this over calling `disposable[Symbol.dispose]()` at the call site: it reads better and keeps the
+ * well-known symbol referenced in a single place.
+ *
+ * @param disposable - the disposable to dispose
+ */
+export declare function dispose(disposable: Disposable): void;
+/**
+ * Abstract base for a {@link DisposableEx}: it carries the re-dispose guard (via {@link MultipleDisposeBehavior})
+ * and the {@link DisposableEx.dispose} alias; a subclass only implements {@link DisposableBase.performDispose}.
+ */
+export declare abstract class DisposableBase implements DisposableEx {
+    /**
+     * How the disposable behaves when disposed more than once.
+     *
+     * @default {@link MultipleDisposeBehavior.Ignore}
+     */
+    protected multipleDisposeBehavior: MultipleDisposeBehavior;
+    /**
+     * Whether this disposable has been disposed (its teardown has run at least once).
+     *
+     * @returns `true` once disposal has started.
+     */
+    protected get isDisposed(): boolean;
+    private _isDisposed;
+    /**
+     * Disposes the object. Convenience alias that delegates to `this[Symbol.dispose]()`.
+     */
+    dispose(): void;
+    /**
+     * Disposes the object by running {@link DisposableBase.performDispose}, honoring the configured
+     * {@link MultipleDisposeBehavior} on a repeat dispose.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Performs the actual teardown. Called at most once unless {@link MultipleDisposeBehavior.Invoke} is set.
+     */
+    protected abstract performDispose(): void;
+}
+/**
+ * A disposable that executes a callback when disposed.
+ */
+export declare class CallbackDisposable extends DisposableBase {
+    private readonly callback;
+    /**
+     * Creates a new instance of {@link CallbackDisposable}.
+     *
+     * @param params - The parameters.
+     */
+    constructor(params: CallbackDisposableConstructorParams);
+    /**
+     * Runs the dispose callback.
+     */
+    protected performDispose(): void;
+}
+/**
+ * An {@link AsyncDisposableEx} that combines multiple async disposables and disposes all of them when it
+ * is disposed.
+ */
+export declare class CombineAsyncDisposable extends AsyncDisposableBase {
+    private readonly children;
+    private readonly disposeOrder;
+    private readonly errorBehavior;
+    /**
+     * Creates a new instance of {@link CombineAsyncDisposable}.
+     *
+     * @param params - The parameters.
+     */
+    constructor(params: CombineAsyncDisposableConstructorParams);
+    /**
+     * Disposes all combined children in the configured {@link DisposeOrder}, applying the configured
+     * {@link DisposeErrorBehavior} when a child throws.
+     *
+     * @returns A {@link Promise} that resolves once all children have been disposed.
+     */
+    protected performDisposeAsync(): Promise<void>;
+    private getOrderedChildren;
+}
+/**
+ * A {@link DisposableEx} that combines multiple disposables and disposes all of them when it is
+ * disposed.
+ */
+export declare class CombineDisposable extends DisposableBase {
+    private readonly children;
+    private readonly disposeOrder;
+    private readonly errorBehavior;
+    /**
+     * Creates a new instance of {@link CombineDisposable}.
+     *
+     * @param params - The parameters.
+     */
+    constructor(params: CombineDisposableConstructorParams);
+    /**
+     * Disposes all combined children in the configured {@link DisposeOrder}, applying the configured
+     * {@link DisposeErrorBehavior} when a child throws.
+     */
+    protected performDispose(): void;
+    private getOrderedChildren;
+}
+/**
+ * Disposes an {@link AsyncDisposable}.
+ *
+ * Prefer this over calling `asyncDisposable[Symbol.asyncDispose]()` at the call site: it reads better and
+ * keeps the well-known symbol referenced in a single place.
+ *
+ * @param asyncDisposable - the async disposable to dispose
+ * @returns A {@link Promise} that resolves once the disposal completes.
+ */
+export declare function disposeAsync(asyncDisposable: AsyncDisposable): Promise<void>;
+/**
+ * Type guard to check if an object implements the {@link AsyncDisposable} interface.
+ *
+ * @param $unknown - the object to check for the {@link AsyncDisposable} interface
+ * @returns Whether the object implements the {@link AsyncDisposable} interface
+ */
+export declare function isAsyncDisposable($unknown: unknown): $unknown is AsyncDisposable;
+/**
+ * Type guard to check if an object implements the {@link AsyncDisposableEx} interface.
+ *
+ * @param $unknown - the object to check for the {@link AsyncDisposableEx} interface
+ * @returns Whether the object implements the {@link AsyncDisposableEx} interface
+ */
+export declare function isAsyncDisposableEx($unknown: unknown): $unknown is AsyncDisposableEx;
+/**
+ * Type guard to check if an object implements the {@link Disposable} interface.
+ *
+ * @param $unknown - the object to check for the {@link Disposable} interface
+ * @returns Whether the object implements the {@link Disposable} interface
+ */
+export declare function isDisposable($unknown: unknown): $unknown is Disposable;
+/**
+ * Type guard to check if an object implements the {@link DisposableEx} interface.
+ *
+ * @param $unknown - the object to check for the {@link DisposableEx} interface
+ * @returns Whether the object implements the {@link DisposableEx} interface
+ */
+export declare function isDisposableEx($unknown: unknown): $unknown is DisposableEx;
+/**
+ * Adapts a plain {@link AsyncDisposable} into an {@link AsyncDisposableEx} by adding a convenience
+ * {@link AsyncDisposableEx.asyncDispose} method that delegates to `Symbol.asyncDispose`.
+ *
+ * If the object already implements {@link AsyncDisposableEx}, it is returned unchanged.
+ *
+ * @param asyncDisposable - the async disposable to adapt
+ * @returns An {@link AsyncDisposableEx} wrapping the async disposable.
+ */
+export declare function toAsyncDisposableEx(asyncDisposable: AsyncDisposable): AsyncDisposableEx;
+/**
+ * Adapts a plain {@link Disposable} into a {@link DisposableEx} by adding a convenience
+ * {@link DisposableEx.dispose} method that delegates to `Symbol.dispose`.
+ *
+ * If the object already implements {@link DisposableEx}, it is returned unchanged.
+ *
+ * @param disposable - the disposable to adapt
+ * @returns A {@link DisposableEx} wrapping the disposable.
+ */
+export declare function toDisposableEx(disposable: Disposable): DisposableEx;