A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its
then method, which registers callbacks to receive either a promise’s eventual value or the reason why the promise cannot be fulfilled.
This specification details the behavior of the
then method, providing an interoperable base which all Promises/A+ conformant promise implementations can be depended on to provide. As such, the specification should be considered very stable. Although the Promises/A+ organization may occasionally revise this specification with minor backward-compatible changes to address newly-discovered corner cases, we will integrate large or backward-incompatible only after careful consideration, discussion, and testing.
Historically, Promises/A+ clarifies the behavioral clauses of the earlier Promises/A proposal, extending it to cover de facto behaviors and omitting parts that are underspecified or problematic.
Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable
then method. Future work in companion specifications may touch on these subjects.
thenmethod whose behavior conforms to this specification.
undefined, a thenable, or a promise).
A promise must be in one of three states: pending, fulfilled, or rejected.
Here, “must not change” means immutable identity (i.e.
===), but does not imply deep immutability.
A promise must provide a
then method to access its current or eventual value or reason.
then method accepts two arguments:
onRejectedare optional arguments:
onFulfilledis not a function, it must be ignored.
onRejectedis not a function, it must be ignored.
onFulfilledis a function:
promiseis fulfilled, with
promise’s value as its first argument.
onRejectedis a function,
promiseis rejected, with
promise’s reason as its first argument.
onRejectedmust not be called until the execution context stack contains only platform code. [3.1].
onRejectedmust be called as functions (i.e. with no
thenmay be called multiple times on the same promise.
promiseis fulfilled, all respective
onFulfilledcallbacks must execute in the order of their originating calls to
promiseis rejected, all respective
onRejectedcallbacks must execute in the order of their originating calls to
then must return a promise [3.3].
promise2 = promise1.then(onFulfilled, onRejected);
onRejectedreturns a value
x, run the Promise Resolution Procedure
onRejectedthrows an exception
promise2must be rejected with
eas the reason.
onFulfilledis not a function and
promise2must be fulfilled with the same value as
onRejectedis not a function and
promise2must be rejected with the same reason as
The promise resolution procedure is an abstract operation taking as input a promise and a value, which we denote as
[[Resolve]](promise, x). If
x is a thenable, it attempts to make
promise adopt the state of
x, under the assumption that
x behaves at least somewhat like a promise. Otherwise, it fulfills
promise with the value
This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliant
then method. It also allows Promises/A+ implementations to “assimilate” nonconformant implementations with reasonable
[[Resolve]](promise, x), perform the following steps:
xrefer to the same object, reject
TypeErroras the reason.
xis a promise, adopt its state [3.4]:
promisemust remain pending until
xis fulfilled or rejected.
xis fulfilled, fulfill
promisewith the same value.
xis rejected, reject
promisewith the same reason.
xis an object or function,
x.thenresults in a thrown exception
eas the reason.
thenis a function, call it with
this, first argument
resolvePromise, and second argument
resolvePromiseis called with a value
rejectPromiseis called with a reason
rejectPromiseare called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.
thenthrows an exception
rejectPromisehave been called, ignore it.
eas the reason.
thenis not a function, fulfill
xis not an object or function, fulfill
If a promise is resolved with a thenable that participates in a circular thenable chain, such that the recursive nature of
[[Resolve]](promise, thenable) eventually causes
[[Resolve]](promise, thenable) to be called again, following the above algorithm will lead to infinite recursion. Implementations are encouraged, but not required, to detect such recursion and reject
promise with an informative
TypeError as the reason. [3.6]
Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures that
onRejected execute asynchronously, after the event loop turn in which
then is called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such as
setImmediate, or with a “micro-task” mechanism such as
process.nextTick. Since the promise implementation is considered platform code, it may itself contain a task-scheduling queue or “trampoline” in which the handlers are called.
That is, in strict mode
this will be
undefined inside of them; in sloppy mode, it will be the global object.
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.
Generally, it will only be known that
x is a true promise if it comes from the current implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant promises.
This procedure of first storing a reference to
x.then, then testing that reference, and then calling that reference, avoids multiple accesses to the
x.then property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.
Implementations should not set arbitrary limits on the depth of thenable chains, and assume that beyond that arbitrary limit the recursion will be infinite. Only true cycles should lead to a
TypeError; if an infinite chain of distinct thenables is encountered, recursing forever is the correct behavior.
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.