Skip to content

25 Control Abstraction Objects

25.1 Iteration

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

25.1.1.1 The Iterable Interface

The Iterable interface includes the property described in Table 53:

Iterable Interface Required Properties">
Property Value Requirements
@@iterator A function that returns an Iterator object. The returned object must conform to the Iterator interface.

25.1.1.2 The Iterator Interface

An object that implements the Iterator interface must include the property in Table 54. Such objects may also implement the properties in Table 55.

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.

 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.

25.1.1.3 The IteratorResult Interface

The IteratorResult interface includes the properties listed in Table 56:

IteratorResult Interface Properties">
Property Value Requirements
done Either true or false. 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 consider to have the value false.
value Any ECMAScript language value. If done is false, this is the current iteration element value. If done is true, this is the return value of the iterator, if it supplied one. If the iterator does not have a return value, value is undefined. In that case, the value property may be absent from the conforming object if it does not inherit an explicit value property.

25.1.2 The %IteratorPrototype% Object

The value of the [[Prototype]] internal slot of the %IteratorPrototype% object is the intrinsic object %ObjectPrototype%. The %IteratorPrototype% object is an ordinary object. The initial value of the [[Extensible]] internal slot of the %IteratorPrototype% object is true.

Note

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

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

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

25.1.2.1 %IteratorPrototype% [ @@iterator ] ( )

The following steps are taken:

  1. Return the this value.

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

25.2 GeneratorFunction Objects

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

A staggering variety of boxes and arrows.

25.2.1 The GeneratorFunction Constructor

The GeneratorFunction constructor is the %GeneratorFunction% intrinsic. When GeneratorFunction is called as a function rather than as a constructor, it creates and initializes a new GeneratorFunction object. Thus the function call GeneratorFunction (…) is equivalent to the object creation expression new GeneratorFunction (…) with the same arguments.

GeneratorFunction is designed to be subclassable. It 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.

25.2.1.1 GeneratorFunction ( p1, p2, … , pn, body )

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

When the GeneratorFunction function is called with some arguments p1, p2, … , pn, body (where n might be 0, that is, there are no “p” arguments, and where body might also not be provided), the following steps are taken:

  1. Let C be the active function object.
  2. Let args be the argumentsList that was passed to this function by [[Call]] or [[Construct]].
  3. Return ? CreateDynamicFunction(C, NewTarget, "generator", args).
 Note

See NOTE for 19.2.1.1.

25.2.2 Properties of the GeneratorFunction Constructor

The GeneratorFunction constructor is a standard built-in function object that inherits from the Function constructor. The value of the [[Prototype]] internal slot of the GeneratorFunction constructor is the intrinsic object %Function%.

The value of the [[Extensible]] internal slot of the GeneratorFunction constructor is true.

The value of the name property of the GeneratorFunction is "GeneratorFunction".

The GeneratorFunction constructor has the following properties:

25.2.2.1 GeneratorFunction.length

This is a data property with a value of 1. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.2.2.2 GeneratorFunction.prototype

The initial value of GeneratorFunction.prototype is the intrinsic object %Generator%.

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

25.2.3 Properties of the GeneratorFunction Prototype Object

The GeneratorFunction prototype object is an ordinary object. It is not a function object and does not have an [[ECMAScriptCode]] internal slot or any other of the internal slots listed in Table 27 or Table 57. In addition to being the value of the prototype property of the %GeneratorFunction% intrinsic, it is the %Generator% intrinsic (see Figure 2).

The value of the [[Prototype]] internal slot of the GeneratorFunction prototype object is the %FunctionPrototype% intrinsic object. The initial value of the [[Extensible]] internal slot of the GeneratorFunction prototype object is true.

25.2.3.1 GeneratorFunction.prototype.constructor

The initial value of GeneratorFunction.prototype.constructor is the intrinsic object %GeneratorFunction%.

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

25.2.3.2 GeneratorFunction.prototype.prototype

The value of GeneratorFunction.prototype.prototype is the %GeneratorPrototype% intrinsic object.

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

25.2.3.3 GeneratorFunction.prototype [ @@toStringTag ]

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

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

25.2.4 GeneratorFunction Instances

Every GeneratorFunction instance is an ECMAScript function object and has the internal slots listed in Table 27. The value of the [[FunctionKind]] internal slot for all such instances is "generator".

Each GeneratorFunction instance has the following own properties:

25.2.4.1 length

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

25.2.4.2 name

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

25.2.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 object 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 the a GeneratorFunction's prototype property does not have a constructor property whose value is the GeneratorFunction instance.

25.3 Generator Objects

A Generator object is an instance of a generator function and conforms to both the Iterator and Iterable interfaces.

Generator instances directly inherit properties from the object that is the value of the prototype property of the Generator function that created the instance. Generator instances indirectly inherit properties from the Generator Prototype intrinsic, %GeneratorPrototype%.

25.3.1 Properties of Generator Prototype

The Generator prototype object is the %GeneratorPrototype% intrinsic. It is also the initial value of the prototype property of the %Generator% intrinsic (the GeneratorFunction.prototype).

