123 lines
4.5 KiB
TypeScript
123 lines
4.5 KiB
TypeScript
/// <reference types="node" />
|
|
/**
|
|
*
|
|
* A module containing support for cancelling asynchronous operations
|
|
*
|
|
* @packageDocumentation
|
|
* @module cancel
|
|
*/
|
|
import { EventEmitter } from "events";
|
|
import * as promise from "./promise";
|
|
/**
|
|
* Callback signature for when cancel() has been invoked on a CancelController
|
|
*/
|
|
export type CancelListener = () => void;
|
|
/**
|
|
* Abstract interface for an object capable of cancelling asynchronous operations.
|
|
*
|
|
* Modern browsers and Node 15+ include an AbortController which essentially does the same thing. But our baseline
|
|
* is still node 10, so we provide our own implementation. Also, Abort is, unfortunately, a problematic term, so we
|
|
* stick to Cancel.
|
|
*/
|
|
export interface ICancelController {
|
|
/**
|
|
* API to invoke to cancel all asynchronous operations connected to this controller
|
|
*/
|
|
cancel(): void;
|
|
/**
|
|
* Checks whether or not the controller is in the cancelled state
|
|
*/
|
|
hasBeenCancelled(): boolean;
|
|
/**
|
|
* Registers a callback to be notified when cancel() is invoked externally. In general, the callback
|
|
* will cancel an asynchronous operation by rejecting the associated promise.
|
|
*
|
|
* IMPORTANT: The listener is invoked synchronously if the controller has already been cancelled.
|
|
*
|
|
* @param listener - function to invoke on cancel; invoked synchronously if the controller has already been
|
|
* cancelled
|
|
*
|
|
* @return undefined if the controller has already been cancelled, otherwise a function object whose invocation
|
|
* will remove the listener from the controller's event emitter.
|
|
*
|
|
*/
|
|
addListener(listener: CancelListener): promise.PromiseCleanupFunctor | undefined;
|
|
}
|
|
export declare const EVENT_NAME = "cancelled";
|
|
/**
|
|
* Signature for a factory function that can create EventEmitter objects
|
|
*/
|
|
export type EventEmitterFactory = () => EventEmitter;
|
|
/**
|
|
* Configuration options for the CRT implementation of ICancelController
|
|
*/
|
|
export interface CancelControllerOptions {
|
|
/**
|
|
* Event emitters have, by default, a small maximum number of listeners. When that default is insufficient for
|
|
* a use case, this factory option allows for customization of how the internal event emitter is created.
|
|
*/
|
|
emitterFactory?: EventEmitterFactory;
|
|
}
|
|
/**
|
|
* CRT implementation of the ICancelController interface
|
|
*/
|
|
export declare class CancelController implements ICancelController {
|
|
private cancelled;
|
|
private emitter;
|
|
constructor(options?: CancelControllerOptions);
|
|
/**
|
|
* Cancels all asynchronous operations associated with this controller
|
|
*/
|
|
cancel(): void;
|
|
/**
|
|
* Checks whether or not the controller is in the cancelled state
|
|
*/
|
|
hasBeenCancelled(): boolean;
|
|
/**
|
|
* Registers a callback to be notified when cancel() is invoked externally. In general, the callback
|
|
* will cancel an asynchronous operation by rejecting the associated promise.
|
|
*
|
|
* IMPORTANT: The listener is invoked synchronously if the controller has already been cancelled.
|
|
*
|
|
* @param listener - function to invoke on cancel; invoked synchronously if the controller has been cancelled
|
|
*
|
|
* @return undefined if the controller has already been cancelled, otherwise a function object whose invocation
|
|
* will remove the listener from the controller's event emitter.
|
|
*
|
|
*/
|
|
addListener(listener: CancelListener): promise.PromiseCleanupFunctor | undefined;
|
|
}
|
|
/**
|
|
* Configuration options for creating a promise that can be rejected by cancellation and resolved by the receipt
|
|
* of an event from an EventEmitter.
|
|
*/
|
|
export interface CancellableNextEventPromiseOptions<ResultType> {
|
|
/**
|
|
* Optional cancel controller that can cancel the created promise
|
|
*/
|
|
cancelController?: ICancelController;
|
|
/**
|
|
* Event emitter to listen to for potential promise completion
|
|
*/
|
|
emitter: EventEmitter;
|
|
/**
|
|
* Name of the event to listen on for potential promise completion
|
|
*/
|
|
eventName: string;
|
|
/**
|
|
* Optional transformation function for the event payload
|
|
*/
|
|
eventDataTransformer?: (eventData: any) => ResultType;
|
|
/**
|
|
* Message to reject the promise with if cancellation is invoked
|
|
*/
|
|
cancelMessage?: string;
|
|
}
|
|
/**
|
|
* Creates a promise that can be rejected by a CancelController and resolved by the receipt of an event from an
|
|
* EventEmitter.
|
|
*
|
|
* @param config promise creation options
|
|
*/
|
|
export declare function newCancellablePromiseFromNextEvent<ResultType>(config: CancellableNextEventPromiseOptions<ResultType>): Promise<ResultType>;
|