27 Control Abstraction Objects

27.1 Iteration

27.1.1 Common Iteration Interfaces

An interface is a set of property keys whose associated values match a specific specification. Any object that provides all the properties as described by an interface's specification conforms to that interface. An interface is not represented by a distinct object. There may be many separately implemented objects that conform to any interface. An individual object may conform to multiple interfaces.

27.1.1.1 The Iterable Interface

The iterable interface includes the property described in Table 80:

Table 80: Iterable Interface Required Properties
Property Value Requirements
%Symbol.iterator% a function that returns an iterator object The returned object must conform to the iterator interface.

27.1.1.2 The Iterator Interface

An object that implements the iterator interface must include the property in Table 81. Such objects may also implement the properties in Table 82.

Table 81: Iterator Interface Required Properties
Property Value Requirements
"next" a function that returns an IteratorResult object The returned object must conform to the IteratorResult interface. If a previous call to the next method of an iterator has returned an IteratorResult object whose "done" property is true, then all subsequent calls to the next method of that object should also return an IteratorResult object whose "done" property is true. However, this requirement is not enforced.
Note 1

Arguments may be passed to the next function but their interpretation and validity is dependent upon the target iterator. The for-of statement and other common users of iterators do not pass any arguments, so iterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Table 82: Iterator Interface Optional Properties
Property Value Requirements
"return" a function that returns an IteratorResult object The returned object must conform to the IteratorResult interface. Invoking this method notifies the iterator object that the caller does not intend to make any more next method calls to the iterator. The returned IteratorResult object will typically have a "done" property whose value is true, and a "value" property with the value passed as the argument of the return method. However, this requirement is not enforced.
"throw" a function that returns an IteratorResult object The returned object must conform to the IteratorResult interface. Invoking this method notifies the iterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to throw the value passed as the argument. If the method does not throw, the returned IteratorResult object will typically have a "done" property whose value is true.
Note 2

Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including for-of, yield*, and array destructuring call these methods after performing an existence check. Most ECMAScript library functions that accept iterable objects as arguments also conditionally call them.

27.1.1.3 The Async Iterable Interface

The async iterable interface includes the properties described in Table 83:

Table 83: Async Iterable Interface Required Properties
Property Value Requirements
%Symbol.asyncIterator% a function that returns an async iterator object The returned object must conform to the async iterator interface.

27.1.1.4 The Async Iterator Interface

An object that implements the async iterator interface must include the properties in Table 84. Such objects may also implement the properties in Table 85.

Table 84: Async Iterator Interface Required Properties
Property Value Requirements
"next" a function that returns a promise for an IteratorResult object

The returned promise, when fulfilled, must fulfill with an object that conforms to the IteratorResult interface. If a previous call to the next method of an async iterator has returned a promise for an IteratorResult object whose "done" property is true, then all subsequent calls to the next method of that object should also return a promise for an IteratorResult object whose "done" property is true. However, this requirement is not enforced.

Additionally, the IteratorResult object that serves as a fulfillment value should have a "value" property whose value is not a promise (or "thenable"). However, this requirement is also not enforced.
Note 1

Arguments may be passed to the next function but their interpretation and validity is dependent upon the target async iterator. The for-await-of statement and other common users of async iterators do not pass any arguments, so async iterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Table 85: Async Iterator Interface Optional Properties
Property Value Requirements
"return" a function that returns a promise for an IteratorResult object

The returned promise, when fulfilled, must fulfill with an object that conforms to the IteratorResult interface. Invoking this method notifies the async iterator object that the caller does not intend to make any more next method calls to the async iterator. The returned promise will fulfill with an IteratorResult object which will typically have a "done" property whose value is true, and a "value" property with the value passed as the argument of the return method. However, this requirement is not enforced.

Additionally, the IteratorResult object that serves as a fulfillment value should have a "value" property whose value is not a promise (or "thenable"). If the argument value is used in the typical manner, then if it is a rejected promise, a promise rejected with the same reason should be returned; if it is a fulfilled promise, then its fulfillment value should be used as the "value" property of the returned promise's IteratorResult object fulfillment value. However, these requirements are also not enforced.
"throw" a function that returns a promise for an IteratorResult object

The returned promise, when fulfilled, must fulfill with an object that conforms to the IteratorResult interface. Invoking this method notifies the async iterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to return a rejected promise which rejects with the value passed as the argument.

If the returned promise is fulfilled, the IteratorResult object fulfillment value will typically have a "done" property whose value is true. Additionally, it should have a "value" property whose value is not a promise (or "thenable"), but this requirement is not enforced.
Note 2

Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including for-await-of and yield* call these methods after performing an existence check.

27.1.1.5 The IteratorResult Interface

The IteratorResult interface includes the properties listed in Table 86:

Table 86: IteratorResult Interface Properties
Property Value Requirements
"done" a Boolean This is the result status of an iterator next method call. If the end of the iterator was reached "done" is true. If the end was not reached "done" is false and a value is available. If a "done" property (either own or inherited) does not exist, it is considered to have the value false.
"value" an 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" is undefined. In that case, the "value" property may be absent from the conforming object if it does not inherit an explicit "value" property.

27.1.2 Iterator Helper Objects

An Iterator Helper object is an ordinary object that represents a lazy transformation of some specific source iterator object. There is not a named constructor for Iterator Helper objects. Instead, Iterator Helper objects are created by calling certain methods of Iterator instance objects.

27.1.2.1 The %IteratorHelperPrototype% Object

The %IteratorHelperPrototype% object:

27.1.2.1.1 %IteratorHelperPrototype%.next ( )

  1. Return ? GeneratorResume(this value, undefined, "Iterator Helper").

27.1.2.1.2 %IteratorHelperPrototype%.return ( )

  1. Let O be this value.
  2. Perform ? RequireInternalSlot(O, [[UnderlyingIterator]]).
  3. Assert: O has a [[GeneratorState]] internal slot.
  4. If O.[[GeneratorState]] is suspended-start, then
    1. Set O.[[GeneratorState]] to completed.
    2. NOTE: Once a generator enters the completed state it never leaves it and its associated execution context is never resumed. Any execution state associated with O can be discarded at this point.
    3. Perform ? IteratorClose(O.[[UnderlyingIterator]], NormalCompletion(unused)).
    4. Return CreateIteratorResultObject(undefined, true).
  5. Let C be ReturnCompletion(undefined).
  6. Return ? GeneratorResumeAbrupt(O, C, "Iterator Helper").