The Generator prototype is an ordinary object. It is not a Generator instance and does not have a [[GeneratorState]] internal slot.

The value of the [[Prototype]] internal slot of the Generator prototype object is the intrinsic object %IteratorPrototype%. The initial value of the [[Extensible]] internal slot of the Generator prototype object is true.

All Generator instances indirectly inherit properties of the Generator prototype object.

25.3.1.1 Generator.prototype.constructor

The initial value of Generator.prototype.constructor is the intrinsic object %Generator%.

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

25.3.1.2 Generator.prototype.next ( value )

The next method performs the following steps:

  1. Let g be the this value.
  2. Return ? GeneratorResume(g, value).

25.3.1.3 Generator.prototype.return ( value )

The return method performs the following steps:

  1. Let g be the this value.
  2. Let C be Completion{[[Type]]: return, [[Value]]: value, [[Target]]: empty}.
  3. Return ? GeneratorResumeAbrupt(g, C).

25.3.1.4 Generator.prototype.throw ( exception )

The throw method performs the following steps:

  1. Let g be the this value.
  2. Let C be Completion{[[Type]]: throw, [[Value]]: exception, [[Target]]: empty}.
  3. Return ? GeneratorResumeAbrupt(g, C).

25.3.1.5 Generator.prototype [ @@toStringTag ]

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

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

25.3.2 Properties of Generator Instances

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

Internal Slot Description
[[GeneratorState]] The current execution state of the generator. The possible values are: undefined, "suspendedStart", "suspendedYield", "executing", and "completed".
[[GeneratorContext]] The execution context that is used when executing the code of this generator.

25.3.3 Generator Abstract Operations

25.3.3.1 GeneratorStart ( generator, generatorBody )

The abstract operation GeneratorStart with arguments generator and generatorBody performs the following steps:

  1. Assert: The value of generator.[[GeneratorState]] is undefined.
  2. Let genContext be the running execution context.
  3. Set the Generator component of genContext to generator.
  4. Set the code evaluation state of genContext such that when evaluation is resumed for that execution context the following steps will be performed:
    1. Let result be the result of evaluating generatorBody.
    2. Assert: If we return here, the generator either threw an exception or performed either an implicit or explicit return.
    3. Remove genContext 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.
    4. Set generator.[[GeneratorState]] to "completed".
    5. Once a generator enters the "completed" state it never leaves it and its associated execution context is never resumed. Any execution state associated with generator can be discarded at this point.
    6. If result.[[Type]] is normal, let resultValue be undefined.
    7. Else if result.[[Type]] is return, let resultValue be result.[[Value]].
    8. Else,
      1. Assert: result.[[Type]] is throw.
      2. Return Completion(result).
    9. Return CreateIterResultObject(resultValue, true).
  5. Set generator.[[GeneratorContext]] to genContext.
  6. Set generator.[[GeneratorState]] to "suspendedStart".
  7. Return NormalCompletion(undefined).

25.3.3.2 GeneratorValidate ( generator )

The abstract operation GeneratorValidate with argument generator performs the following steps:

  1. If Type(generator) is not Object, throw a TypeError exception.
  2. If generator does not have a [[GeneratorState]] internal slot, throw a TypeError exception.
  3. Assert: generator also has a [[GeneratorContext]] internal slot.
  4. Let state be generator.[[GeneratorState]].
  5. If state is "executing", throw a TypeError exception.
  6. Return state.

25.3.3.3 GeneratorResume ( generator, value )

The abstract operation GeneratorResume with arguments generator and value performs the following steps:

  1. Let state be ? GeneratorValidate(generator).
  2. If state is "completed", return CreateIterResultObject(undefined, true).
  3. Assert: state is either "suspendedStart" or "suspendedYield".
  4. Let genContext be generator.[[GeneratorContext]].
  5. Let methodContext be the running execution context.
  6. Suspend methodContext.
  7. Set generator.[[GeneratorState]] to "executing".
  8. Push genContext onto the execution context stack; genContext is now the running execution context.
  9. Resume the suspended evaluation of genContext using NormalCompletion(value) as the result of the operation that suspended it. Let result be the value returned by the resumed computation.
  10. Assert: When we return here, genContext has already been removed from the execution context stack and methodContext is the currently running execution context.
  11. Return Completion(result).

25.3.3.4 GeneratorResumeAbrupt ( generator, abruptCompletion )

The abstract operation GeneratorResumeAbrupt with arguments generator and abruptCompletion performs the following steps:

  1. Let state be ? GeneratorValidate(generator).
  2. If state is "suspendedStart", then
    1. Set generator.[[GeneratorState]] to "completed".
    2. Once a generator enters the "completed" state it never leaves it and its associated execution context is never resumed. Any execution state associated with generator can be discarded at this point.
    3. Set state to "completed".
  3. If state is "completed", then
    1. If abruptCompletion.[[Type]] is return, then
      1. Return CreateIterResultObject(abruptCompletion.[[Value]], true).
    2. Return Completion(abruptCompletion).
  4. Assert: state is "suspendedYield".
  5. Let genContext be generator.[[GeneratorContext]].
  6. Let methodContext be the running execution context.
  7. Suspend methodContext.
  8. Set generator.[[GeneratorState]] to "executing".
  9. Push genContext onto the execution context stack; genContext is now the running execution context.
  10. Resume the suspended evaluation of genContext using abruptCompletion as the result of the operation that suspended it. Let result be the completion record returned by the resumed computation.
  11. Assert: When we return here, genContext has already been removed from the execution context stack and methodContext is the currently running execution context.
  12. Return Completion(result).

