ECMA-262 (12th Edition) ECMAScript 2021 Language Specification

Table 68:

IteratorResult

Interface Properties

Property

Value

Requirements

"done"

Either

true

false

This is the result status of an

iterator

method call. If the end of the iterator was

reached

"done"

true

. If the end was not reached

"done"

false

and a value is available.

If a

"done"

property (either own or inherited) does not exist, it is consider to have the

value

false

"value"

Any

ECMAScript
language
value

If done is

false

, this is the current iteration element value. If done is

true

, this is the return

value of the iterator, if it supplied one. If the iterator does not have a return value,

"value"

undefined

. In that case, the

"value"

property may be absent from the conforming object

if it does not inherit an explicit

"value"

property.

The

%IteratorPrototype%

object:

has a [[Prototype]] internal slot whose value is

%Object.prototype%

is an

ordinary object

NOTE

The following steps are taken:

1. Return the

this

value.

The value of the

"name"

property of this function is

"[Symbol.iterator]"

The

%AsyncIteratorPrototype%

object:

has a [[Prototype]] internal slot whose value is

%Object.prototype%

is an

ordinary object

All objects defined in this specification that implement the Iterator interface also inherit from
%IteratorPrototype%. ECMAScript code may also define objects that inherit from
%IteratorPrototype%. The %IteratorPrototype% object provides a place where additional
methods that are applicable to all iterator objects may be added.

The following expression is one way that ECMAScript code can access the %IteratorPrototype%
object:

Object

.getPrototypeOf(

Object

.getPrototypeOf([][

Symbol

.iterator]()))

27.1.2 The %IteratorPrototype% Object

27.1.2.1 %IteratorPrototype% [ @@iterator ] ( )

27.1.3 The %AsyncIteratorPrototype% Object

752

NOTE

The following steps are taken:

1. Return the

this

value.

The value of the

"name"

property of this function is

"[Symbol.asyncIterator]"

An Async-from-Sync Iterator object is an async iterator that adapts a specific synchronous iterator. There is not a
named

constructor

for Async-from-Sync Iterator objects. Instead, Async-from-Sync iterator objects are created by the

CreateAsyncFromSyncIterator

abstract operation as needed.

The abstract operation CreateAsyncFromSyncIterator takes argument

syncIteratorRecord

. It is used to create an async

iterator

Record

from a synchronous iterator

Record

. It performs the following steps when called:

1. Let

asyncIterator

be !

OrdinaryObjectCreate

(

%AsyncFromSyncIteratorPrototype%

, « [[SyncIteratorRecord]] »).

2. Set

asyncIterator

.[[SyncIteratorRecord]] to

syncIteratorRecord

3. Let

nextMethod

be !

Get