27.1.2.1.3 %IteratorHelperPrototype% [ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value "Iterator Helper".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

27.1.3 Iterator Objects

27.1.3.1 The Iterator Constructor

The Iterator constructor:

  • is %Iterator%.
  • is the initial value of the "Iterator" property of the global object.
  • is designed to be subclassable. It may be used as the value of an extends clause of a class definition.

27.1.3.1.1 Iterator ( )

This function performs the following steps when called:

  1. If NewTarget is either undefined or the active function object, throw a TypeError exception.
  2. Return ? OrdinaryCreateFromConstructor(NewTarget, "%Iterator.prototype%").

27.1.3.2 Properties of the Iterator Constructor

The Iterator constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

27.1.3.2.1 Iterator.from ( O )

  1. Let iteratorRecord be ? GetIteratorFlattenable(O, iterate-string-primitives).
  2. Let hasInstance be ? OrdinaryHasInstance(%Iterator%, iteratorRecord.[[Iterator]]).
  3. If hasInstance is true, then
    1. Return iteratorRecord.[[Iterator]].
  4. Let wrapper be OrdinaryObjectCreate(%WrapForValidIteratorPrototype%, « [[Iterated]] »).
  5. Set wrapper.[[Iterated]] to iteratorRecord.
  6. Return wrapper.

27.1.3.2.1.1 The %WrapForValidIteratorPrototype% Object

The %WrapForValidIteratorPrototype% object:

27.1.3.2.1.1.1 %WrapForValidIteratorPrototype%.next ( )

  1. Let O be this value.
  2. Perform ? RequireInternalSlot(O, [[Iterated]]).
  3. Let iteratorRecord be O.[[Iterated]].
  4. Return ? Call(iteratorRecord.[[NextMethod]], iteratorRecord.[[Iterator]]).

27.1.3.2.1.1.2 %WrapForValidIteratorPrototype%.return ( )

  1. Let O be this value.
  2. Perform ? RequireInternalSlot(O, [[Iterated]]).
  3. Let iterator be O.[[Iterated]].[[Iterator]].
  4. Assert: iterator is an Object.
  5. Let returnMethod be ? GetMethod(iterator, "return").
  6. If returnMethod is undefined, then
    1. Return CreateIteratorResultObject(undefined, true).
  7. Return ? Call(returnMethod, iterator).

27.1.3.2.2 Iterator.prototype

The initial value of Iterator.prototype is the Iterator prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

27.1.4 Properties of the Iterator Prototype Object

The Iterator prototype object:

Note

All objects defined in this specification that implement the iterator interface also inherit from %Iterator.prototype%. ECMAScript code may also define objects that inherit from %Iterator.prototype%. %Iterator.prototype% 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 %Iterator.prototype% object:

Object.getPrototypeOf(Object.getPrototypeOf([][Symbol.iterator]()))

27.1.4.1 Iterator.prototype.constructor

Iterator.prototype.constructor is an accessor property with attributes { [[Enumerable]]: false, [[Configurable]]: true }. The [[Get]] and [[Set]] attributes are defined as follows:

27.1.4.1.1 get Iterator.prototype.constructor

The value of the [[Get]] attribute is a built-in function that requires no arguments. It performs the following steps when called:

  1. Return %Iterator%.

27.1.4.1.2 set Iterator.prototype.constructor

The value of the [[Set]] attribute is a built-in function that takes an argument v. It performs the following steps when called:

  1. Perform ? SetterThatIgnoresPrototypeProperties(this value, %Iterator.prototype%, "constructor", v).
  2. Return undefined.
 Note

Unlike the "constructor" property on most built-in prototypes, for web-compatibility reasons this property must be an accessor.

27.1.4.2 Iterator.prototype.drop ( limit )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. Let numLimit be Completion(ToNumber(limit)).
  5. IfAbruptCloseIterator(numLimit, iterated).
  6. If numLimit is NaN, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  7. Let integerLimit be ! ToIntegerOrInfinity(numLimit).
  8. If integerLimit < 0, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  9. Set iterated to ? GetIteratorDirect(O).
  10. Let closure be a new Abstract Closure with no parameters that captures iterated and integerLimit and performs the following steps when called:
    1. Let remaining be integerLimit.
    2. Repeat, while remaining > 0,
      1. If remaining ≠ +∞, then
        1. Set remaining to remaining - 1.
      2. Let next be ? IteratorStep(iterated).
      3. If next is done, return ReturnCompletion(undefined).
    3. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, return ReturnCompletion(undefined).
      3. Let completion be Completion(Yield(value)).
      4. IfAbruptCloseIterator(completion, iterated).
  11. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterator]] »).
  12. Set result.[[UnderlyingIterator]] to iterated.
  13. Return result.

27.1.4.3 Iterator.prototype.every ( predicate )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(predicate) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let counter be 0.
  7. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return true.
    3. Let result be Completion(Call(predicate, undefined, « value, 𝔽(counter) »)).
    4. IfAbruptCloseIterator(result, iterated).
    5. If ToBoolean(result) is false, return ? IteratorClose(iterated, NormalCompletion(false)).
    6. Set counter to counter + 1.

27.1.4.4 Iterator.prototype.filter ( predicate )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(predicate) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let closure be a new Abstract Closure with no parameters that captures iterated and predicate and performs the following steps when called:
    1. Let counter be 0.
    2. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, return ReturnCompletion(undefined).
      3. Let selected be Completion(Call(predicate, undefined, « value, 𝔽(counter) »)).
      4. IfAbruptCloseIterator(selected, iterated).
      5. If ToBoolean(selected) is true, then
        1. Let completion be Completion(Yield(value)).
        2. IfAbruptCloseIterator(completion, iterated).
      6. Set counter to counter + 1.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterator]] »).
  8. Set result.[[UnderlyingIterator]] to iterated.
  9. Return result.

