This proposal specifies how cancelation is triggered, handled and propagated in a Promises/A+ promise library.
In addition to the terminology from Promises/A+ we use the following:
OperationCanceled
is an error used to reject canceled promises.- "direct cancelation" is when a promise or resolver is canceled by the consumer of the promise calling
cancel
. - "indirect cancelation" is when a promise is canceled as the result of another promise that was waiting on it being directly or indirectly canceled.
When a promise is directly canceled it is rejected with an OperationCanceled
error. This error must obey the following points:
- It must be an instance of error (
error instanceof Error === true
). - It must have a
name
property with value"OperationCanceled"
.
When the cancel
method is called on a promise or resolver it is directly canceled. The cancel
method accepts one argument:
promise.cancel(options);
resolver.cancel(options);
- The promise or resolver must be rejected with an
OperationCanceled
error. options
is optional.- If
options
is notnull
or of typeobject
its properties, except forname
, are copied onto theOperationCanceled
error. cancel
returns a promise:- The promise is fulfilled with
undefined
once allonCanceled
callbacks are complete, - or is rejected with the first exception thrown by the callbacks, if any.
- The promise is fulfilled with
- Resolvers must detect when a derived promise is canceled [3.1].
- Resolvers may directly cancel themselves if the only derived and pending promise is canceled (directly or indirectly).
An onCanceled
callback can be added to the resolver in an implementation specific way. The onCanceled
callback accepts one argument, the resolver itself.
- When a resolver is directly canceled, the resolver for that promise must invoke its
onCanceled
callback. - The
onCanceled
callback must be ignored if it's not a function. - The first argument to the callback must be the resolver itself.
- In practical terms, an implementation may provide a
cancel
method on its derived promises that notifies the resolver when that promise is canceled.