25.3.3.5 GeneratorYield ( iterNextObj )

The abstract operation GeneratorYield with argument iterNextObj performs the following steps:

  1. Assert: iterNextObj is an Object that implements the IteratorResult interface.
  2. Let genContext be the running execution context.
  3. Assert: genContext is the execution context of a generator.
  4. Let generator be the value of the Generator component of genContext.
  5. Set generator.[[GeneratorState]] to "suspendedYield".
  6. Remove genContext 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 the code evaluation state of genContext such that when evaluation is resumed with a Completion resumptionValue the following steps will be performed:
    1. Return resumptionValue.
    2. NOTE: This returns to the evaluation of the YieldExpression that originally called this abstract operation.
  8. Return NormalCompletion(iterNextObj).
  9. NOTE: This returns to the evaluation of the operation that had most previously resumed evaluation of genContext.

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

25.4.1 Promise Abstract Operations

25.4.1.1 PromiseCapability Records

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

PromiseCapability Records have the fields listed in Table 58.

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 object.
[[Reject]] A function object The function that is used to reject the given promise object.

25.4.1.1.1 IfAbruptRejectPromise ( value, capability )

IfAbruptRejectPromise is a short hand 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. If value is an abrupt completion, then
    1. Perform ? Call(capability.[[Reject]], undefined, « value.[[Value]] »).
    2. Return capability.[[Promise]].
  2. Else if value is a Completion Record, let value be value.[[Value]].

25.4.1.2 PromiseReaction Records

The PromiseReaction is a Record value used to store information about how a promise should react when it becomes resolved or rejected with a given value. PromiseReaction records are created by the PerformPromiseThen abstract operation, and are used by a PromiseReactionJob.

PromiseReaction records have the fields listed in Table 59.

Field Name Value Meaning
[[Capability]] A PromiseCapability Record The capabilities of the promise for which this record provides a reaction handler.
[[Type]] Either "Fulfill" or "Reject". The [[Type]] is used when [[Handler]] is undefined to allow for behaviour specific to the settlement type.
[[Handler]] A function object or undefined. 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 undefined, a function that depends on the value of [[Type]] will be used instead.

25.4.1.3 CreateResolvingFunctions ( promise )

When CreateResolvingFunctions is performed with argument promise, the following steps are taken:

  1. Let alreadyResolved be a new Record { [[Value]]: false }.
  2. Let resolve be a new built-in function object as defined in Promise Resolve Functions (25.4.1.3.2).
  3. Set resolve.[[Promise]] to promise.
  4. Set resolve.[[AlreadyResolved]] to alreadyResolved.
  5. Let reject be a new built-in function object as defined in Promise Reject Functions (25.4.1.3.1).
  6. Set reject.[[Promise]] to promise.
  7. Set reject.[[AlreadyResolved]] to alreadyResolved.
  8. Return a new Record { [[Resolve]]: resolve, [[Reject]]: reject }.

25.4.1.3.1 Promise Reject Functions

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

When a promise reject function F is called with argument reason, the following steps are taken:

  1. Assert: F has a [[Promise]] internal slot whose value is an Object.
  2. Let promise be F.[[Promise]].
  3. Let alreadyResolved be F.[[AlreadyResolved]].
  4. If alreadyResolved.[[Value]] is true, return undefined.
  5. Set alreadyResolved.[[Value]] to true.
  6. Return RejectPromise(promise, reason).

The length property of a promise reject function is 1.

25.4.1.3.2 Promise Resolve Functions

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

When a promise resolve function F is called with argument resolution, the following steps are taken:

  1. Assert: F has a [[Promise]] internal slot whose value is an Object.
  2. Let promise be F.[[Promise]].
  3. Let alreadyResolved be F.[[AlreadyResolved]].
  4. If alreadyResolved.[[Value]] is true, return undefined.
  5. Set alreadyResolved.[[Value]] to true.
  6. If SameValue(resolution, promise) is true, then
    1. Let selfResolutionError be a newly created TypeError object.
    2. Return RejectPromise(promise, selfResolutionError).
  7. If Type(resolution) is not Object, then
    1. Return FulfillPromise(promise, resolution).
  8. Let then be Get(resolution, "then").
  9. If then is an abrupt completion, then
    1. Return RejectPromise(promise, then.[[Value]]).
  10. Let thenAction be then.[[Value]].
  11. If IsCallable(thenAction) is false, then
    1. Return FulfillPromise(promise, resolution).
  12. Perform EnqueueJob("PromiseJobs", PromiseResolveThenableJob, « promise, resolution, thenAction »).
  13. Return undefined.