27.1.4.5 Iterator.prototype.find ( predicate )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(predicate) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let counter be 0.
  7. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return undefined.
    3. Let result be Completion(Call(predicate, undefined, « value, 𝔽(counter) »)).
    4. IfAbruptCloseIterator(result, iterated).
    5. If ToBoolean(result) is true, return ? IteratorClose(iterated, NormalCompletion(value)).
    6. Set counter to counter + 1.

27.1.4.6 Iterator.prototype.flatMap ( mapper )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(mapper) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let closure be a new Abstract Closure with no parameters that captures iterated and mapper and performs the following steps when called:
    1. Let counter be 0.
    2. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, return ReturnCompletion(undefined).
      3. Let mapped be Completion(Call(mapper, undefined, « value, 𝔽(counter) »)).
      4. IfAbruptCloseIterator(mapped, iterated).
      5. Let innerIterator be Completion(GetIteratorFlattenable(mapped, reject-primitives)).
      6. IfAbruptCloseIterator(innerIterator, iterated).
      7. Let innerAlive be true.
      8. Repeat, while innerAlive is true,
        1. Let innerValue be Completion(IteratorStepValue(innerIterator)).
        2. IfAbruptCloseIterator(innerValue, iterated).
        3. If innerValue is done, then
          1. Set innerAlive to false.
        4. Else,
          1. Let completion be Completion(Yield(innerValue)).
          2. If completion is an abrupt completion, then
            1. Let backupCompletion be Completion(IteratorClose(innerIterator, completion)).
            2. IfAbruptCloseIterator(backupCompletion, iterated).
            3. Return ? IteratorClose(iterated, completion).
      9. Set counter to counter + 1.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterator]] »).
  8. Set result.[[UnderlyingIterator]] to iterated.
  9. Return result.

27.1.4.7 Iterator.prototype.forEach ( procedure )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(procedure) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let counter be 0.
  7. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return undefined.
    3. Let result be Completion(Call(procedure, undefined, « value, 𝔽(counter) »)).
    4. IfAbruptCloseIterator(result, iterated).
    5. Set counter to counter + 1.

27.1.4.8 Iterator.prototype.map ( mapper )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(mapper) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let closure be a new Abstract Closure with no parameters that captures iterated and mapper and performs the following steps when called:
    1. Let counter be 0.
    2. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, return ReturnCompletion(undefined).
      3. Let mapped be Completion(Call(mapper, undefined, « value, 𝔽(counter) »)).
      4. IfAbruptCloseIterator(mapped, iterated).
      5. Let completion be Completion(Yield(mapped)).
      6. IfAbruptCloseIterator(completion, iterated).
      7. Set counter to counter + 1.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterator]] »).
  8. Set result.[[UnderlyingIterator]] to iterated.
  9. Return result.

27.1.4.9 Iterator.prototype.reduce ( reducer [ , initialValue ] )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(reducer) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. If initialValue is not present, then
    1. Let accumulator be ? IteratorStepValue(iterated).
    2. If accumulator is done, throw a TypeError exception.
    3. Let counter be 1.
  7. Else,
    1. Let accumulator be initialValue.
    2. Let counter be 0.
  8. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return accumulator.
    3. Let result be Completion(Call(reducer, undefined, « accumulator, value, 𝔽(counter) »)).
    4. IfAbruptCloseIterator(result, iterated).
    5. Set accumulator to result.
    6. Set counter to counter + 1.

27.1.4.10 Iterator.prototype.some ( predicate )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If IsCallable(predicate) is false, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. Set iterated to ? GetIteratorDirect(O).
  6. Let counter be 0.
  7. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return false.
    3. Let result be Completion(Call(predicate, undefined, « value, 𝔽(counter) »)).
    4. IfAbruptCloseIterator(result, iterated).
    5. If ToBoolean(result) is true, return ? IteratorClose(iterated, NormalCompletion(true)).
    6. Set counter to counter + 1.

27.1.4.11 Iterator.prototype.take ( limit )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: O, [[NextMethod]]: undefined, [[Done]]: false }.
  4. Let numLimit be Completion(ToNumber(limit)).
  5. IfAbruptCloseIterator(numLimit, iterated).
  6. If numLimit is NaN, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  7. Let integerLimit be ! ToIntegerOrInfinity(numLimit).
  8. If integerLimit < 0, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  9. Set iterated to ? GetIteratorDirect(O).
  10. Let closure be a new Abstract Closure with no parameters that captures iterated and integerLimit and performs the following steps when called:
    1. Let remaining be integerLimit.
    2. Repeat,
      1. If remaining = 0, then
        1. Return ? IteratorClose(iterated, ReturnCompletion(undefined)).
      2. If remaining ≠ +∞, then
        1. Set remaining to remaining - 1.
      3. Let value be ? IteratorStepValue(iterated).
      4. If value is done, return ReturnCompletion(undefined).
      5. Let completion be Completion(Yield(value)).
      6. IfAbruptCloseIterator(completion, iterated).
  11. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterator]] »).
  12. Set result.[[UnderlyingIterator]] to iterated.
  13. Return result.

27.1.4.12 Iterator.prototype.toArray ( )

This method performs the following steps when called:

  1. Let O be the this value.
  2. If O is not an Object, throw a TypeError exception.
  3. Let iterated be ? GetIteratorDirect(O).
  4. Let items be a new empty List.
  5. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return CreateArrayFromList(items).
    3. Append value to items.

27.1.4.13 Iterator.prototype [ %Symbol.iterator% ] ( )

This function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "[Symbol.iterator]".

27.1.4.14 Iterator.prototype [ %Symbol.toStringTag% ]

Iterator.prototype[%Symbol.toStringTag%] is an accessor property with attributes { [[Enumerable]]: false, [[Configurable]]: true }. The [[Get]] and [[Set]] attributes are defined as follows:

27.1.4.14.1 get Iterator.prototype [ %Symbol.toStringTag% ]

The value of the [[Get]] attribute is a built-in function that requires no arguments. It performs the following steps when called:

  1. Return "Iterator".

