Multipage preference

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 properties described in Table 79:

Table 79: 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 80. Such objects may also implement the properties in Table 81.

Table 80: 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 81: 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 82:

Table 82: 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 83. Such objects may also implement the properties in Table 84.

Table 83: 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 84: 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 85:

Table 85: 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 obj be this value.
  2. Perform ? RequireInternalSlot(obj, [[UnderlyingIterators]]).
  3. Assert: obj has a [[GeneratorState]] internal slot.
  4. If obj.[[GeneratorState]] is suspended-start, then
    1. Set obj.[[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 obj can be discarded at this point.
    3. Perform ? IteratorCloseAll(obj.[[UnderlyingIterators]], NormalCompletion(unused)).
    4. Return CreateIteratorResultObject(undefined, true).
  5. Let completion be ReturnCompletion(undefined).
  6. Return ? GeneratorResumeAbrupt(obj, completion, "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.concat ( ...items )

  1. Let iterables be a new empty List.
  2. For each element item of items, do
    1. If item is not an Object, throw a TypeError exception.
    2. Let method be ? GetMethod(item, %Symbol.iterator%).
    3. If method is undefined, throw a TypeError exception.
    4. Append the Record { [[OpenMethod]]: method, [[Iterable]]: item } to iterables.
  3. Let closure be a new Abstract Closure with no parameters that captures iterables and performs the following steps when called:
    1. For each Record iterable of iterables, do
      1. Let iterator be ? Call(iterable.[[OpenMethod]], iterable.[[Iterable]]).
      2. If iterator is not an Object, throw a TypeError exception.
      3. Let iteratorRecord be ? GetIteratorDirect(iterator).
      4. Let innerAlive be true.
      5. Repeat, while innerAlive is true,
        1. Let innerValue be ? IteratorStepValue(iteratorRecord).
        2. If innerValue is done, then
          1. Set innerAlive to false.
        3. Else,
          1. Let completion be Completion(Yield(innerValue)).
          2. If completion is an abrupt completion, then
            1. Return ? IteratorClose(iteratorRecord, completion).
    2. Return ReturnCompletion(undefined).
  4. Let gen be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  5. Set gen.[[UnderlyingIterators]] to a new empty List.
  6. Return gen.

27.1.3.2.2 Iterator.from ( obj )

  1. Let iteratorRecord be ? GetIteratorFlattenable(obj, 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.2.1 The %WrapForValidIteratorPrototype% Object

The %WrapForValidIteratorPrototype% object:

27.1.3.2.2.1.1 %WrapForValidIteratorPrototype%.next ( )

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

27.1.3.2.2.1.2 %WrapForValidIteratorPrototype%.return ( )

  1. Let obj be this value.
  2. Perform ? RequireInternalSlot(obj, [[Iterated]]).
  3. Let iterator be obj.[[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.3 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.3.2.4 Iterator.zip ( iterables [ , options ] )

This function performs the following steps when called:

  1. If iterables is not an Object, throw a TypeError exception.
  2. Set options to ? GetOptionsObject(options).
  3. Let mode be ? Get(options, "mode").
  4. If mode is undefined, set mode to "shortest".
  5. If mode is not one of "shortest", "longest", or "strict", throw a TypeError exception.
  6. Let paddingOption be undefined.
  7. If mode is "longest", then
    1. Set paddingOption to ? Get(options, "padding").
    2. If paddingOption is not undefined and paddingOption is not an Object, throw a TypeError exception.
  8. Let iters be a new empty List.
  9. Let padding be a new empty List.
  10. Let inputIter be ? GetIterator(iterables, sync).
  11. Let next be not-started.
  12. Repeat, while next is not done,
    1. Set next to Completion(IteratorStepValue(inputIter)).
    2. IfAbruptCloseIterators(next, iters).
    3. If next is not done, then
      1. Let iter be Completion(GetIteratorFlattenable(next, reject-primitives)).
      2. Let needClosing be the list-concatenation of « inputIter » and iters.
      3. IfAbruptCloseIterators(iter, needClosing).
      4. Append iter to iters.
  13. Let iterCount be the number of elements in iters.
  14. If mode is "longest", then
    1. If paddingOption is undefined, then
      1. Repeat iterCount times:
        1. Append undefined to padding.
    2. Else,
      1. Let paddingIter be Completion(GetIterator(paddingOption, sync)).
      2. IfAbruptCloseIterators(paddingIter, iters).
      3. Let usingIterator be true.
      4. Repeat iterCount times:
        1. If usingIterator is true, then
          1. Set next to Completion(IteratorStepValue(paddingIter)).
          2. IfAbruptCloseIterators(next, iters).
          3. If next is done, then
            1. Set usingIterator to false.
          4. Else,
            1. Append next to padding.
        2. If usingIterator is false, append undefined to padding.
      5. If usingIterator is true, then
        1. Let completion be Completion(IteratorClose(paddingIter, NormalCompletion(unused))).
        2. IfAbruptCloseIterators(completion, iters).
  15. Let finishResults be a new Abstract Closure with parameters (results) that captures nothing and performs the following steps when called:
    1. Return CreateArrayFromList(results).
  16. Return IteratorZip(iters, mode, padding, finishResults).

27.1.3.2.5 Iterator.zipKeyed ( iterables [ , options ] )

This function performs the following steps when called:

  1. If iterables is not an Object, throw a TypeError exception.
  2. Set options to ? GetOptionsObject(options).
  3. Let mode be ? Get(options, "mode").
  4. If mode is undefined, set mode to "shortest".
  5. If mode is not one of "shortest", "longest", or "strict", throw a TypeError exception.
  6. Let paddingOption be undefined.
  7. If mode is "longest", then
    1. Set paddingOption to ? Get(options, "padding").
    2. If paddingOption is not undefined and paddingOption is not an Object, throw a TypeError exception.
  8. Let iters be a new empty List.
  9. Let padding be a new empty List.
  10. Let allKeys be ? iterables.[[OwnPropertyKeys]]().
  11. Let keys be a new empty List.
  12. For each element key of allKeys, do
    1. Let propertyDesc be Completion(iterables.[[GetOwnProperty]](key)).
    2. IfAbruptCloseIterators(propertyDesc, iters).
    3. If propertyDesc is not undefined and propertyDesc.[[Enumerable]] is true, then
      1. Let value be Completion(Get(iterables, key)).
      2. IfAbruptCloseIterators(value, iters).
      3. If value is not undefined, then
        1. Append key to keys.
        2. Let iter be Completion(GetIteratorFlattenable(value, reject-primitives)).
        3. IfAbruptCloseIterators(iter, iters).
        4. Append iter to iters.
  13. Let iterCount be the number of elements in iters.
  14. If mode is "longest", then
    1. If paddingOption is undefined, then
      1. Repeat iterCount times:
        1. Append undefined to padding.
    2. Else,
      1. For each element key of keys, do
        1. Let value be Completion(Get(paddingOption, key)).
        2. IfAbruptCloseIterators(value, iters).
        3. Append value to padding.
  15. Let finishResults be a new Abstract Closure with parameters (results) that captures keys and iterCount and performs the following steps when called:
    1. Let obj be OrdinaryObjectCreate(null).
    2. For each integer i such that 0 ≤ i < iterCount, in ascending order, do
      1. Perform ! CreateDataPropertyOrThrow(obj, keys[i], results[i]).
    3. Return obj.
  16. Return IteratorZip(iters, mode, padding, finishResults).

27.1.3.3 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.3.3.1 Iterator.prototype.chunks ( chunkSize )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If chunkSize is not an integral Number, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. If chunkSize is not in the inclusive interval from 1𝔽 to 𝔽(232 - 1), then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  6. Set iterated to ? GetIteratorDirect(obj).
  7. Let closure be a new Abstract Closure with no parameters that captures iterated and chunkSize and performs the following steps when called:
    1. Let buffer be a new empty List.
    2. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, then
        1. If buffer is not empty, then
          1. Perform Completion(Yield(CreateArrayFromList(buffer))).
        2. Return ReturnCompletion(undefined).
      3. Append value to buffer.
      4. If the number of elements in buffer is ℝ(chunkSize), then
        1. Let completion be Completion(Yield(CreateArrayFromList(buffer))).
        2. IfAbruptCloseIterator(completion, iterated).
        3. Set buffer to a new empty List.
  8. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  9. Set result.[[UnderlyingIterators]] to « iterated ».
  10. Return result.

27.1.3.3.2 Iterator.prototype.constructor

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

27.1.3.3.2.1 get Iterator.prototype.constructor

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

  1. Return %Iterator%.

27.1.3.3.2.2 set Iterator.prototype.constructor

The value of the [[Setter]] 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.3.3.3 Iterator.prototype.drop ( limit )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. Let numberLimit be Completion(ToNumber(limit)).
  5. IfAbruptCloseIterator(numberLimit, iterated).
  6. If numberLimit is NaN, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  7. If numberLimit is finite and numberLimit > 𝔽(253 - 1), then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  8. Let intLimit be ! ToIntegerOrInfinity(numberLimit).
  9. If intLimit < 0, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  10. Set iterated to ? GetIteratorDirect(obj).
  11. Let closure be a new Abstract Closure with no parameters that captures iterated and intLimit and performs the following steps when called:
    1. Let remaining be 𝔽(intLimit).
    2. Repeat, while remaining > +0𝔽,
      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).
  12. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  13. Set result.[[UnderlyingIterators]] to « iterated ».
  14. Return result.

27.1.3.3.4 Iterator.prototype.every ( predicate )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
    7. Set counter to counter + 1𝔽.

27.1.3.3.5 Iterator.prototype.filter ( predicate )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
      7. Set counter to counter + 1𝔽.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  8. Set result.[[UnderlyingIterators]] to « iterated ».
  9. Return result.

27.1.3.3.6 Iterator.prototype.find ( predicate )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
    7. Set counter to counter + 1𝔽.

27.1.3.3.7 Iterator.prototype.flatMap ( mapper )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
      10. Set counter to counter + 1𝔽.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  8. Set result.[[UnderlyingIterators]] to « iterated ».
  9. Return result.

27.1.3.3.8 Iterator.prototype.forEach ( procedure )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
    6. Set counter to counter + 1𝔽.

27.1.3.3.9 Iterator.prototype.includes ( searchElement [ , skippedElements ] )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If skippedElements is undefined, then
    1. Let toSkip be +0𝔽.
  5. Else,
    1. If skippedElements is not one of +∞𝔽, -∞𝔽, or an integral Number, then
      1. Let error be ThrowCompletion(a newly created TypeError object).
      2. Return ? IteratorClose(iterated, error).
    2. Let toSkip be skippedElements.
  6. If toSkip < -0𝔽, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  7. If toSkip is finite and toSkip > 𝔽(253 - 1), then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  8. Let skipped be +0𝔽.
  9. Set iterated to ? GetIteratorDirect(obj).
  10. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return false.
    3. If skipped < toSkip, then
      1. Set skipped to skipped + 1𝔽.
    4. Else if SameValueZero(value, searchElement) is true, then
      1. Return ? IteratorClose(iterated, NormalCompletion(true)).

27.1.3.3.10 Iterator.prototype.join ( separator )

This method converts the values of the iterator to Strings, and then concatenates these Strings, separated by occurrences of the separator. If no separator is provided, a single comma is used as the separator.

It performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If separator is undefined, then
    1. Let separatorString be ",".
  5. Else,
    1. Let separatorString be Completion(ToString(separator)).
    2. IfAbruptCloseIterator(separatorString, iterated).
  6. Set iterated to ? GetIteratorDirect(obj).
  7. Let result be the empty String.
  8. Let first be true.
  9. Repeat,
    1. Let value be ? IteratorStepValue(iterated).
    2. If value is done, return result.
    3. If first is true, then
      1. Set first to false.
    4. Else,
      1. Set result to the string-concatenation of result and separatorString.
    5. If value is neither undefined nor null, then
      1. Let valueString be Completion(ToString(value)).
      2. IfAbruptCloseIterator(valueString, iterated).
      3. Set result to the string-concatenation of result and valueString.

27.1.3.3.11 Iterator.prototype.map ( mapper )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
      8. Set counter to counter + 1𝔽.
  7. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  8. Set result.[[UnderlyingIterators]] to « iterated ».
  9. Return result.

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

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
    7. Set counter to counter + 1𝔽.

27.1.3.3.13 Iterator.prototype.some ( predicate )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[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(obj).
  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. NOTE: The following step will not change counter once it reaches 253𝔽.
    7. Set counter to counter + 1𝔽.

27.1.3.3.14 Iterator.prototype.take ( limit )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. Let numberLimit be Completion(ToNumber(limit)).
  5. IfAbruptCloseIterator(numberLimit, iterated).
  6. If numberLimit is NaN, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  7. If numberLimit is finite and numberLimit > 𝔽(253 - 1), then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  8. Let intLimit be ! ToIntegerOrInfinity(numberLimit).
  9. If intLimit < 0, then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  10. Set iterated to ? GetIteratorDirect(obj).
  11. Let closure be a new Abstract Closure with no parameters that captures iterated and intLimit and performs the following steps when called:
    1. Let remaining be 𝔽(intLimit).
    2. Repeat,
      1. If remaining is +0𝔽, then
        1. Return ? IteratorClose(iterated, ReturnCompletion(undefined)).
      2. 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).
  12. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  13. Set result.[[UnderlyingIterators]] to « iterated ».
  14. Return result.

27.1.3.3.15 Iterator.prototype.toArray ( )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be ? GetIteratorDirect(obj).
  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.3.3.16 Iterator.prototype.windows ( windowSize [ , undersized ] )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let iterated be the Iterator Record { [[Iterator]]: obj, [[NextMethod]]: undefined, [[Done]]: false }.
  4. If windowSize is not an integral Number, then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  5. If windowSize is not in the inclusive interval from 1𝔽 to 𝔽(232 - 1), then
    1. Let error be ThrowCompletion(a newly created RangeError object).
    2. Return ? IteratorClose(iterated, error).
  6. If undersized is undefined, set undersized to "only-full".
  7. If undersized is neither "only-full" nor "allow-partial", then
    1. Let error be ThrowCompletion(a newly created TypeError object).
    2. Return ? IteratorClose(iterated, error).
  8. Set iterated to ? GetIteratorDirect(obj).
  9. Let closure be a new Abstract Closure with no parameters that captures iterated, windowSize, and undersized and performs the following steps when called:
    1. Let buffer be a new empty List.
    2. Repeat,
      1. Let value be ? IteratorStepValue(iterated).
      2. If value is done, then
        1. If undersized is "allow-partial", buffer is not empty, and the number of elements in buffer < ℝ(windowSize), then
          1. Perform Completion(Yield(CreateArrayFromList(buffer))).
        2. Return ReturnCompletion(undefined).
      3. If the number of elements in buffer is ℝ(windowSize), then
        1. Remove the first element from buffer.
      4. Append value to buffer.
      5. If the number of elements in buffer is ℝ(windowSize), then
        1. Let completion be Completion(Yield(CreateArrayFromList(buffer))).
        2. IfAbruptCloseIterator(completion, iterated).
  10. Let result be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  11. Set result.[[UnderlyingIterators]] to « iterated ».
  12. Return result.

27.1.3.3.17 Iterator.prototype [ %Symbol.dispose% ] ( )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. Let return be ? GetMethod(obj, "return").
  3. If return is not undefined, then
    1. Perform ? Call(return, obj).
  4. Return undefined.

The value of the "name" property of this method is "[Symbol.dispose]".

27.1.3.3.18 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.3.3.19 Iterator.prototype [ %Symbol.toStringTag% ]

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

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

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

  1. Return "Iterator".

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

The value of the [[Setter]] 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.3.4 Abstract Operations for Iterators

27.1.3.4.1 IteratorZip ( iters, mode, padding, finishResults )

The abstract operation IteratorZip takes arguments iters (a List of Iterator Records), mode ("shortest", "longest", or "strict"), padding (a List of ECMAScript language values), and finishResults (an Abstract Closure that takes a List of ECMAScript language values and returns an ECMAScript language value) and returns a Generator. It performs the following steps when called:

  1. Let iterCount be the number of elements in iters.
  2. Let openIters be a copy of iters.
  3. Let closure be a new Abstract Closure with no parameters that captures iters, iterCount, openIters, mode, padding, and finishResults and performs the following steps when called:
    1. If iterCount = 0, return ReturnCompletion(undefined).
    2. Repeat,
      1. Let results be a new empty List.
      2. Assert: openIters is not empty.
      3. For each integer i such that 0 ≤ i < iterCount, in ascending order, do
        1. Let iter be iters[i].
        2. If iter is null, then
          1. Assert: mode is "longest".
          2. Let result be padding[i].
        3. Else,
          1. Let result be Completion(IteratorStepValue(iter)).
          2. If result is an abrupt completion, then
            1. Remove iter from openIters.
            2. Return ? IteratorCloseAll(openIters, result).
          3. Set result to ! result.
          4. If result is done, then
            1. Remove iter from openIters.
            2. If mode is "shortest", then
              1. Return ? IteratorCloseAll(openIters, ReturnCompletion(undefined)).
            3. Else if mode is "strict", then
              1. If i ≠ 0, then
                1. Return ? IteratorCloseAll(openIters, ThrowCompletion(a newly created TypeError object)).
              2. For each integer k such that 1 ≤ k < iterCount, in ascending order, do
                1. Assert: iters[k] is not null.
                2. Let open be Completion(IteratorStep(iters[k])).
                3. If open is an abrupt completion, then
                  1. Remove iters[k] from openIters.
                  2. Return ? IteratorCloseAll(openIters, open).
                4. Set open to ! open.
                5. If open is done, then
                  1. Remove iters[k] from openIters.
                6. Else,
                  1. Return ? IteratorCloseAll(openIters, ThrowCompletion(a newly created TypeError object)).
              3. Return ReturnCompletion(undefined).
            4. Else,
              1. Assert: mode is "longest".
              2. If openIters is empty, return ReturnCompletion(undefined).
              3. Set iters[i] to null.
              4. Set result to padding[i].
        4. Append result to results.
      4. Set results to finishResults(results).
      5. Let completion be Completion(Yield(results)).
      6. IfAbruptCloseIterators(completion, openIters).
  4. Let gen be CreateIteratorFromClosure(closure, "Iterator Helper", %IteratorHelperPrototype%, « [[UnderlyingIterators]] »).
  5. Set gen.[[UnderlyingIterators]] to openIters.
  6. Return gen.

27.1.4 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.4.1 %AsyncIteratorPrototype% [ %Symbol.asyncDispose% ] ( )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Let return be Completion(GetMethod(obj, "return")).
  4. IfAbruptRejectPromise(return, promiseCapability).
  5. If return is undefined, then
    1. Perform ! Call(promiseCapability.[[Resolve]], undefined, « undefined »).
  6. Else,
    1. Let result be Completion(Call(return, obj, « »)).
    2. IfAbruptRejectPromise(result, promiseCapability).
    3. Let resultWrapper be Completion(PromiseResolve(%Promise%, result)).
    4. IfAbruptRejectPromise(resultWrapper, promiseCapability).
    5. Let unwrap be a new Abstract Closure with no parameters that captures nothing and performs the following steps when called:
      1. Return undefined.
    6. Let onFulfilled be CreateBuiltinFunction(unwrap, 1, "", « »).
    7. Perform PerformPromiseThen(resultWrapper, onFulfilled, undefined, promiseCapability).
  7. Return promiseCapability.[[Promise]].

The value of the "name" property of this method is "[Symbol.asyncDispose]".

27.1.4.2 %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.5 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.5.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.5.2 The %AsyncFromSyncIteratorPrototype% Object

The %AsyncFromSyncIteratorPrototype% object:

27.1.5.2.1 %AsyncFromSyncIteratorPrototype%.next ( [ value ] )

  1. Let obj be the this value.
  2. Assert: obj is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be obj.[[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.5.2.2 %AsyncFromSyncIteratorPrototype%.return ( [ value ] )

  1. Let obj be the this value.
  2. Assert: obj is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be obj.[[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.5.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 obj be the this value.
  2. Assert: obj is an Object that has a [[SyncIteratorRecord]] internal slot.
  3. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  4. Let syncIteratorRecord be obj.[[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.5.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 86.

Table 86: 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.5.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 (value) that captures done and performs the following steps when called:
    1. Return CreateIteratorResultObject(value, 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 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 Resource Management

27.2.1 Common Resource Management Interfaces

27.2.1.1 The Disposable Interface

The Disposable interface includes the properties described in Table 87:

Table 87: Disposable Interface Required Properties
Property Value Requirements
%Symbol.dispose% a function object

Invoking this method notifies the Disposable object that the caller does not intend to continue to use this object. This method should perform any necessary logic to perform explicit clean-up of the resource including, but not limited to, file system handles, streams, host objects, etc. When an exception is thrown from this method, it typically means that the resource could not be explicitly freed.

Invoking this method more than once on the same object should avoid repeating clean-up logic against the already-disposed resource and should not throw an exception, even if an exception was thrown on the first invocation. However, this requirement is not enforced.

When using a Disposable object with a using or await using declaration, the resource will be automatically disposed when the Block or Module immediately containing the declaration has been evaluated.

27.2.1.2 The AsyncDisposable Interface

The AsyncDisposable interface includes the properties described in Table 88:

Table 88: AsyncDisposable Interface Required Properties
Property Value Requirements
%Symbol.asyncDispose% a function object that returns a promise

Invoking this method notifies the AsyncDisposable object that the caller does not intend to continue to use this object. This method should perform any necessary logic to perform explicit clean-up of the resource including, but not limited to, file system handles, streams, host objects, etc. When the promise returned by this method is rejected, it typically means that the resource could not be explicitly freed. An AsyncDisposable object is not considered “disposed” until the resulting Promise has been fulfilled.

Invoking this method more than once on the same object should avoid repeating clean-up logic against the already-disposed resource and should not throw an exception or return a rejected promise, even if an exception was thrown or a rejected promise was returned on the first invocation. However, this requirement is not enforced.

When using an AsyncDisposable object with an await using declaration, the resource will be automatically disposed when the Block or Module immediately containing the declaration has been evaluated.

27.3 DisposableStack Objects

A DisposableStack is an object that can be used to contain one or more resources that should be disposed together.

Any DisposableStack object is in one of two mutually exclusive states: disposed or pending. A disposable stack d is pending if and only if neither d.dispose() nor d.move() has been invoked for d.

27.3.1 The DisposableStack Constructor

The DisposableStack constructor:

  • is %DisposableStack%.
  • is the initial value of the "DisposableStack" property of the global object.
  • creates and initializes a new DisposableStack 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 DisposableStack behaviour must include a super call to the DisposableStack constructor to create and initialize the subclass instance with the internal state necessary to support the built-in methods of DisposableStack.prototype.

27.3.1.1 DisposableStack ( )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let disposableStack be ? OrdinaryCreateFromConstructor(NewTarget, "%DisposableStack.prototype%", « [[DisposableState]], [[DisposableResourceStack]] »).
  3. Set disposableStack.[[DisposableState]] to pending.
  4. Set disposableStack.[[DisposableResourceStack]] to a new empty List.
  5. Return disposableStack.

27.3.2 Properties of the DisposableStack Constructor

The DisposableStack constructor:

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

27.3.2.1 DisposableStack.prototype

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

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

27.3.3 Properties of the DisposableStack Prototype Object

The DisposableStack prototype object:

  • is %DisposableStack.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have a [[DisposableState]] internal slot or any of the other internal slots of DisposableStack instances.

27.3.3.1 DisposableStack.prototype.adopt ( value, onDispose )

This method performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, throw a ReferenceError exception.
  4. If IsCallable(onDispose) is false, throw a TypeError exception.
  5. Let closure be a new Abstract Closure with no parameters that captures value and onDispose and performs the following steps when called:
    1. Return ? Call(onDispose, undefined, « value »).
  6. Let func be CreateBuiltinFunction(closure, 0, "", « »).
  7. Perform ! AddDisposableResource(disposableStack.[[DisposableResourceStack]], undefined, sync-dispose, func).
  8. Return value.

27.3.3.2 DisposableStack.prototype.constructor

The initial value of DisposableStack.prototype.constructor is %DisposableStack%.

27.3.3.3 DisposableStack.prototype.defer ( onDispose )

This method performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, throw a ReferenceError exception.
  4. If IsCallable(onDispose) is false, throw a TypeError exception.
  5. Perform ! AddDisposableResource(disposableStack.[[DisposableResourceStack]], undefined, sync-dispose, onDispose).
  6. Return undefined.

27.3.3.4 DisposableStack.prototype.dispose ( )

This method performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, return undefined.
  4. Set disposableStack.[[DisposableState]] to disposed.
  5. Return ? DisposeResources(disposableStack.[[DisposableResourceStack]], NormalCompletion(undefined)).

27.3.3.5 get DisposableStack.prototype.disposed

DisposableStack.prototype.disposed is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, return true.
  4. Return false.

27.3.3.6 DisposableStack.prototype.move ( )

This method performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, throw a ReferenceError exception.
  4. Let newDisposableStack be OrdinaryObjectCreate(%DisposableStack.prototype%, « [[DisposableState]], [[DisposableResourceStack]] »).
  5. Set newDisposableStack.[[DisposableState]] to pending.
  6. Set newDisposableStack.[[DisposableResourceStack]] to disposableStack.[[DisposableResourceStack]].
  7. Set disposableStack.[[DisposableResourceStack]] to a new empty List.
  8. Set disposableStack.[[DisposableState]] to disposed.
  9. Return newDisposableStack.

27.3.3.7 DisposableStack.prototype.use ( value )

This method performs the following steps when called:

  1. Let disposableStack be the this value.
  2. Perform ? RequireInternalSlot(disposableStack, [[DisposableState]]).
  3. If disposableStack.[[DisposableState]] is disposed, throw a ReferenceError exception.
  4. Perform ? AddDisposableResource(disposableStack.[[DisposableResourceStack]], value, sync-dispose).
  5. Return value.

27.3.3.8 DisposableStack.prototype [ %Symbol.dispose% ] ( )

The initial value of the %Symbol.dispose% property is %DisposableStack.prototype.dispose%, defined in 27.3.3.4.

27.3.3.9 DisposableStack.prototype [ %Symbol.toStringTag% ]

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

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

27.3.4 Properties of DisposableStack Instances

DisposableStack instances are ordinary objects that inherit properties from the DisposableStack prototype object (the intrinsic %DisposableStack.prototype%). DisposableStack instances are initially created with internal slots described in Table 89.

Table 89: Internal Slots of DisposableStack Instances
Internal Slot Type Description
[[DisposableState]] pending or disposed Governs how a disposable stack will react to incoming calls to its %Symbol.dispose% method.
[[DisposableResourceStack]] a List of DisposableResource Records Resources to be disposed when the disposable stack is disposed. Resources are added in the order they are initialized, and are disposed in reverse order.

27.4 AsyncDisposableStack Objects

An AsyncDisposableStack is an object that can be used to contain one or more resources that should be asynchronously disposed together.

Any AsyncDisposableStack object is in one of two mutually exclusive states: disposed or pending. An async-disposable stack d is pending if and only if neither d.disposeAsync() nor d.move() has been invoked for d.

27.4.1 The AsyncDisposableStack Constructor

The AsyncDisposableStack constructor:

  • is %AsyncDisposableStack%.
  • is the initial value of the "AsyncDisposableStack" property of the global object.
  • creates and initializes a new AsyncDisposableStack 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 AsyncDisposableStack behaviour must include a super call to the AsyncDisposableStack constructor to create and initialize the subclass instance with the internal state necessary to support the built-in methods of AsyncDisposableStack.prototype.

27.4.1.1 AsyncDisposableStack ( )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let asyncDisposableStack be ? OrdinaryCreateFromConstructor(NewTarget, "%AsyncDisposableStack.prototype%", « [[AsyncDisposableState]], [[DisposableResourceStack]] »).
  3. Set asyncDisposableStack.[[AsyncDisposableState]] to pending.
  4. Set asyncDisposableStack.[[DisposableResourceStack]] to a new empty List.
  5. Return asyncDisposableStack.

27.4.2 Properties of the AsyncDisposableStack Constructor

The AsyncDisposableStack constructor:

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

27.4.2.1 AsyncDisposableStack.prototype

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

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

27.4.3 Properties of the AsyncDisposableStack Prototype Object

The AsyncDisposableStack prototype object:

  • is %AsyncDisposableStack.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have an [[AsyncDisposableState]] internal slot or any of the other internal slots of AsyncDisposableStack instances.

27.4.3.1 AsyncDisposableStack.prototype.adopt ( value, onDisposeAsync )

This method performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, throw a ReferenceError exception.
  4. If IsCallable(onDisposeAsync) is false, throw a TypeError exception.
  5. Let closure be a new Abstract Closure with no parameters that captures value and onDisposeAsync and performs the following steps when called:
    1. Return ? Call(onDisposeAsync, undefined, « value »).
  6. Let func be CreateBuiltinFunction(closure, 0, "", « »).
  7. Perform ! AddDisposableResource(asyncDisposableStack.[[DisposableResourceStack]], undefined, async-dispose, func).
  8. Return value.

27.4.3.2 AsyncDisposableStack.prototype.constructor

The initial value of AsyncDisposableStack.prototype.constructor is %AsyncDisposableStack%.

27.4.3.3 AsyncDisposableStack.prototype.defer ( onDisposeAsync )

This method performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, throw a ReferenceError exception.
  4. If IsCallable(onDisposeAsync) is false, throw a TypeError exception.
  5. Perform ! AddDisposableResource(asyncDisposableStack.[[DisposableResourceStack]], undefined, async-dispose, onDisposeAsync).
  6. Return undefined.

27.4.3.4 AsyncDisposableStack.prototype.disposeAsync ( )

This async method performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, return undefined.
  4. Set asyncDisposableStack.[[AsyncDisposableState]] to disposed.
  5. Return ? DisposeResources(asyncDisposableStack.[[DisposableResourceStack]], NormalCompletion(undefined)).

27.4.3.5 get AsyncDisposableStack.prototype.disposed

AsyncDisposableStack.prototype.disposed is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, return true.
  4. Return false.

27.4.3.6 AsyncDisposableStack.prototype.move ( )

This method performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, throw a ReferenceError exception.
  4. Let newAsyncDisposableStack be OrdinaryObjectCreate(%AsyncDisposableStack.prototype%, « [[AsyncDisposableState]], [[DisposableResourceStack]] »).
  5. Set newAsyncDisposableStack.[[AsyncDisposableState]] to pending.
  6. Set newAsyncDisposableStack.[[DisposableResourceStack]] to asyncDisposableStack.[[DisposableResourceStack]].
  7. Set asyncDisposableStack.[[DisposableResourceStack]] to a new empty List.
  8. Set asyncDisposableStack.[[AsyncDisposableState]] to disposed.
  9. Return newAsyncDisposableStack.

27.4.3.7 AsyncDisposableStack.prototype.use ( value )

This method performs the following steps when called:

  1. Let asyncDisposableStack be the this value.
  2. Perform ? RequireInternalSlot(asyncDisposableStack, [[AsyncDisposableState]]).
  3. If asyncDisposableStack.[[AsyncDisposableState]] is disposed, throw a ReferenceError exception.
  4. Perform ? AddDisposableResource(asyncDisposableStack.[[DisposableResourceStack]], value, async-dispose).
  5. Return value.

27.4.3.8 AsyncDisposableStack.prototype [ %Symbol.asyncDispose% ] ( )

The initial value of the %Symbol.asyncDispose% property is %AsyncDisposableStack.prototype.disposeAsync%, defined in 27.4.3.4.

27.4.3.9 AsyncDisposableStack.prototype [ %Symbol.toStringTag% ]

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

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

27.4.4 Properties of AsyncDisposableStack Instances

AsyncDisposableStack instances are ordinary objects that inherit properties from the AsyncDisposableStack prototype object (the intrinsic %AsyncDisposableStack.prototype%). AsyncDisposableStack instances are initially created with internal slots described in Table 90.

Table 90: Internal Slots of AsyncDisposableStack Instances
Internal Slot Type Description
[[AsyncDisposableState]] pending or disposed Governs how a disposable stack will react to incoming calls to its %Symbol.asyncDispose% method.
[[DisposableResourceStack]] a List of DisposableResource Records Resources to be disposed when the disposable stack is disposed. Resources are added in the order they are initialized, and are disposed in reverse order.

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

A thenable is an object obj for which Get(obj, "then") returns a function object.

27.5.1 Promise Abstract Operations

27.5.1.1 PromiseCapability Records

A PromiseCapability Record is a Record 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 91.

Table 91: 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.5.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. Set value to ! value.

27.5.1.2 PromiseReaction Records

A PromiseReaction Record is a Record 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 92.

Table 92: 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.5.1.3 CreateResolvingFunctions ( toResolve )

The abstract operation CreateResolvingFunctions takes argument toResolve (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 promiseOrEmpty be the Record { [[Value]]: toResolve }.
  2. Let resolveSteps be a new Abstract Closure with parameters (resolution) that captures promiseOrEmpty and performs the following steps when called:
    1. If promiseOrEmpty.[[Value]] is empty, return undefined.
    2. Let promise be promiseOrEmpty.[[Value]].
    3. Set promiseOrEmpty.[[Value]] to empty.
    4. If SameValue(resolution, promise) is true, then
      1. Let selfResolutionError be a newly created TypeError object.
      2. Perform RejectPromise(promise, selfResolutionError).
      3. Return undefined.
    5. If resolution is not an Object, then
      1. Perform FulfillPromise(promise, resolution).
      2. Return undefined.
    6. Let then be Completion(Get(resolution, "then")).
    7. If then is an abrupt completion, then
      1. Perform RejectPromise(promise, then.[[Value]]).
      2. Return undefined.
    8. Let thenAction be then.[[Value]].
    9. If IsCallable(thenAction) is false, then
      1. Perform FulfillPromise(promise, resolution).
      2. Return undefined.
    10. Let thenJobCallback be HostMakeJobCallback(thenAction).
    11. Let job be NewPromiseResolveThenableJob(promise, resolution, thenJobCallback).
    12. Perform HostEnqueuePromiseJob(job.[[Job]], job.[[Realm]]).
    13. Return undefined.
  3. Let resolve be CreateBuiltinFunction(resolveSteps, 1, "", « »).
  4. Let rejectSteps be a new Abstract Closure with parameters (reason) that captures promiseOrEmpty and performs the following steps when called:
    1. If promiseOrEmpty.[[Value]] is empty, return undefined.
    2. Let promise be promiseOrEmpty.[[Value]].
    3. Set promiseOrEmpty.[[Value]] to empty.
    4. Perform RejectPromise(promise, reason).
    5. Return undefined.
  5. Let reject be CreateBuiltinFunction(rejectSteps, 1, "", « »).
  6. Return the Record { [[Resolve]]: resolve, [[Reject]]: reject }.

27.5.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.5.1.5 NewPromiseCapability ( ctor )

The abstract operation NewPromiseCapability takes argument ctor (an ECMAScript language value) and returns either a normal completion containing a PromiseCapability Record or a throw completion. It attempts to use ctor 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(ctor) is false, throw a TypeError exception.
  2. NOTE: ctor is assumed to be a constructor function that supports the parameter conventions of the Promise constructor (see 27.5.3.1).
  3. Let resolvingFuncs be the Record { [[Resolve]]: undefined, [[Reject]]: undefined }.
  4. Let executorClosure be a new Abstract Closure with parameters (resolve, reject) that captures resolvingFuncs and performs the following steps when called:
    1. If resolvingFuncs.[[Resolve]] is not undefined, throw a TypeError exception.
    2. If resolvingFuncs.[[Reject]] is not undefined, throw a TypeError exception.
    3. Set resolvingFuncs.[[Resolve]] to resolve.
    4. Set resolvingFuncs.[[Reject]] to reject.
    5. Return NormalCompletion(undefined).
  5. Let executor be CreateBuiltinFunction(executorClosure, 2, "", « »).
  6. Let promise be ? Construct(ctor, « executor »).
  7. If IsCallable(resolvingFuncs.[[Resolve]]) is false, throw a TypeError exception.
  8. If IsCallable(resolvingFuncs.[[Reject]]) is false, throw a TypeError exception.
  9. Return the PromiseCapability Record { [[Promise]]: promise, [[Resolve]]: resolvingFuncs.[[Resolve]], [[Reject]]: resolvingFuncs.[[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.5.1.6 IsPromise ( arg )

The abstract operation IsPromise takes argument arg (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 arg is not an Object, return false.
  2. If arg does not have a [[PromiseState]] internal slot, return false.
  3. Return true.

27.5.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.5.1.8 TriggerPromiseReactions ( reactions, arg )

The abstract operation TriggerPromiseReactions takes arguments reactions (a List of PromiseReaction Records) and arg (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, arg).
    2. Perform HostEnqueuePromiseJob(job.[[Job]], job.[[Realm]]).
  2. Return unused.

27.5.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.5.2 Promise Jobs

27.5.2.1 NewPromiseReactionJob ( reaction, arg )

The abstract operation NewPromiseReactionJob takes arguments reaction (a PromiseReaction Record) and arg (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 arg 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(arg).
      2. Else,
        1. Assert: type is reject.
        2. Let handlerResult be ThrowCompletion(arg).
    5. Else,
      1. Let handlerResult be Completion(HostCallJobCallback(handler, undefined, « arg »)).
    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. 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.5.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 resolvingFuncs be CreateResolvingFunctions(promiseToResolve).
    2. Let thenCallResult be Completion(HostCallJobCallback(then, thenable, « resolvingFuncs.[[Resolve]], resolvingFuncs.[[Reject]] »)).
    3. If thenCallResult is an abrupt completion, then
      1. Return ! Call(resolvingFuncs.[[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.5.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 built-in methods of Promise and Promise.prototype.

27.5.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 resolvingFuncs be CreateResolvingFunctions(promise).
  10. Let completion be Completion(Call(executor, undefined, « resolvingFuncs.[[Resolve]], resolvingFuncs.[[Reject]] »)).
  11. If completion is an abrupt completion, then
    1. Perform ! Call(resolvingFuncs.[[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.5.4 Properties of the Promise Constructor

The Promise constructor:

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

27.5.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 ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Let promiseResolve be Completion(GetPromiseResolve(ctor)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAll(iteratorRecord, ctor, 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.5.4.1.1 GetPromiseResolve ( promiseCtor )

The abstract operation GetPromiseResolve takes argument promiseCtor (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(promiseCtor, "resolve").
  2. If IsCallable(promiseResolve) is false, throw a TypeError exception.
  3. Return promiseResolve.

27.5.4.1.2 PerformPromiseAll ( iteratorRecord, ctor, resultCapability, promiseResolve )

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

  1. Let values be a new empty List.
  2. NOTE: remainingElementsCount starts at 1 instead of 0 to ensure resultCapability.[[Resolve]] is only called once, even in the presence of a misbehaving "then" which calls the passed callback before the input iterator is exhausted.
  3. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  4. Let index be 0.
  5. 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, ctor, « next »).
    5. Let fulfilledSteps be a new Abstract Closure with parameters (value) that captures values, resultCapability, and remainingElementsCount and performs the following steps when called:
      1. Let activeFunc be the active function object.
      2. If activeFunc.[[AlreadyCalled]] is true, return undefined.
      3. Set activeFunc.[[AlreadyCalled]] to true.
      4. Let thisIndex be activeFunc.[[Index]].
      5. Set values[thisIndex] to value.
      6. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      7. If remainingElementsCount.[[Value]] = 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Return ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      8. Return undefined.
    6. Let onFulfilled be CreateBuiltinFunction(fulfilledSteps, 1, "", « [[AlreadyCalled]], [[Index]] »).
    7. Set onFulfilled.[[AlreadyCalled]] to false.
    8. Set onFulfilled.[[Index]] to index.
    9. Set index to index + 1.
    10. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    11. Perform ? Invoke(nextPromise, "then", « onFulfilled, resultCapability.[[Reject]] »).

27.5.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 ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Let promiseResolve be Completion(GetPromiseResolve(ctor)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAllSettled(iteratorRecord, ctor, 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.5.4.2.1 PerformPromiseAllSettled ( iteratorRecord, ctor, resultCapability, promiseResolve )

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

  1. Let values be a new empty List.
  2. NOTE: remainingElementsCount starts at 1 instead of 0 to ensure resultCapability.[[Resolve]] is only called once, even in the presence of a misbehaving "then" which calls one of the passed callbacks before the input iterator is exhausted.
  3. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  4. Let index be 0.
  5. 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, ctor, « next »).
    5. Let alreadyCalled be the Record { [[Value]]: false }.
    6. Let fulfilledSteps be a new Abstract Closure with parameters (value) that captures values, resultCapability, and remainingElementsCount and performs the following steps when called:
      1. Let activeFunc be the active function object.
      2. If activeFunc.[[AlreadyCalled]].[[Value]] is true, return undefined.
      3. Set activeFunc.[[AlreadyCalled]].[[Value]] to true.
      4. Let obj be OrdinaryObjectCreate(%Object.prototype%).
      5. Perform ! CreateDataPropertyOrThrow(obj, "status", "fulfilled").
      6. Perform ! CreateDataPropertyOrThrow(obj, "value", value).
      7. Let thisIndex be activeFunc.[[Index]].
      8. Set values[thisIndex] to obj.
      9. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      10. If remainingElementsCount.[[Value]] = 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Return ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      11. Return undefined.
    7. Let onFulfilled be CreateBuiltinFunction(fulfilledSteps, 1, "", « [[AlreadyCalled]], [[Index]] »).
    8. Set onFulfilled.[[AlreadyCalled]] to alreadyCalled.
    9. Set onFulfilled.[[Index]] to index.
    10. Let rejectedSteps be a new Abstract Closure with parameters (error) that captures values, resultCapability, and remainingElementsCount and performs the following steps when called:
      1. Let activeFunc be the active function object.
      2. If activeFunc.[[AlreadyCalled]].[[Value]] is true, return undefined.
      3. Set activeFunc.[[AlreadyCalled]].[[Value]] to true.
      4. Let obj be OrdinaryObjectCreate(%Object.prototype%).
      5. Perform ! CreateDataPropertyOrThrow(obj, "status", "rejected").
      6. Perform ! CreateDataPropertyOrThrow(obj, "reason", error).
      7. Let thisIndex be activeFunc.[[Index]].
      8. Set values[thisIndex] to obj.
      9. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      10. If remainingElementsCount.[[Value]] = 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Return ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      11. Return undefined.
    11. Let onRejected be CreateBuiltinFunction(rejectedSteps, 1, "", « [[AlreadyCalled]], [[Index]] »).
    12. Set onRejected.[[AlreadyCalled]] to alreadyCalled.
    13. Set onRejected.[[Index]] to index.
    14. Set index to index + 1.
    15. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    16. Perform ? Invoke(nextPromise, "then", « onFulfilled, onRejected »).

27.5.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 ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Let promiseResolve be Completion(GetPromiseResolve(ctor)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseAny(iteratorRecord, ctor, 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.5.4.3.1 PerformPromiseAny ( iteratorRecord, ctor, resultCapability, promiseResolve )

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

  1. Let errors be a new empty List.
  2. NOTE: remainingElementsCount starts at 1 instead of 0 to ensure resultCapability.[[Reject]] is only called once, even in the presence of a misbehaving "then" which calls the passed callback before the input iterator is exhausted.
  3. Let remainingElementsCount be the Record { [[Value]]: 1 }.
  4. Let index be 0.
  5. 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 aggregateError be a newly created AggregateError object.
        2. Perform ! DefinePropertyOrThrow(aggregateError, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errors) }).
        3. Perform ? Call(resultCapability.[[Reject]], undefined, « aggregateError »).
      3. Return resultCapability.[[Promise]].
    3. Append undefined to errors.
    4. Let nextPromise be ? Call(promiseResolve, ctor, « next »).
    5. Let rejectedSteps be a new Abstract Closure with parameters (error) that captures errors, resultCapability, and remainingElementsCount and performs the following steps when called:
      1. Let activeFunc be the active function object.
      2. If activeFunc.[[AlreadyCalled]] is true, return undefined.
      3. Set activeFunc.[[AlreadyCalled]] to true.
      4. Let thisIndex be activeFunc.[[Index]].
      5. Set errors[thisIndex] to error.
      6. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      7. If remainingElementsCount.[[Value]] = 0, then
        1. Let aggregateError be a newly created AggregateError object.
        2. Perform ! DefinePropertyOrThrow(aggregateError, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errors) }).
        3. Return ? Call(resultCapability.[[Reject]], undefined, « aggregateError »).
      8. Return undefined.
    6. Let onRejected be CreateBuiltinFunction(rejectedSteps, 1, "", « [[AlreadyCalled]], [[Index]] »).
    7. Set onRejected.[[AlreadyCalled]] to false.
    8. Set onRejected.[[Index]] to index.
    9. Set index to index + 1.
    10. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    11. Perform ? Invoke(nextPromise, "then", « resultCapability.[[Resolve]], onRejected »).

27.5.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.5.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 ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Let promiseResolve be Completion(GetPromiseResolve(ctor)).
  4. IfAbruptRejectPromise(promiseResolve, promiseCapability).
  5. Let iteratorRecord be Completion(GetIterator(iterable, sync)).
  6. IfAbruptRejectPromise(iteratorRecord, promiseCapability).
  7. Let result be Completion(PerformPromiseRace(iteratorRecord, ctor, 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 1

If the iterable argument yields no values or if none of the promises yielded by iterable ever settle, then the pending promise returned by this method will never be settled.

 Note 2

This function expects its this value to be a constructor function that supports the parameter conventions of the Promise constructor. It also expects that its this value provides a resolve method.

27.5.4.5.1 PerformPromiseRace ( iteratorRecord, ctor, resultCapability, promiseResolve )

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

  1. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Return resultCapability.[[Promise]].
    3. Let nextPromise be ? Call(promiseResolve, ctor, « next »).
    4. Perform ? Invoke(nextPromise, "then", « resultCapability.[[Resolve]], resultCapability.[[Reject]] »).

27.5.4.6 Promise.reject ( reason )

This function returns a new promise rejected with the passed argument.

  1. Let ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Perform ? Call(promiseCapability.[[Reject]], undefined, « reason »).
  4. Return promiseCapability.[[Promise]].
 Note

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

27.5.4.7 Promise.resolve ( resolution )

This function returns either a new promise resolved with the passed argument, or the argument itself if the argument is a promise produced by this constructor.

  1. Let ctor be the this value.
  2. If ctor is not an Object, throw a TypeError exception.
  3. Return ? PromiseResolve(ctor, resolution).
 Note

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

27.5.4.7.1 PromiseResolve ( ctor, resolution )

The abstract operation PromiseResolve takes arguments ctor (an Object) and resolution (an ECMAScript language value) and returns either a normal completion containing an Object or a throw completion. It returns a new promise resolved with resolution. It performs the following steps when called:

  1. If IsPromise(resolution) is true, then
    1. Let resolutionCtor be ? Get(resolution, "constructor").
    2. If SameValue(resolutionCtor, ctor) is true, return resolution.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Perform ? Call(promiseCapability.[[Resolve]], undefined, « resolution »).
  4. Return promiseCapability.[[Promise]].

27.5.4.8 Promise.try ( callback, ...args )

This function performs the following steps when called:

  1. Let ctor be the this value.
  2. If ctor is not an Object, throw a TypeError exception.
  3. Let status be Completion(Call(callback, undefined, args)).
  4. If status is an abrupt completion, then
    1. Let promiseCapability be ? NewPromiseCapability(ctor).
    2. Perform ? Call(promiseCapability.[[Reject]], undefined, « status.[[Value]] »).
    3. Return promiseCapability.[[Promise]].
  5. Else,
    1. Return ? PromiseResolve(ctor, ! status).
 Note

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

27.5.4.9 Promise.withResolvers ( )

This function returns an object with three properties: a new promise together with the resolve and reject functions associated with it.

  1. Let ctor be the this value.
  2. Let promiseCapability be ? NewPromiseCapability(ctor).
  3. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  4. Perform ! CreateDataPropertyOrThrow(obj, "promise", promiseCapability.[[Promise]]).
  5. Perform ! CreateDataPropertyOrThrow(obj, "resolve", promiseCapability.[[Resolve]]).
  6. Perform ! CreateDataPropertyOrThrow(obj, "reject", promiseCapability.[[Reject]]).
  7. Return obj.

27.5.4.10 get Promise [ %Symbol.species% ]

Promise[%Symbol.species%] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Return the this value.

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

Note

Promise prototype methods normally use their this value's constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by redefining its %Symbol.species% property.

27.5.5 Properties of the Promise Prototype Object

The Promise prototype object:

  • is %Promise.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have a [[PromiseState]] internal slot or any of the other internal slots of Promise instances.

27.5.5.1 Promise.prototype.catch ( onRejected )

This method performs the following steps when called:

  1. Let promise be the this value.
  2. Return ? Invoke(promise, "then", « undefined, onRejected »).

27.5.5.2 Promise.prototype.constructor

The initial value of Promise.prototype.constructor is %Promise%.

27.5.5.3 Promise.prototype.finally ( onFinally )

This method performs the following steps when called:

  1. Let promise be the this value.
  2. If promise is not an Object, throw a TypeError exception.
  3. Let ctor be ? SpeciesConstructor(promise, %Promise%).
  4. Assert: IsConstructor(ctor) is true.
  5. If IsCallable(onFinally) is false, then
    1. Let thenFinally be onFinally.
    2. Let catchFinally be onFinally.
  6. Else,
    1. Let thenFinallyClosure be a new Abstract Closure with parameters (value) that captures onFinally and ctor and performs the following steps when called:
      1. Let result be ? Call(onFinally, undefined).
      2. Let p be ? PromiseResolve(ctor, result).
      3. Let returnValue be a new Abstract Closure with no parameters that captures value and performs the following steps when called:
        1. Return NormalCompletion(value).
      4. Let valueThunk be CreateBuiltinFunction(returnValue, 0, "", « »).
      5. Return ? Invoke(p, "then", « valueThunk »).
    2. Let thenFinally be CreateBuiltinFunction(thenFinallyClosure, 1, "", « »).
    3. Let catchFinallyClosure be a new Abstract Closure with parameters (reason) that captures onFinally and ctor and performs the following steps when called:
      1. Let result be ? Call(onFinally, undefined).
      2. Let p be ? PromiseResolve(ctor, result).
      3. Let throwReason be a new Abstract Closure with no parameters that captures reason and performs the following steps when called:
        1. Throw reason.
      4. Let thrower be CreateBuiltinFunction(throwReason, 0, "", « »).
      5. Return ? Invoke(p, "then", « thrower »).
    4. Let catchFinally be CreateBuiltinFunction(catchFinallyClosure, 1, "", « »).
  7. Return ? Invoke(promise, "then", « thenFinally, catchFinally »).

27.5.5.4 Promise.prototype.then ( onFulfilled, onRejected )

This method performs the following steps when called:

  1. Let promise be the this value.
  2. If IsPromise(promise) is false, throw a TypeError exception.
  3. Let ctor be ? SpeciesConstructor(promise, %Promise%).
  4. Let resultCapability be ? NewPromiseCapability(ctor).
  5. Return PerformPromiseThen(promise, onFulfilled, onRejected, resultCapability).

27.5.5.4.1 PerformPromiseThen ( promise, onFulfilled, onRejected [ , resultCapability ] )

The abstract operation PerformPromiseThen takes arguments promise (a Promise), onFulfilled (an ECMAScript language value), and onRejected (an ECMAScript language value) and optional argument resultCapability (a PromiseCapability Record) and returns an Object or undefined. It performs the “then” operation on promise using onFulfilled and onRejected as its settlement actions. If resultCapability is passed, the result is stored by updating resultCapability's promise. If it is not passed, then PerformPromiseThen is being called by a specification-internal operation where the result does not matter. It performs the following steps when called:

  1. Assert: IsPromise(promise) is true.
  2. If resultCapability is not present, then
    1. Set resultCapability to undefined.
  3. If IsCallable(onFulfilled) is false, then
    1. Let onFulfilledJobCallback be empty.
  4. Else,
    1. Let onFulfilledJobCallback be HostMakeJobCallback(onFulfilled).
  5. If IsCallable(onRejected) is false, then
    1. Let onRejectedJobCallback be empty.
  6. Else,
    1. Let onRejectedJobCallback be HostMakeJobCallback(onRejected).
  7. Let fulfillReaction be the PromiseReaction Record { [[Capability]]: resultCapability, [[Type]]: fulfill, [[Handler]]: onFulfilledJobCallback }.
  8. Let rejectReaction be the PromiseReaction Record { [[Capability]]: resultCapability, [[Type]]: reject, [[Handler]]: onRejectedJobCallback }.
  9. If promise.[[PromiseState]] is pending, then
    1. Append fulfillReaction to promise.[[PromiseFulfillReactions]].
    2. Append rejectReaction to promise.[[PromiseRejectReactions]].
  10. Else if promise.[[PromiseState]] is fulfilled, then
    1. Let value be promise.[[PromiseResult]].
    2. Let fulfillJob be NewPromiseReactionJob(fulfillReaction, value).
    3. Perform HostEnqueuePromiseJob(fulfillJob.[[Job]], fulfillJob.[[Realm]]).
  11. Else,
    1. Assert: promise.[[PromiseState]] is rejected.
    2. Let reason be promise.[[PromiseResult]].
    3. If promise.[[PromiseIsHandled]] is false, perform HostPromiseRejectionTracker(promise, "handle").
    4. Let rejectJob be NewPromiseReactionJob(rejectReaction, reason).
    5. Perform HostEnqueuePromiseJob(rejectJob.[[Job]], rejectJob.[[Realm]]).
  12. Set promise.[[PromiseIsHandled]] to true.
  13. If resultCapability is undefined, return undefined.
  14. Return resultCapability.[[Promise]].

27.5.5.5 Promise.prototype [ %Symbol.toStringTag% ]

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

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

27.5.6 Properties of Promise Instances

Promise instances are ordinary objects that inherit properties from the Promise prototype object (the intrinsic, %Promise.prototype%). Promise instances are initially created with the internal slots described in Table 93.

Table 93: Internal Slots of Promise Instances
Internal Slot Type Description
[[PromiseState]] pending, fulfilled, or rejected Governs how a promise will react to incoming calls to its then method.
[[PromiseResult]] an ECMAScript language value or empty The value with which the promise has been fulfilled or rejected, if any. empty if and only if the [[PromiseState]] is pending.
[[PromiseFulfillReactions]] a List of PromiseReaction Records Records to be processed when/if the promise transitions from the pending state to the fulfilled state.
[[PromiseRejectReactions]] a List of PromiseReaction Records Records to be processed when/if the promise transitions from the pending state to the rejected state.
[[PromiseIsHandled]] a Boolean Indicates whether the promise has ever had a fulfillment or rejection handler; used in unhandled rejection tracking.

27.6 GeneratorFunction Objects

GeneratorFunctions are functions that are usually created by evaluating GeneratorDeclarations, GeneratorExpressions, and GeneratorMethods. They may also be created by calling the %GeneratorFunction% intrinsic.

Figure 6 describes the relationship between the different objects that are involved in representing generator functions:

Figure 6 (Informative): Generator Objects Relationships
Implicit and explicit relationships involving a generator function, a generator instance created by it, the prototype object between them, and several built-in objects

27.6.1 The GeneratorFunction Constructor

The GeneratorFunction constructor:

  • is %GeneratorFunction%.
  • is a subclass of Function.
  • creates and initializes a new GeneratorFunction when called as a function rather than as a constructor. Thus the function call GeneratorFunction (…) is equivalent to the object creation expression new GeneratorFunction (…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified GeneratorFunction behaviour must include a super call to the GeneratorFunction constructor to create and initialize subclass instances with the internal slots necessary for built-in GeneratorFunction behaviour. All ECMAScript syntactic forms for defining generator function objects create direct instances of GeneratorFunction. There is no syntactic means to create instances of GeneratorFunction subclasses.

27.6.1.1 GeneratorFunction ( ...paramArgs, bodyArg )

The last argument (if any) specifies the body (executable code) of a generator function; any preceding arguments specify formal parameters.

This function performs the following steps when called:

  1. Let activeFunc be the active function object.
  2. If bodyArg is not present, set bodyArg to the empty String.
  3. Return ? CreateDynamicFunction(activeFunc, NewTarget, generator, paramArgs, bodyArg).
 Note

See NOTE for 20.2.1.1.

27.6.2 Properties of the GeneratorFunction Constructor

The GeneratorFunction constructor:

  • is a standard built-in function object that inherits from the Function constructor.
  • has a [[Prototype]] internal slot whose value is %Function%.
  • has a "length" property whose value is 1𝔽.
  • has a "name" property whose value is "GeneratorFunction".
  • has the following properties:

27.6.2.1 GeneratorFunction.prototype

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

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

27.6.3 Properties of the GeneratorFunction Prototype Object

The GeneratorFunction prototype object:

27.6.3.1 GeneratorFunction.prototype.constructor

The initial value of GeneratorFunction.prototype.constructor is %GeneratorFunction%.

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

27.6.3.2 GeneratorFunction.prototype.prototype

The initial value of GeneratorFunction.prototype.prototype is %GeneratorPrototype%.

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

27.6.3.3 GeneratorFunction.prototype [ %Symbol.toStringTag% ]

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

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

27.6.4 GeneratorFunction Instances

Every GeneratorFunction instance is an ECMAScript function object and has the internal slots listed in Table 26. The value of the [[IsClassConstructor]] internal slot for all such instances is false.

Each GeneratorFunction instance has the following own properties:

27.6.4.1 length

The specification for the "length" property of Function instances given in 20.2.4.1 also applies to GeneratorFunction instances.

27.6.4.2 name

The specification for the "name" property of Function instances given in 20.2.4.2 also applies to GeneratorFunction instances.

27.6.4.3 prototype

Whenever a GeneratorFunction instance is created another ordinary object is also created and is the initial value of the generator function's "prototype" property. The value of the prototype property is used to initialize the [[Prototype]] internal slot of a newly created Generator when the generator function object is invoked using [[Call]].

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

Note

Unlike Function instances, the object that is the value of a GeneratorFunction's "prototype" property does not have a "constructor" property whose value is the GeneratorFunction instance.

27.7 AsyncGeneratorFunction Objects

AsyncGeneratorFunctions are functions that are usually created by evaluating AsyncGeneratorDeclaration, AsyncGeneratorExpression, and AsyncGeneratorMethod syntactic productions. They may also be created by calling the %AsyncGeneratorFunction% intrinsic.

27.7.1 The AsyncGeneratorFunction Constructor

The AsyncGeneratorFunction constructor:

  • is %AsyncGeneratorFunction%.
  • is a subclass of Function.
  • creates and initializes a new AsyncGeneratorFunction when called as a function rather than as a constructor. Thus the function call AsyncGeneratorFunction (...) is equivalent to the object creation expression new AsyncGeneratorFunction (...) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified AsyncGeneratorFunction behaviour must include a super call to the AsyncGeneratorFunction constructor to create and initialize subclass instances with the internal slots necessary for built-in AsyncGeneratorFunction behaviour. All ECMAScript syntactic forms for defining async generator function objects create direct instances of AsyncGeneratorFunction. There is no syntactic means to create instances of AsyncGeneratorFunction subclasses.

27.7.1.1 AsyncGeneratorFunction ( ...paramArgs, bodyArg )

The last argument (if any) specifies the body (executable code) of an async generator function; any preceding arguments specify formal parameters.

This function performs the following steps when called:

  1. Let activeFunc be the active function object.
  2. If bodyArg is not present, set bodyArg to the empty String.
  3. Return ? CreateDynamicFunction(activeFunc, NewTarget, async-generator, paramArgs, bodyArg).
 Note

See NOTE for 20.2.1.1.

27.7.2 Properties of the AsyncGeneratorFunction Constructor

The AsyncGeneratorFunction constructor:

  • is a standard built-in function object that inherits from the Function constructor.
  • has a [[Prototype]] internal slot whose value is %Function%.
  • has a "length" property whose value is 1𝔽.
  • has a "name" property whose value is "AsyncGeneratorFunction".
  • has the following properties:

27.7.2.1 AsyncGeneratorFunction.prototype

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

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

27.7.3 Properties of the AsyncGeneratorFunction Prototype Object

The AsyncGeneratorFunction prototype object:

27.7.3.1 AsyncGeneratorFunction.prototype.constructor

The initial value of AsyncGeneratorFunction.prototype.constructor is %AsyncGeneratorFunction%.

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

27.7.3.2 AsyncGeneratorFunction.prototype.prototype

The initial value of AsyncGeneratorFunction.prototype.prototype is %AsyncGeneratorPrototype%.

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

27.7.3.3 AsyncGeneratorFunction.prototype [ %Symbol.toStringTag% ]

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

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

27.7.4 AsyncGeneratorFunction Instances

Every AsyncGeneratorFunction instance is an ECMAScript function object and has the internal slots listed in Table 26. The value of the [[IsClassConstructor]] internal slot for all such instances is false.

Each AsyncGeneratorFunction instance has the following own properties:

27.7.4.1 length

The value of the "length" property is an integral Number that indicates the typical number of arguments expected by the AsyncGeneratorFunction. However, the language permits the function to be invoked with some other number of arguments. The behaviour of an AsyncGeneratorFunction when invoked on a number of arguments other than the number specified by its "length" property depends on the function.

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

27.7.4.2 name

The specification for the "name" property of Function instances given in 20.2.4.2 also applies to AsyncGeneratorFunction instances.

27.7.4.3 prototype

Whenever an AsyncGeneratorFunction instance is created, another ordinary object is also created and is the initial value of the async generator function's "prototype" property. The value of the prototype property is used to initialize the [[Prototype]] internal slot of a newly created AsyncGenerator when the generator function object is invoked using [[Call]].

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

Note

Unlike function instances, the object that is the value of an AsyncGeneratorFunction's "prototype" property does not have a "constructor" property whose value is the AsyncGeneratorFunction instance.

27.8 Generator Objects

A Generator is created by calling a generator function and conforms to both the iterator interface and the iterable interface.

Generator instances directly inherit properties from the initial value of the "prototype" property of the generator function that created the instance. Generator instances indirectly inherit properties from %GeneratorPrototype%.

27.8.1 The %GeneratorPrototype% Object

The %GeneratorPrototype% object:

  • is %GeneratorFunction.prototype.prototype%.
  • is an ordinary object.
  • is not a Generator instance and does not have a [[GeneratorState]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Iterator.prototype%.
  • has properties that are indirectly inherited by all Generator instances.

27.8.1.1 %GeneratorPrototype%.constructor

The initial value of %GeneratorPrototype%.constructor is %GeneratorFunction.prototype%.

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

27.8.1.2 %GeneratorPrototype%.next ( value )

  1. Return ? GeneratorResume(this value, value, empty).

27.8.1.3 %GeneratorPrototype%.return ( value )

This method performs the following steps when called:

  1. Let gen be the this value.
  2. Let completion be ReturnCompletion(value).
  3. Return ? GeneratorResumeAbrupt(gen, completion, empty).

27.8.1.4 %GeneratorPrototype%.throw ( exception )

This method performs the following steps when called:

  1. Let gen be the this value.
  2. Let completion be ThrowCompletion(exception).
  3. Return ? GeneratorResumeAbrupt(gen, completion, empty).

27.8.1.5 %GeneratorPrototype% [ %Symbol.toStringTag% ]

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

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

27.8.2 Properties of Generator Instances

Generator instances are initially created with the internal slots described in Table 94.

Table 94: Internal Slots of Generator Instances
Internal Slot Type Description
[[GeneratorState]] suspended-start, suspended-yield, executing, or completed The current execution state of the generator.
[[GeneratorContext]] an execution context The execution context that is used when executing the code of this generator.
[[GeneratorBrand]] a String or empty A brand used to distinguish different kinds of generators. The [[GeneratorBrand]] of generators declared by ECMAScript source text is always empty.

27.8.3 Generator Abstract Operations

27.8.3.1 GeneratorStart ( gen, genBody )

The abstract operation GeneratorStart takes arguments gen (a Generator) and genBody (a FunctionBody Parse Node or an Abstract Closure with no parameters) and returns unused. It performs the following steps when called:

  1. Assert: gen.[[GeneratorState]] is suspended-start.
  2. Let genContext be the running execution context.
  3. Set the Generator component of genContext to gen.
  4. Let closure be a new Abstract Closure with no parameters that captures genBody and performs the following steps when called:
    1. Let acGenContext be the running execution context.
    2. Let acGen be the Generator component of acGenContext.
    3. If genBody is a Parse Node, then
      1. Let result be Completion(Evaluation of genBody).
    4. Else,
      1. Assert: genBody is an Abstract Closure with no parameters.
      2. Let result be Completion(genBody()).
    5. Assert: If we return here, the generator either threw an exception or performed either an implicit or explicit return.
    6. Remove acGenContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
    7. Set acGen.[[GeneratorState]] to completed.
    8. 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 acGen can be discarded at this point.
    9. If result is a throw completion, then
      1. Let resumption be result.
    10. Else,
      1. If result is a normal completion, then
        1. Let resultValue be undefined.
      2. Else if result is a return completion, then
        1. Let resultValue be result.[[Value]].
      3. Let resumption be NormalCompletion(CreateIteratorResultObject(resultValue, true)).
    11. Let callerContext be the running execution context.
    12. Resume callerContext, passing resumption.
    13. Assert: This step is never reached.
  5. Set the code evaluation state of genContext such that when evaluation is resumed for that execution context, closure will be called with no arguments.
  6. Set gen.[[GeneratorContext]] to genContext.
  7. Return unused.

27.8.3.2 GeneratorValidate ( gen, genBrand )

The abstract operation GeneratorValidate takes arguments gen (an ECMAScript language value) and genBrand (a String or empty) and returns either a normal completion containing one of suspended-start, suspended-yield, or completed, or a throw completion. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(gen, [[GeneratorState]]).
  2. Perform ? RequireInternalSlot(gen, [[GeneratorBrand]]).
  3. If gen.[[GeneratorBrand]] is not genBrand, throw a TypeError exception.
  4. Assert: gen has a [[GeneratorContext]] internal slot.
  5. Let state be gen.[[GeneratorState]].
  6. If state is executing, throw a TypeError exception.
  7. Return state.

27.8.3.3 GeneratorResume ( gen, value, genBrand )

The abstract operation GeneratorResume takes arguments gen (an ECMAScript language value), value (an ECMAScript language value or empty), and genBrand (a String or empty) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Let state be ? GeneratorValidate(gen, genBrand).
  2. If state is completed, return CreateIteratorResultObject(undefined, true).
  3. Assert: state is either suspended-start or suspended-yield.
  4. Let genContext be gen.[[GeneratorContext]].
  5. Set gen.[[GeneratorState]] to executing.
  6. Return ? RunSuspendedContext(genContext, NormalCompletion(value)).

27.8.3.4 GeneratorResumeAbrupt ( gen, abruptCompletion, genBrand )

The abstract operation GeneratorResumeAbrupt takes arguments gen (an ECMAScript language value), abruptCompletion (a return completion or a throw completion), and genBrand (a String or empty) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Let state be ? GeneratorValidate(gen, genBrand).
  2. If state is suspended-start, then
    1. Set gen.[[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 gen can be discarded at this point.
    3. Set state to completed.
  3. If state is completed, then
    1. If abruptCompletion is a return completion, then
      1. Return CreateIteratorResultObject(abruptCompletion.[[Value]], true).
    2. Return ? abruptCompletion.
  4. Assert: state is suspended-yield.
  5. Let genContext be gen.[[GeneratorContext]].
  6. Set gen.[[GeneratorState]] to executing.
  7. Return ? RunSuspendedContext(genContext, abruptCompletion).

27.8.3.5 GetGeneratorKind ( )

The abstract operation GetGeneratorKind takes no arguments and returns non-generator, sync, or async. It performs the following steps when called:

  1. Let genContext be the running execution context.
  2. If genContext does not have a Generator component, return non-generator.
  3. Let gen be the Generator component of genContext.
  4. If gen has an [[AsyncGeneratorState]] internal slot, return async.
  5. Return sync.

27.8.3.6 GeneratorYield ( iteratorResult )

The abstract operation GeneratorYield takes argument iteratorResult (an Object that conforms to the IteratorResult interface) and returns either a normal completion containing an ECMAScript language value or an abrupt completion. It performs the following steps when called:

  1. Let genContext be the running execution context.
  2. Assert: genContext is the execution context of a generator.
  3. Let gen be the value of the Generator component of genContext.
  4. Assert: GetGeneratorKind() is sync.
  5. Set gen.[[GeneratorState]] to suspended-yield.
  6. Return ? RunCallerContext(iteratorResult).

27.8.3.7 Yield ( arg )

The abstract operation Yield takes argument arg (an ECMAScript language value) and returns either a normal completion containing an ECMAScript language value or an abrupt completion. It performs the following steps when called:

  1. Let genKind be GetGeneratorKind().
  2. If genKind is async, return ? AsyncGeneratorYield(? Await(arg)).
  3. Return ? GeneratorYield(CreateIteratorResultObject(arg, false)).

27.8.3.8 CreateIteratorFromClosure ( closure, genBrand, genProto [ , extraSlots ] )

The abstract operation CreateIteratorFromClosure takes arguments closure (an Abstract Closure with no parameters), genBrand (a String or empty), and genProto (an Object) and optional argument extraSlots (a List of names of internal slots) and returns a Generator. It performs the following steps when called:

  1. NOTE: closure can contain uses of the Yield operation to yield an IteratorResult object.
  2. If extraSlots is not present, set extraSlots to a new empty List.
  3. Let internalSlotsList be the list-concatenation of extraSlots and « [[GeneratorState]], [[GeneratorContext]], [[GeneratorBrand]] ».
  4. Let gen be OrdinaryObjectCreate(genProto, internalSlotsList).
  5. Set gen.[[GeneratorBrand]] to genBrand.
  6. Set gen.[[GeneratorState]] to suspended-start.
  7. Let callerContext be the running execution context.
  8. Let calleeContext be a new execution context.
  9. Set the Function of calleeContext to null.
  10. Set the Realm of calleeContext to the current Realm Record.
  11. Set the ScriptOrModule of calleeContext to callerContext's ScriptOrModule.
  12. If callerContext is not already suspended, suspend callerContext.
  13. Push calleeContext onto the execution context stack; calleeContext is now the running execution context.
  14. Perform GeneratorStart(gen, closure).
  15. Remove calleeContext from the execution context stack and restore callerContext as the running execution context.
  16. Return gen.

27.9 AsyncGenerator Objects

An AsyncGenerator is created by calling an async generator function and conforms to both the async iterator interface and the async iterable interface.

AsyncGenerator instances directly inherit properties from the initial value of the "prototype" property of the async generator function that created the instance. AsyncGenerator instances indirectly inherit properties from %AsyncGeneratorPrototype%.

27.9.1 The %AsyncGeneratorPrototype% Object

The %AsyncGeneratorPrototype% object:

  • is %AsyncGeneratorFunction.prototype.prototype%.
  • is an ordinary object.
  • is not an AsyncGenerator instance and does not have an [[AsyncGeneratorState]] internal slot.
  • has a [[Prototype]] internal slot whose value is %AsyncIteratorPrototype%.
  • has properties that are indirectly inherited by all AsyncGenerator instances.

27.9.1.1 %AsyncGeneratorPrototype%.constructor

The initial value of %AsyncGeneratorPrototype%.constructor is %AsyncGeneratorFunction.prototype%.

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

27.9.1.2 %AsyncGeneratorPrototype%.next ( value )

  1. Let gen be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Let result be Completion(AsyncGeneratorValidate(gen, empty)).
  4. IfAbruptRejectPromise(result, promiseCapability).
  5. Let state be gen.[[AsyncGeneratorState]].
  6. If state is completed, then
    1. Let iteratorResult be CreateIteratorResultObject(undefined, true).
    2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « iteratorResult »).
    3. Return promiseCapability.[[Promise]].
  7. Let completion be NormalCompletion(value).
  8. Perform AsyncGeneratorEnqueue(gen, completion, promiseCapability).
  9. If state is either suspended-start or suspended-yield, then
    1. Perform AsyncGeneratorResume(gen, completion).
  10. Else,
    1. Assert: state is either executing or draining-queue.
  11. Return promiseCapability.[[Promise]].

27.9.1.3 %AsyncGeneratorPrototype%.return ( value )

  1. Let gen be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Let result be Completion(AsyncGeneratorValidate(gen, empty)).
  4. IfAbruptRejectPromise(result, promiseCapability).
  5. Let completion be ReturnCompletion(value).
  6. Perform AsyncGeneratorEnqueue(gen, completion, promiseCapability).
  7. Let state be gen.[[AsyncGeneratorState]].
  8. If state is either suspended-start or completed, then
    1. Set gen.[[AsyncGeneratorState]] to draining-queue.
    2. Perform AsyncGeneratorAwaitReturn(gen).
  9. Else if state is suspended-yield, then
    1. Perform AsyncGeneratorResume(gen, completion).
  10. Else,
    1. Assert: state is either executing or draining-queue.
  11. Return promiseCapability.[[Promise]].

27.9.1.4 %AsyncGeneratorPrototype%.throw ( exception )

  1. Let gen be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Let result be Completion(AsyncGeneratorValidate(gen, empty)).
  4. IfAbruptRejectPromise(result, promiseCapability).
  5. Let state be gen.[[AsyncGeneratorState]].
  6. If state is suspended-start, then
    1. Set gen.[[AsyncGeneratorState]] to completed.
    2. Set state to completed.
  7. If state is completed, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « exception »).
    2. Return promiseCapability.[[Promise]].
  8. Let completion be ThrowCompletion(exception).
  9. Perform AsyncGeneratorEnqueue(gen, completion, promiseCapability).
  10. If state is suspended-yield, then
    1. Perform AsyncGeneratorResume(gen, completion).
  11. Else,
    1. Assert: state is either executing or draining-queue.
  12. Return promiseCapability.[[Promise]].

27.9.1.5 %AsyncGeneratorPrototype% [ %Symbol.toStringTag% ]

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

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

27.9.2 Properties of AsyncGenerator Instances

AsyncGenerator instances are initially created with the internal slots described below:

Table 95: Internal Slots of AsyncGenerator Instances
Internal Slot Type Description
[[AsyncGeneratorState]] suspended-start, suspended-yield, executing, draining-queue, or completed The current execution state of the async generator.
[[AsyncGeneratorContext]] an execution context The execution context that is used when executing the code of this async generator.
[[AsyncGeneratorQueue]] a List of AsyncGeneratorRequest Records Records which represent requests to resume the async generator. Except during state transitions, it is non-empty if and only if [[AsyncGeneratorState]] is either executing or draining-queue.
[[GeneratorBrand]] a String or empty A brand used to distinguish different kinds of async generators. The [[GeneratorBrand]] of async generators declared by ECMAScript source text is always empty.

27.9.3 AsyncGenerator Abstract Operations

27.9.3.1 AsyncGeneratorRequest Records

An AsyncGeneratorRequest is a Record used to store information about how an async generator should be resumed and contains capabilities for fulfilling or rejecting the corresponding promise.

They have the following fields:

Table 96: AsyncGeneratorRequest Record Fields
Field Name Value Meaning
[[Completion]] a Completion Record The Completion Record which should be used to resume the async generator.
[[Capability]] a PromiseCapability Record The promise capabilities associated with this request.

27.9.3.2 AsyncGeneratorStart ( gen, genBody )

The abstract operation AsyncGeneratorStart takes arguments gen (an AsyncGenerator) and genBody (a FunctionBody Parse Node or an Abstract Closure with no parameters) and returns unused. It performs the following steps when called:

  1. Assert: gen.[[AsyncGeneratorState]] is suspended-start.
  2. Let genContext be the running execution context.
  3. Set the Generator component of genContext to gen.
  4. Let closure be a new Abstract Closure with no parameters that captures genBody and performs the following steps when called:
    1. Let acGenContext be the running execution context.
    2. Let acGen be the Generator component of acGenContext.
    3. If genBody is a Parse Node, then
      1. Let result be Completion(Evaluation of genBody).
    4. Else,
      1. Assert: genBody is an Abstract Closure with no parameters.
      2. Let result be Completion(genBody()).
    5. Assert: If we return here, the async generator either threw an exception or performed either an implicit or explicit return.
    6. Remove acGenContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
    7. Set acGen.[[AsyncGeneratorState]] to draining-queue.
    8. If result is a normal completion, set result to NormalCompletion(undefined).
    9. If result is a return completion, set result to NormalCompletion(result.[[Value]]).
    10. Perform AsyncGeneratorCompleteStep(acGen, result, true).
    11. Perform AsyncGeneratorDrainQueue(acGen).
    12. Let callerContext be the running execution context.
    13. Resume callerContext, passing NormalCompletion(undefined).
    14. Assert: This step is never reached.
  5. Set the code evaluation state of genContext such that when evaluation is resumed for that execution context, closure will be called with no arguments.
  6. Set gen.[[AsyncGeneratorContext]] to genContext.
  7. Set gen.[[AsyncGeneratorQueue]] to a new empty List.
  8. Return unused.

27.9.3.3 AsyncGeneratorValidate ( gen, genBrand )

The abstract operation AsyncGeneratorValidate takes arguments gen (an ECMAScript language value) and genBrand (a String or empty) and returns either a normal completion containing unused or a throw completion. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(gen, [[AsyncGeneratorContext]]).
  2. Perform ? RequireInternalSlot(gen, [[AsyncGeneratorState]]).
  3. Perform ? RequireInternalSlot(gen, [[AsyncGeneratorQueue]]).
  4. If gen.[[GeneratorBrand]] is not genBrand, throw a TypeError exception.
  5. Return unused.

27.9.3.4 AsyncGeneratorEnqueue ( gen, completion, promiseCapability )

The abstract operation AsyncGeneratorEnqueue takes arguments gen (an AsyncGenerator), completion (a Completion Record), and promiseCapability (a PromiseCapability Record) and returns unused. It performs the following steps when called:

  1. Let request be AsyncGeneratorRequest { [[Completion]]: completion, [[Capability]]: promiseCapability }.
  2. Append request to gen.[[AsyncGeneratorQueue]].
  3. Return unused.

27.9.3.5 AsyncGeneratorCompleteStep ( gen, completion, done [ , realm ] )

The abstract operation AsyncGeneratorCompleteStep takes arguments gen (an AsyncGenerator), completion (a Completion Record), and done (a Boolean) and optional argument realm (a Realm Record) and returns unused. It performs the following steps when called:

  1. Assert: gen.[[AsyncGeneratorQueue]] is not empty.
  2. Let next be the first element of gen.[[AsyncGeneratorQueue]].
  3. Remove the first element from gen.[[AsyncGeneratorQueue]].
  4. Let promiseCapability be next.[[Capability]].
  5. Let value be completion.[[Value]].
  6. If completion is a throw completion, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « value »).
  7. Else,
    1. Assert: completion is a normal completion.
    2. If realm is present, then
      1. Let oldRealm be the running execution context's Realm.
      2. Set the running execution context's Realm to realm.
      3. Let iteratorResult be CreateIteratorResultObject(value, done).
      4. Set the running execution context's Realm to oldRealm.
    3. Else,
      1. Let iteratorResult be CreateIteratorResultObject(value, done).
    4. Perform ! Call(promiseCapability.[[Resolve]], undefined, « iteratorResult »).
  8. Return unused.

27.9.3.6 AsyncGeneratorResume ( gen, completion )

The abstract operation AsyncGeneratorResume takes arguments gen (an AsyncGenerator) and completion (a Completion Record) and returns unused. It performs the following steps when called:

  1. Assert: gen.[[AsyncGeneratorState]] is either suspended-start or suspended-yield.
  2. Let genContext be gen.[[AsyncGeneratorContext]].
  3. Set gen.[[AsyncGeneratorState]] to executing.
  4. Perform ! RunSuspendedContext(genContext, completion).
  5. Return unused.

27.9.3.7 AsyncGeneratorUnwrapYieldResumption ( resumptionValue )

The abstract operation AsyncGeneratorUnwrapYieldResumption takes argument resumptionValue (a Completion Record) and returns either a normal completion containing an ECMAScript language value or an abrupt completion. It performs the following steps when called:

  1. If resumptionValue is not a return completion, return ? resumptionValue.
  2. Let awaited be Completion(Await(resumptionValue.[[Value]])).
  3. If awaited is a throw completion, return ? awaited.
  4. Assert: awaited is a normal completion.
  5. Return ReturnCompletion(awaited.[[Value]]).

27.9.3.8 AsyncGeneratorYield ( arg )

The abstract operation AsyncGeneratorYield takes argument arg (an ECMAScript language value) and returns either a normal completion containing an ECMAScript language value or an abrupt completion. It performs the following steps when called:

  1. Let genContext be the running execution context.
  2. Assert: genContext is the execution context of a generator.
  3. Let gen be the value of the Generator component of genContext.
  4. Assert: GetGeneratorKind() is async.
  5. Let completion be NormalCompletion(arg).
  6. Assert: The execution context stack has at least two elements.
  7. Let previousContext be the second to top element of the execution context stack.
  8. Let previousRealm be previousContext's Realm.
  9. Perform AsyncGeneratorCompleteStep(gen, completion, false, previousRealm).
  10. Let queue be gen.[[AsyncGeneratorQueue]].
  11. If queue is not empty, then
    1. NOTE: Execution continues without suspending the generator.
    2. Let toYield be the first element of queue.
    3. Let resumptionValue be Completion(toYield.[[Completion]]).
    4. Return ? AsyncGeneratorUnwrapYieldResumption(resumptionValue).
  12. Set gen.[[AsyncGeneratorState]] to suspended-yield.
  13. Let resumptionValue be Completion(RunCallerContext(undefined)).
  14. Return ? AsyncGeneratorUnwrapYieldResumption(resumptionValue).

27.9.3.9 AsyncGeneratorAwaitReturn ( gen )

The abstract operation AsyncGeneratorAwaitReturn takes argument gen (an AsyncGenerator) and returns unused. It performs the following steps when called:

  1. Assert: gen.[[AsyncGeneratorState]] is draining-queue.
  2. Let queue be gen.[[AsyncGeneratorQueue]].
  3. Assert: queue is not empty.
  4. Let next be the first element of queue.
  5. Let completion be Completion(next.[[Completion]]).
  6. Assert: completion is a return completion.
  7. Let promiseCompletion be Completion(PromiseResolve(%Promise%, completion.[[Value]])).
  8. If promiseCompletion is an abrupt completion, then
    1. Perform AsyncGeneratorCompleteStep(gen, promiseCompletion, true).
    2. Perform AsyncGeneratorDrainQueue(gen).
    3. Return unused.
  9. Assert: promiseCompletion is a normal completion.
  10. Let promise be promiseCompletion.[[Value]].
  11. Let fulfilledClosure be a new Abstract Closure with parameters (value) that captures gen and performs the following steps when called:
    1. Assert: gen.[[AsyncGeneratorState]] is draining-queue.
    2. Let result be NormalCompletion(value).
    3. Perform AsyncGeneratorCompleteStep(gen, result, true).
    4. Perform AsyncGeneratorDrainQueue(gen).
    5. Return NormalCompletion(undefined).
  12. Let onFulfilled be CreateBuiltinFunction(fulfilledClosure, 1, "", « »).
  13. Let rejectedClosure be a new Abstract Closure with parameters (reason) that captures gen and performs the following steps when called:
    1. Assert: gen.[[AsyncGeneratorState]] is draining-queue.
    2. Let result be ThrowCompletion(reason).
    3. Perform AsyncGeneratorCompleteStep(gen, result, true).
    4. Perform AsyncGeneratorDrainQueue(gen).
    5. Return NormalCompletion(undefined).
  14. Let onRejected be CreateBuiltinFunction(rejectedClosure, 1, "", « »).
  15. Perform PerformPromiseThen(promise, onFulfilled, onRejected).
  16. Return unused.

27.9.3.10 AsyncGeneratorDrainQueue ( gen )

The abstract operation AsyncGeneratorDrainQueue takes argument gen (an AsyncGenerator) and returns unused. It drains the generator's AsyncGeneratorQueue until it encounters an AsyncGeneratorRequest which holds a return completion. It performs the following steps when called:

  1. Assert: gen.[[AsyncGeneratorState]] is draining-queue.
  2. Let queue be gen.[[AsyncGeneratorQueue]].
  3. Repeat, while queue is not empty,
    1. Let next be the first element of queue.
    2. Let completion be Completion(next.[[Completion]]).
    3. If completion is a return completion, then
      1. Perform AsyncGeneratorAwaitReturn(gen).
      2. Return unused.
    4. If completion is a normal completion, then
      1. Set completion to NormalCompletion(undefined).
    5. Perform AsyncGeneratorCompleteStep(gen, completion, true).
  4. Set gen.[[AsyncGeneratorState]] to completed.
  5. Return unused.

27.10 AsyncFunction Objects

AsyncFunctions are functions that are usually created by evaluating AsyncFunctionDeclarations, AsyncFunctionExpressions, AsyncMethods, and AsyncArrowFunctions. They may also be created by calling the %AsyncFunction% intrinsic.

27.10.1 The AsyncFunction Constructor

The AsyncFunction constructor:

  • is %AsyncFunction%.
  • is a subclass of Function.
  • creates and initializes a new AsyncFunction when called as a function rather than as a constructor. Thus the function call AsyncFunction(…) is equivalent to the object creation expression new AsyncFunction(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified AsyncFunction behaviour must include a super call to the AsyncFunction constructor to create and initialize a subclass instance with the internal slots necessary for built-in async function behaviour. All ECMAScript syntactic forms for defining async function objects create direct instances of AsyncFunction. There is no syntactic means to create instances of AsyncFunction subclasses.

27.10.1.1 AsyncFunction ( ...paramArgs, bodyArg )

The last argument (if any) specifies the body (executable code) of an async function. Any preceding arguments specify formal parameters.

This function performs the following steps when called:

  1. Let activeFunc be the active function object.
  2. If bodyArg is not present, set bodyArg to the empty String.
  3. Return ? CreateDynamicFunction(activeFunc, NewTarget, async, paramArgs, bodyArg).
 Note
See NOTE for 20.2.1.1.

27.10.2 Properties of the AsyncFunction Constructor

The AsyncFunction constructor:

  • is a standard built-in function object that inherits from the Function constructor.
  • has a [[Prototype]] internal slot whose value is %Function%.
  • has a "length" property whose value is 1𝔽.
  • has a "name" property whose value is "AsyncFunction".
  • has the following properties:

27.10.2.1 AsyncFunction.prototype

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

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

27.10.3 Properties of the AsyncFunction Prototype Object

The AsyncFunction prototype object:

27.10.3.1 AsyncFunction.prototype.constructor

The initial value of AsyncFunction.prototype.constructor is %AsyncFunction%.

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

27.10.3.2 AsyncFunction.prototype [ %Symbol.toStringTag% ]

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

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

27.10.4 AsyncFunction Instances

Every AsyncFunction instance is an ECMAScript function object and has the internal slots listed in Table 26. The value of the [[IsClassConstructor]] internal slot for all such instances is false. AsyncFunction instances are not constructors and do not have a [[Construct]] internal method. AsyncFunction instances do not have a prototype property as they are not constructable.

Each AsyncFunction instance has the following own properties:

27.10.4.1 length

The specification for the "length" property of Function instances given in 20.2.4.1 also applies to AsyncFunction instances.

27.10.4.2 name

The specification for the "name" property of Function instances given in 20.2.4.2 also applies to AsyncFunction instances.

27.10.5 Async Functions Abstract Operations

27.10.5.1 AsyncFunctionStart ( promiseCapability, asyncFuncBody )

The abstract operation AsyncFunctionStart takes arguments promiseCapability (a PromiseCapability Record) and asyncFuncBody (a FunctionBody Parse Node, an ExpressionBody Parse Node, or an Abstract Closure with no parameters) and returns unused. It performs the following steps when called:

  1. Let runningContext be the running execution context.
  2. Let asyncContext be a copy of runningContext.
  3. NOTE: Copying the execution state is required for AsyncBlockStart to resume its execution. It is ill-defined to resume a currently executing context.
  4. Perform AsyncBlockStart(promiseCapability, asyncFuncBody, asyncContext).
  5. Return unused.

27.10.5.2 AsyncBlockStart ( promiseCapability, asyncBody, asyncContext )

The abstract operation AsyncBlockStart takes arguments promiseCapability (a PromiseCapability Record), asyncBody (a Parse Node or an Abstract Closure with no parameters), and asyncContext (an execution context) and returns unused. It performs the following steps when called:

  1. Let closure be a new Abstract Closure with no parameters that captures promiseCapability and asyncBody and performs the following steps when called:
    1. Let acAsyncContext be the running execution context.
    2. If asyncBody is a Parse Node, then
      1. Let result be Completion(Evaluation of asyncBody).
    3. Else,
      1. Assert: asyncBody is an Abstract Closure with no parameters.
      2. Let result be Completion(asyncBody()).
    4. Assert: If we return here, the async function either threw an exception or performed an implicit or explicit return; all awaiting is done.
    5. Remove acAsyncContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
    6. If result is a normal completion, then
      1. Perform ! Call(promiseCapability.[[Resolve]], undefined, « undefined »).
    7. Else if result is a return completion, then
      1. Perform ! Call(promiseCapability.[[Resolve]], undefined, « result.[[Value]] »).
    8. Else,
      1. Assert: result is a throw completion.
      2. Perform ! Call(promiseCapability.[[Reject]], undefined, « result.[[Value]] »).
    9. Let callerContext be the running execution context.
    10. Resume callerContext, passing NormalCompletion(unused).
    11. Assert: This step is never reached.
  2. Set the code evaluation state of asyncContext such that when evaluation is resumed for that execution context, closure will be called with no arguments.
  3. Let result be ! RunSuspendedContext(asyncContext, NormalCompletion(empty)).
  4. Assert: result is unused.
  5. NOTE: The possible sources of result values are Await or, if the async function doesn't await anything, step 1.j above.
  6. Return unused.

27.10.5.3 Await ( arg )

The abstract operation Await takes argument arg (an ECMAScript language value) and returns either a normal completion containing either an ECMAScript language value or empty, or a throw completion. It performs the following steps when called:

  1. Let asyncContext be the running execution context.
  2. Let promise be ? PromiseResolve(%Promise%, arg).
  3. Let fulfilledClosure be a new Abstract Closure with parameters (value) that captures asyncContext and performs the following steps when called:
    1. Perform Completion(RunSuspendedContext(asyncContext, NormalCompletion(value))).
    2. NOTE: The Completion Record returned by RunSuspendedContext is intentionally ignored.
    3. Return NormalCompletion(undefined).
  4. Let onFulfilled be CreateBuiltinFunction(fulfilledClosure, 1, "", « »).
  5. Let rejectedClosure be a new Abstract Closure with parameters (reason) that captures asyncContext and performs the following steps when called:
    1. Perform Completion(RunSuspendedContext(asyncContext, ThrowCompletion(reason))).
    2. NOTE: The Completion Record returned by RunSuspendedContext is intentionally ignored.
    3. Return NormalCompletion(undefined).
  6. Let onRejected be CreateBuiltinFunction(rejectedClosure, 1, "", « »).
  7. Perform PerformPromiseThen(promise, onFulfilled, onRejected).
  8. Return ? RunCallerContext(empty).