The length property of a promise resolve function is 1.

25.4.1.4 FulfillPromise ( promise, value )

When the FulfillPromise abstract operation is called with arguments promise and value, the following steps are taken:

  1. Assert: The value of 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. Return TriggerPromiseReactions(reactions, value).

25.4.1.5 NewPromiseCapability ( C )

The abstract operation NewPromiseCapability takes a constructor function, and attempts to use that constructor function in the fashion of the built-in Promise constructor to create a Promise object and extract its resolve and reject functions. The promise plus the resolve and reject functions are used to initialize a new PromiseCapability Record which is returned as the value of this abstract operation.

  1. If IsConstructor(C) is false, throw a TypeError exception.
  2. NOTE: C is assumed to be a constructor function that supports the parameter conventions of the Promise constructor (see 25.4.3.1).
  3. Let promiseCapability be a new PromiseCapability { [[Promise]]: undefined, [[Resolve]]: undefined, [[Reject]]: undefined }.
  4. Let executor be a new built-in function object as defined in GetCapabilitiesExecutor Functions.
  5. Set executor.[[Capability]] to promiseCapability.
  6. Let promise be ? Construct(C, « executor »).
  7. If IsCallable(promiseCapability.[[Resolve]]) is false, throw a TypeError exception.
  8. If IsCallable(promiseCapability.[[Reject]]) is false, throw a TypeError exception.
  9. Set promiseCapability.[[Promise]] to promise.
  10. Return promiseCapability.
 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.

25.4.1.5.1 GetCapabilitiesExecutor Functions

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

When a GetCapabilitiesExecutor function F is called with arguments resolve and reject, the following steps are taken:

  1. Assert: F has a [[Capability]] internal slot whose value is a PromiseCapability Record.
  2. Let promiseCapability be F.[[Capability]].
  3. If promiseCapability.[[Resolve]] is not undefined, throw a TypeError exception.
  4. If promiseCapability.[[Reject]] is not undefined, throw a TypeError exception.
  5. Set promiseCapability.[[Resolve]] to resolve.
  6. Set promiseCapability.[[Reject]] to reject.
  7. Return undefined.

The length property of a GetCapabilitiesExecutor function is 2.

25.4.1.6 IsPromise ( x )

The abstract operation IsPromise checks for the promise brand on an object.

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

25.4.1.7 RejectPromise ( promise, reason )

When the RejectPromise abstract operation is called with arguments promise and reason, the following steps are taken:

  1. Assert: The value of 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. Return TriggerPromiseReactions(reactions, reason).

25.4.1.8 TriggerPromiseReactions ( reactions, argument )

The abstract operation TriggerPromiseReactions takes a collection of PromiseReactionRecords and enqueues a new Job for each record. Each such Job processes the [[Type]] and [[Handler]] of the PromiseReactionRecord, and if the [[Handler]] is a function, calls it passing the given argument. If the [[Handler]] is undefined, the behaviour is determined by the [[Type]].

  1. For each reaction in reactions, in original insertion order, do
    1. Perform EnqueueJob("PromiseJobs", PromiseReactionJob, « reaction, argument »).
  2. Return undefined.

25.4.1.9 HostPromiseRejectionTracker ( promise, operation )

HostPromiseRejectionTracker is an implementation-defined abstract operation that allows host environments to track promise rejections.

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

Note 1

HostPromiseRejectionTracker is called in two scenarios:

  • When a promise is rejected without any handlers, it is called with its operation argument set to "reject".
  • When a handler is added to a rejected promise for the first time, it is called with its operation argument set to "handle".

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

 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.

25.4.2 Promise Jobs

25.4.2.1 PromiseReactionJob ( reaction, argument )

The job PromiseReactionJob with parameters reaction and argument 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.

  1. Assert: reaction is a PromiseReaction Record.
  2. Let promiseCapability be reaction.[[Capability]].
  3. Let type be reaction.[[Type]].
  4. Let handler be reaction.[[Handler]].
  5. If handler is undefined, then
    1. If type is "Fulfill", let handlerResult be NormalCompletion(argument).
    2. Else,
      1. Assert: type is "Reject".
      2. Let handlerResult be Completion {[[Type]]: throw, [[Value]]: argument, [[Target]]: empty}.
  6. Else, let handlerResult be Call(handler, undefined, « argument »).
  7. If handlerResult is an abrupt completion, then
    1. Let status be Call(promiseCapability.[[Reject]], undefined, « handlerResult.[[Value]] »).
  8. Else,
    1. Let status be Call(promiseCapability.[[Resolve]], undefined, « handlerResult.[[Value]] »).
  9. Return Completion(status).

25.4.2.2 PromiseResolveThenableJob ( promiseToResolve, thenable, then )

The job PromiseResolveThenableJob with parameters promiseToResolve, thenable, and then performs the following steps:

  1. Let resolvingFunctions be CreateResolvingFunctions(promiseToResolve).
  2. Let thenCallResult be Call(then, thenable, « resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]] »).
  3. If thenCallResult is an abrupt completion, then
    1. Let status be Call(resolvingFunctions.[[Reject]], undefined, « thenCallResult.[[Value]] »).
    2. Return Completion(status).
  4. Return Completion(thenCallResult).
 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.