27.1.4.14.2 set Iterator.prototype [ %Symbol.toStringTag% ]

The value of the [[Set]] attribute is a built-in function that takes an argument v. It performs the following steps when called:

  1. Perform ? SetterThatIgnoresPrototypeProperties(this value, %Iterator.prototype%, %Symbol.toStringTag%, v).
  2. Return undefined.
 Note

Unlike the %Symbol.toStringTag% property on most built-in prototypes, for web-compatibility reasons this property must be an accessor.

27.1.5 The %AsyncIteratorPrototype% Object

The %AsyncIteratorPrototype% object:

Note

All objects defined in this specification that implement the async iterator 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.5.1 %AsyncIteratorPrototype% [ %Symbol.asyncIterator% ] ( )

This function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "[Symbol.asyncIterator]".

27.1.6 Async-from-Sync Iterator Objects

An Async-from-Sync Iterator object is an async iterator that adapts a specific synchronous iterator. Async-from-Sync Iterator objects are never directly accessible to ECMAScript code. 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.

27.1.6.1 CreateAsyncFromSyncIterator ( syncIteratorRecord )

The abstract operation CreateAsyncFromSyncIterator takes argument syncIteratorRecord (an Iterator Record) and returns an Iterator Record. 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 Iterator Record { [[Iterator]]: asyncIterator, [[NextMethod]]: nextMethod, [[Done]]: false }.
  5. Return iteratorRecord.

27.1.6.2 The %AsyncFromSyncIteratorPrototype% Object

The %AsyncFromSyncIteratorPrototype% object:

27.1.6.2.1 %AsyncFromSyncIteratorPrototype%.next ( [ value ] )

  1. Let O be the this value.
  2. Assert: O is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be O.[[SyncIteratorRecord]].
  5. If value is present, then
    1. Let result be Completion(IteratorNext(syncIteratorRecord, value)).
  6. Else,
    1. Let result be Completion(IteratorNext(syncIteratorRecord)).
  7. IfAbruptRejectPromise(result, promiseCapability).
  8. Return AsyncFromSyncIteratorContinuation(result, promiseCapability, syncIteratorRecord, true).

27.1.6.2.2 %AsyncFromSyncIteratorPrototype%.return ( [ value ] )

  1. Let O be the this value.
  2. Assert: O is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be O.[[SyncIteratorRecord]].
  5. Let syncIterator be syncIteratorRecord.[[Iterator]].
  6. Let return be Completion(GetMethod(syncIterator, "return")).
  7. IfAbruptRejectPromise(return, promiseCapability).
  8. If return is undefined, then
    1. Let iteratorResult be CreateIteratorResultObject(value, true).
    2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « iteratorResult »).
    3. Return promiseCapability.[[Promise]].
  9. If value is present, then
    1. Let result be Completion(Call(return, syncIterator, « value »)).
  10. Else,
    1. Let result be Completion(Call(return, syncIterator)).
  11. IfAbruptRejectPromise(result, promiseCapability).
  12. If result is not an Object, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « a newly created TypeError object »).
    2. Return promiseCapability.[[Promise]].
  13. Return AsyncFromSyncIteratorContinuation(result, promiseCapability, syncIteratorRecord, false).

27.1.6.2.3 %AsyncFromSyncIteratorPrototype%.throw ( [ value ] )

Note
In this specification, value is always provided, but is left optional for consistency with %AsyncFromSyncIteratorPrototype%.return ( [ value ] ).
  1. Let O be the this value.
  2. Assert: O is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be O.[[SyncIteratorRecord]].
  5. Let syncIterator be syncIteratorRecord.[[Iterator]].
  6. Let throw be Completion(GetMethod(syncIterator, "throw")).
  7. IfAbruptRejectPromise(throw, promiseCapability).
  8. If throw is undefined, then
    1. NOTE: If syncIterator does not have a throw method, close it to give it a chance to clean up before we reject the capability.
    2. Let closeCompletion be NormalCompletion(empty).
    3. Let result be Completion(IteratorClose(syncIteratorRecord, closeCompletion)).
    4. IfAbruptRejectPromise(result, promiseCapability).
    5. NOTE: The next step throws a TypeError to indicate that there was a protocol violation: syncIterator does not have a throw method.
    6. NOTE: If closing syncIterator does not throw then the result of that operation is ignored, even if it yields a rejected promise.
    7. Perform ! Call(promiseCapability.[[Reject]], undefined, « a newly created TypeError object »).
    8. Return promiseCapability.[[Promise]].
  9. If value is present, then
    1. Let result be Completion(Call(throw, syncIterator, « value »)).
  10. Else,
    1. Let result be Completion(Call(throw, syncIterator)).
  11. IfAbruptRejectPromise(result, promiseCapability).
  12. If result is not an Object, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « a newly created TypeError object »).
    2. Return promiseCapability.[[Promise]].
  13. Return AsyncFromSyncIteratorContinuation(result, promiseCapability, syncIteratorRecord, true).

27.1.6.3 Properties of Async-from-Sync Iterator Instances

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 87.

Table 87: Internal Slots of Async-from-Sync Iterator Instances
Internal Slot Type Description
[[SyncIteratorRecord]] an Iterator Record Represents the original synchronous iterator which is being adapted.

27.1.6.4 AsyncFromSyncIteratorContinuation ( result, promiseCapability, syncIteratorRecord, closeOnRejection )

