File Explorer

1/*2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.3 * SPDX-License-Identifier: Apache-2.0.4 */5 6/**7 *8 * A module containing promise-related utility types and functions9 *10 * @packageDocumentation11 * @module promise12 */13 14/**15 * Signature for a function that will perform some arbitrary promise-related cleanup task, like removing one or16 * more event listeners from an EventEmitter.17 */18export type PromiseCleanupFunctor = () => void;19 20/**21 * A helper function that takes a promise and creates a wrapper promise that invokes a cleanup function when the inner22 * promise is completed for any reason.  The primary use is to remove event listeners related to promise completion23 * when the promise actually completes.  This allows us to keep the number of listeners on a CancelController bounded by24 * the number of incomplete promises associated with it.  If we didn't clean up, the listener set would grow25 * without limit.26 *27 * For cancellation, this leads to an internal usage pattern that is strongly recommended:28 *29 * ```30 * async doSomethingCancellable(...) : Promise<...> {31 *    removeListenerFunctor = undefined;32 *33 *    innerPromise = new Promise(async (resolve, reject) => {34 *       ...35 *36 *       cancelListenerFunction = () => { clean up and reject innerPromise };37 *       removeListenerFunctor = cancelController.addListener(cancelListenerFunction);38 *39 *       ...40 *    }41 *42 *    return makeSelfCleaningPromise(innerPromise, removeListenerFunctor);43 * }44 * ```45 *46 * @param promise promise to wrap with automatic cleanup47 * @param cleaner cleaner function to invoke when the promise is completed48 *49 * @return a promise with matching result/err, that invokes the cleaner function on inner promise completion50 */51export function makeSelfCleaningPromise<ResultType>(promise: Promise<ResultType>, cleaner? : PromiseCleanupFunctor) : Promise<ResultType> {52    if (!cleaner) {53        return promise;54    }55 56    return promise.finally(() => { cleaner(); });57}58 59/**60 * Generic type signature for a promise resolution function61 */62export type LiftedResolver<ResultType> = (value : ResultType) => void;63 64/**65 * Generic type signature for a promise rejection function66 */67export type LiftedRejecter = (error? : any) => void;68 69/**70 * A promise variant that makes the resolve and reject functions available for external invocations.71 *72 * Useful for situations where you want to await for something that might never complete while still allowing73 * the promise to be cancellable.74 *75 * You get around the potentially infinite await by not awaiting at all and instead letting external events trigger76 * resolve and reject (in particular, CancelController).77 */78export interface LiftedPromise<ResultType> {79 80    /**81     * The actual promise whose resolve and reject methods have been exposed.82     */83    promise: Promise<ResultType>;84 85    /**86     * Resolve function for the associated promise87     */88    resolve: LiftedResolver<ResultType>;89 90    /**91     * Reject function for the associated promise92     */93    reject: LiftedRejecter;94}95 96/**97 * Factory function to create a new LiftedPromise98 *99 * @param promiseBody optional body function to invoke as part of promise creation100 *101 * @return a promise whose resolve and reject methods have been lifted out of the internal body function and made102 * available to external actors103 */104export function newLiftedPromise<ResultType>(promiseBody?: (resolve : LiftedResolver<ResultType>, reject : LiftedRejecter) => void) : LiftedPromise<ResultType> {105    let localResolve : LiftedResolver<ResultType> | undefined = undefined;106    let localReject : LiftedRejecter | undefined = undefined;107 108    let promise = new Promise<ResultType>((resolve, reject) => {109        localResolve = resolve;110        localReject = reject;111    });112 113    if (!localResolve || !localReject) {114        // should never happen115        throw new Error("Failed to bind resolve and reject when making lifted promise");116    }117 118    if (promiseBody) {119        promiseBody(localResolve, localReject);120    }121 122    return {123        promise : promise,124        resolve: localResolve,125        reject : localReject126    };127}128 129 130