25.4.3 The Promise Constructor

The Promise constructor is the %Promise% intrinsic object and the initial value of the Promise property of the global object. When called as a constructor it creates and initializes a new Promise object. Promise is not intended to be called as a function and will throw an exception when called in that manner.

The Promise constructor is designed to be subclassable. It may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified Promise behaviour must include a super call to the Promise constructor to create and initialize the subclass instance with the internal state necessary to support the Promise and Promise.prototype built-in methods.

25.4.3.1 Promise ( executor )

When the Promise function is called with argument executor, the following steps are taken:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. If IsCallable(executor) is false, throw a TypeError exception.
  3. Let promise be ? OrdinaryCreateFromConstructor(NewTarget, "%PromisePrototype%", « [[PromiseState]], [[PromiseResult]], [[PromiseFulfillReactions]], [[PromiseRejectReactions]], [[PromiseIsHandled]] »).
  4. Set promise.[[PromiseState]] to "pending".
  5. Set promise.[[PromiseFulfillReactions]] to a new empty List.
  6. Set promise.[[PromiseRejectReactions]] to a new empty List.
  7. Set promise.[[PromiseIsHandled]] to false.
  8. Let resolvingFunctions be CreateResolvingFunctions(promise).
  9. Let completion be Call(executor, undefined, « resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]] »).
  10. If completion is an abrupt completion, then
    1. Perform ? Call(resolvingFunctions.[[Reject]], undefined, « completion.[[Value]] »).
  11. 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 object. The executor is called with two arguments: resolve and reject. These are functions that may be used by the executor function to report eventual completion or failure of the deferred computation. Returning from the executor function does not mean that the deferred action has been completed but only that the request to eventually perform the deferred action has been accepted.

The resolve function that is passed to an executor function accepts a single argument. The executor code may eventually call the resolve function to indicate that it wishes to resolve the associated Promise object. The argument passed to the resolve function represents the eventual value of the deferred action and can be either the actual fulfillment value or another Promise object which will provide the value if it is fulfilled.

The reject function that is passed to an executor function accepts a single argument. The executor code may eventually call the reject function to indicate that the associated Promise is rejected and will never be fulfilled. The argument passed to the reject function is used as the rejection value of the promise. Typically it will be an Error object.

The resolve and reject functions passed to an executor function by the Promise constructor have the capability to actually resolve and reject the associated promise. Subclasses may have different constructor behaviour that passes in customized values for resolve and reject.

25.4.4 Properties of the Promise Constructor

The value of the [[Prototype]] internal slot of the Promise constructor is the intrinsic object %FunctionPrototype%.

The Promise constructor has the following properties:

25.4.4.1 Promise.all ( iterable )

The all function returns a new promise which is fulfilled with an array of fulfillment values for the passed promises, or rejects with the reason of the first passed promise that rejects. It resolves all elements of the passed iterable to promises as it runs this algorithm.

  1. Let C be the this value.
  2. If Type(C) is not Object, throw a TypeError exception.
  3. Let promiseCapability be ? NewPromiseCapability(C).
  4. Let iterator be GetIterator(iterable).
  5. IfAbruptRejectPromise(iterator, promiseCapability).
  6. Let iteratorRecord be Record { [[Iterator]]: iterator, [[Done]]: false }.
  7. Let result be PerformPromiseAll(iteratorRecord, C, promiseCapability).
  8. If result is an abrupt completion, then
    1. If iteratorRecord.[[Done]] is false, let result be IteratorClose(iterator, result).
    2. IfAbruptRejectPromise(result, promiseCapability).
  9. Return Completion(result).
 Note

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

25.4.4.1.1 Runtime Semantics: PerformPromiseAll( iteratorRecord, constructor, resultCapability )

When the PerformPromiseAll abstract operation is called with arguments iteratorRecord, constructor, and resultCapability, the following steps are taken:

  1. Assert: constructor is a constructor function.
  2. Assert: resultCapability is a PromiseCapability Record.
  3. Let values be a new empty List.
  4. Let remainingElementsCount be a new Record { [[Value]]: 1 }.
  5. Let index be 0.
  6. Repeat,
    1. Let next be IteratorStep(iteratorRecord.[[Iterator]]).
    2. If next is an abrupt completion, set iteratorRecord.[[Done]] to true.
    3. ReturnIfAbrupt(next).
    4. If next is false, then
      1. Set iteratorRecord.[[Done]] to true.
      2. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] - 1.
      3. If remainingElementsCount.[[Value]] is 0, then
        1. Let valuesArray be CreateArrayFromList(values).
        2. Perform ? Call(resultCapability.[[Resolve]], undefined, « valuesArray »).
      4. Return resultCapability.[[Promise]].
    5. Let nextValue be IteratorValue(next).
    6. If nextValue is an abrupt completion, set iteratorRecord.[[Done]] to true.
    7. ReturnIfAbrupt(nextValue).
    8. Append undefined to values.
    9. Let nextPromise be ? Invoke(constructor, "resolve", « nextValue »).
    10. Let resolveElement be a new built-in function object as defined in Promise.all Resolve Element Functions.
    11. Set resolveElement.[[AlreadyCalled]] to a new Record { [[Value]]: false }.
    12. Set resolveElement.[[Index]] to index.
    13. Set resolveElement.[[Values]] to values.
    14. Set resolveElement.[[Capability]] to resultCapability.
    15. Set resolveElement.[[RemainingElements]] to remainingElementsCount.
    16. Set remainingElementsCount.[[Value]] to remainingElementsCount.[[Value]] + 1.
    17. Perform ? Invoke(nextPromise, "then", « resolveElement, resultCapability.[[Reject]] »).
    18. Set index to index + 1.