The abstract operation AsyncFromSyncIteratorContinuation takes arguments result (an Object), promiseCapability (a PromiseCapability Record for an intrinsic %Promise%), syncIteratorRecord (an Iterator Record), and closeOnRejection (a Boolean) and returns a Promise. It performs the following steps when called:

  1. NOTE: Because promiseCapability is derived from the intrinsic %Promise%, the calls to promiseCapability.[[Reject]] entailed by the use IfAbruptRejectPromise below are guaranteed not to throw.
  2. Let done be Completion(IteratorComplete(result)).
  3. IfAbruptRejectPromise(done, promiseCapability).
  4. Let value be Completion(IteratorValue(result)).
  5. IfAbruptRejectPromise(value, promiseCapability).
  6. Let valueWrapper be Completion(PromiseResolve(%Promise%, value)).
  7. If valueWrapper is an abrupt completion, done is false, and closeOnRejection is true, then
    1. Set valueWrapper to Completion(IteratorClose(syncIteratorRecord, valueWrapper)).
  8. IfAbruptRejectPromise(valueWrapper, promiseCapability).
  9. Let unwrap be a new Abstract Closure with parameters (v) that captures done and performs the following steps when called:
    1. Return CreateIteratorResultObject(v, done).
  10. Let onFulfilled be CreateBuiltinFunction(unwrap, 1, "", « »).
  11. NOTE: onFulfilled is used 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.
  12. If done is true, or if closeOnRejection is false, then
    1. Let onRejected be undefined.
  13. Else,
    1. Let closeIterator be a new Abstract Closure with parameters (error) that captures syncIteratorRecord and performs the following steps when called:
      1. Return ? IteratorClose(syncIteratorRecord, ThrowCompletion(error)).
    2. Let onRejected be CreateBuiltinFunction(closeIterator, 1, "", « »).
    3. NOTE: onRejected is used to close the Iterator when the "value" property of an IteratorResult object it yields is a rejected promise.
  14. Perform PerformPromiseThen(valueWrapper, onFulfilled, onRejected, promiseCapability).
  15. Return promiseCapability.[[Promise]].

27.2 Promise Objects

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

Any Promise is in one of three mutually exclusive states: fulfilled, rejected, and pending:

  • A promise p is fulfilled if p.then(f, r) will immediately enqueue a Job to call the function f.
  • A promise p is rejected if p.then(f, r) will immediately enqueue a Job to call the function r.
  • 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.

27.2.1 Promise Abstract Operations

27.2.1.1 PromiseCapability Records

A PromiseCapability Record is a Record value used to encapsulate a Promise or promise-like object along with the functions that are capable of resolving or rejecting that promise. PromiseCapability Records are produced by the NewPromiseCapability abstract operation.

PromiseCapability Records have the fields listed in Table 88.

Table 88: PromiseCapability Record Fields
Field Name Value Meaning
[[Promise]] an Object An object that is usable as a promise.
[[Resolve]] a function object The function that is used to resolve the given promise.
[[Reject]] a function object The function that is used to reject the given promise.

27.2.1.1.1 IfAbruptRejectPromise ( value, capability )

IfAbruptRejectPromise is a shorthand for a sequence of algorithm steps that use a PromiseCapability Record. An algorithm step of the form:

  1. IfAbruptRejectPromise(value, capability).

means the same thing as:

  1. Assert: value is a Completion Record.
  2. If value is an abrupt completion, then
    1. Perform ? Call(capability.[[Reject]], undefined, « value.[[Value]] »).
    2. Return capability.[[Promise]].
  3. Else,
    1. Set value to ! value.

27.2.1.2 PromiseReaction Records

A PromiseReaction Record 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 operation, and are used by the Abstract Closure returned by NewPromiseReactionJob.

PromiseReaction Records have the fields listed in Table 89.

Table 89: 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 or reject The [[Type]] is used when [[Handler]] is empty to allow for behaviour specific to the settlement type.
[[Handler]] a JobCallback Record or 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.

27.2.1.3 CreateResolvingFunctions ( promise )

The abstract operation CreateResolvingFunctions takes argument promise (a Promise) and returns a Record with fields [[Resolve]] (a function object) and [[Reject]] (a function object). 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 }.

27.2.1.3.1 Promise Reject Functions

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 F be the active function object.
  2. Assert: F has a [[Promise]] internal slot whose value is an Object.
  3. Let promise be F.[[Promise]].
  4. Let alreadyResolved be F.[[AlreadyResolved]].
  5. If alreadyResolved.[[Value]] is true, return undefined.
  6. Set alreadyResolved.[[Value]] to true.
  7. Perform RejectPromise(promise, reason).
  8. Return undefined.

The "length" property of a promise reject function is 1𝔽.

27.2.1.3.2 Promise Resolve Functions

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 F be the active function object.
  2. Assert: F has a [[Promise]] internal slot whose value is an Object.
  3. Let promise be F.[[Promise]].
  4. Let alreadyResolved be F.[[AlreadyResolved]].
  5. If alreadyResolved.[[Value]] is true, return undefined.
  6. Set alreadyResolved.[[Value]] to true.
  7. If SameValue(resolution, promise) is true, then
    1. Let selfResolutionError be a newly created TypeError object.
    2. Perform RejectPromise(promise, selfResolutionError).
    3. Return undefined.
  8. If resolution is not an Object, then
    1. Perform FulfillPromise(promise, resolution).
    2. Return undefined.
  9. Let then be Completion(Get(resolution, "then")).
  10. If then is an abrupt completion, then
    1. Perform RejectPromise(promise, then.[[Value]]).
    2. Return undefined.
  11. Let thenAction be then.[[Value]].
  12. If IsCallable(thenAction) is false, then
    1. Perform FulfillPromise(promise, resolution).
    2. Return undefined.
  13. Let thenJobCallback be HostMakeJobCallback(thenAction).
  14. Let job be NewPromiseResolveThenableJob(promise, resolution, thenJobCallback).
  15. Perform HostEnqueuePromiseJob(job.[[Job]], job.[[Realm]]).
  16. Return undefined.

The "length" property of a promise resolve function is 1𝔽.

27.2.1.4 FulfillPromise ( promise, value )

The abstract operation FulfillPromise takes arguments promise (a Promise) and value (an ECMAScript language value) and returns unused. It performs the following steps when called:

  1. Assert: promise.[[PromiseState]] is pending.
  2. Let reactions be 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. Perform TriggerPromiseReactions(reactions, value).
  8. Return unused.

27.2.1.5 NewPromiseCapability ( C )

