Cancelation/A+ Draft B

gistfile1.md

Cancelation/A+

This proposal specifies how cancelation is triggered, handled and propagated in a Promises/A+ promise library.

Terminology

In addition to the terminology from Promises/A+ we use the following:

1. OperationCanceled is an error used to reject canceled promises.
2. "direct cancelation" is when a promise or resolver is canceled by the consumer of the promise calling cancel.
3. "indirect cancelation" is when a promise is canceled as the result of another promise that was waiting on it being directly or indirectly canceled.

Requirements

The OperationCanceled Error

When a promise is directly canceled it is rejected with an OperationCanceled error. This error must obey the following points:

1. It must be an instance of error (error instanceof Error === true).
2. It must have a name property with value "OperationCanceled".

The cancel Method

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);

1. The promise or resolver must be rejected with an OperationCanceled error.
2. options is optional.
3. If options is not null or of type object its properties, except for name, are copied onto the OperationCanceled error.
4. cancel returns a promise:
   1. The promise is fulfilled with undefined once all onCanceled callbacks are complete,
   2. or is rejected with the first exception thrown by the callbacks, if any.

Indirect cancelation

1. Resolvers must detect when a derived promise is canceled [3.1].
2. Resolvers may directly cancel themselves if the only derived and pending promise is canceled (directly or indirectly).

The onCanceled Callback

An onCanceled callback can be added to the resolver in an implementation specific way. The onCanceled callback accepts one argument, the resolver itself.

1. When a resolver is directly canceled, the resolver for that promise must invoke its onCanceled callback.
2. The onCanceled callback must be ignored if it's not a function.
3. The first argument to the callback must be the resolver itself.

Notes

1. In practical terms, an implementation may provide a cancel method on its derived promises that notifies the resolver when that promise is canceled.