File Explorer

1/**2 *3 * A module containing promise-related utility types and functions4 *5 * @packageDocumentation6 * @module promise7 */8/**9 * Signature for a function that will perform some arbitrary promise-related cleanup task, like removing one or10 * more event listeners from an EventEmitter.11 */12export type PromiseCleanupFunctor = () => void;13/**14 * A helper function that takes a promise and creates a wrapper promise that invokes a cleanup function when the inner15 * promise is completed for any reason.  The primary use is to remove event listeners related to promise completion16 * when the promise actually completes.  This allows us to keep the number of listeners on a CancelController bounded by17 * the number of incomplete promises associated with it.  If we didn't clean up, the listener set would grow18 * without limit.19 *20 * For cancellation, this leads to an internal usage pattern that is strongly recommended:21 *22 * ```23 * async doSomethingCancellable(...) : Promise<...> {24 *    removeListenerFunctor = undefined;25 *26 *    innerPromise = new Promise(async (resolve, reject) => {27 *       ...28 *29 *       cancelListenerFunction = () => { clean up and reject innerPromise };30 *       removeListenerFunctor = cancelController.addListener(cancelListenerFunction);31 *32 *       ...33 *    }34 *35 *    return makeSelfCleaningPromise(innerPromise, removeListenerFunctor);36 * }37 * ```38 *39 * @param promise promise to wrap with automatic cleanup40 * @param cleaner cleaner function to invoke when the promise is completed41 *42 * @return a promise with matching result/err, that invokes the cleaner function on inner promise completion43 */44export declare function makeSelfCleaningPromise<ResultType>(promise: Promise<ResultType>, cleaner?: PromiseCleanupFunctor): Promise<ResultType>;45/**46 * Generic type signature for a promise resolution function47 */48export type LiftedResolver<ResultType> = (value: ResultType) => void;49/**50 * Generic type signature for a promise rejection function51 */52export type LiftedRejecter = (error?: any) => void;53/**54 * A promise variant that makes the resolve and reject functions available for external invocations.55 *56 * Useful for situations where you want to await for something that might never complete while still allowing57 * the promise to be cancellable.58 *59 * You get around the potentially infinite await by not awaiting at all and instead letting external events trigger60 * resolve and reject (in particular, CancelController).61 */62export interface LiftedPromise<ResultType> {63    /**64     * The actual promise whose resolve and reject methods have been exposed.65     */66    promise: Promise<ResultType>;67    /**68     * Resolve function for the associated promise69     */70    resolve: LiftedResolver<ResultType>;71    /**72     * Reject function for the associated promise73     */74    reject: LiftedRejecter;75}76/**77 * Factory function to create a new LiftedPromise78 *79 * @param promiseBody optional body function to invoke as part of promise creation80 *81 * @return a promise whose resolve and reject methods have been lifted out of the internal body function and made82 * available to external actors83 */84export declare function newLiftedPromise<ResultType>(promiseBody?: (resolve: LiftedResolver<ResultType>, reject: LiftedRejecter) => void): LiftedPromise<ResultType>;85