Promises/A+

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 itsthenmethod, 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 thethenmethod, 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 interoperablethenmethod. Future work in companion specifications may touch on these subjects.

Terminology

“promise” is an object or function with athenmethod whose behavior conforms to this specification.
“thenable” is an object or function that defines athenmethod.
“value” is any legal JavaScript value (includingundefined,a thenable, or a promise).
“exception” is a value that is thrown using thethrowstatement.
“reason” is a value that indicates why a promise was rejected.

Requirements

Promise States

A promise must be in one of three states: pending, fulfilled, or rejected.

When pending, a promise:
1. may transition to either the fulfilled or rejected state.
When fulfilled, a promise:
1. must not transition to any other state.
2. must have a value, which must not change.
When rejected, a promise:
1. must not transition to any other state.
2. must have a reason, which must not change.

Here, “must not change” means immutable identity (i.e.===), but does not imply deep immutability.

The`then`Method

A promise must provide athenmethod to access its current or eventual value or reason.

A promise’sthenmethod accepts two arguments:

promise.then(onFulfilled,onRejected)

BothonFulfilledandonRejectedare optional arguments:
1. IfonFulfilledis not a function, it must be ignored.
2. IfonRejectedis not a function, it must be ignored.
IfonFulfilledis a function:
1. it must be called afterpromiseis fulfilled, withpromise’s value as its first argument.
2. it must not be called beforepromiseis fulfilled.
3. it must not be called more than once.
IfonRejectedis a function,
1. it must be called afterpromiseis rejected, withpromise’s reason as its first argument.
2. it must not be called beforepromiseis rejected.
3. it must not be called more than once.
onFulfilledoronRejectedmust not be called until theexecution contextstack contains only platform code. [3.1].
onFulfilledandonRejectedmust be called as functions (i.e. with nothisvalue). [3.2]
thenmay be called multiple times on the same promise.
1. If/whenpromiseis fulfilled, all respectiveonFulfilledcallbacks must execute in the order of their originating calls tothen.
2. If/whenpromiseis rejected, all respectiveonRejectedcallbacks must execute in the order of their originating calls tothen.
thenmust return a promise [3.3].
```
promise2=promise1.then(onFulfilled,onRejected);
```
1. If eitheronFulfilledoronRejectedreturns a valuex,run the Promise Resolution Procedure[[Resolve]](promise2, x).
2. If eitheronFulfilledoronRejectedthrows an exceptione,promise2must be rejected witheas the reason.
3. IfonFulfilledis not a function andpromise1is fulfilled,promise2must be fulfilled with the same value aspromise1.
4. IfonRejectedis not a function andpromise1is rejected,promise2must be rejected with the same reason aspromise1.

The Promise Resolution Procedure

Thepromise resolution procedureis an abstract operation taking as input a promise and a value, which we denote as[[Resolve]](promise, x).Ifxis a thenable, it attempts to makepromiseadopt the state ofx,under the assumption thatxbehaves at least somewhat like a promise. Otherwise, it fulfillspromisewith the valuex.

This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliantthenmethod. It also allows Promises/A+ implementations to “assimilate” nonconformant implementations with reasonablethenmethods.

To run[[Resolve]](promise, x),perform the following steps:

Ifpromiseandxrefer to the same object, rejectpromisewith aTypeErroras the reason.
Ifxis a promise, adopt its state [3.4]:
1. Ifxis pending,promisemust remain pending untilxis fulfilled or rejected.
2. If/whenxis fulfilled, fulfillpromisewith the same value.
3. If/whenxis rejected, rejectpromisewith the same reason.
Otherwise, ifxis an object or function,
1. Letthenbex.then.[3.5]
2. If retrieving the propertyx.thenresults in a thrown exceptione,rejectpromisewitheas the reason.
3. Ifthenis a function, call it withxasthis,first argumentresolvePromise,and second argumentrejectPromise,where:
  1. If/whenresolvePromiseis called with a valuey,run[[Resolve]](promise, y).
  2. If/whenrejectPromiseis called with a reasonr,rejectpromisewithr.
  3. If bothresolvePromiseandrejectPromiseare called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.
  4. If callingthenthrows an exceptione,
    1. IfresolvePromiseorrejectPromisehave been called, ignore it.
    2. Otherwise, rejectpromisewitheas the reason.
4. Ifthenis not a function, fulfillpromisewithx.
Ifxis not an object or function, fulfillpromisewithx.

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 rejectpromisewith an informativeTypeErroras the reason. [3.6]

Notes

Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures thatonFulfilledandonRejectedexecute asynchronously, after the event loop turn in whichthenis called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such assetTimeoutorsetImmediate,or with a “micro-task” mechanism such asMutationObserverorprocess.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 modethiswill beundefinedinside 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 === promise1and under what conditions.
Generally, it will only be known thatxis 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.thenproperty. 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.