shelving/util/async.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import type { ErrorCallback, ValueCallback } from "./callback.js";
/** Is a value an asynchronous value implementing a `then()` function. */
export declare function isAsync<T>(value: PromiseLike<T> | T): value is PromiseLike<T>;
/** Is a value a synchronous value. */
export declare function notAsync<T>(value: PromiseLike<T> | T): value is T;
/**
 * Throw the value if it's an async (promised) value.
 * @returns Synchronous (not promised) value.
 * @throws Promise if value is an asynchronous (promised) value.
 */
export declare function throwAsync<T>(value: PromiseLike<T> | T): T;
/** Assert an unknown value is synchronous (i.e. does not have a `.then()` method). */
export declare function assertNotAsync<T>(value: PromiseLike<T> | T): asserts value is T;
/** Assert an unknown value is asynchronous (i.e. has a `.then()` method). */
export declare function assertAsync<T>(value: PromiseLike<T> | T): asserts value is PromiseLike<T>;
/** Assert that an unknown value is a `Promise` */
export declare function assertPromise<T>(value: Promise<T> | T): asserts value is Promise<T>;
/** Run any queued microtasks now. */
export declare function runMicrotasks(): Promise<void>;
/**
 * Get the result of multiple promises concurrently.
 *
 * DH: An issue with `Promise.all()` is: if _one_ of its promises rejects, the parent promise rejects immediately.
 * - This leaves all of the other promises lost in unhandled purgatory.
 * - The program may then have dangling open threads that prevent the program from exiting, even after it has returned its main result.
 * - This function waits for the resolution of *all* promises before rejecting.
 *
 * @param promises Promises that we need to wait for.
 * @throws unknown Rethrows the first error found after resolving all the promises (the first in the _list_, not the first overall).
 */
export declare function getConcurrent<T extends ImmutableArray<unknown>>(...promises: T): Promise<{
    readonly [P in keyof T]: Awaited<T[P]>;
}>;
/** Type of `Promise` with `._resolve()` and `._reject()` methods available. */
export declare abstract class AbstractPromise<T> extends Promise<T> {
    static get [Symbol.species](): PromiseConstructor;
    /** Resolve this promise with a value. */
    protected readonly _resolve: ValueCallback<T>;
    /** Reject this promise with a reason. */
    protected readonly _reject: ErrorCallback;
    constructor();
}
/** Deferred allows you to access the internal resolve/reject callbacks of a `Promise` */
export type Deferred<T> = {
    promise: Promise<T>;
    resolve: ValueCallback<T>;
    reject: ErrorCallback;
};
/**
 * Get a deferred to access the `resolve()` and `reject()` functions of a promise.
 * - See https://github.com/tc39/proposal-promise-with-resolvers/
 */
export declare function getDeferred<T = unknown>(): Deferred<T>;
/** Get a promise that automatically resolves after a delay. */
export declare function getDelay(ms: number): Promise<void>;