The abstract operation NewPromiseCapability takes argument C (an ECMAScript language value) and returns either a normal completion containing a PromiseCapability Record or a throw completion. It attempts to use C as a constructor in the fashion of the built-in Promise constructor to create a promise and extract its resolve and reject functions. The promise plus the resolve and reject functions are used to initialize a new PromiseCapability Record. It performs the following steps when called:

  1. If IsConstructor(C) is false, throw a TypeError exception.
  2. NOTE: C is assumed to be a constructor function that supports the parameter conventions of the Promise constructor (see 27.2.3.1).
  3. Let resolvingFunctions be the Record { [[Resolve]]: undefined, [[Reject]]: undefined }.
  4. Let executorClosure be a new Abstract Closure with parameters (resolve, reject) that captures resolvingFunctions and performs the following steps when called:
    1. If resolvingFunctions.[[Resolve]] is not undefined, throw a TypeError exception.
    2. If resolvingFunctions.[[Reject]] is not undefined, throw a TypeError exception.
    3. Set resolvingFunctions.[[Resolve]] to resolve.
    4. Set resolvingFunctions.[[Reject]] to reject.
    5. Return NormalCompletion(undefined).
  5. Let executor be CreateBuiltinFunction(executorClosure, 2, "", « »).
  6. Let promise be ? Construct(C, « executor »).
  7. If IsCallable(resolvingFunctions.[[Resolve]]) is false, throw a TypeError exception.
  8. If IsCallable(resolvingFunctions.[[Reject]]) is false, throw a TypeError exception.
  9. Return the PromiseCapability Record { [[Promise]]: promise, [[Resolve]]: resolvingFunctions.[[Resolve]], [[Reject]]: resolvingFunctions.[[Reject]] }.
 Note

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.6 IsPromise ( x )

The abstract operation IsPromise takes argument x (an ECMAScript language value) and returns a Boolean. It checks for the promise brand on an object. It performs the following steps when called:

  1. If x is not an Object, return false.
  2. If x does not have a [[PromiseState]] internal slot, return false.
  3. Return true.

27.2.1.7 RejectPromise ( promise, reason )

The abstract operation RejectPromise takes arguments promise (a Promise) and reason (an ECMAScript language value) and returns unused. It performs the following steps when called:

  1. Assert: promise.[[PromiseState]] is pending.
  2. Let reactions be 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. Perform TriggerPromiseReactions(reactions, reason).
  9. Return unused.

27.2.1.8 TriggerPromiseReactions ( reactions, argument )

The abstract operation TriggerPromiseReactions takes arguments reactions (a List of PromiseReaction Records) and argument (an ECMAScript language value) and returns unused. 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]] is empty, the behaviour is determined by the [[Type]]. It performs the following steps when called:

  1. For each element reaction of reactions, do
    1. Let job be NewPromiseReactionJob(reaction, argument).
    2. Perform HostEnqueuePromiseJob(job.[[Job]], job.[[Realm]]).
  2. Return unused.

27.2.1.9 HostPromiseRejectionTracker ( promise, operation )

The host-defined abstract operation HostPromiseRejectionTracker takes arguments promise (a Promise) and operation ("reject" or "handle") and returns unused. It allows host environments to track promise rejections.

The default implementation of HostPromiseRejectionTracker is to return unused.

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.

 Note 2

If operation is "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 if operation is "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 )

The abstract operation NewPromiseReactionJob takes arguments reaction (a PromiseReaction Record) and argument (an ECMAScript language value) and returns a Record with fields [[Job]] (a Job Abstract Closure) and [[Realm]] (a Realm Record or null). It returns a new Job Abstract Closure 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:
    1. Let promiseCapability be reaction.[[Capability]].
    2. Let type be reaction.[[Type]].
    3. Let handler be reaction.[[Handler]].
    4. If handler is empty, then
      1. If type is fulfill, then
        1. Let handlerResult be NormalCompletion(argument).
      2. Else,
        1. Assert: type is reject.
        2. Let handlerResult be ThrowCompletion(argument).
    5. Else,
      1. Let handlerResult be Completion(HostCallJobCallback(handler, undefined, « argument »)).
    6. If promiseCapability is undefined, then
      1. Assert: handlerResult is not an abrupt completion.
      2. Return empty.
    7. Assert: promiseCapability is a PromiseCapability Record.
    8. If handlerResult is an abrupt completion, then
      1. Return ? Call(promiseCapability.[[Reject]], undefined, « handlerResult.[[Value]] »).
    9. Else,
      1. Return ? Call(promiseCapability.[[Resolve]], undefined, « handlerResult.[[Value]] »).
  2. Let handlerRealm be null.
  3. If reaction.[[Handler]] is not empty, then
    1. Let getHandlerRealmResult be Completion(GetFunctionRealm(reaction.[[Handler]].[[Callback]])).
    2. If getHandlerRealmResult is a normal completion, set handlerRealm to getHandlerRealmResult.[[Value]].
    3. Else, set handlerRealm to the current Realm Record.
    4. 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 }.

27.2.2.2 NewPromiseResolveThenableJob ( promiseToResolve, thenable, then )

The abstract operation NewPromiseResolveThenableJob takes arguments promiseToResolve (a Promise), thenable (an Object), and then (a JobCallback Record) and returns a Record with fields [[Job]] (a Job Abstract Closure) and [[Realm]] (a Realm Record). It performs the following steps when called:

  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:
    1. Let resolvingFunctions be CreateResolvingFunctions(promiseToResolve).
    2. Let thenCallResult be Completion(HostCallJobCallback(then, thenable, « resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]] »)).
    3. If thenCallResult is an abrupt completion, then
      1. Return ? Call(resolvingFunctions.[[Reject]], undefined, « thenCallResult.[[Value]] »).
    4. Return ! thenCallResult.
  2. Let getThenRealmResult be Completion(GetFunctionRealm(then.[[Callback]])).
  3. If getThenRealmResult is a normal completion, let thenRealm be getThenRealmResult.[[Value]].
  4. Else, let thenRealm be 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

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

The Promise constructor:

  • is %Promise%.
  • is the initial value of the "Promise" property of the global object.
  • creates and initializes a new Promise when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • 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.

27.2.3.1 Promise ( executor )