25.4.4.1.2 Promise.all Resolve Element Functions

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

When a Promise.all resolve element function F is called with argument x, the following steps are taken:

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

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

25.4.4.2 Promise.prototype

The initial value of Promise.prototype is the intrinsic object %PromisePrototype%.

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

25.4.4.3 Promise.race ( iterable )

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

  1. Let C be the this value.
  2. If Type(C) is not Object, throw a TypeError exception.
  3. Let promiseCapability be ? NewPromiseCapability(C).
  4. Let iterator be GetIterator(iterable).
  5. IfAbruptRejectPromise(iterator, promiseCapability).
  6. Let iteratorRecord be Record { [[Iterator]]: iterator, [[Done]]: false }.
  7. Let result be PerformPromiseRace(iteratorRecord, C, promiseCapability).
  8. If result is an abrupt completion, then
    1. If iteratorRecord.[[Done]] is false, let result be IteratorClose(iterator, result).
    2. IfAbruptRejectPromise(result, promiseCapability).
  9. Return Completion(result).
 Note 1

If the iterable argument is empty or if none of the promises in iterable ever settle then the pending promise returned by this method will never be settled.

 Note 2

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

25.4.4.3.1 Runtime Semantics: PerformPromiseRace ( iteratorRecord, constructor, resultCapability )

When the PerformPromiseRace abstract operation is called with arguments iteratorRecord, constructor, and resultCapability, the following steps are taken:

  1. Assert: constructor is a constructor function.
  2. Assert: resultCapability is a PromiseCapability Record.
  3. Repeat,
    1. Let next be IteratorStep(iteratorRecord.[[Iterator]]).
    2. If next is an abrupt completion, set iteratorRecord.[[Done]] to true.
    3. ReturnIfAbrupt(next).
    4. If next is false, then
      1. Set iteratorRecord.[[Done]] to true.
      2. Return resultCapability.[[Promise]].
    5. Let nextValue be IteratorValue(next).
    6. If nextValue is an abrupt completion, set iteratorRecord.[[Done]] to true.
    7. ReturnIfAbrupt(nextValue).
    8. Let nextPromise be ? Invoke(constructor, "resolve", « nextValue »).
    9. Perform ? Invoke(nextPromise, "then", « resultCapability.[[Resolve]], resultCapability.[[Reject]] »).

25.4.4.4 Promise.reject ( r )

The reject function returns a new promise rejected with the passed argument.

  1. Let C be the this value.
  2. If Type(C) is not Object, throw a TypeError exception.
  3. Let promiseCapability be ? NewPromiseCapability(C).
  4. Perform ? Call(promiseCapability.[[Reject]], undefined, « r »).
  5. Return promiseCapability.[[Promise]].
 Note

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

25.4.4.5 Promise.resolve ( x )

The resolve 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 C be the this value.
  2. If Type(C) is not Object, throw a TypeError exception.
  3. If IsPromise(x) is true, then
    1. Let xConstructor be ? Get(x, "constructor").
    2. If SameValue(xConstructor, C) is true, return x.
  4. Let promiseCapability be ? NewPromiseCapability(C).
  5. Perform ? Call(promiseCapability.[[Resolve]], undefined, « x »).
  6. Return promiseCapability.[[Promise]].
 Note

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

25.4.4.6 get Promise [ @@species ]

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

  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 object's constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by redefining its @@species property.

25.4.5 Properties of the Promise Prototype Object

The Promise prototype object is the intrinsic object %PromisePrototype%. The value of the [[Prototype]] internal slot of the Promise prototype object is the intrinsic object %ObjectPrototype%. The Promise prototype object is an ordinary object. It does not have a [[PromiseState]] internal slot or any of the other internal slots of Promise instances.

25.4.5.1 Promise.prototype.catch ( onRejected )

When the catch method is called with argument onRejected, the following steps are taken:

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

25.4.5.2 Promise.prototype.constructor

The initial value of Promise.prototype.constructor is the intrinsic object %Promise%.

25.4.5.3 Promise.prototype.then ( onFulfilled, onRejected )

When the then method is called with arguments onFulfilled and onRejected, the following steps are taken:

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

25.4.5.3.1 PerformPromiseThen ( promise, onFulfilled, onRejected, resultCapability )

