File Explorer

1/// <reference types="node" />2/**3 *4 * A module containing support for cancelling asynchronous operations5 *6 * @packageDocumentation7 * @module cancel8 */9import { EventEmitter } from "events";10import * as promise from "./promise";11/**12 * Callback signature for when cancel() has been invoked on a CancelController13 */14export type CancelListener = () => void;15/**16 * Abstract interface for an object capable of cancelling asynchronous operations.17 *18 * Modern browsers and Node 15+ include an AbortController which essentially does the same thing.  But our baseline19 * is still node 10, so we provide our own implementation.  Also, Abort is, unfortunately, a problematic term, so we20 * stick to Cancel.21 */22export interface ICancelController {23    /**24     * API to invoke to cancel all asynchronous operations connected to this controller25     */26    cancel(): void;27    /**28     * Checks whether or not the controller is in the cancelled state29     */30    hasBeenCancelled(): boolean;31    /**32     * Registers a callback to be notified when cancel() is invoked externally.  In general, the callback33     * will cancel an asynchronous operation by rejecting the associated promise.34     *35     * IMPORTANT: The listener is invoked synchronously if the controller has already been cancelled.36     *37     * @param listener - function to invoke on cancel; invoked synchronously if the controller has already been38     * cancelled39     *40     * @return undefined if the controller has already been cancelled, otherwise a function object whose invocation41     * will remove the listener from the controller's event emitter.42     *43     */44    addListener(listener: CancelListener): promise.PromiseCleanupFunctor | undefined;45}46export declare const EVENT_NAME = "cancelled";47/**48 * Signature for a factory function that can create EventEmitter objects49 */50export type EventEmitterFactory = () => EventEmitter;51/**52 * Configuration options for the CRT implementation of ICancelController53 */54export interface CancelControllerOptions {55    /**56     * Event emitters have, by default, a small maximum number of listeners.  When that default is insufficient for57     * a use case, this factory option allows for customization of how the internal event emitter is created.58     */59    emitterFactory?: EventEmitterFactory;60}61/**62 * CRT implementation of the ICancelController interface63 */64export declare class CancelController implements ICancelController {65    private cancelled;66    private emitter;67    constructor(options?: CancelControllerOptions);68    /**69     * Cancels all asynchronous operations associated with this controller70     */71    cancel(): void;72    /**73     * Checks whether or not the controller is in the cancelled state74     */75    hasBeenCancelled(): boolean;76    /**77     * Registers a callback to be notified when cancel() is invoked externally.  In general, the callback78     * will cancel an asynchronous operation by rejecting the associated promise.79     *80     * IMPORTANT: The listener is invoked synchronously if the controller has already been cancelled.81     *82     * @param listener - function to invoke on cancel; invoked synchronously if the controller has been cancelled83     *84     * @return undefined if the controller has already been cancelled, otherwise a function object whose invocation85     * will remove the listener from the controller's event emitter.86     *87     */88    addListener(listener: CancelListener): promise.PromiseCleanupFunctor | undefined;89}90/**91 * Configuration options for creating a promise that can be rejected by cancellation and resolved by the receipt92 * of an event from an EventEmitter.93 */94export interface CancellableNextEventPromiseOptions<ResultType> {95    /**96     * Optional cancel controller that can cancel the created promise97     */98    cancelController?: ICancelController;99    /**100     * Event emitter to listen to for potential promise completion101     */102    emitter: EventEmitter;103    /**104     * Name of the event to listen on for potential promise completion105     */106    eventName: string;107    /**108     * Optional transformation function for the event payload109     */110    eventDataTransformer?: (eventData: any) => ResultType;111    /**112     * Message to reject the promise with if cancellation is invoked113     */114    cancelMessage?: string;115}116/**117 * Creates a promise that can be rejected by a CancelController and resolved by the receipt of an event from an118 * EventEmitter.119 *120 * @param config promise creation options121 */122export declare function newCancellablePromiseFromNextEvent<ResultType>(config: CancellableNextEventPromiseOptions<ResultType>): Promise<ResultType>;123