thorish/dist/types/src/promise.d.ts

This is a library of useful JS concepts and data structures for Node and the browser. It it, unashamedly, a dumping ground for code needed by [@samthor](https://twitter.com/samthor)'s projects.

/**
 * A {@link Promise} that will never resolve.
 */
export declare const unresolvedPromise: Promise<never>;
/**
 * A {@link Promise} that is already resolved.
 */
export declare const resolvedPromise: Promise<void>;
/**
 * Wraps a trigger function (e.g., {@link setTimeout} or {@link requestAnimationFrame}) and returns
 * a {@link Promise} that resolves when it is fired.
 *
 * Using {@link setInterval} is _not_ a good candidate for this function.
 */
export declare function wrapTrigger<TCallbackParam = void, TArgs extends any[] = []>(trigger: (callback: (arg: TCallbackParam) => any, ...moreArgs: TArgs) => any, ...moreArgs: TArgs): Promise<TCallbackParam>;
/**
 * Sets a timeout via {@link Promise}.
 *
 * Pass an optional {@link AbortSignal} to resolve early with success on abort.
 */
export declare function timeout(ms: number, signal?: AbortSignal): Promise<void>;
/**
 * Wraps {@link Promise.withResolvers} with a polyfill.
 */
export declare const promiseWithResolvers: <T>() => PromiseWithResolvers<T>;
export declare const resolvable: <T>() => PromiseWithResolvers<T>;
/**
 * Returns a {@link Promise} that resolves after a the first event of the given name is fired.
 *
 * This doesn't correctly infer the type of the {@link Event}, but you can specify it via template.
 *
 * If the {@link AbortSignal} is aborted, this will reject with an unspecified {@link Error}.
 */
export declare function promiseForEvent<X extends Event = Event>(target: EventTarget, eventName: string, options?: Partial<{
    passive: boolean;
    signal: AbortSignal;
}>): Promise<X>;
/**
 * Helper which finds the next completed promise (using {@link Promise.race}) from the given array,
 * removing it from the passed array in-place. This is O(n) with the number of elements, as each
 * element must be wrapped in an additional {@link Promise} that includes the index.
 *
 * Returns `undefined` if the array was empty. This is unlike {@link Promise.race}, which will wait
 * forever.
 */
export declare function spliceNextPromise<T>(arr: Promise<T>[]): Promise<T | undefined>;
/**
 * Wrap a simple {@link Function} that returns a {@link Promise} such that, if many calls are made
 * while it is resolving, the next callers "join" the train and get the same result.
 *
 * This is a simple memoize implementation.
 */
export declare function buildCallTrain<R>(fn: () => Promise<R>): () => Promise<R>;
export type RunnerOptions = {
    immediate?: boolean;
    /**
     * Prevent the final callback from running if this {@link AbortSignal} is aborted.
     */
    signal?: AbortSignal;
};
/**
 * Builds a {@link requestAnimationFrame} runner, which runs the callback at most once per frame.
 *
 * Accepts options: `immediate` to queue immediately, and `signal` which is checked before the callback is finally run.
 * If the passed {@link AbortSignal} is aborted, the returned `Promise` is rejected with its `reason`, but is internally read to prevent unhandled exceptions.
 */
export declare function rafRunner<T = void>(callback: () => T, options?: RunnerOptions): () => Promise<T>;
/**
 * Builds a runner which fires the faster of {@link setTimeout} and {@link requestAnimationFrame}, which runs the callback at most once per frame.
 *
 * Accepts options: `immediate` to queue immediately, and `signal` which is checked before the callback is finally run.
 * If the passed {@link AbortSignal} is aborted, the returned `Promise` is rejected with its `reason`, but is internally read to prevent unhandled exceptions.
 */
export declare function fastFrameRunner<T = void>(callback: () => T, options?: RunnerOptions): () => Promise<T>;
/**
 * Builds a next-tick runner, which runs the callback at most once per tick.
 *
 * Accepts options: `immediate` to queue immediately, and `signal` which is checked before the callback is finally run.
 * If the passed {@link AbortSignal} is aborted, the returned `Promise` is rejected with its `reason`, but is internally read to prevent unhandled exceptions.
 */
export declare function tickRunner<T = void>(callback: () => T, options?: RunnerOptions): () => Promise<T>;