The abstract operation PerformPromiseThen performs the “then” operation on promise using onFulfilled and onRejected as its settlement actions. The result is resultCapability's promise.

  1. Assert: IsPromise(promise) is true.
  2. Assert: resultCapability is a PromiseCapability Record.
  3. If IsCallable(onFulfilled) is false, then
    1. Set onFulfilled to undefined.
  4. If IsCallable(onRejected) is false, then
    1. Set onRejected to undefined.
  5. Let fulfillReaction be the PromiseReaction { [[Capability]]: resultCapability, [[Type]]: "Fulfill", [[Handler]]: onFulfilled }.
  6. Let rejectReaction be the PromiseReaction { [[Capability]]: resultCapability, [[Type]]: "Reject", [[Handler]]: onRejected }.
  7. If promise.[[PromiseState]] is "pending", then
    1. Append fulfillReaction as the last element of the List that is promise.[[PromiseFulfillReactions]].
    2. Append rejectReaction as the last element of the List that is promise.[[PromiseRejectReactions]].
  8. Else if promise.[[PromiseState]] is "fulfilled", then
    1. Let value be promise.[[PromiseResult]].
    2. Perform EnqueueJob("PromiseJobs", PromiseReactionJob, « fulfillReaction, value »).
  9. Else,
    1. Assert: The value of promise.[[PromiseState]] is "rejected".
    2. Let reason be promise.[[PromiseResult]].
    3. If promise.[[PromiseIsHandled]] is false, perform HostPromiseRejectionTracker(promise, "handle").
    4. Perform EnqueueJob("PromiseJobs", PromiseReactionJob, « rejectReaction, reason »).
  10. Set promise.[[PromiseIsHandled]] to true.
  11. Return resultCapability.[[Promise]].

25.4.5.4 Promise.prototype [ @@toStringTag ]

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

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

25.4.6 Properties of Promise Instances

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

Internal Slot Description
[[PromiseState]] A String value that governs how a promise will react to incoming calls to its then method. The possible values are: "pending", "fulfilled", and "rejected".
[[PromiseResult]] The value with which the promise has been fulfilled or rejected, if any. Only meaningful if [[PromiseState]] is not "pending".
[[PromiseFulfillReactions]] A List of PromiseReaction records to be processed when/if the promise transitions from the "pending" state to the "fulfilled" state.
[[PromiseRejectReactions]] A List of PromiseReaction records to be processed when/if the promise transitions from the "pending" state to the "rejected" state.
[[PromiseIsHandled]] A boolean indicating whether the promise has ever had a fulfillment or rejection handler; used in unhandled rejection tracking.

25.5 AsyncFunction Objects

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

25.5.1 The AsyncFunction Constructor

The AsyncFunction constructor is the %AsyncFunction% intrinsic object and is a subclass of Function. When AsyncFunction is called as a function rather than as a constructor, it creates and initializes a new AsyncFunction object. Thus the function call AsyncFunction(…) is equivalent to the object creation expression new AsyncFunction(…) with the same arguments.

The AsyncFunction constructor is designed to be subclassable. It 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.

25.5.1.1 AsyncFunction( p1, p2, … , pn, body )

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

When the AsyncFunction function is called with some arguments p1, p2, …, pn, body (where n might be 0, that is, there are no p arguments, and where body might also not be provided), the following steps are taken:

  1. Let C be the active function object.
 Note
See NOTE for 19.2.1.1.

25.5.2 Properties of the AsyncFunction Constructor

The AsyncFunction constructor is a standard built-in function object that inherits from the Function constructor. The value of the [[Prototype]] internal slot of the AsyncFunction constructor is the intrinsic object %Function%.

The value of the [[Extensible]] internal slot of the AsyncFunction constructor is true.

The value of the name property of the AsyncFunction is "AsyncFunction".

The AsyncFunction constructor has the following properties:

25.5.2.1 AsyncFunction.length

This is a data property with a value of 1. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

25.5.2.2 AsyncFunction.prototype

The initial value of AsyncFunction.prototype is the intrinsic object %AsyncFunctionPrototype%.

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

25.5.3 Properties of the AsyncFunction Prototype Object

The AsyncFunction prototype object is an ordinary object. It is not a function object and does not have an [[ECMAScriptCode]] internal slot or any other of the internal slots listed in Table 27. In addition to being the value of the prototype property of the %AsyncFunction% intrinsic, it is the %AsyncFunctionPrototype% intrinsic.

The value of the [[Prototype]] internal slot of the AsyncFunction prototype object is the %FunctionPrototype% intrinsic object. The initial value of the [[Extensible]] internal slot of the AsyncFunction prototype object is true.

25.5.3.1 AsyncFunction.prototype.constructor

The initial value of AsyncFunction.prototype.constructor is the intrinsic object %AsyncFunction%

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

25.5.3.2 AsyncFunction.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "AsyncFunction".

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

25.5.4 AsyncFunction Instances

Every AsyncFunction instance is an ECMAScript function object and has the internal slots listed in Table 27. The value of the [[FunctionKind]] internal slot for all such instances is "async". 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:

