An open standard for sound, interoperable JavaScript promises—by implementers, for implementers.
Apromiserepresents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through itsthen
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 thethen
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 changes only after careful consideration, discussion, and testing.
Historically, Promises/A+ clarifies the behavioral clauses of the earlierPromises/A proposal,extending it to coverde factobehaviors 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 interoperablethen
method. Future work in companion specifications may touch on these subjects.
then
method whose behavior conforms to this specification.then
method.undefined
,a thenable, or a promise).throw
statement.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.
then
MethodA promise must provide athen
method to access its current or eventual value or reason.
A promise’sthen
method accepts two arguments:
promise.then(onFulfilled,onRejected)
onFulfilled
andonRejected
are optional arguments:
onFulfilled
is not a function, it must be ignored.onRejected
is not a function, it must be ignored.onFulfilled
is a function:
promise
is fulfilled, withpromise
’s value as its first argument.promise
is fulfilled.onRejected
is a function,
promise
is rejected, withpromise
’s reason as its first argument.promise
is rejected.onFulfilled
oronRejected
must not be called until theexecution contextstack contains only platform code. [3.1].onFulfilled
andonRejected
must be called as functions (i.e. with nothis
value). [3.2]then
may be called multiple times on the same promise.
promise
is fulfilled, all respectiveonFulfilled
callbacks must execute in the order of their originating calls tothen
.promise
is rejected, all respectiveonRejected
callbacks must execute in the order of their originating calls tothen
.then
must return a promise [3.3].
promise2=promise1.then(onFulfilled,onRejected);
onFulfilled
oronRejected
returns a valuex
,run the Promise Resolution Procedure[[Resolve]](promise2, x)
.onFulfilled
oronRejected
throws an exceptione
,promise2
must be rejected withe
as the reason.onFulfilled
is not a function andpromise1
is fulfilled,promise2
must be fulfilled with the same value aspromise1
.onRejected
is not a function andpromise1
is rejected,promise2
must be rejected with the same reason aspromise1
.Thepromise resolution procedureis an abstract operation taking as input a promise and a value, which we denote as[[Resolve]](promise, x)
.Ifx
is a thenable, it attempts to makepromise
adopt the state ofx
,under the assumption thatx
behaves at least somewhat like a promise. Otherwise, it fulfillspromise
with the valuex
.
This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliantthen
method. It also allows Promises/A+ implementations to “assimilate” nonconformant implementations with reasonablethen
methods.
To run[[Resolve]](promise, x)
,perform the following steps:
promise
andx
refer to the same object, rejectpromise
with aTypeError
as the reason.x
is a promise, adopt its state [3.4]:
x
is pending,promise
must remain pending untilx
is fulfilled or rejected.x
is fulfilled, fulfillpromise
with the same value.x
is rejected, rejectpromise
with the same reason.x
is an object or function,
then
bex.then
.[3.5]x.then
results in a thrown exceptione
,rejectpromise
withe
as the reason.then
is a function, call it withx
asthis
,first argumentresolvePromise
,and second argumentrejectPromise
,where:
resolvePromise
is called with a valuey
,run[[Resolve]](promise, y)
.rejectPromise
is called with a reasonr
,rejectpromise
withr
.resolvePromise
andrejectPromise
are called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.then
throws an exceptione
,
resolvePromise
orrejectPromise
have been called, ignore it.promise
withe
as the reason.then
is not a function, fulfillpromise
withx
.x
is not an object or function, fulfillpromise
withx
.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 rejectpromise
with an informativeTypeError
as the reason. [3.6]
Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures thatonFulfilled
andonRejected
execute asynchronously, after the event loop turn in whichthen
is called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such assetTimeout
orsetImmediate
,or with a “micro-task” mechanism such asMutationObserver
orprocess.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 modethis
will beundefined
inside of them; in sloppy mode, it will be the global object.
Implementations may allowpromise2 === promise1
,provided the implementation meets all requirements. Each implementation should document whether it can producepromise2 === promise1
and under what conditions.
Generally, it will only be known thatx
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 tox.then
,then testing that reference, and then calling that reference, avoids multiple accesses to thex.then
property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.
Implementations shouldnotset 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 aTypeError
;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.