27.6 AsyncGenerator Objects
An AsyncGenerator object is an instance of an async generator function and conforms to both the AsyncIterator and AsyncIterable interfaces.
AsyncGenerator instances directly inherit properties from the object that is the initial value of the
27.6.1 Properties of the AsyncGenerator Prototype Object
The AsyncGenerator prototype 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.6.1.1 AsyncGenerator.prototype.constructor
The initial value of AsyncGenerator.prototype.constructor
is
This property has the attributes { [[Writable]]:
27.6.1.2 AsyncGenerator.prototype.next ( value )
- Let generator be the
this value. - Let completion be
NormalCompletion (value). - Return !
AsyncGeneratorEnqueue (generator, completion,empty ).
27.6.1.3 AsyncGenerator.prototype.return ( value )
- Let generator be the
this value. - Let completion be
Completion { [[Type]]:return , [[Value]]: value, [[Target]]:empty }. - Return !
AsyncGeneratorEnqueue (generator, completion,empty ).
27.6.1.4 AsyncGenerator.prototype.throw ( exception )
- Let generator be the
this value. - Let completion be
ThrowCompletion (exception). - Return !
AsyncGeneratorEnqueue (generator, completion,empty ).
27.6.1.5 AsyncGenerator.prototype [ @@toStringTag ]
The initial value of the
This property has the attributes { [[Writable]]:
27.6.2 Properties of AsyncGenerator Instances
AsyncGenerator instances are initially created with the internal slots described below:
Internal Slot | Description |
---|---|
[[AsyncGeneratorState]] | The current execution state of the async generator. The possible values are: |
[[AsyncGeneratorContext]] | The |
[[AsyncGeneratorQueue]] | A |
[[GeneratorBrand]] | A brand used to distinguish different kinds of async generators. The [[GeneratorBrand]] of async generators declared by ECMAScript source text is always |
27.6.3 AsyncGenerator Abstract Operations
27.6.3.1 AsyncGeneratorRequest Records
The AsyncGeneratorRequest is a
They have the following fields:
Field Name | Value | Meaning |
---|---|---|
[[Completion]] | A |
The completion which should be used to resume the async generator. |
[[Capability]] | A |
The promise capabilities associated with this request. |
27.6.3.2 AsyncGeneratorStart ( generator, generatorBody )
The abstract operation AsyncGeneratorStart takes arguments generator and generatorBody (a
Assert : generator is an AsyncGenerator instance.Assert : generator.[[AsyncGeneratorState]] isundefined .- Let genContext be the
running execution context . - Set the Generator component of genContext to generator.
- Set the code evaluation state of genContext such that when evaluation is resumed for that
execution context the following steps will be performed:- If generatorBody is a
Parse Node , then- Let result be the result of evaluating generatorBody.
- Else,
Assert : generatorBody is anAbstract Closure with no parameters.- Let result be generatorBody().
Assert : If we return here, the async generator either threw an exception or performed either an implicit or explicit return.- Remove genContext from the
execution context stack and restore theexecution context that is at the top of theexecution context stack as therunning execution context . - Set generator.[[AsyncGeneratorState]] to
completed . - If result is a normal completion, let resultValue be
undefined . - Else,
- Let resultValue be result.[[Value]].
- If result.[[Type]] is not
return , then- Return !
AsyncGeneratorReject (generator, resultValue).
- Return !
- Return !
AsyncGeneratorResolve (generator, resultValue,true ).
- If generatorBody is a
- Set generator.[[AsyncGeneratorContext]] to genContext.
- Set generator.[[AsyncGeneratorState]] to
suspendedStart . - Set generator.[[AsyncGeneratorQueue]] to a new empty
List . - Return
undefined .
27.6.3.3 AsyncGeneratorValidate ( generator, generatorBrand )
The abstract operation AsyncGeneratorValidate takes arguments generator and generatorBrand. It performs the following steps when called:
- Perform ?
RequireInternalSlot (generator, [[AsyncGeneratorContext]]). - Perform ?
RequireInternalSlot (generator, [[AsyncGeneratorState]]). - Perform ?
RequireInternalSlot (generator, [[AsyncGeneratorQueue]]). - If generator.[[GeneratorBrand]] is not the same value as generatorBrand, throw a
TypeError exception.
27.6.3.4 AsyncGeneratorResolve ( generator, value, done )
The abstract operation AsyncGeneratorResolve takes arguments generator, value, and done (a Boolean). It performs the following steps when called:
Assert : generator is an AsyncGenerator instance.- Let queue be generator.[[AsyncGeneratorQueue]].
Assert : queue is not an emptyList .- Let next be the first element of queue.
- Remove the first element from queue.
- Let promiseCapability be next.[[Capability]].
- Let iteratorResult be !
CreateIterResultObject (value, done). - Perform !
Call (promiseCapability.[[Resolve]],undefined , « iteratorResult »). - Perform !
AsyncGeneratorResumeNext (generator). - Return
undefined .
27.6.3.5 AsyncGeneratorReject ( generator, exception )
The abstract operation AsyncGeneratorReject takes arguments generator and exception. It performs the following steps when called:
Assert : generator is an AsyncGenerator instance.- Let queue be generator.[[AsyncGeneratorQueue]].
Assert : queue is not an emptyList .- Let next be the first element of queue.
- Remove the first element from queue.
- Let promiseCapability be next.[[Capability]].
- Perform !
Call (promiseCapability.[[Reject]],undefined , « exception »). - Perform !
AsyncGeneratorResumeNext (generator). - Return
undefined .
27.6.3.6 AsyncGeneratorResumeNext ( generator )
The abstract operation AsyncGeneratorResumeNext takes argument generator. It performs the following steps when called:
Assert : generator is an AsyncGenerator instance.- Let state be generator.[[AsyncGeneratorState]].
Assert : state is notexecuting .- If state is
awaiting-return , returnundefined . - Let queue be generator.[[AsyncGeneratorQueue]].
- If queue is an empty
List , returnundefined . - Let next be the value of the first element of queue.
Assert : next is an AsyncGeneratorRequest record.- Let completion be next.[[Completion]].
- If completion is an
abrupt completion , then- If state is
suspendedStart , then- Set generator.[[AsyncGeneratorState]] to
completed . - Set state to
completed .
- Set generator.[[AsyncGeneratorState]] to
- If state is
completed , then- If completion.[[Type]] is
return , then- Set generator.[[AsyncGeneratorState]] to
awaiting-return . - Let promise be ?
PromiseResolve (%Promise% , completion.[[Value]]). - Let stepsFulfilled be the algorithm steps defined in
AsyncGeneratorResumeNext Return Processor Fulfilled Functions . - Let lengthFulfilled be the number of non-optional parameters of the function definition in
AsyncGeneratorResumeNext Return Processor Fulfilled Functions . - Let onFulfilled be !
CreateBuiltinFunction (stepsFulfilled, lengthFulfilled,"" , « [[Generator]] »). - Set onFulfilled.[[Generator]] to generator.
- Let stepsRejected be the algorithm steps defined in
AsyncGeneratorResumeNext Return Processor Rejected Functions . - Let lengthRejected be the number of non-optional parameters of the function definition in
AsyncGeneratorResumeNext Return Processor Rejected Functions . - Let onRejected be !
CreateBuiltinFunction (stepsRejected, lengthRejected,"" , « [[Generator]] »). - Set onRejected.[[Generator]] to generator.
- Perform !
PerformPromiseThen (promise, onFulfilled, onRejected). - Return
undefined .
- Set generator.[[AsyncGeneratorState]] to
- Else,
Assert : completion.[[Type]] isthrow .- Perform !
AsyncGeneratorReject (generator, completion.[[Value]]). - Return
undefined .
- If completion.[[Type]] is
- If state is
- Else if state is
completed , return !AsyncGeneratorResolve (generator,undefined ,true ). Assert : state is eithersuspendedStart orsuspendedYield .- Let genContext be generator.[[AsyncGeneratorContext]].
- Let callerContext be the
running execution context . - Suspend callerContext.
- Set generator.[[AsyncGeneratorState]] to
executing . - Push genContext onto the
execution context stack ; genContext is now therunning execution context . - Resume the suspended evaluation of genContext using completion as the result of the operation that suspended it. Let result be the completion record returned by the resumed computation.
Assert : result is never anabrupt completion .Assert : When we return here, genContext has already been removed from theexecution context stack and callerContext is the currentlyrunning execution context .- Return
undefined .
27.6.3.6.1 AsyncGeneratorResumeNext Return Processor Fulfilled Functions
An
When an
- Let F be the
active function object . - Set F.[[Generator]].[[AsyncGeneratorState]] to
completed . - Return !
AsyncGeneratorResolve (F.[[Generator]], value,true ).
The
27.6.3.6.2 AsyncGeneratorResumeNext Return Processor Rejected Functions
An
When an
- Let F be the
active function object . - Set F.[[Generator]].[[AsyncGeneratorState]] to
completed . - Return !
AsyncGeneratorReject (F.[[Generator]], reason).
The
27.6.3.7 AsyncGeneratorEnqueue ( generator, completion, generatorBrand )
The abstract operation AsyncGeneratorEnqueue takes arguments generator, completion (a
- Let promiseCapability be !
NewPromiseCapability (%Promise% ). - Let check be
AsyncGeneratorValidate (generator, generatorBrand). - If check is an
abrupt completion , then- Let badGeneratorError be a newly created
TypeError object. - Perform !
Call (promiseCapability.[[Reject]],undefined , « badGeneratorError »). - Return promiseCapability.[[Promise]].
- Let badGeneratorError be a newly created
- Let queue be generator.[[AsyncGeneratorQueue]].
- Let request be AsyncGeneratorRequest { [[Completion]]: completion, [[Capability]]: promiseCapability }.
- Append request to the end of queue.
- Let state be generator.[[AsyncGeneratorState]].
- If state is not
executing , then- Perform !
AsyncGeneratorResumeNext (generator).
- Perform !
- Return promiseCapability.[[Promise]].
27.6.3.8 AsyncGeneratorYield ( value )
The abstract operation AsyncGeneratorYield takes argument value. It performs the following steps when called:
- Let genContext be the
running execution context . Assert : genContext is theexecution context of a generator.- Let generator be the value of the Generator component of genContext.
Assert :GetGeneratorKind () isasync .- Set value to ?
Await (value). - Set generator.[[AsyncGeneratorState]] to
suspendedYield . - Remove genContext from the
execution context stack and restore theexecution context that is at the top of theexecution context stack as therunning execution context . - Set the code evaluation state of genContext such that when evaluation is resumed with a
Completion resumptionValue the following steps will be performed:- If resumptionValue.[[Type]] is not
return , returnCompletion (resumptionValue). - Let awaited be
Await (resumptionValue.[[Value]]). - If awaited.[[Type]] is
throw , returnCompletion (awaited). Assert : awaited.[[Type]] isnormal .- Return
Completion { [[Type]]:return , [[Value]]: awaited.[[Value]], [[Target]]:empty }. - NOTE: When one of the above steps returns, it returns to the evaluation of the
YieldExpression production that originally called this abstract operation.
- If resumptionValue.[[Type]] is not
- Return !
AsyncGeneratorResolve (generator, value,false ). - NOTE: This returns to the evaluation of the operation that had most previously resumed evaluation of genContext.
27.6.3.9 CreateAsyncIteratorFromClosure ( closure, generatorBrand, generatorPrototype )
The abstract operation CreateAsyncIteratorFromClosure takes arguments closure (an
- NOTE: closure can contain uses of the
Await shorthand and uses of theYield shorthand to yield an IteratorResult object. - Let internalSlotsList be « [[AsyncGeneratorState]], [[AsyncGeneratorContext]], [[AsyncGeneratorQueue]], [[GeneratorBrand]] ».
- Let generator be !
OrdinaryObjectCreate (generatorPrototype, internalSlotsList). - Set generator.[[GeneratorBrand]] to generatorBrand.
- Set generator.[[AsyncGeneratorState]] to
undefined . - Perform !
AsyncGeneratorStart (generator, closure). - Return generator.