This is a work-in-progress repository for a proposal for adding cancelable promises to JavaScript. Per the May 2016 TC39 meeting, it is currently at Stage 1, and under heavy development. You can view the in-progress spec draft and take part in the discussions on the issue tracker.
In general, many of the async operations undertaken by JavaScript code should be cancelable. That is, the developer should have the ability to request the cessation of any ongoing work, as they no longer care about the result. Examples, many from the web platform, include:
- The Fetch API
- Every other API that performs a fetch (i.e. loads a resource)
- Canceling an in-progress animation
- Consuming streams, such as by piping them together
- Long-running off-main-thread computational operations (e.g. cryptography)
- Asking the user for permission
- Async iteration or observation
The majority of these async operations are already represented by promises, JavaScript's natural asynchronous type. Thus, we seek a mechanism for cancelation that integrates well with promises; we call this "cancelable promises."
The proposal has two main parts: how to represent cancelation, and how to initiate cancelation
A canceled operation is not "successful", but it did not really "fail" either. We want cancelation to propagate in the same way as an exception, but it is not an error.
In order for this proposal to gain consensus, cancelations must be caught by catch blocks; we cannot treat cancelations as a new completion type which skips catch blocks and only triggers finally. However, it's important that they be distinguished objects which are in general treated differently. Top-level error handling and unhandled promise rejection tracking should ignore cancelations, and it should be syntactically easy to catch everything but cancelations.
The reasoning behind this is spelled out in more detail in the ["Not an Error"](Not an Error.md) document. This proposal concretely includes:
- A new class,
Cancel, which does not derive fromError. - Special-case handling of
Cancelinstances in both synchronous error reporting and asynchronous rejection tracking - New syntax,
try { ... } else (e) { ... }, which ignores instances ofCancel. - A new Promise method,
promise.else(onRejected), which ignores instances ofCancel.
Cancel tokens provide a standard way to cancel any API, especially asynchronous ones. The standard usage is:
const cancelToken = new CancelToken(cancel => {
cancelButton.onclick = () => cancel("The cancel button was clicked");
});
performCancelableOperation(cancelToken);The cancel tokens of this proposal are heavily inspired by Kevin Smith's design sketch, which are in turn inspired by the .NET task cancelation architecture. They are discussed further, in much more detail, in ["Cancel Tokens"](Cancel Tokens.md).