This proposal clarifies the behavioral clauses of the Promises/A proposal, extending it to cover de facto behaviors and omitting parts that are underspecified or problematic.
As with Promises/A, this proposal does not deal with how to create, fulfill, or reject promises.
For a full description of the differences between Promises/A+ and Promises/A, see Differences from Promises/A.
A promise represents a value that may not be available yet. The primary method for interacting with a promise is its
undefinedor a promise).
===), but does not imply deep immutability.
A promise must be in one of three states: pending, fulfilled, or rejected.
When in pending, a promise:
When in fulfilled, a promise:
When in rejected, a promise:
A promise must provide a
then method to access its current or eventual fulfillment value or rejection reason.
then method accepts two arguments:
onRejected are optional arguments:
onFulfilledis not a function, it must be ignored.
onRejectedis not a function, it must be ignored.
onFulfilled is a function:
promiseis fulfilled, with
promise’s fulfillment value as its first argument.
onRejectedhas been called.
onRejected is a function,
promiseis rejected, with
promise’s rejection reason as its first argument.
onFulfilledhas been called.
then must return before
onRejected is called 4.1.
then may be called multiple times on the same promise.
promiseis fulfilled, respective
onFulfilledcallbacks must execute in the order of their originating calls to
promiseis rejected, respective
onRejectedcallbacks must execute in the order of their originating calls to
then must return a promise 4.2.
promise2 = promise1.then(onFulfilled, onRejected);
onRejected returns a value that is not a promise,
promise2 must be fulfilled with that value.
onRejected throws an exception,
promise2 must be rejected with the thrown exception as the reason.
onRejected returns a promise (call it
promise2 must assume the state of
promise2must remain pending until
returnedPromiseis fulfilled or rejected.
promise2must be fulfilled with the same value.
promise2must be rejected with the same reason.
onFulfilled is not a function and
promise1 is fulfilled,
promise2 must be fulfilled with the same value.
onRejected is not a function and
promise1 is rejected,
promise2 must be rejected with the same reason.
In practical terms, an implementation must use a mechanism such as
process.nextTick to ensure that
onRejected are not invoked in the same turn of the event loop as the call to
then to which they are passed.
Implementations may allow
promise2 === promise1, provided the implementation meets all requirements. Each implementation should document whether it can produce
promise2 === promise1 and under what conditions.
The mechanism by which
promise2 assumes the state of
returnedPromise is not specified. One reasonable approach is to call
returnedPromise.then(fulfillPromise2, rejectPromise2), where:
fulfillPromise2is a function which fulfills
promise2with its first parameter.
rejectPromise2is a function which rejects
promise2with its first parameter.
returnedPromise may not be Promises/A+-compliant, but could instead be any object with a
then method, it isn’t always possible to satisfy the requirement of
promise2 assuming the same state as
returnedPromise. Thus, the procedure here represents a best-faith effort.
To the extent possible under law, the Promises/A+ organization has waived all copyright and related or neighboring rights to Promises/A+ Promise Specification. This work is published from: United States.