25.5.4.1 length

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

25.5.4.2 name

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

25.5.5 Async Functions Abstract Operations

25.5.5.1 AsyncFunctionCreate ( kind, parameters, body, Scope, Strict )

The abstract operation AsyncFunctionCreate requires the arguments: kind which is one of (Normal, Method, Arrow), a parameter list Parse Node specified by parameters, a body Parse Node specified by body, a Lexical Environment specified by Scope, and a Boolean flag Strict. AsyncFunctionCreate performs the following steps:

  1. Let functionPrototype be the intrinsic object %AsyncFunctionPrototype%.

25.5.5.2 AsyncFunctionStart ( promiseCapability, asyncFunctionBody )

  1. Let runningContext be the running execution context.
  2. Let asyncContext be a copy of runningContext.
  3. Set the code evaluation state of asyncContext such that when evaluation is resumed for that execution context the following steps will be performed:
    1. Let result be the result of evaluating asyncFunctionBody.
    2. Assert: If we return here, the async function either threw an exception or performed an implicit or explicit return; all awaiting is done.
    3. Remove asyncContext 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.
    4. If result.[[Type]] is normal, then
      1. Perform ! Call(promiseCapability.[[Resolve]], undefined, «undefined»).
    5. Else if result.[[Type]] is return, then
      1. Perform ! Call(promiseCapability.[[Resolve]], undefined, «result.[[Value]]»).
    6. Else,
      1. Assert: result.[[Type]] is throw.
      2. Perform ! Call(promiseCapability.[[Reject]], undefined, «result.[[Value]]»).
    7. Return.
  4. Push asyncContext onto the execution context stack; asyncContext is now the running execution context.
  5. Resume the suspended evaluation of asyncContext. Let result be the value returned by the resumed computation.
  6. Assert: When we return here, asyncContext has already been removed from the execution context stack and runningContext is the currently running execution context.
  7. Assert: result is a normal completion with a value of undefined. The possible sources of completion values are AsyncFunctionAwait or, if the async function doesn't await anything, the step 3.g above.
  8. Return.

25.5.5.3 AsyncFunctionAwait ( value )

  1. Let asyncContext be the running execution context.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Let resolveResult be ! Call(promiseCapability.[[Resolve]], undefined, « value »).
  4. Let onFulfilled be a new built-in function object as defined in AsyncFunction Awaited Fulfilled.
  5. Let onRejected be a new built-in function object as defined in AsyncFunction Awaited Rejected.
  6. Set onFulfilled.[[AsyncContext]] to asyncContext.
  7. Set onRejected.[[AsyncContext]] to asyncContext.
  8. Let throwawayCapability be ! NewPromiseCapability(%Promise%).
  9. Set throwawayCapability.[[Promise]].[[PromiseIsHandled]] to true.
  10. Perform ! PerformPromiseThen(promiseCapability.[[Promise]], onFulfilled, onRejected, throwawayCapability).
  11. Remove asyncContext 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.
  12. Set the code evaluation state of asyncContext such that when evaluation is resumed with a Completion resumptionValue the following steps will be performed:
    1. Return resumptionValue.
  13. Return.
 Note
The return value of this abstract operation is unused. The interesting return is that of resumptionValue being returned to the AwaitExpression that originally called this abstract operation.

25.5.5.4 AsyncFunction Awaited Fulfilled

An AsyncFunction Awaited Fulfilled function is an anonymous built-in function that has an [[AsyncContext]] internal slot. The value of the [[AsyncContext]] internal slot is the execution context that will be restored when the function is called.

When an AsyncFunction Awaited Fulfilled function F is called with argument value, the following steps are taken:

  1. Let asyncContext be F.[[AsyncContext]].
  2. Let prevContext be the running execution context.
  3. Suspend prevContext.
  4. Push asyncContext onto the execution context stack; asyncContext is now the running execution context.
  5. Resume the suspended evaluation of asyncContext using NormalCompletion(value) as the result of the operation that suspended it. Let result be the value returned by the resumed computation.
  6. Assert: When we reach this step, asyncContext has already been removed from the execution context stack and prevContext is the currently running execution context.
  7. Return Completion(result).

25.5.5.5 AsyncFunction Awaited Rejected

An AsyncFunction Awaited Rejected function is an anonymous built-in function that has an [[AsyncContext]] internal slot. The value of the [[AsyncContext]] internal slot is the execution context that will be restored when the function is called.

When an AsyncFunction Awaited Rejected function F is called with argument reason, the following steps are taken:

  1. Let asyncContext be F.[[AsyncContext]].
  2. Let prevContext be the running execution context.
  3. Suspend prevContext.
  4. Push asyncContext onto the execution context stack; asyncContext is now the running execution context.
  5. Resume the suspended evaluation of asyncContext using Completion{[[Type]]: throw, [[Value]]: reason, [[Target]]: empty} as the result of the operation that suspended it. Let result be the value returned by the resumed computation.
  6. Assert: When we reach this step, asyncContext has already been removed from the execution context stack and prevContext is the currently running execution context.
  7. Return Completion(result).