/**
 *
 * A module containing promise-related utility types and functions
 *
 * @packageDocumentation
 * @module promise
 */
/**
 * Signature for a function that will perform some arbitrary promise-related cleanup task, like removing one or
 * more event listeners from an EventEmitter.
 */
export type PromiseCleanupFunctor = () => void;
/**
 * A helper function that takes a promise and creates a wrapper promise that invokes a cleanup function when the inner
 * promise is completed for any reason.  The primary use is to remove event listeners related to promise completion
 * when the promise actually completes.  This allows us to keep the number of listeners on a CancelController bounded by
 * the number of incomplete promises associated with it.  If we didn't clean up, the listener set would grow
 * without limit.
 *
 * For cancellation, this leads to an internal usage pattern that is strongly recommended:
 *
 * ```
 * async doSomethingCancellable(...) : Promise<...> {
 *    removeListenerFunctor = undefined;
 *
 *    innerPromise = new Promise(async (resolve, reject) => {
 *       ...
 *
 *       cancelListenerFunction = () => { clean up and reject innerPromise };
 *       removeListenerFunctor = cancelController.addListener(cancelListenerFunction);
 *
 *       ...
 *    }
 *
 *    return makeSelfCleaningPromise(innerPromise, removeListenerFunctor);
 * }
 * ```
 *
 * @param promise promise to wrap with automatic cleanup
 * @param cleaner cleaner function to invoke when the promise is completed
 *
 * @return a promise with matching result/err, that invokes the cleaner function on inner promise completion
 */
export declare function makeSelfCleaningPromise<ResultType>(promise: Promise<ResultType>, cleaner?: PromiseCleanupFunctor): Promise<ResultType>;
/**
 * Generic type signature for a promise resolution function
 */
export type LiftedResolver<ResultType> = (value: ResultType) => void;
/**
 * Generic type signature for a promise rejection function
 */
export type LiftedRejecter = (error?: any) => void;
/**
 * A promise variant that makes the resolve and reject functions available for external invocations.
 *
 * Useful for situations where you want to await for something that might never complete while still allowing
 * the promise to be cancellable.
 *
 * You get around the potentially infinite await by not awaiting at all and instead letting external events trigger
 * resolve and reject (in particular, CancelController).
 */
export interface LiftedPromise<ResultType> {
    /**
     * The actual promise whose resolve and reject methods have been exposed.
     */
    promise: Promise<ResultType>;
    /**
     * Resolve function for the associated promise
     */
    resolve: LiftedResolver<ResultType>;
    /**
     * Reject function for the associated promise
     */
    reject: LiftedRejecter;
}
/**
 * Factory function to create a new LiftedPromise
 *
 * @param promiseBody optional body function to invoke as part of promise creation
 *
 * @return a promise whose resolve and reject methods have been lifted out of the internal body function and made
 * available to external actors
 */
export declare function newLiftedPromise<ResultType>(promiseBody?: (resolve: LiftedResolver<ResultType>, reject: LiftedRejecter) => void): LiftedPromise<ResultType>;