This function performs the following steps when called:

  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.[[PromiseResult]] to empty.
  6. Set promise.[[PromiseFulfillReactions]] to a new empty List.
  7. Set promise.[[PromiseRejectReactions]] to a new empty List.
  8. Set promise.[[PromiseIsHandled]] to false.
  9. Let resolvingFunctions be CreateResolvingFunctions(promise).
  10. Let completion be Completion(Call(executor, undefined, « resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]] »)).
  11. If completion is an abrupt completion, then
    1. Perform ? Call(resolvingFunctions.[[Reject]], undefined, « completion.[[Value]] »).
  12. Return promise.
 Note

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. 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. 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 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

The Promise constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

27.2.4.1 Promise.all ( iterable )

This 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 C be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(C).
  3. Let promiseResolve be Completion(GetPromiseResolve(C)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAll(iteratorRecord, C, promiseCapability, promiseResolve)).
  8. If result is an abrupt completion, then
    1. If iteratorRecord.[[Done]] is false, set result to Completion(IteratorClose(iteratorRecord, result)).
    2. IfAbruptRejectPromise(result, promiseCapability).
  9. Return ! result.
 Note

This 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 )

The abstract operation GetPromiseResolve takes argument promiseConstructor (a constructor) and returns either a normal completion containing a function object or a throw completion. It performs the following steps when called:

  1. Let promiseResolve be ? Get(promiseConstructor, "resolve").
  2. If IsCallable(promiseResolve) is false, throw a TypeError exception.
  3. Return promiseResolve.

27.2.4.1.2 PerformPromiseAll ( iteratorRecord, constructor, resultCapability, promiseResolve )

The abstract operation PerformPromiseAll takes arguments iteratorRecord (an Iterator Record), constructor (a constructor), resultCapability (a PromiseCapability Record), and promiseResolve (a function object) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Let values be a new empty List.
  2. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  3. Let index be 0.
  4. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      2. If remainingElementsCount.[[Value]] = 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Perform ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      3. Return resultCapability.[[Promise]].
    3. Append undefined to values.
    4. Let nextPromise be ? Call(promiseResolve, constructor, « next »).
    5. Let steps be the algorithm steps defined in Promise.all Resolve Element Functions.
    6. Let length be the number of non-optional parameters of the function definition in Promise.all Resolve Element Functions.
    7. Let onFulfilled be CreateBuiltinFunction(steps, length, "", « [[AlreadyCalled]], [[Index]], [[Values]], [[Capability]], [[RemainingElements]] »).
    8. Set onFulfilled.[[AlreadyCalled]] to false.
    9. Set onFulfilled.[[Index]] to index.
    10. Set onFulfilled.[[Values]] to values.
    11. Set onFulfilled.[[Capability]] to resultCapability.
    12. Set onFulfilled.[[RemainingElements]] to remainingElementsCount.
    13. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    14. Perform ? Invoke(nextPromise, "then", « onFulfilled, resultCapability.[[Reject]] »).
    15. Set index to index + 1.

27.2.4.1.3 Promise.all Resolve Element Functions

A 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 x, the following steps are taken:

  1. Let F be the active function object.
  2. If F.[[AlreadyCalled]] is true, return undefined.
  3. Set F.[[AlreadyCalled]] to true.
  4. Let index be F.[[Index]].
  5. Let values be F.[[Values]].
  6. Let promiseCapability be F.[[Capability]].
  7. Let remainingElementsCount be F.[[RemainingElements]].
  8. Set values[index] to x.
  9. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
  10. If remainingElementsCount.[[Value]] = 0, then
    1. Let valuesArray be CreateArrayFromList(values).
    2. Return ? Call(promiseCapability.[[Resolve]], undefined, « valuesArray »).
  11. Return undefined.

The "length" property of a Promise.all resolve element function is 1𝔽.

27.2.4.2 Promise.allSettled ( iterable )

This 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 C be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(C).
  3. Let promiseResolve be Completion(GetPromiseResolve(C)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAllSettled(iteratorRecord, C, promiseCapability, promiseResolve)).
  8. If result is an abrupt completion, then
    1. If iteratorRecord.[[Done]] is false, set result to Completion(IteratorClose(iteratorRecord, result)).
    2. IfAbruptRejectPromise(result, promiseCapability).
  9. Return ! result.
 Note

This 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 )

The abstract operation PerformPromiseAllSettled takes arguments iteratorRecord (an Iterator Record), constructor (a constructor), resultCapability (a PromiseCapability Record), and promiseResolve (a function object) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Let values be a new empty List.
  2. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  3. Let index be 0.
  4. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      2. If remainingElementsCount.[[Value]] = 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Perform ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      3. Return resultCapability.[[Promise]].
    3. Append undefined to values.
    4. Let nextPromise be ? Call(promiseResolve, constructor, « next »).
    5. Let stepsFulfilled be the algorithm steps defined in Promise.allSettled Resolve Element Functions.
    6. Let lengthFulfilled be the number of non-optional parameters of the function definition in Promise.allSettled Resolve Element Functions.
    7. Let onFulfilled be CreateBuiltinFunction(stepsFulfilled, lengthFulfilled, "", « [[AlreadyCalled]], [[Index]], [[Values]], [[Capability]], [[RemainingElements]] »).
    8. Let alreadyCalled be the Record { [[Value]]: false }.
    9. Set onFulfilled.[[AlreadyCalled]] to alreadyCalled.
    10. Set onFulfilled.[[Index]] to index.
    11. Set onFulfilled.[[Values]] to values.
    12. Set onFulfilled.[[Capability]] to resultCapability.
    13. Set onFulfilled.[[RemainingElements]] to remainingElementsCount.
    14. Let stepsRejected be the algorithm steps defined in Promise.allSettled Reject Element Functions.
    15. Let lengthRejected be the number of non-optional parameters of the function definition in Promise.allSettled Reject Element Functions.
    16. Let onRejected be CreateBuiltinFunction(stepsRejected, lengthRejected, "", « [[AlreadyCalled]], [[Index]], [[Values]], [[Capability]], [[RemainingElements]] »).
    17. Set onRejected.[[AlreadyCalled]] to alreadyCalled.
    18. Set onRejected.[[Index]] to index.
    19. Set onRejected.[[Values]] to values.
    20. Set onRejected.[[Capability]] to resultCapability.
    21. Set onRejected.[[RemainingElements]] to remainingElementsCount.
    22. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    23. Perform ? Invoke(nextPromise, "then", « onFulfilled, onRejected »).
    24. Set index to index + 1.

