@mnaoumov/typescript-lib 0.0.0 → 1.0.0

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

@@ -0,0 +1,414 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * Contains utility functions for asynchronous operations.
+ */
+import type { Promisable } from 'type-fest';
+import type { GenericAsyncFunction, GenericFunction, GenericVoidFunction } from './function.mjs';
+/**
+ * Parameters for {@link invokeAsyncSafelyAfterDelay}.
+ */
+export interface InvokeAsyncSafelyAfterDelayParams {
+    /**
+     * The abort signal to listen to.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * The asynchronous function to invoke.
+     *
+     * @param abortSignal - The abort signal to listen to.
+     */
+    readonly asyncFunction: (abortSignal: AbortSignal) => Promisable<void>;
+    /**
+     * The delay in milliseconds.
+     *
+     * @default `0`
+     */
+    readonly delayInMilliseconds?: number;
+    /**
+     * The stack trace of the source function.
+     */
+    readonly stackTrace?: string;
+}
+/**
+ * A type representing a function that resolves a {@link Promise}.
+ *
+ * @typeParam T - The type of the value.
+ */
+export type PromiseResolve<T> = undefined extends T ? (value?: PromiseLike<T> | T) => void : (value: PromiseLike<T> | T) => void;
+/**
+ * Options for {@link retryWithTimeout}.
+ */
+export interface RetryOptions {
+    /**
+     * A abort signal to cancel the retry operation.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * A delay in milliseconds between retry attempts.
+     *
+     * @default `100`
+     */
+    readonly retryDelayInMilliseconds?: number;
+    /**
+     * Whether to retry the function on error.
+     *
+     * @default `false`
+     */
+    readonly shouldRetryOnError?: boolean;
+    /**
+     * A maximum time in milliseconds to wait before giving up on retrying.
+     *
+     * @default `5000`
+     */
+    readonly timeoutInMilliseconds?: number;
+}
+/**
+ * Adds an error handler to a {@link Promise} that catches any errors and emits an async error event.
+ *
+ * @param asyncFunction - The asynchronous function to add an error handler to.
+ * @param stackTrace - The stack trace of the source function.
+ * @returns A {@link Promise} that resolves when the asynchronous function completes or emits async error event.
+ */
+export declare function addErrorHandler(asyncFunction: () => Promise<unknown>, stackTrace?: string): Promise<void>;
+/**
+ * Filters an array asynchronously, keeping only the elements that satisfy the provided predicate function.
+ *
+ * @typeParam T - The type of elements in the input array.
+ * @param array - The array to filter.
+ * @param predicate - The predicate function to test each element.
+ * @returns A {@link Promise} that resolves with an array of elements that satisfy the predicate function.
+ */
+export declare function asyncFilter<T>(array: T[], predicate: (value: T, index: number, array: T[]) => Promisable<boolean>): Promise<T[]>;
+/**
+ * Filters an array asynchronously in place, keeping only the elements that satisfy the provided predicate function.
+ *
+ * @typeParam T - The type of elements in the input array.
+ * @param array - The array to filter.
+ * @param predicate - The predicate function to test each element.
+ * @returns A {@link Promise} that resolves when the array is filtered.
+ */
+export declare function asyncFilterInPlace<T>(array: T[], predicate: (value: T, index: number, array: T[]) => Promisable<boolean>): Promise<void>;
+/**
+ * Maps over an array asynchronously, applying the provided callback function to each element, and then flattens the results into a single array.
+ *
+ * @typeParam T - The type of elements in the input array.
+ * @typeParam U - The type of elements in the output array.
+ * @param array - The array to map over and flatten.
+ * @param callback - The callback function to apply to each element.
+ * @returns A {@link Promise} that resolves with a flattened array of the results of the callback function.
+ */
+export declare function asyncFlatMap<T, U>(array: T[], callback: (value: T, index: number, array: T[]) => Promisable<U[]>): Promise<U[]>;
+/**
+ * Maps over an array asynchronously, applying the provided callback function to each element.
+ *
+ * @typeParam T - The type of elements in the input array.
+ * @typeParam U - The type of elements in the output array.
+ * @param array - The array to map over.
+ * @param callback - The callback function to apply to each element.
+ * @returns A {@link Promise} that resolves with an array of the results of the callback function.
+ */
+export declare function asyncMap<T, U>(array: T[], callback: (value: T, index: number, array: T[]) => Promisable<U>): Promise<U[]>;
+/**
+ * Converts an asynchronous function to a synchronous one by automatically handling the Promise rejection.
+ *
+ * @typeParam Arguments - The types of the arguments the function accepts.
+ * @param asyncFunction - The asynchronous function to convert.
+ * @param stackTrace - The stack trace of the source function.
+ * @returns A function that wraps the asynchronous function in a synchronous interface.
+ */
+export declare function convertAsyncToSync<Arguments extends unknown[]>(asyncFunction: GenericAsyncFunction<Arguments>, stackTrace?: string): GenericVoidFunction<Arguments>;
+/**
+ * Converts a synchronous function to an asynchronous one by wrapping it in a {@link Promise}.
+ *
+ * @typeParam Arguments - The types of the arguments the function accepts.
+ * @typeParam Result - The type of the function's return value.
+ * @param syncFunction - The synchronous function to convert.
+ * @returns A function that wraps the synchronous function in an asynchronous interface.
+ */
+export declare function convertSyncToAsync<Arguments extends unknown[], Result>(syncFunction: GenericFunction<Arguments, Result>): GenericAsyncFunction<Arguments, Result>;
+/**
+ * Handles a silent error.
+ *
+ * @param error - The error to handle.
+ * @returns Whether the error is a silent error.
+ */
+export declare function handleSilentError(error: unknown): boolean;
+/**
+ * Ignores an error that is thrown by an asynchronous function.
+ *
+ * @param promise - The promise to ignore the error of.
+ * @param fallbackValue - Always `undefined`.
+ * @returns A {@link Promise} that resolves when the asynchronous function completes or fails.
+ */
+export declare function ignoreError(promise: Promise<unknown>, fallbackValue?: undefined): Promise<void>;
+/**
+ * Invokes an asynchronous function and returns a fallback value if an error is thrown.
+ *
+ * @typeParam T - The type of the value returned by the asynchronous function.
+ * @param promise - The promise to ignore the error of.
+ * @param fallbackValue - The value to return if an error is thrown.
+ * @returns A {@link Promise} that resolves with the value returned by the asynchronous function or the fallback value if an error is thrown.
+ */
+export declare function ignoreError<T>(promise: Promise<T>, fallbackValue: T): Promise<T>;
+/**
+ * Invokes a {@link Promise} and safely handles any errors by catching them and emitting an async error event.
+ *
+ * @param asyncFunction - The asynchronous function to invoke safely.
+ * @param stackTrace - The stack trace of the source function.
+ */
+export declare function invokeAsyncSafely(asyncFunction: () => Promisable<unknown>, stackTrace?: string): void;
+/**
+ * Invokes an asynchronous function after a delay.
+ *
+ * @param params - The parameters for the function.
+ */
+export declare function invokeAsyncSafelyAfterDelay(params: InvokeAsyncSafelyAfterDelayParams): void;
+/**
+ * Executes async functions sequentially.
+ *
+ * @typeParam T - The type of the value.
+ * @param asyncFns - The async functions to execute sequentially.
+ * @returns A {@link Promise} that resolves with an array of the results of the async functions.
+ */
+export declare function promiseAllAsyncFnsSequentially<T>(asyncFns: (() => Promisable<T>)[]): Promise<T[]>;
+/**
+ * Executes promises sequentially.
+ *
+ * @typeParam T - The type of the value.
+ * @param promises - The promises to execute sequentially.
+ * @returns A {@link Promise} that resolves with an array of the results of the promises.
+ */
+export declare function promiseAllSequentially<T>(promises: Promisable<T>[]): Promise<T[]>;
+/**
+ * Options for {@link retryWithTimeout}.
+ */
+export interface RetryWithTimeoutParams {
+    /**
+     * The function to handle the timeout.
+     *
+     * @param context - The timeout context.
+     */
+    readonly onTimeout?: (context: TimeoutContext) => void;
+    /**
+     * The function to execute.
+     *
+     * @param abortSignal - The abort signal to listen to.
+     * @returns The result of the function.
+     */
+    readonly operationFunction: (abortSignal: AbortSignal) => Promisable<boolean>;
+    /**
+     * The name of the operation.
+     *
+     * @default `''`
+     */
+    readonly operationName?: string;
+    /**
+     * The retry options.
+     */
+    readonly retryOptions?: RetryOptions;
+    /**
+     * The stack trace of the source function.
+     */
+    readonly stackTrace?: string;
+}
+/**
+ * Options for {@link runWithTimeout}.
+ *
+ * @typeParam Result - The type of the result returned by the operation function.
+ */
+export interface RunWithTimeoutParams<Result> {
+    /**
+     * The context of the function.
+     */
+    readonly context?: unknown;
+    /**
+     * The function to handle the timeout.
+     *
+     * @param context - The timeout context.
+     */
+    readonly onTimeout?: (context: TimeoutContext) => void;
+    /**
+     * The operation function to execute.
+     *
+     * @param abortSignal - The abort signal to listen to.
+     * @returns The result of the function.
+     */
+    readonly operationFunction: (abortSignal: AbortSignal) => Promisable<Result>;
+    /**
+     * The name of the operation.
+     *
+     * @default `''`
+     */
+    readonly operationName?: string;
+    /**
+     * The stack trace of the source function.
+     */
+    readonly stackTrace?: string | undefined;
+    /**
+     * The maximum time to wait in milliseconds.
+     */
+    readonly timeoutInMilliseconds: number;
+}
+/**
+ * Parameters for {@link sleep}.
+ */
+export interface SleepParams {
+    /**
+     * The abort signal to listen to.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * The time to wait in milliseconds.
+     */
+    readonly milliseconds: number;
+    /**
+     * Whether to throw an error if the abort signal is aborted.
+     *
+     * @default `false`
+     */
+    readonly shouldThrowOnAbort?: boolean;
+}
+/**
+ * Context provided to the timeout handler.
+ */
+export interface TimeoutContext {
+    /**
+     * The duration in milliseconds since the operation started.
+     */
+    readonly duration: number;
+    /**
+     * Registers a callback to be invoked when the operation completes.
+     *
+     * @param callback - The function to call when the operation completes.
+     */
+    onOperationCompleted: (callback: () => void) => void;
+    /**
+     * The name of the operation.
+     */
+    readonly operationName: string;
+    /**
+     * Terminates the operation that timed out.
+     */
+    terminateOperation: () => void;
+}
+/**
+ * Parameters for {@link timeout}.
+ */
+export interface TimeoutParams {
+    /**
+     * The abort signal to listen to.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Whether to throw an error if the abort signal is aborted.
+     *
+     * @default `false`
+     */
+    readonly shouldThrowOnAbort?: boolean;
+    /**
+     * The timeout period in milliseconds.
+     */
+    readonly timeoutInMilliseconds: number;
+}
+/**
+ * Chains a promise with another promise.
+ *
+ * @param chainPromise - Represents the chained promise.
+ * @param promisableFunction - The function to chain.
+ * @returns Chained promise or `null` if no async logic is chained.
+ */
+export declare function chain(chainPromise: null | Promise<void>, promisableFunction: () => null | Promisable<void>): null | Promise<void>;
+/**
+ * Marks an error to terminate retry logic.
+ *
+ * @param error - The error to mark to terminate retry logic.
+ */
+export declare function marksAsTerminateRetry(error: Error): void;
+/**
+ * An async function that never ends.
+ *
+ * @returns A {@link Promise} that never resolves.
+ */
+export declare function neverEnds(): Promise<never>;
+/**
+ * Gets the next tick.
+ *
+ * @returns A promise that resolves when the next tick is available.
+ */
+export declare function nextTickAsync(): Promise<void>;
+/**
+ * Converts to native promisable, converting {@link PromiseLike} (aka Thenable) to a native {@link Promise}.
+ *
+ * @typeParam T - The type of the value.
+ * @param promisable - The promisable to normalize.
+ * @returns The value itself or a native {@link Promise} if the value is a {@link PromiseLike}.
+ */
+export declare function normalizePromisable<T>(promisable: Promisable<T>): Promise<T> | T;
+/**
+ * Gets the next queue microtask.
+ *
+ * @returns A promise that resolves when the next queue microtask is available.
+ */
+export declare function queueMicrotaskAsync(): Promise<void>;
+/**
+ * Gets the next request animation frame.
+ *
+ * @param fallbackTimeoutInMilliseconds - The fallback timeout in milliseconds to resolve the promise if `requestAnimationFrame` does not fire (e.g. the window is not active).
+ *                                        Defaults to `100` milliseconds. Use `0` to disable the fallback.
+ * @returns A promise that resolves when the next request animation frame is available (or when the fallback time is reached).
+ */
+export declare function requestAnimationFrameAsync(fallbackTimeoutInMilliseconds?: number): Promise<void>;
+/**
+ * Retries the provided function until it returns `true` or the timeout is reached.
+ *
+ * @param params - The parameters for the function.
+ * @returns A {@link Promise} that resolves when the function returns `true` or rejects when the timeout is reached.
+ */
+export declare function retryWithTimeout(params: RetryWithTimeoutParams): Promise<void>;
+/**
+ * Executes a function with a timeout. If the function does not complete within the specified time, it is considered to have timed out.
+ *
+ * If `DEBUG=obsidian-dev-utils:Async:runWithTimeout` is set, the execution is not terminated after the timeout and the function is allowed to run indefinitely.
+ *
+ * @typeParam Result - The type of the result from the asynchronous function.
+ * @param params - The parameters for the function.
+ * @returns A {@link Promise} that resolves with the result of the asynchronous function or rejects if it times out.
+ */
+export declare function runWithTimeout<Result>(params: RunWithTimeoutParams<Result>): Promise<Result>;
+/**
+ * Gets the next set immediate.
+ *
+ * @returns A promise that resolves when the next set immediate is available.
+ */
+export declare function setImmediateAsync(): Promise<void>;
+/**
+ * Delays execution for a specified number of milliseconds.
+ *
+ * @param delay - The time to wait in milliseconds.
+ * @returns A {@link Promise} that resolves after the specified delay.
+ */
+export declare function setTimeoutAsync(delay?: number): Promise<void>;
+/**
+ * Delays execution for a specified number of milliseconds.
+ *
+ * @param params - The parameters for the function.
+ * @returns A {@link Promise} that resolves after the specified delay.
+ */
+export declare function sleep(params: SleepParams): Promise<void>;
+/**
+ * Returns a {@link Promise} that rejects after the specified timeout period.
+ *
+ * @param params - The parameters for the function.
+ * @returns A {@link Promise} that always rejects with a timeout error.
+ */
+export declare function timeout(params: TimeoutParams): Promise<never>;
+/**
+ * Converts an AsyncIterableIterator to an array by consuming all its elements.
+ *
+ * @typeParam T - The type of elements produced by the AsyncIterableIterator.
+ * @param iter - The AsyncIterableIterator to convert.
+ * @returns A {@link Promise} that resolves with an array of all the elements in the AsyncIterableIterator.
+ */
+export declare function toArray<T>(iter: AsyncIterableIterator<T>): Promise<T[]>;