(

asyncIterator

"next"

4. Let

iteratorRecord

be the

Record

{ [[Iterator]]:

asyncIterator

, [[NextMethod]]:

nextMethod

, [[Done]]:

false

5. Return

iteratorRecord

The

%AsyncFromSyncIteratorPrototype%

object:

has properties that are inherited by all Async-from-Sync Iterator Objects.
is an

ordinary object

has a [[Prototype]] internal slot whose value is

%AsyncIteratorPrototype%

has the following properties:

1. Let

be the

this

value.

Assert

Type

(

) is Object and

has a [[SyncIteratorRecord]] internal slot.

3. Let

promiseCapability

be !

NewPromiseCapability

(

%Promise%

4. Let

syncIteratorRecord

.[[SyncIteratorRecord]].

5. If

value

is present, then

a. Let

result

IteratorNext

(

syncIteratorRecord

value

6. Else,

All objects defined in this specification that implement the AsyncIterator interface also inherit
from %AsyncIteratorPrototype%. ECMAScript code may also define objects that inherit from
%AsyncIteratorPrototype%. The %AsyncIteratorPrototype% object provides a place where
additional methods that are applicable to all async iterator objects may be added.

27.1.3.1 %AsyncIteratorPrototype% [ @@asyncIterator ] ( )

27.1.4 Async-from-Sync Iterator Objects

27.1.4.1 CreateAsyncFromSyncIterator (

syncIteratorRecord

)

27.1.4.2 The %AsyncFromSyncIteratorPrototype% Object

27.1.4.2.1 %AsyncFromSyncIteratorPrototype%.next ( [

value

] )

753

a. Let

result

IteratorNext

(

syncIteratorRecord

IfAbruptRejectPromise

(

result

promiseCapability

8. Return !

AsyncFromSyncIteratorContinuation

(

result

promiseCapability

1. Let

be the

this

value.

Assert

Type

(

) is Object and

has a [[SyncIteratorRecord]] internal slot.

3. Let

promiseCapability

be !

NewPromiseCapability

(

%Promise%

4. Let

syncIterator

.[[SyncIteratorRecord]].[[Iterator]].

5. Let

return

GetMethod

(

syncIterator

"return"

IfAbruptRejectPromise

(

return

promiseCapability

7. If

return

undefined

, then

a. Let

iterResult

be !

CreateIterResultObject

(

value

true

b. Perform !

Call

(

promiseCapability

.[[Resolve]],

undefined

, «

iterResult

»).

c. Return

promiseCapability

.[[Promise]].

8. If

value

is present, then

a. Let

result

Call

(

return

syncIterator

, «

value

»).

9. Else,

a. Let

result

Call

(

return

syncIterator

10.

IfAbruptRejectPromise

(

result

promiseCapability

11. If

Type

(

result

) is not Object, then

a. Perform !

Call

(

promiseCapability

.[[Reject]],

undefined

, « a newly created

TypeError

object »).

b. Return

promiseCapability

.[[Promise]].

12. Return !

AsyncFromSyncIteratorContinuation

(

result

promiseCapability

NOTE

1. Let

be the

this

value.

Assert

Type

(

) is Object and

has a [[SyncIteratorRecord]] internal slot.

3. Let

promiseCapability

be !

NewPromiseCapability

(

%Promise%

4. Let

syncIterator

.[[SyncIteratorRecord]].[[Iterator]].

5. Let

throw

GetMethod

(

syncIterator

"throw"

IfAbruptRejectPromise

(

throw

promiseCapability

7. If

throw

undefined

, then

a. Perform !

Call

(

promiseCapability

.[[Reject]],

undefined

, «

value

»).

b. Return

promiseCapability

.[[Promise]].

8. If

value

is present, then

a. Let

result

Call

(

throw

syncIterator

, «

value

»).

9. Else,

a. Let

result

Call

(

throw

syncIterator

10.

IfAbruptRejectPromise

(

result

promiseCapability

11. If

Type

(

result

) is not Object, then

a. Perform !

Call

(

promiseCapability

.[[Reject]],

undefined

, « a newly created

TypeError

object »).

b. Return

promiseCapability

.[[Promise]].

In this specification,

value

is always provided, but is left optional for consistency with

%AsyncFromSyncIteratorPrototype%.return ( [

value

] )

27.1.4.2.2 %AsyncFromSyncIteratorPrototype%.return ( [

value

] )

27.1.4.2.3 %AsyncFromSyncIteratorPrototype%.throw ( [

value

] )

754

12. Return !

AsyncFromSyncIteratorContinuation

(

result

promiseCapability

An async-from-sync iterator value unwrap function is an anonymous built-in function that is used by

AsyncFromSyncIteratorContinuation

when processing the

"value"

property of an

IteratorResult

object, in order to wait

for its value if it is a promise and re-package the result in a new "unwrapped"

IteratorResult

object. Each async-from-

sync iterator value unwrap function has a [[Done]] internal slot.

When an async-from-sync iterator value unwrap function is called with argument

value

, the following steps are taken:

1. Let

be the

active function object

2. Return !

CreateIterResultObject

(

value

.[[Done]]).

Async-from-Sync Iterator instances are ordinary objects that inherit properties from the

%AsyncFromSyncIteratorPrototype%

intrinsic object. Async-from-Sync Iterator instances are initially created with the

internal slots listed in

Table 69

. Async-from-Sync Iterator instances are not directly observable from ECMAScript code.

Table 69: Internal Slots of Async-from-Sync Iterator Instances

Internal Slot

Description

[[SyncIteratorRecord]] A

Record

, of the type returned by

GetIterator

, representing the original synchronous

iterator which is being adapted.

The abstract operation AsyncFromSyncIteratorContinuation takes arguments

result

and

promiseCapability

PromiseCapability Record

). It performs the following steps when called:

1. Let

done

IteratorComplete

(

result

IfAbruptRejectPromise

(

done

promiseCapability

3. Let

value

IteratorValue

(

result

IfAbruptRejectPromise

(

value

promiseCapability

5. Let

valueWrapper

PromiseResolve

(

%Promise%

value

IfAbruptRejectPromise

(

valueWrapper

promiseCapability

7. Let

steps

be the algorithm steps defined in

Async-from-Sync Iterator Value Unwrap Functions

8. Let

length

be the number of non-optional parameters of the function definition in

Async-from-Sync Iterator

Value Unwrap Functions

9. Let

onFulfilled

be !

CreateBuiltinFunction

(

steps

length

, « [[Done]] »).

10. Set

onFulfilled

.[[Done]] to

done

11. Perform !

PerformPromiseThen

(

valueWrapper

onFulfilled

undefined

promiseCapability

12. Return

promiseCapability

.[[Promise]].

A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous)

27.1.4.2.4 Async-from-Sync Iterator Value Unwrap Functions

27.1.4.3 Properties of Async-from-Sync Iterator Instances

27.1.4.4 AsyncFromSyncIteratorContinuation (

result

promiseCapability

)

27.2 Promise Objects

755

computation.

Any Promise object is in one of three mutually exclusive states:

fulfilled

rejected

, and

pending

A promise

is fulfilled if

p.then(f, r)

will immediately enqueue a

Job

to call the function

A promise

is rejected if

p.then(f, r)

will immediately enqueue a

Job

to call the function

A promise is pending if it is neither fulfilled nor rejected.

A promise is said to be

settled

if it is not pending, i.e. if it is either fulfilled or rejected.

A promise is

resolved

if it is settled or if it has been “locked in” to match the state of another promise. Attempting to

resolve or reject a resolved promise has no effect. A promise is

unresolved

if it is not resolved. An unresolved promise is

always in the pending state. A resolved promise may be pending, fulfilled or rejected.

PromiseCapability Record

is a

Record

value used to encapsulate a promise object along with the functions that are

capable of resolving or rejecting that promise object. PromiseCapability Records are produced by the

NewPromiseCapability

abstract operation.

PromiseCapability Records have the fields listed in

Table 70

Table 70:

PromiseCapability Record

Fields

Field Name

Value

Meaning

[[Promise]]

An object

An object that is usable as a promise.

[[Resolve]]

function object

The function that is used to resolve the given promise object.

[[Reject]]

function object

The function that is used to reject the given promise object.

IfAbruptRejectPromise is a shorthand for a sequence of algorithm steps that use a

PromiseCapability Record

. An

algorithm step of the form:

IfAbruptRejectPromise

(

value

capability

means the same thing as:

1. If

value

is an

abrupt completion

, then

a. Perform ?

Call

(

capability

.[[Reject]],

undefined

, «

value

.[[Value]] »).

b. Return

capability

.[[Promise]].

2. Else if

value

is a

Completion Record

, set

value

.[[Value]].

The PromiseReaction is a

Record

value used to store information about how a promise should react when it becomes

resolved or rejected with a given value. PromiseReaction records are created by the

PerformPromiseThen

abstract

27.2.1 Promise Abstract Operations

27.2.1.1 PromiseCapability Records

27.2.1.1.1 IfAbruptRejectPromise (

value

capability

)

27.2.1.2 PromiseReaction Records

756

operation, and are used by the

Abstract Closure

returned by

NewPromiseReactionJob

PromiseReaction records have the fields listed in

Table 71

Table 71: PromiseReaction

Record

Fields

Field Name

Value

Meaning

[[Capability]] A

PromiseCapability
Record

, or

undefined

The capabilities of the promise for which this record provides a reaction
handler.

[[Type]]

Fulfill

Reject

The [[Type]] is used when [[Handler]] is

empty

to allow for behaviour specific to

the settlement type.

[[Handler]]

JobCallback

Record

empty

The function that should be applied to the incoming value, and whose return
value will govern what happens to the derived promise. If [[Handler]] is

empty

a function that depends on the value of [[Type]] will be used instead.

The abstract operation CreateResolvingFunctions takes argument

promise

. It performs the following steps when called:

1. Let

alreadyResolved

be the

Record

{ [[Value]]:

false

2. Let

stepsResolve

be the algorithm steps defined in

Promise Resolve Functions

3. Let

lengthResolve

be the number of non-optional parameters of the function definition in

Promise Resolve

Functions

4. Let

resolve

be !

CreateBuiltinFunction

(

stepsResolve

lengthResolve

, « [[Promise]], [[AlreadyResolved]] »).

5. Set

resolve

.[[Promise]] to

promise

6. Set

resolve

.[[AlreadyResolved]] to

alreadyResolved

7. Let

stepsReject

be the algorithm steps defined in

Promise Reject Functions

8. Let

lengthReject

be the number of non-optional parameters of the function definition in

Promise Reject

Functions

9. Let

reject

be !

CreateBuiltinFunction

(

stepsReject

lengthReject

, « [[Promise]], [[AlreadyResolved]] »).

10. Set

reject

.[[Promise]] to

promise

11. Set

reject

.[[AlreadyResolved]] to

alreadyResolved

12. Return the

Record

{ [[Resolve]]:

resolve

, [[Reject]]:

reject

A promise reject function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal
slots.

When a promise reject function is called with argument

reason

, the following steps are taken:

1. Let

be the

active function object

Assert

has a [[Promise]] internal slot whose value is an Object.

3. Let

promise

.[[Promise]].

4. Let

alreadyResolved

.[[AlreadyResolved]].

5. If

alreadyResolved

.[[Value]] is

true

, return

undefined

27.2.1.3 CreateResolvingFunctions (

promise

)

27.2.1.3.1 Promise Reject Functions

757

6. Set

alreadyResolved

.[[Value]] to

true

7. Return

RejectPromise

(

promise

reason

The

"length"

property of a promise reject function is

𝔽

A promise resolve function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal
slots.

When a promise resolve function is called with argument

resolution

, the following steps are taken:

1. Let

be the

active function object

Assert

has a [[Promise]] internal slot whose value is an Object.

3. Let

promise

.[[Promise]].

4. Let

alreadyResolved

.[[AlreadyResolved]].

5. If

alreadyResolved

.[[Value]] is

true

, return

undefined

6. Set

alreadyResolved

.[[Value]] to

true

7. If

SameValue

(

resolution

promise

) is

true

, then

a. Let

selfResolutionError

be a newly created

TypeError

object.

b. Return

RejectPromise

(

promise

selfResolutionError

8. If

Type

(

resolution

) is not Object, then

a. Return

FulfillPromise

(

promise

resolution

9. Let

then

Get

(

resolution

"then"

10. If

then

is an

a. Return

promise

then

.[[Value]]).

11. Let

thenAction

then

.[[Value]].

12. If

IsCallable

(

thenAction

) is

false

, then

a. Return

FulfillPromise

(

promise

resolution

13. Let

thenJobCallback

HostMakeJobCallback

(

thenAction

14. Let

job

NewPromiseResolveThenableJob

(

promise

resolution

thenJobCallback

15. Perform

HostEnqueuePromiseJob

(

job

.[[Job]],

job

.[[Realm]]).

16. Return

undefined

The

"length"

property of a promise resolve function is

𝔽

The abstract operation FulfillPromise takes arguments

promise

and

value

. It performs the following steps when called:

Assert

: The value of

promise

.[[PromiseState]] is

pending

2. Let

reactions

promise

.[[PromiseFulfillReactions]].

3. Set

promise

.[[PromiseResult]] to

value

4. Set

promise

.[[PromiseFulfillReactions]] to

undefined

5. Set

promise

.[[PromiseRejectReactions]] to

undefined

6. Set

promise

.[[PromiseState]] to

fulfilled

7. Return

TriggerPromiseReactions

(

reactions

value

27.2.1.3.2 Promise Resolve Functions

27.2.1.4 FulfillPromise (

promise

value

)

27.2.1.5 NewPromiseCapability (

)

758

The abstract operation NewPromiseCapability takes argument

. It attempts to use

as a

constructor

in the fashion of

the built-in Promise

constructor

to create a Promise object and extract its

resolve

and

reject

functions. The

Promise object plus the

resolve

and

reject

functions are used to initialize a new

PromiseCapability Record

. It

performs the following steps when called:

1. If

IsConstructor

(

) is

false

, throw a

TypeError

exception.

2. NOTE:

is assumed to be a

constructor

function that supports the parameter conventions of the Promise

constructor

(see

27.2.3.1

3. Let

promiseCapability

be the

PromiseCapability Record

{ [[Promise]]:

undefined

, [[Resolve]]:

undefined

[[Reject]]:

undefined

4. Let

steps

be the algorithm steps defined in

GetCapabilitiesExecutor Functions

5. Let

length

be the number of non-optional parameters of the function definition in

GetCapabilitiesExecutor

Functions

6. Let

executor

be !

CreateBuiltinFunction

(

steps

length

, « [[Capability]] »).

7. Set

executor

.[[Capability]] to

promiseCapability

8. Let

promise

be ?

Construct

(

, «

executor

»).

9. If

IsCallable

(

promiseCapability

.[[Resolve]]) is

false

, throw a

TypeError

exception.

10. If

IsCallable

(

promiseCapability

.[[Reject]]) is

false

, throw a

TypeError

exception.

11. Set

promiseCapability

.[[Promise]] to

promise

12. Return

promiseCapability

NOTE

A GetCapabilitiesExecutor function is an anonymous built-in function that has a [[Capability]] internal slot.

When a GetCapabilitiesExecutor function is called with arguments

resolve

and

reject

, the following steps are taken:

1. Let

be the

active function object

Assert

has a [[Capability]] internal slot whose value is a

PromiseCapability Record

3. Let

promiseCapability

.[[Capability]].

4. If

promiseCapability

.[[Resolve]] is not

undefined

, throw a

TypeError

exception.

5. If

promiseCapability

.[[Reject]] is not

undefined

, throw a

TypeError

exception.

6. Set

promiseCapability

.[[Resolve]] to

resolve

7. Set

promiseCapability

.[[Reject]] to

reject

8. Return

undefined

The

"length"

property of a GetCapabilitiesExecutor function is

𝔽

The abstract operation IsPromise takes argument

. It checks for the promise brand on an object. It performs the

following steps when called:

1. If

Type

(

) is not Object, return

false

2. If

does not have a [[PromiseState]] internal slot, return

false

This abstract operation supports Promise subclassing, as it is generic on any

constructor

that calls

a passed executor function argument in the same way as the Promise

constructor

. It is used to

generalize static methods of the Promise

constructor

to any subclass.

27.2.1.5.1 GetCapabilitiesExecutor Functions

27.2.1.6 IsPromise (

)

759

3. Return

true

The abstract operation RejectPromise takes arguments

promise

and

reason

. It performs the following steps when called:

Assert

: The value of

promise

.[[PromiseState]] is

pending

2. Let

reactions

promise

.[[PromiseRejectReactions]].

3. Set

promise

.[[PromiseResult]] to

reason

4. Set

promise

.[[PromiseFulfillReactions]] to

undefined

5. Set

promise

.[[PromiseRejectReactions]] to

undefined

6. Set

promise

.[[PromiseState]] to

rejected

7. If

promise

.[[PromiseIsHandled]] is

false

, perform

HostPromiseRejectionTracker

(

promise

"reject"

8. Return

TriggerPromiseReactions

(

reactions

reason

The abstract operation TriggerPromiseReactions takes arguments

reactions

List

of PromiseReaction Records) and

argument

. It enqueues a new

Job

for each record in

reactions

. Each such

Job

processes the [[Type]] and [[Handler]] of

the PromiseReaction

Record

, and if the [[Handler]] is not

empty

, calls it passing the given argument. If the [[Handler]]

empty

, the behaviour is determined by the [[Type]]. It performs the following steps when called:

1. For each element

reaction

reactions

, do

a. Let

job

NewPromiseReactionJob

(

reaction

argument

b. Perform

HostEnqueuePromiseJob

(

job

.[[Job]],

job

.[[Realm]]).

2. Return

undefined

The

host-defined

abstract operation HostPromiseRejectionTracker takes arguments

promise

(a Promise) and

operation

(

"reject"

"handle"

). It allows

host

environments to track promise rejections.

An implementation of HostPromiseRejectionTracker must complete normally in all cases. The default implementation
of HostPromiseRejectionTracker is to unconditionally return an empty normal completion.

NOTE 1

HostPromiseRejectionTracker is called in two scenarios:

When a promise is rejected without any handlers, it is called with its

operation

argument

set to

"reject"

When a handler is added to a rejected promise for the first time, it is called with its

operation

argument set to

"handle"

A typical implementation of HostPromiseRejectionTracker might try to notify developers of
unhandled rejections, while also being careful to notify them if such previous notifications are
later invalidated by new handlers being attached.

27.2.1.7 RejectPromise (

promise

reason

)

27.2.1.8 TriggerPromiseReactions (

reactions

argument

)

27.2.1.9 HostPromiseRejectionTracker (

promise

operation

)

760

NOTE 2

The abstract operation NewPromiseReactionJob takes arguments

that applies the appropriate handler to the incoming value, and uses the handler's return value to resolve or

reject the derived promise associated with that handler. It performs the following steps when called:

1. Let

job

be a new

Job

Abstract Closure

with no parameters that captures

reaction

and

argument

and performs the

following steps when called:

Assert

reaction

is a PromiseReaction

Record

b. Let

promiseCapability

reaction

.[[Capability]].

c. Let

type

reaction

.[[Type]].

d. Let

handler

reaction

.[[Handler]].

e. If

handler

empty

, then

i. If

type

Fulfill

, let

handlerResult

NormalCompletion

(

argument

ii. Else,

Assert

type

Reject

2. Let

handlerResult

ThrowCompletion

(

argument

f. Else, let

handlerResult

HostCallJobCallback

(

handler

undefined

, «

argument

»).

g. If

promiseCapability

undefined

, then

Assert

handlerResult

is not an

abrupt completion

ii. Return

NormalCompletion

(

empty

Assert

promiseCapability

is a

PromiseCapability Record

i. If

handlerResult

is an

abrupt completion

, then

i. Let

status

Call

(

promiseCapability

.[[Reject]],

undefined

, «

handlerResult

.[[Value]] »).

j. Else,

i. Let

status

Call

(

promiseCapability

.[[Resolve]],

undefined

, «

handlerResult

.[[Value]] »).

k. Return

Completion

(

status

2. Let

handlerRealm

null

3. If

reaction

.[[Handler]] is not

empty

, then

a. Let

getHandlerRealmResult

GetFunctionRealm

(

reaction

.[[Handler]].[[Callback]]).

b. If

getHandlerRealmResult

is a normal completion, set

handlerRealm

getHandlerRealmResult

.[[Value]].

c. Else, set

handlerRealm

the current Realm Record

d. NOTE:

handlerRealm

is never

null

unless the handler is

undefined

. When the handler is a revoked Proxy

and no ECMAScript code runs,

handlerRealm

is used to create error objects.

4. Return the

Record

{ [[Job]]:

job

, [[Realm]]:

handlerRealm

The abstract operation NewPromiseResolveThenableJob takes arguments

promiseToResolve

thenable

, and

then

. It

performs the following steps when called:

operation

"handle"

, an implementation should not hold a reference to

promise

in a way that

would interfere with garbage collection. An implementation may hold a reference to

promise

operation

"reject"

, since it is expected that rejections will be rare and not on hot code paths.

27.2.2 Promise Jobs

27.2.2.1 NewPromiseReactionJob (

reaction

argument

)

27.2.2.2 NewPromiseResolveThenableJob (

promiseToResolve

thenable

then

)

761

1. Let

job

be a new

Job

Abstract Closure

with no parameters that captures

promiseToResolve

thenable

, and

then

and

performs the following steps when called:

a. Let

resolvingFunctions

CreateResolvingFunctions

(

promiseToResolve

b. Let

thenCallResult

HostCallJobCallback

(

then

thenable

, «

resolvingFunctions

.[[Resolve]],

resolvingFunctions

.[[Reject]] »).

c. If

thenCallResult

is an

abrupt completion

, then

i. Let

status

Call

(

resolvingFunctions

.[[Reject]],

undefined

, «

thenCallResult

.[[Value]] »).

ii. Return

Completion

(

status

d. Return

Completion

(

thenCallResult

2. Let

getThenRealmResult

GetFunctionRealm

(

then

.[[Callback]]).

3. If

getThenRealmResult

is a normal completion, let

thenRealm

getThenRealmResult

.[[Value]].

4. Else, let

thenRealm

the current Realm Record

5. NOTE:

thenRealm

is never

null

. When

then

.[[Callback]] is a revoked Proxy and no code runs,

thenRealm

is used

to create error objects.

6. Return the

Record

{ [[Job]]:

job

, [[Realm]]:

thenRealm

NOTE

The Promise

constructor

%Promise%

is the initial value of the

"Promise"

property of the

global object

creates and initializes a new Promise object when called as a

constructor

is not intended to be called as a function and will throw an exception when called in that manner.
is designed to be subclassable. It may be used as the value in an

extends

clause of a class definition. Subclass

constructors that intend to inherit the specified Promise behaviour must include a

super

call to the Promise

constructor

to create and initialize the subclass instance with the internal state necessary to support the

Promise

and

Promise.prototype

built-in methods.

When the

Promise

function is called with argument

executor

, the following steps are taken:

1. If NewTarget is

undefined

, throw a

TypeError

exception.

2. If

IsCallable

(

executor

) is

false

, throw a

TypeError

exception.

3. Let

promise

be ?

OrdinaryCreateFromConstructor

(NewTarget,

"%Promise.prototype%"

, « [[PromiseState]],

[[PromiseResult]], [[PromiseFulfillReactions]], [[PromiseRejectReactions]], [[PromiseIsHandled]] »).

4. Set

promise

.[[PromiseState]] to

pending

5. Set

promise

.[[PromiseFulfillReactions]] to a new empty

List

6. Set

promise

.[[PromiseRejectReactions]] to a new empty

List

7. Set

promise

.[[PromiseIsHandled]] to

false

8. Let

resolvingFunctions

CreateResolvingFunctions

(

promise

9. Let

completion

Call

(

executor

undefined

, «

resolvingFunctions

.[[Resolve]],

resolvingFunctions

.[[Reject]] »).

This

Job

uses the supplied thenable and its

then

method to resolve the given promise. This

process must take place as a

Job

to ensure that the evaluation of the

then

method occurs after

evaluation of any surrounding code has completed.

27.2.3 The Promise Constructor

27.2.3.1 Promise (

executor

)

762

10. If

completion

is an

abrupt completion

, then

a. Perform ?

Call

(

resolvingFunctions

.[[Reject]],

undefined

, «

completion

.[[Value]] »).

11. Return

promise

NOTE

The Promise

constructor

has a [[Prototype]] internal slot whose value is

%Function.prototype%

has the following properties:

The

all

function returns a new promise which is fulfilled with an array of fulfillment values for the passed promises,

or rejects with the reason of the first passed promise that rejects. It resolves all elements of the passed iterable to
promises as it runs this algorithm.

1. Let

be the

this

value.

2. Let

promiseCapability

be ?

NewPromiseCapability

(

3. Let

promiseResolve

GetPromiseResolve

(

IfAbruptRejectPromise

(

promiseResolve

promiseCapability

5. Let

iteratorRecord

GetIterator

(

iterable

IfAbruptRejectPromise

(

iteratorRecord

promiseCapability

7. Let

result

PerformPromiseAll

(

iteratorRecord

promiseCapability

promiseResolve

8. If

result

is an

abrupt completion

, then

a. If

iteratorRecord

.[[Done]] is

false

, set

result

IteratorClose

(

iteratorRecord

result

IfAbruptRejectPromise

(

result

promiseCapability

The

executor

argument must be a

function object

. It is called for initiating and reporting

completion of the possibly deferred action represented by this Promise object. The executor is
called with two arguments:

resolve

and

reject

. These are functions that may be used by the

executor

function to report eventual completion or failure of the deferred computation. Returning from
the executor function does not mean that the deferred action has been completed but only that
the request to eventually perform the deferred action has been accepted.

The

resolve

function that is passed to an

executor

function accepts a single argument. The

executor

code may eventually call the

resolve

function to indicate that it wishes to resolve the associated

Promise object. The argument passed to the

resolve

function represents the eventual value of the

deferred action and can be either the actual fulfillment value or another Promise object which
will provide the value if it is fulfilled.

The

reject

function that is passed to an

executor

function accepts a single argument. The

executor

code may eventually call the

reject

function to indicate that the associated Promise is rejected and

will never be fulfilled. The argument passed to the

reject

function is used as the rejection value of

the promise. Typically it will be an Error object.

The resolve and reject functions passed to an

executor

function by the Promise

constructor

have

the capability to actually resolve and reject the associated promise. Subclasses may have different

constructor

behaviour that passes in customized values for resolve and reject.

27.2.4 Properties of the Promise Constructor

27.2.4.1 Promise.all (

iterable

)

763

9. Return

Completion

(

result

NOTE

The abstract operation GetPromiseResolve takes argument

promiseConstructor

. It performs the following steps when

called:

Assert

IsConstructor

(

promiseConstructor

) is

true

2. Let

promiseResolve

be ?

Get

(

promiseConstructor

"resolve"

3. If

IsCallable

(

promiseResolve

) is

false

, throw a

TypeError

exception.

4. Return

promiseResolve

The abstract operation PerformPromiseAll takes arguments

iteratorRecord

constructor

resultCapability

PromiseCapability Record

), and

promiseResolve

. It performs the following steps when called:

Assert

IsConstructor

(

constructor

) is

true

Assert

IsCallable

(

promiseResolve

) is

true

3. Let

values

be a new empty

List

4. Let

remainingElementsCount

be the

Record

{ [[Value]]: 1 }.

5. Let

index

be 0.

6. Repeat,

a. Let

next

IteratorStep

(

iteratorRecord

b. If

next

is an

abrupt completion

, set

iteratorRecord

.[[Done]] to

true

ReturnIfAbrupt

(

next

d. If

next

false

, then

i. Set

iteratorRecord

.[[Done]] to

true

ii. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] - 1.

iii. If

remainingElementsCount

.[[Value]] is 0, then

1. Let

valuesArray

be !

CreateArrayFromList

(

values

2. Perform ?

Call

(

resultCapability

.[[Resolve]],

undefined

, «

valuesArray

»).

iv. Return

resultCapability

.[[Promise]].

e. Let

nextValue

IteratorValue

(

next

f. If

nextValue

is an

abrupt completion

, set

iteratorRecord

.[[Done]] to

true

ReturnIfAbrupt

(

nextValue

h. Append

undefined

values

i. Let

nextPromise

be ?

Call

(

promiseResolve

constructor

, «

nextValue

»).

j. Let

steps

be the algorithm steps defined in

Promise.all

Resolve Element Functions

k. Let

length

be the number of non-optional parameters of the function definition in

Promise.all

Resolve Element Functions

l. Let

onFulfilled

be !

CreateBuiltinFunction

(

steps

length

, « [[AlreadyCalled]], [[Index]], [[Values]],

[[Capability]], [[RemainingElements]] »).

m. Set

onFulfilled

.[[AlreadyCalled]] to

false

n. Set

onFulfilled

.[[Index]] to

index

The

all

function requires its

this

value to be a

constructor

function that supports the parameter

conventions of the Promise

constructor

27.2.4.1.1 GetPromiseResolve (

promiseConstructor

)

27.2.4.1.2 PerformPromiseAll (

iteratorRecord

constructor

resultCapability

promiseResolve

)

764

o. Set

onFulfilled

.[[Values]] to

values

p. Set

onFulfilled

.[[Capability]] to

resultCapability

q. Set

onFulfilled

.[[RemainingElements]] to

remainingElementsCount

r. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] + 1.

s. Perform ?

Invoke

(

nextPromise

"then"

, «

onFulfilled

resultCapability

.[[Reject]] »).

t. Set

index

+ 1.

Promise.all

resolve element function is an anonymous built-in function that is used to resolve a specific

Promise.all

element. Each

Promise.all

resolve element function has [[Index]], [[Values]], [[Capability]],

[[RemainingElements]], and [[AlreadyCalled]] internal slots.

When a

Promise.all

resolve element function is called with argument

, the following steps are taken:

1. Let

be the

active function object

2. If

.[[AlreadyCalled]] is

true

, return

undefined

3. Set

.[[AlreadyCalled]] to

true

4. Let

index

.[[Index]].

5. Let

values

.[[Values]].

6. Let

promiseCapability

.[[Capability]].

7. Let

remainingElementsCount

.[[RemainingElements]].

8. Set

values

[

index

] to

9. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] - 1.

10. If

remainingElementsCount

.[[Value]] is 0, then

a. Let

valuesArray

be !

CreateArrayFromList

(

values

b. Return ?

Call

(

promiseCapability

.[[Resolve]],

undefined

, «

valuesArray

»).

11. Return

undefined

The

"length"

property of a

Promise.all

resolve element function is

𝔽

The

allSettled

function returns a promise that is fulfilled with an array of promise state snapshots, but only after

all the original promises have settled, i.e. become either fulfilled or rejected. It resolves all elements of the passed
iterable to promises as it runs this algorithm.

1. Let

be the

this

value.

2. Let

promiseCapability

be ?

NewPromiseCapability

(

3. Let

promiseResolve

GetPromiseResolve

(

IfAbruptRejectPromise

(

promiseResolve

promiseCapability

5. Let

iteratorRecord

GetIterator

(

iterable

IfAbruptRejectPromise

(

iteratorRecord

promiseCapability

7. Let

result

PerformPromiseAllSettled

(

iteratorRecord

promiseCapability

promiseResolve

8. If

result

is an

abrupt completion

, then

a. If

iteratorRecord

.[[Done]] is

false

, set

result

IteratorClose

(

iteratorRecord

result

IfAbruptRejectPromise

(

result

promiseCapability

9. Return

Completion

(

result

27.2.4.1.3

Promise.all

Resolve Element Functions

27.2.4.2 Promise.allSettled (

iterable

)

765

NOTE

The abstract operation PerformPromiseAllSettled takes arguments

iteratorRecord

constructor

resultCapability

PromiseCapability Record

), and

promiseResolve

. It performs the following steps when called:

Assert

: !

IsConstructor

(

constructor

) is

true

Assert

IsCallable

(

promiseResolve

) is

true

3. Let

values

be a new empty

List

4. Let

remainingElementsCount

be the

Record

{ [[Value]]: 1 }.

5. Let

index

be 0.

6. Repeat,

a. Let

next

IteratorStep

(

iteratorRecord

b. If

next

is an

abrupt completion

, set

iteratorRecord

.[[Done]] to

true

ReturnIfAbrupt

(

next

d. If

next

false

, then

i. Set

iteratorRecord

.[[Done]] to

true

ii. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] - 1.

iii. If

remainingElementsCount

.[[Value]] is 0, then

1. Let

valuesArray

be !

CreateArrayFromList

(

values

2. Perform ?

Call

(

resultCapability

.[[Resolve]],

undefined

, «

valuesArray

»).

iv. Return

resultCapability

.[[Promise]].

e. Let

nextValue

IteratorValue

(

next

f. If

nextValue

is an

abrupt completion

, set

iteratorRecord

.[[Done]] to

true

ReturnIfAbrupt

(

nextValue

h. Append

undefined

values

i. Let

nextPromise

be ?

Call

(

promiseResolve

constructor

, «

nextValue

»).

j. Let

stepsFulfilled

be the algorithm steps defined in

Promise.allSettled

Resolve Element

Functions

k. Let

lengthFulfilled

be the number of non-optional parameters of the function definition in

Promise.allSettled

Resolve Element Functions

l. Let

onFulfilled

be !

CreateBuiltinFunction

(

stepsFulfilled

lengthFulfilled

, « [[AlreadyCalled]], [[Index]],

[[Values]], [[Capability]], [[RemainingElements]] »).

m. Let

alreadyCalled

be the

Record

{ [[Value]]:

false

n. Set

onFulfilled

.[[AlreadyCalled]] to

alreadyCalled

o. Set

onFulfilled

.[[Index]] to

index

p. Set

onFulfilled

.[[Values]] to

values

q. Set

onFulfilled

.[[Capability]] to

resultCapability

r. Set

onFulfilled

.[[RemainingElements]] to

remainingElementsCount

s. Let

stepsRejected

be the algorithm steps defined in

Promise.allSettled

Reject Element Functions

t. Let

lengthRejected

be the number of non-optional parameters of the function definition in

Promise.allSettled

Reject Element Functions

u. Let

onRejected

be !

CreateBuiltinFunction

(

stepsRejected

lengthRejected

, « [[AlreadyCalled]], [[Index]],

[[Values]], [[Capability]], [[RemainingElements]] »).

v. Set

onRejected

.[[AlreadyCalled]] to

alreadyCalled

The

allSettled

function requires its

this

value to be a

constructor

function that supports the

parameter conventions of the Promise

constructor

27.2.4.2.1 PerformPromiseAllSettled (

iteratorRecord

constructor

resultCapability

promiseResolve

)

766

w. Set

onRejected

.[[Index]] to

index

x. Set

onRejected

.[[Values]] to

values

y. Set

onRejected

.[[Capability]] to

resultCapability

z. Set

onRejected

.[[RemainingElements]] to

remainingElementsCount

aa. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] + 1.

ab. Perform ?

Invoke

(

nextPromise

"then"

, «

onFulfilled

onRejected

»).

ac. Set

index

+ 1.

Promise.allSettled

resolve element function is an anonymous built-in function that is used to resolve a

specific

Promise.allSettled

element. Each

Promise.allSettled

resolve element function has [[Index]],

[[Values]], [[Capability]], [[RemainingElements]], and [[AlreadyCalled]] internal slots.

When a

Promise.allSettled

resolve element function is called with argument

, the following steps are taken:

1. Let

be the

active function object

2. Let

alreadyCalled

.[[AlreadyCalled]].

3. If

alreadyCalled

.[[Value]] is

true

, return

undefined

4. Set

alreadyCalled

.[[Value]] to

true

5. Let

index

.[[Index]].

6. Let

values

.[[Values]].

7. Let

promiseCapability

.[[Capability]].

8. Let

remainingElementsCount

.[[RemainingElements]].

9. Let

obj

be !

OrdinaryObjectCreate

(

%Object.prototype%

10. Perform !

CreateDataPropertyOrThrow

(

obj

"status"

"fulfilled"

11. Perform !

CreateDataPropertyOrThrow

(

obj

"value"

12. Set

values

[

index

] to

obj

13. Set

remainingElementsCount

.[[Value]] to

remainingElementsCount

.[[Value]] - 1.

14. If

remainingElementsCount

.[[Value]] is 0, then

a. Let

valuesArray

be !

CreateArrayFromList

(

values

b. Return ?

Call

(

promiseCapability

.[[Resolve]],

undefined

, «

valuesArray

»).

15. Return

undefined

The

"length"

property of a

Promise.allSettled

resolve element function is

𝔽

Promise.allSettled

reject element function is an anonymous built-in function that is used to reject a specific

Promise.allSettled

element. Each

Promise.allSettled

reject element function has [[Index]], [[Values]],

[[Capability]], [[RemainingElements]], and [[AlreadyCalled]] internal slots.

When a

Promise.allSettled

reject element function is called with argument

, the following steps are taken:

1. Let

be the

active function object

2. Let

alreadyCalled

.[[AlreadyCalled]].

3. If

alreadyCalled

.[[Value]] is

true

, return

undefined

4. Set

alreadyCalled

.[[Value]] to

true

5. Let

index

.[[Index]].

27.2.4.2.2

Promise.allSettled

Resolve Element Functions

27.2.4.2.3

Promise.allSettled

Reject Element Functions

767

ECMA-262 (12th Edition) ECMAScript 2021 Language Specification - page 57