27.2.4.2.2 Promise.allSettled Resolve Element Functions

A 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 x, the following steps are taken:

  1. Let F be the active function object.
  2. Let alreadyCalled be F.[[AlreadyCalled]].
  3. If alreadyCalled.[[Value]] is true, return undefined.
  4. Set alreadyCalled.[[Value]] to true.
  5. Let index be F.[[Index]].
  6. Let values be F.[[Values]].
  7. Let promiseCapability be F.[[Capability]].
  8. Let remainingElementsCount be F.[[RemainingElements]].
  9. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  10. Perform ! CreateDataPropertyOrThrow(obj, "status", "fulfilled").
  11. Perform ! CreateDataPropertyOrThrow(obj, "value", x).
  12. Set values[index] to obj.
  13. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
  14. If remainingElementsCount.[[Value]] = 0, then
    1. Let valuesArray be CreateArrayFromList(values).
    2. Return ? Call(promiseCapability.[[Resolve]], undefined, « valuesArray »).
  15. Return undefined.

The "length" property of a Promise.allSettled resolve element function is 1𝔽.

27.2.4.2.3 Promise.allSettled Reject Element Functions

A 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 x, the following steps are taken:

  1. Let F be the active function object.
  2. Let alreadyCalled be F.[[AlreadyCalled]].
  3. If alreadyCalled.[[Value]] is true, return undefined.
  4. Set alreadyCalled.[[Value]] to true.
  5. Let index be F.[[Index]].
  6. Let values be F.[[Values]].
  7. Let promiseCapability be F.[[Capability]].
  8. Let remainingElementsCount be F.[[RemainingElements]].
  9. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  10. Perform ! CreateDataPropertyOrThrow(obj, "status", "rejected").
  11. Perform ! CreateDataPropertyOrThrow(obj, "reason", x).
  12. Set values[index] to obj.
  13. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
  14. If remainingElementsCount.[[Value]] = 0, then
    1. Let valuesArray be CreateArrayFromList(values).
    2. Return ? Call(promiseCapability.[[Resolve]], undefined, « valuesArray »).
  15. Return undefined.

The "length" property of a Promise.allSettled reject element function is 1𝔽.

27.2.4.3 Promise.any ( iterable )

This function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError holding the rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.

  1. Let C be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(C).
  3. Let promiseResolve be Completion(GetPromiseResolve(C)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAny(iteratorRecord, C, promiseCapability, promiseResolve)).
  8. If result is an abrupt completion, then
    1. If iteratorRecord.[[Done]] is false, set result to Completion(IteratorClose(iteratorRecord, result)).
    2. IfAbruptRejectPromise(result, promiseCapability).
  9. Return ! result.
 Note

This function requires its this value to be a constructor function that supports the parameter conventions of the Promise constructor.

27.2.4.3.1 PerformPromiseAny ( iteratorRecord, constructor, resultCapability, promiseResolve )

The abstract operation PerformPromiseAny takes arguments iteratorRecord (an Iterator Record), constructor (a constructor), resultCapability (a PromiseCapability Record), and promiseResolve (a function object) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Let errors be a new empty List.
  2. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  3. Let index be 0.
  4. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      2. If remainingElementsCount.[[Value]] = 0, then
        1. Let error be a newly created AggregateError object.
        2. Perform ! DefinePropertyOrThrow(error, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errors) }).
        3. Return ThrowCompletion(error).
      3. Return resultCapability.[[Promise]].
    3. Append undefined to errors.
    4. Let nextPromise be ? Call(promiseResolve, constructor, « next »).
    5. Let stepsRejected be the algorithm steps defined in Promise.any Reject Element Functions.
    6. Let lengthRejected be the number of non-optional parameters of the function definition in Promise.any Reject Element Functions.
    7. Let onRejected be CreateBuiltinFunction(stepsRejected, lengthRejected, "", « [[AlreadyCalled]], [[Index]], [[Errors]], [[Capability]], [[RemainingElements]] »).
    8. Set onRejected.[[AlreadyCalled]] to false.
    9. Set onRejected.[[Index]] to index.
    10. Set onRejected.[[Errors]] to errors.
    11. Set onRejected.[[Capability]] to resultCapability.
    12. Set onRejected.[[RemainingElements]] to remainingElementsCount.
    13. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    14. Perform ? Invoke(nextPromise, "then", « resultCapability.[[Resolve]], onRejected »).
    15. Set index to index + 1.

27.2.4.3.2 Promise.any Reject Element Functions

A Promise.any reject element function is an anonymous built-in function that is used to reject a specific Promise.any element. Each Promise.any reject element function has [[Index]], [[Errors]], [[Capability]], [[RemainingElements]], and [[AlreadyCalled]] internal slots.

When a Promise.any reject element function is called with argument x, the following steps are taken:

  1. Let F be the active function object.
  2. If F.[[AlreadyCalled]] is true, return undefined.
  3. Set F.[[AlreadyCalled]] to true.
  4. Let index be F.[[Index]].
  5. Let errors be F.[[Errors]].
  6. Let promiseCapability be F.[[Capability]].
  7. Let remainingElementsCount be F.[[RemainingElements]].
  8. Set errors[index] to x.
  9. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
  10. If remainingElementsCount.[[Value]] = 0, then
    1. Let error be a newly created AggregateError object.
    2. Perform ! DefinePropertyOrThrow(error, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errors) }).
    3. Return ? Call(promiseCapability.[[Reject]], undefined, « error »).
  11. Return undefined.

The "length" property of a Promise.any reject element function is 1𝔽.

27.2.4.4 Promise.prototype

The initial value of Promise.prototype is the Promise prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

27.2.4.5 Promise.race ( iterable )

This function returns a new promise which is settled in the same way as the first passed promise to settle. It resolves all elements of the passed iterable to promises as it runs this algorithm.

  1. Let C be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(C).
  3. Let promiseResolve be Completion(GetPromiseResolve(C)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).