mirror of
https://github.com/bendtherules/ask262.git
synced 2026-08-18 13:21:55 +00:00
1716 lines
411 KiB
HTML
1716 lines
411 KiB
HTML
<!DOCTYPE html><html lang="en-GB-oxendict"><head><meta name="viewport" content="width=device-width, initial-scale=1"><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-logo.png"><meta property="og:title" content="ECMAScript® 2026 Language Specification"><meta property="og:description" content="Introduction
|
||
This Ecma Standard defines the ECMAScript 2026 Language. It is the seventeenth edition of the ECMAScript Language Specification. ECMAScript is based on several originating technologies, the most well-known being JavaScript (Netscape) and JScript (Microsoft). The language was invent">
|
||
<link rel="icon" href="../img/favicon.ico">
|
||
<link rel="stylesheet" href="../assets/css/ecmarkup.css"><link rel="stylesheet" href="../assets/css/print.css" media="print">
|
||
|
||
<title>ECMAScript® 2026 Language Specification</title><script src="../assets/js/multipage.js?cache=Wu2V1pj2" defer=""></script><script src="../assets/js/ecmarkup.js?cache=BPFBckdu" defer=""></script><link rel="canonical" href="../#sec-control-abstraction-objects"></head>
|
||
<body><div id="spec-container"><emu-clause id="sec-control-abstraction-objects">
|
||
<h1><span class="secnum">27</span> Control Abstraction Objects</h1>
|
||
|
||
<emu-clause id="sec-iteration">
|
||
<h1><span class="secnum">27.1</span> Iteration</h1>
|
||
|
||
<emu-clause id="sec-common-iteration-interfaces">
|
||
<h1><span class="secnum">27.1.1</span> Common Iteration Interfaces</h1>
|
||
<p>An interface is a set of <emu-xref href="#property-key" id="_ref_15594"><a href="ecmascript-data-types-and-values.html#property-key">property keys</a></emu-xref> whose associated values match a specific specification. Any object that provides all the properties as described by an interface's specification <em>conforms</em> 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.</p>
|
||
|
||
<emu-clause id="sec-iterable-interface">
|
||
<h1><span class="secnum">27.1.1.1</span> The Iterable Interface</h1>
|
||
<p>The <dfn variants="iterable,iterables,iterable object,iterable objects" tabindex="-1">iterable interface</dfn> includes the property described in <emu-xref href="#table-iterable-interface-required-properties" id="_ref_816"><a href="control-abstraction-objects.html#table-iterable-interface-required-properties">Table 77</a></emu-xref>:</p>
|
||
<emu-table id="table-iterable-interface-required-properties" caption="Iterable Interface Required Properties" oldids="table-52"><figure><figcaption>Table 77: <emu-xref href="#sec-iterable-interface" id="_ref_15595"><a href="control-abstraction-objects.html#sec-iterable-interface">Iterable</a></emu-xref> Interface Required Properties</figcaption><span id="table-52"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Property
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Requirements
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<code>%Symbol.iterator%</code>
|
||
</td>
|
||
<td>
|
||
a function that returns an <emu-xref href="#sec-iterator-interface" id="_ref_15596"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The returned object must conform to the <emu-xref href="#sec-iterator-interface" id="_ref_15597"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator interface</a></emu-xref>.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator-interface">
|
||
<h1><span class="secnum">27.1.1.2</span> The Iterator Interface</h1>
|
||
<p>An object that implements the <dfn variants="iterator object,iterator objects,iterator,iterators" tabindex="-1">iterator interface</dfn> must include the property in <emu-xref href="#table-iterator-interface-required-properties" id="_ref_817"><a href="control-abstraction-objects.html#table-iterator-interface-required-properties">Table 78</a></emu-xref>. Such objects may also implement the properties in <emu-xref href="#table-iterator-interface-optional-properties" id="_ref_818"><a href="control-abstraction-objects.html#table-iterator-interface-optional-properties">Table 79</a></emu-xref>.</p>
|
||
<emu-table id="table-iterator-interface-required-properties" caption="Iterator Interface Required Properties" oldids="table-53"><figure><figcaption>Table 78: <emu-xref href="#sec-iterator-interface" id="_ref_15598"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> Interface Required Properties</figcaption><span id="table-53"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Property
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Requirements
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<emu-val>"next"</emu-val>
|
||
</td>
|
||
<td>
|
||
a function that returns an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15599"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The returned object must conform to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15600"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. If a previous call to the <code>next</code> method of an <emu-xref href="#sec-iterator-interface" id="_ref_15601"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> has returned an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15602"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> whose <emu-val>"done"</emu-val> property is <emu-val>true</emu-val>, then all subsequent calls to the <code>next</code> method of that object should also return an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15603"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> whose <emu-val>"done"</emu-val> property is <emu-val>true</emu-val>. However, this requirement is not enforced.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>Arguments may be passed to the <code>next</code> 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.</p>
|
||
</div></emu-note>
|
||
<emu-table id="table-iterator-interface-optional-properties" caption="Iterator Interface Optional Properties" oldids="table-54"><figure><figcaption>Table 79: <emu-xref href="#sec-iterator-interface" id="_ref_15604"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> Interface Optional Properties</figcaption><span id="table-54"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Property
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Requirements
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<emu-val>"return"</emu-val>
|
||
</td>
|
||
<td>
|
||
a function that returns an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15605"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The returned object must conform to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15606"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. Invoking this method notifies the <emu-xref href="#sec-iterator-interface" id="_ref_15607"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator object</a></emu-xref> that the caller does not intend to make any more <code>next</code> method calls to the <emu-xref href="#sec-iterator-interface" id="_ref_15608"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref>. The returned <emu-xref href="#sec-iteratorresult-interface" id="_ref_15609"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> will typically have a <emu-val>"done"</emu-val> property whose value is <emu-val>true</emu-val>, and a <emu-val>"value"</emu-val> property with the value passed as the argument of the <code>return</code> method. However, this requirement is not enforced.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<emu-val>"throw"</emu-val>
|
||
</td>
|
||
<td>
|
||
a function that returns an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15610"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The returned object must conform to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15611"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. Invoking this method notifies the <emu-xref href="#sec-iterator-interface" id="_ref_15612"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator object</a></emu-xref> 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 <code>throw</code> the value passed as the argument. If the method does not <code>throw</code>, the returned <emu-xref href="#sec-iteratorresult-interface" id="_ref_15613"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> will typically have a <emu-val>"done"</emu-val> property whose value is <emu-val>true</emu-val>.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including <code>for</code>-<code>of</code>, <code>yield*</code>, and array destructuring call these methods after performing an existence check. Most ECMAScript library functions that accept <emu-xref href="#sec-iterable-interface" id="_ref_15614"><a href="control-abstraction-objects.html#sec-iterable-interface">iterable objects</a></emu-xref> as arguments also conditionally call them.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asynciterable-interface">
|
||
<h1><span class="secnum">27.1.1.3</span> The Async Iterable Interface</h1>
|
||
<p>The <dfn variants="async iterable,async iterables,async iterable object,async iterable objects" tabindex="-1">async iterable interface</dfn> includes the properties described in <emu-xref href="#table-async-iterable" id="_ref_819"><a href="control-abstraction-objects.html#table-async-iterable">Table 80</a></emu-xref>:</p>
|
||
<emu-table id="table-async-iterable" caption="Async Iterable Interface Required Properties"><figure><figcaption>Table 80: Async <emu-xref href="#sec-iterable-interface" id="_ref_15615"><a href="control-abstraction-objects.html#sec-iterable-interface">Iterable</a></emu-xref> Interface Required Properties</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Property</th>
|
||
<th>Value</th>
|
||
<th>Requirements</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><code>%Symbol.asyncIterator%</code></td>
|
||
<td>a function that returns an <emu-xref href="#sec-asynciterator-interface" id="_ref_15616"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator object</a></emu-xref></td>
|
||
<td>The returned object must conform to the <emu-xref href="#sec-asynciterator-interface" id="_ref_15617"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator interface</a></emu-xref>.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asynciterator-interface">
|
||
<h1><span class="secnum">27.1.1.4</span> The Async Iterator Interface</h1>
|
||
<p>An object that implements the <dfn variants="async iterator object,async iterator objects,async iterator,async iterators" tabindex="-1">async iterator interface</dfn> must include the properties in <emu-xref href="#table-async-iterator-required" id="_ref_820"><a href="control-abstraction-objects.html#table-async-iterator-required">Table 81</a></emu-xref>. Such objects may also implement the properties in <emu-xref href="#table-async-iterator-optional" id="_ref_821"><a href="control-abstraction-objects.html#table-async-iterator-optional">Table 82</a></emu-xref>.</p>
|
||
<emu-table id="table-async-iterator-required" caption="Async Iterator Interface Required Properties"><figure><figcaption>Table 81: Async <emu-xref href="#sec-iterator-interface" id="_ref_15618"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> Interface Required Properties</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Property</th>
|
||
<th>Value</th>
|
||
<th>Requirements</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><emu-val>"next"</emu-val></td>
|
||
<td>a function that returns a promise for an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15619"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref></td>
|
||
<td>
|
||
<p>The returned promise, when fulfilled, must fulfill with an object that conforms to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15620"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. If a previous call to the <code>next</code> method of an <emu-xref href="#sec-asynciterator-interface" id="_ref_15621"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator</a></emu-xref> has returned a promise for an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15622"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> whose <emu-val>"done"</emu-val> property is <emu-val>true</emu-val>, then all subsequent calls to the <code>next</code> method of that object should also return a promise for an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15623"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> whose <emu-val>"done"</emu-val> property is <emu-val>true</emu-val>. However, this requirement is not enforced.</p>
|
||
|
||
<p>Additionally, the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15624"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> that serves as a fulfillment value should have a <emu-val>"value"</emu-val> property whose value is not a promise (or "thenable"). However, this requirement is also not enforced.</p>
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>Arguments may be passed to the <code>next</code> function but their interpretation and validity is dependent upon the target async iterator. The <code>for</code>-<code>await</code>-<code>of</code> 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.</p>
|
||
</div></emu-note>
|
||
<emu-table id="table-async-iterator-optional" caption="Async Iterator Interface Optional Properties"><figure><figcaption>Table 82: Async <emu-xref href="#sec-iterator-interface" id="_ref_15625"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> Interface Optional Properties</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Property</th>
|
||
<th>Value</th>
|
||
<th>Requirements</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><emu-val>"return"</emu-val></td>
|
||
<td>a function that returns a promise for an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15626"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref></td>
|
||
<td>
|
||
<p>The returned promise, when fulfilled, must fulfill with an object that conforms to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15627"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. Invoking this method notifies the <emu-xref href="#sec-asynciterator-interface" id="_ref_15628"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator object</a></emu-xref> that the caller does not intend to make any more <code>next</code> method calls to the <emu-xref href="#sec-asynciterator-interface" id="_ref_15629"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator</a></emu-xref>. The returned promise will fulfill with an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15630"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> which will typically have a <emu-val>"done"</emu-val> property whose value is <emu-val>true</emu-val>, and a <emu-val>"value"</emu-val> property with the value passed as the argument of the <code>return</code> method. However, this requirement is not enforced.</p>
|
||
|
||
<p>Additionally, the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15631"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> that serves as a fulfillment value should have a <emu-val>"value"</emu-val> 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 <emu-val>"value"</emu-val> property of the returned promise's <emu-xref href="#sec-iteratorresult-interface" id="_ref_15632"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> fulfillment value. However, these requirements are also not enforced.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><emu-val>"throw"</emu-val></td>
|
||
<td>a function that returns a promise for an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15633"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref></td>
|
||
<td>
|
||
<p>The returned promise, when fulfilled, must fulfill with an object that conforms to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15634"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>. Invoking this method notifies the <emu-xref href="#sec-asynciterator-interface" id="_ref_15635"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator object</a></emu-xref> 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.</p>
|
||
|
||
<p>If the returned promise is fulfilled, the <emu-xref href="#sec-iteratorresult-interface" id="_ref_15636"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> fulfillment value will typically have a <emu-val>"done"</emu-val> property whose value is <emu-val>true</emu-val>. Additionally, it should have a <emu-val>"value"</emu-val> property whose value is not a promise (or "thenable"), but this requirement is not enforced.</p>
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including <code>for</code>-<code>await</code>-<code>of</code> and <code>yield*</code> call these methods after performing an existence check.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iteratorresult-interface">
|
||
<h1><span class="secnum">27.1.1.5</span> The IteratorResult Interface</h1>
|
||
<p>The <dfn variants="IteratorResult object,IteratorResult objects" tabindex="-1">IteratorResult interface</dfn> includes the properties listed in <emu-xref href="#table-iteratorresult-interface-properties" id="_ref_822"><a href="control-abstraction-objects.html#table-iteratorresult-interface-properties">Table 83</a></emu-xref>:</p>
|
||
<emu-table id="table-iteratorresult-interface-properties" caption="IteratorResult Interface Properties" oldids="table-55"><figure><figcaption>Table 83: IteratorResult Interface Properties</figcaption><span id="table-55"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Property
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Requirements
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<emu-val>"done"</emu-val>
|
||
</td>
|
||
<td>
|
||
a Boolean
|
||
</td>
|
||
<td>
|
||
This is the result status of an <emu-xref href="#sec-iterator-interface" id="_ref_15637"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> <code>next</code> method call. If the end of the <emu-xref href="#sec-iterator-interface" id="_ref_15638"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> was reached <emu-val>"done"</emu-val> is <emu-val>true</emu-val>. If the end was not reached <emu-val>"done"</emu-val> is <emu-val>false</emu-val> and a value is available. If a <emu-val>"done"</emu-val> property (either own or inherited) does not exist, it is considered to have the value <emu-val>false</emu-val>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<emu-val>"value"</emu-val>
|
||
</td>
|
||
<td>
|
||
an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15639"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
If done is <emu-val>false</emu-val>, this is the current iteration element value. If done is <emu-val>true</emu-val>, this is the return value of the <emu-xref href="#sec-iterator-interface" id="_ref_15640"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref>, if it supplied one. If the <emu-xref href="#sec-iterator-interface" id="_ref_15641"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> does not have a return value, <emu-val>"value"</emu-val> is <emu-val>undefined</emu-val>. In that case, the <emu-val>"value"</emu-val> property may be absent from the conforming object if it does not inherit an explicit <emu-val>"value"</emu-val> property.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator-helper-objects">
|
||
<h1><span class="secnum">27.1.2</span> Iterator Helper Objects</h1>
|
||
<p>An <dfn variants="Iterator Helper objects" tabindex="-1">Iterator Helper object</dfn> is an <emu-xref href="#ordinary-object" id="_ref_15642"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref> that represents a lazy transformation of some specific source <emu-xref href="#sec-iterator-interface" id="_ref_15643"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator object</a></emu-xref>. There is not a named <emu-xref href="#constructor" id="_ref_15644"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> for Iterator Helper objects. Instead, Iterator Helper objects are created by calling certain methods of <emu-xref href="#sec-iterator-interface" id="_ref_15645"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> instance objects.</p>
|
||
|
||
<emu-clause id="sec-%iteratorhelperprototype%-object">
|
||
<h1><span class="secnum">27.1.2.1</span> The %IteratorHelperPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%IteratorHelperPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>has properties that are inherited by all <emu-xref href="#sec-iterator-helper-objects" id="_ref_15646"><a href="control-abstraction-objects.html#sec-iterator-helper-objects">Iterator Helper objects</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15647"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_15648"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">%Iterator.prototype%</a></emu-xref>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-%iteratorhelperprototype%.next" type="built-in function">
|
||
<h1><span class="secnum">27.1.2.1.1</span> %IteratorHelperPrototype%.next ( )</h1>
|
||
<emu-alg><ol><li>Return ? <emu-xref aoid="GeneratorResume" id="_ref_15649"><a href="control-abstraction-objects.html#sec-generatorresume" class="e-user-code">GeneratorResume</a></emu-xref>(<emu-val>this</emu-val> value, <emu-val>undefined</emu-val>, <emu-val>"Iterator Helper"</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%iteratorhelperprototype%.return" type="built-in function">
|
||
<h1><span class="secnum">27.1.2.1.2</span> %IteratorHelperPrototype%.return ( )</h1>
|
||
<emu-alg><ol><li>Let <var>O</var> be <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15650"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[UnderlyingIterators]]</var>).</li><li><emu-xref href="#assert" id="_ref_15651"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> has a <var class="field">[[GeneratorState]]</var> internal slot.</li><li>If <var>O</var>.<var class="field">[[GeneratorState]]</var> is <emu-const>suspended-start</emu-const>, then<ol><li>Set <var>O</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>completed</emu-const>.</li><li>NOTE: Once a generator enters the completed state it never leaves it and its associated <emu-xref href="#sec-execution-contexts" id="_ref_15652"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> is never resumed. Any execution state associated with <var>O</var> can be discarded at this point.</li><li>Perform ? <emu-xref aoid="IteratorCloseAll" id="_ref_15653"><a href="abstract-operations.html#sec-iteratorcloseall" class="e-user-code">IteratorCloseAll</a></emu-xref>(<var>O</var>.<var class="field">[[UnderlyingIterators]]</var>, <emu-xref aoid="NormalCompletion" id="_ref_15654"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-const>unused</emu-const>)).</li><li>Return <emu-xref aoid="CreateIteratorResultObject" id="_ref_15655"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).</li></ol></li><li>Let <var>C</var> be <emu-xref aoid="ReturnCompletion" id="_ref_15656"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Return ? <emu-xref aoid="GeneratorResumeAbrupt" id="_ref_15657"><a href="control-abstraction-objects.html#sec-generatorresumeabrupt" class="e-user-code">GeneratorResumeAbrupt</a></emu-xref>(<var>O</var>, <var>C</var>, <emu-val>"Iterator Helper"</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%iteratorhelperprototype%-%symbol.tostringtag%">
|
||
<h1><span class="secnum">27.1.2.1.3</span> %IteratorHelperPrototype% [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15658"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"Iterator Helper"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator-objects">
|
||
<h1><span class="secnum">27.1.3</span> Iterator Objects</h1>
|
||
|
||
<emu-clause id="sec-iterator-constructor">
|
||
<h1><span class="secnum">27.1.3.1</span> The Iterator Constructor</h1>
|
||
<p>The <dfn tabindex="-1">Iterator</dfn> <emu-xref href="#constructor" id="_ref_15659"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%Iterator%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"Iterator"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_15660"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>is designed to be subclassable. It may be used as the value of an <emu-val>extends</emu-val> clause of a class definition.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-iterator" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.1.1</span> Iterator ( )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If NewTarget is either <emu-val>undefined</emu-val> or the <emu-xref href="#active-function-object" id="_ref_15661"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_15662"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(NewTarget, <emu-val>"%Iterator.prototype%"</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-iterator-constructor">
|
||
<h1><span class="secnum">27.1.3.2</span> Properties of the Iterator Constructor</h1>
|
||
<p>The <emu-xref href="#sec-iterator-interface" id="_ref_15663"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> <emu-xref href="#constructor" id="_ref_15664"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_15665"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-iterator.concat" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.2.1</span> Iterator.concat ( ...<var>items</var> )</h1>
|
||
<emu-alg><ol><li>Let <var>iterables</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15666"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>For each element <var>item</var> of <var>items</var>, do<ol><li>If <var>item</var> <emu-xref href="#sec-object-type" id="_ref_15667"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>method</var> be ? <emu-xref aoid="GetMethod" id="_ref_15668"><a href="abstract-operations.html#sec-getmethod" class="e-user-code">GetMethod</a></emu-xref>(<var>item</var>, <emu-xref href="#sec-well-known-symbols" id="_ref_15669"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.iterator%</a></emu-xref>).</li><li>If <var>method</var> is <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Append the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15670"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[OpenMethod]]</var>: <var>method</var>, <var class="field">[[Iterable]]</var>: <var>item</var> } to <var>iterables</var>.</li></ol></li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15671"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterables</var> and performs the following steps when called:<ol><li>For each <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15672"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> <var>iterable</var> of <var>iterables</var>, do<ol><li>Let <var>iter</var> be ? <emu-xref aoid="Call" id="_ref_15673"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>iterable</var>.<var class="field">[[OpenMethod]]</var>, <var>iterable</var>.<var class="field">[[Iterable]]</var>).</li><li>If <var>iter</var> <emu-xref href="#sec-object-type" id="_ref_15674"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iteratorRecord</var> be ? <emu-xref aoid="GetIteratorDirect" id="_ref_15675"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>iter</var>).</li><li>Let <var>innerAlive</var> be <emu-val>true</emu-val>.</li><li>Repeat, while <var>innerAlive</var> is <emu-val>true</emu-val>,<ol><li>Let <var>innerValue</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15676"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iteratorRecord</var>).</li><li>If <var>innerValue</var> is <emu-const>done</emu-const>, then<ol><li>Set <var>innerAlive</var> to <emu-val>false</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15677"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15678"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>innerValue</var>)).</li><li>If <var>completion</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_15679"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15680"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iteratorRecord</var>, <var>completion</var>).</li></ol></li></ol></li></ol></li></ol></li><li>Return <emu-xref aoid="ReturnCompletion" id="_ref_15681"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>gen</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15682"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15683"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>gen</var>.<var class="field">[[UnderlyingIterators]]</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15684"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Return <var>gen</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.from" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.2.2</span> Iterator.from ( <var>O</var> )</h1>
|
||
<emu-alg><ol><li>Let <var>iteratorRecord</var> be ? <emu-xref aoid="GetIteratorFlattenable" id="_ref_15685"><a href="abstract-operations.html#sec-getiteratorflattenable" class="e-user-code">GetIteratorFlattenable</a></emu-xref>(<var>O</var>, <emu-const>iterate-string-primitives</emu-const>).</li><li>Let <var>hasInstance</var> be ? <emu-xref aoid="OrdinaryHasInstance" id="_ref_15686"><a href="abstract-operations.html#sec-ordinaryhasinstance" class="e-user-code">OrdinaryHasInstance</a></emu-xref>(<emu-xref href="#sec-iterator-constructor" id="_ref_15687"><a href="control-abstraction-objects.html#sec-iterator-constructor">%Iterator%</a></emu-xref>, <var>iteratorRecord</var>.<var class="field">[[Iterator]]</var>).</li><li>If <var>hasInstance</var> is <emu-val>true</emu-val>, then<ol><li>Return <var>iteratorRecord</var>.<var class="field">[[Iterator]]</var>.</li></ol></li><li>Let <var>wrapper</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_15688"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-%wrapforvaliditeratorprototype%-object" id="_ref_15689"><a href="control-abstraction-objects.html#sec-%wrapforvaliditeratorprototype%-object">%WrapForValidIteratorPrototype%</a></emu-xref>, « <var class="field">[[Iterated]]</var> »).</li><li>Set <var>wrapper</var>.<var class="field">[[Iterated]]</var> to <var>iteratorRecord</var>.</li><li>Return <var>wrapper</var>.</li></ol></emu-alg>
|
||
|
||
<emu-clause id="sec-%wrapforvaliditeratorprototype%-object">
|
||
<h1><span class="secnum">27.1.3.2.2.1</span> The %WrapForValidIteratorPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%WrapForValidIteratorPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15690"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_15691"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">%Iterator.prototype%</a></emu-xref>.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-%wrapforvaliditeratorprototype%.next" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.2.2.1.1</span> %WrapForValidIteratorPrototype%.next ( )</h1>
|
||
<emu-alg><ol><li>Let <var>O</var> be <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15692"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[Iterated]]</var>).</li><li>Let <var>iteratorRecord</var> be <var>O</var>.<var class="field">[[Iterated]]</var>.</li><li>Return ? <emu-xref aoid="Call" id="_ref_15693"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>iteratorRecord</var>.<var class="field">[[NextMethod]]</var>, <var>iteratorRecord</var>.<var class="field">[[Iterator]]</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%wrapforvaliditeratorprototype%.return" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.2.2.1.2</span> %WrapForValidIteratorPrototype%.return ( )</h1>
|
||
<emu-alg><ol><li>Let <var>O</var> be <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15694"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[Iterated]]</var>).</li><li>Let <var>iterator</var> be <var>O</var>.<var class="field">[[Iterated]]</var>.<var class="field">[[Iterator]]</var>.</li><li><emu-xref href="#assert" id="_ref_15695"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>iterator</var> <emu-xref href="#sec-object-type" id="_ref_15696"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>.</li><li>Let <var>returnMethod</var> be ? <emu-xref aoid="GetMethod" id="_ref_15697"><a href="abstract-operations.html#sec-getmethod" class="e-user-code">GetMethod</a></emu-xref>(<var>iterator</var>, <emu-val>"return"</emu-val>).</li><li>If <var>returnMethod</var> is <emu-val>undefined</emu-val>, then<ol><li>Return <emu-xref aoid="CreateIteratorResultObject" id="_ref_15698"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).</li></ol></li><li>Return ? <emu-xref aoid="Call" id="_ref_15699"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>returnMethod</var>, <var>iterator</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype">
|
||
<h1><span class="secnum">27.1.3.2.3</span> Iterator.prototype</h1>
|
||
<p>The initial value of Iterator.prototype is the <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_15700"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">Iterator prototype object</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-%iteratorprototype%-object" id="sec-%iterator.prototype%-object"><span id="sec-%iteratorprototype%-object"></span>
|
||
<h1><span class="secnum">27.1.3.3</span> Properties of the Iterator Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">Iterator prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%Iterator.prototype%</dfn>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15701"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15702"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
</ul>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>All objects defined in this specification that implement the <emu-xref href="#sec-iterator-interface" id="_ref_15703"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator interface</a></emu-xref> 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 <emu-xref href="#sec-iterator-interface" id="_ref_15704"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator objects</a></emu-xref> may be added.</p>
|
||
<p>The following expression is one way that ECMAScript code can access the %Iterator.prototype% object:</p>
|
||
<pre><code class="javascript hljs"><span class="hljs-title class_">Object</span>.<span class="hljs-title function_">getPrototypeOf</span>(<span class="hljs-title class_">Object</span>.<span class="hljs-title function_">getPrototypeOf</span>([][<span class="hljs-title class_">Symbol</span>.<span class="hljs-property">iterator</span>]()))</code></pre>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-iterator.prototype.constructor">
|
||
<h1><span class="secnum">27.1.3.3.1</span> Iterator.prototype.constructor</h1>
|
||
<p><code>Iterator.prototype.constructor</code> is an <emu-xref href="#sec-object-type" id="_ref_15705"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> with attributes { <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }. The <var class="field">[[Get]]</var> and <var class="field">[[Set]]</var> attributes are defined as follows:</p>
|
||
|
||
<emu-clause id="sec-get-iterator.prototype.constructor" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.1.1</span> get Iterator.prototype.constructor</h1>
|
||
<p>The value of the <var class="field">[[Get]]</var> attribute is a built-in function that requires no arguments. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return <emu-xref href="#sec-iterator-constructor" id="_ref_15706"><a href="control-abstraction-objects.html#sec-iterator-constructor">%Iterator%</a></emu-xref>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-set-iterator.prototype.constructor" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.1.2</span> set Iterator.prototype.constructor</h1>
|
||
<p>The value of the <var class="field">[[Set]]</var> attribute is a built-in function that takes an argument <var>v</var>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="SetterThatIgnoresPrototypeProperties" id="_ref_15707"><a href="abstract-operations.html#sec-SetterThatIgnoresPrototypeProperties" class="e-user-code">SetterThatIgnoresPrototypeProperties</a></emu-xref>(<emu-val>this</emu-val> value, <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_15708"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">%Iterator.prototype%</a></emu-xref>, <emu-val>"constructor"</emu-val>, <var>v</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Unlike the <emu-val>"constructor"</emu-val> property on most built-in prototypes, for web-compatibility reasons this property must be an accessor.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.drop" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.2</span> Iterator.prototype.drop ( <var>limit</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15709"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15710"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>Let <var>numLimit</var> be <emu-xref aoid="Completion" id="_ref_15711"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="ToNumber" id="_ref_15712"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>limit</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15713"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>numLimit</var>, <var>iterated</var>).</li><li>If <var>numLimit</var> is <emu-val>NaN</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15714"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>RangeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15715"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Let <var>integerLimit</var> be ! <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15716"><a href="abstract-operations.html#sec-tointegerorinfinity">ToIntegerOrInfinity</a></emu-xref>(<var>numLimit</var>).</li><li>If <var>integerLimit</var> < 0, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15717"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>RangeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15718"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15719"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15720"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterated</var> and <var>integerLimit</var> and performs the following steps when called:<ol><li>Let <var>remaining</var> be <var>integerLimit</var>.</li><li>Repeat, while <var>remaining</var> > 0,<ol><li>If <var>remaining</var> ≠ +∞, then<ol><li>Set <var>remaining</var> to <var>remaining</var> - 1.</li></ol></li><li>Let <var>next</var> be ? <emu-xref aoid="IteratorStep" id="_ref_15721"><a href="abstract-operations.html#sec-iteratorstep" class="e-user-code">IteratorStep</a></emu-xref>(<var>iterated</var>).</li><li>If <var>next</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15722"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15723"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15724"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15725"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15726"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>value</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15727"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>completion</var>, <var>iterated</var>).</li></ol></li></ol></li><li>Let <var>result</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15728"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15729"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>result</var>.<var class="field">[[UnderlyingIterators]]</var> to « <var>iterated</var> ».</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.every" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.3</span> Iterator.prototype.every ( <var>predicate</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15730"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15731"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15732"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>predicate</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15733"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15734"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15735"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15736"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-val>true</emu-val>.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15737"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15738"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>predicate</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15739"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15740"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>result</var>, <var>iterated</var>).</li><li>If <emu-xref aoid="ToBoolean" id="_ref_15741"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>result</var>) is <emu-val>false</emu-val>, return ? <emu-xref aoid="IteratorClose" id="_ref_15742"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <emu-xref aoid="NormalCompletion" id="_ref_15743"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>false</emu-val>)).</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.filter" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.4</span> Iterator.prototype.filter ( <var>predicate</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15744"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15745"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15746"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>predicate</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15747"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15748"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15749"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15750"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterated</var> and <var>predicate</var> and performs the following steps when called:<ol><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15751"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15752"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Let <var>selected</var> be <emu-xref aoid="Completion" id="_ref_15753"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15754"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>predicate</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15755"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15756"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>selected</var>, <var>iterated</var>).</li><li>If <emu-xref aoid="ToBoolean" id="_ref_15757"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>selected</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15758"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15759"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>value</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15760"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>completion</var>, <var>iterated</var>).</li></ol></li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></li><li>Let <var>result</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15761"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15762"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>result</var>.<var class="field">[[UnderlyingIterators]]</var> to « <var>iterated</var> ».</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.find" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.5</span> Iterator.prototype.find ( <var>predicate</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15763"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15764"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15765"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>predicate</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15766"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15767"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15768"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15769"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15770"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15771"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>predicate</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15772"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15773"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>result</var>, <var>iterated</var>).</li><li>If <emu-xref aoid="ToBoolean" id="_ref_15774"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>result</var>) is <emu-val>true</emu-val>, return ? <emu-xref aoid="IteratorClose" id="_ref_15775"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <emu-xref aoid="NormalCompletion" id="_ref_15776"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>)).</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.flatmap" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.6</span> Iterator.prototype.flatMap ( <var>mapper</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15777"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15778"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15779"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>mapper</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15780"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15781"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15782"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15783"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterated</var> and <var>mapper</var> and performs the following steps when called:<ol><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15784"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15785"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Let <var>mapped</var> be <emu-xref aoid="Completion" id="_ref_15786"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15787"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>mapper</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15788"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15789"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>mapped</var>, <var>iterated</var>).</li><li>Let <var>innerIterator</var> be <emu-xref aoid="Completion" id="_ref_15790"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetIteratorFlattenable" id="_ref_15791"><a href="abstract-operations.html#sec-getiteratorflattenable" class="e-user-code">GetIteratorFlattenable</a></emu-xref>(<var>mapped</var>, <emu-const>reject-primitives</emu-const>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15792"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>innerIterator</var>, <var>iterated</var>).</li><li>Let <var>innerAlive</var> be <emu-val>true</emu-val>.</li><li>Repeat, while <var>innerAlive</var> is <emu-val>true</emu-val>,<ol><li>Let <var>innerValue</var> be <emu-xref aoid="Completion" id="_ref_15793"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorStepValue" id="_ref_15794"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>innerIterator</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15795"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>innerValue</var>, <var>iterated</var>).</li><li>If <var>innerValue</var> is <emu-const>done</emu-const>, then<ol><li>Set <var>innerAlive</var> to <emu-val>false</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15796"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15797"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>innerValue</var>)).</li><li>If <var>completion</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_15798"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Let <var>backupCompletion</var> be <emu-xref aoid="Completion" id="_ref_15799"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_15800"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>innerIterator</var>, <var>completion</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15801"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>backupCompletion</var>, <var>iterated</var>).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15802"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>completion</var>).</li></ol></li></ol></li></ol></li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></li><li>Let <var>result</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15803"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15804"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>result</var>.<var class="field">[[UnderlyingIterators]]</var> to « <var>iterated</var> ».</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.foreach" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.7</span> Iterator.prototype.forEach ( <var>procedure</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15805"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15806"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15807"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>procedure</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15808"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15809"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15810"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15811"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15812"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15813"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>procedure</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15814"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15815"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>result</var>, <var>iterated</var>).</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.map" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.8</span> Iterator.prototype.map ( <var>mapper</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15816"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15817"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15818"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>mapper</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15819"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15820"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15821"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15822"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterated</var> and <var>mapper</var> and performs the following steps when called:<ol><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15823"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15824"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Let <var>mapped</var> be <emu-xref aoid="Completion" id="_ref_15825"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15826"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>mapper</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15827"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15828"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>mapped</var>, <var>iterated</var>).</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15829"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15830"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>mapped</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15831"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>completion</var>, <var>iterated</var>).</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></li><li>Let <var>result</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15832"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15833"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>result</var>.<var class="field">[[UnderlyingIterators]]</var> to « <var>iterated</var> ».</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.reduce" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.9</span> Iterator.prototype.reduce ( <var>reducer</var> [ , <var>initialValue</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15834"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15835"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15836"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>reducer</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15837"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15838"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15839"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>If <var>initialValue</var> is not present, then<ol><li>Let <var>accumulator</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15840"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>accumulator</var> is <emu-const>done</emu-const>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>counter</var> be 1.</li></ol></li><li>Else,<ol><li>Let <var>accumulator</var> be <var>initialValue</var>.</li><li>Let <var>counter</var> be 0.</li></ol></li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15841"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <var>accumulator</var>.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15842"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15843"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>reducer</var>, <emu-val>undefined</emu-val>, « <var>accumulator</var>, <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15844"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15845"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>result</var>, <var>iterated</var>).</li><li>Set <var>accumulator</var> to <var>result</var>.</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.some" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.10</span> Iterator.prototype.some ( <var>predicate</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15846"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15847"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15848"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>predicate</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15849"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>TypeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15850"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15851"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>counter</var> be 0.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15852"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-val>false</emu-val>.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15853"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15854"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>predicate</var>, <emu-val>undefined</emu-val>, « <var>value</var>, <emu-xref aoid="𝔽" id="_ref_15855"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>counter</var>) »)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15856"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>result</var>, <var>iterated</var>).</li><li>If <emu-xref aoid="ToBoolean" id="_ref_15857"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>result</var>) is <emu-val>true</emu-val>, return ? <emu-xref aoid="IteratorClose" id="_ref_15858"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <emu-xref aoid="NormalCompletion" id="_ref_15859"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>true</emu-val>)).</li><li>Set <var>counter</var> to <var>counter</var> + 1.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.take" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.11</span> Iterator.prototype.take ( <var>limit</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15860"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15861"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>O</var>, <var class="field">[[NextMethod]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>Let <var>numLimit</var> be <emu-xref aoid="Completion" id="_ref_15862"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="ToNumber" id="_ref_15863"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>limit</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15864"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>numLimit</var>, <var>iterated</var>).</li><li>If <var>numLimit</var> is <emu-val>NaN</emu-val>, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15865"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>RangeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15866"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Let <var>integerLimit</var> be ! <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15867"><a href="abstract-operations.html#sec-tointegerorinfinity">ToIntegerOrInfinity</a></emu-xref>(<var>numLimit</var>).</li><li>If <var>integerLimit</var> < 0, then<ol><li>Let <var>error</var> be <emu-xref aoid="ThrowCompletion" id="_ref_15868"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(a newly created <emu-val>RangeError</emu-val> object).</li><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15869"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <var>error</var>).</li></ol></li><li>Set <var>iterated</var> to ? <emu-xref aoid="GetIteratorDirect" id="_ref_15870"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15871"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>iterated</var> and <var>integerLimit</var> and performs the following steps when called:<ol><li>Let <var>remaining</var> be <var>integerLimit</var>.</li><li>Repeat,<ol><li>If <var>remaining</var> = 0, then<ol><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15872"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iterated</var>, <emu-xref aoid="ReturnCompletion" id="_ref_15873"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>)).</li></ol></li><li>If <var>remaining</var> ≠ +∞, then<ol><li>Set <var>remaining</var> to <var>remaining</var> - 1.</li></ol></li><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15874"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="ReturnCompletion" id="_ref_15875"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_15876"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Yield" id="_ref_15877"><a href="control-abstraction-objects.html#sec-yield" class="e-user-code">Yield</a></emu-xref>(<var>value</var>)).</li><li><emu-xref aoid="IfAbruptCloseIterator" id="_ref_15878"><a href="abstract-operations.html#sec-ifabruptcloseiterator" class="e-user-code">IfAbruptCloseIterator</a></emu-xref>(<var>completion</var>, <var>iterated</var>).</li></ol></li></ol></li><li>Let <var>result</var> be <emu-xref aoid="CreateIteratorFromClosure" id="_ref_15879"><a href="control-abstraction-objects.html#sec-createiteratorfromclosure">CreateIteratorFromClosure</a></emu-xref>(<var>closure</var>, <emu-val>"Iterator Helper"</emu-val>, <emu-xref href="#sec-%iteratorhelperprototype%-object" id="_ref_15880"><a href="control-abstraction-objects.html#sec-%iteratorhelperprototype%-object">%IteratorHelperPrototype%</a></emu-xref>, « <var class="field">[[UnderlyingIterators]]</var> »).</li><li>Set <var>result</var>.<var class="field">[[UnderlyingIterators]]</var> to « <var>iterated</var> ».</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype.toarray" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.12</span> Iterator.prototype.toArray ( )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>If <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15881"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>iterated</var> be ? <emu-xref aoid="GetIteratorDirect" id="_ref_15882"><a href="abstract-operations.html#sec-getiteratordirect" class="e-user-code">GetIteratorDirect</a></emu-xref>(<var>O</var>).</li><li>Let <var>items</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15883"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Repeat,<ol><li>Let <var>value</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_15884"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iterated</var>).</li><li>If <var>value</var> is <emu-const>done</emu-const>, return <emu-xref aoid="CreateArrayFromList" id="_ref_15885"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>items</var>).</li><li>Append <var>value</var> to <var>items</var>.</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-%iteratorprototype%-@@iterator,sec-%iteratorprototype%-%symbol.iterator%" id="sec-iterator.prototype-%symbol.iterator%" type="built-in function"><span id="sec-%iteratorprototype%-%symbol.iterator%"></span><span id="sec-%iteratorprototype%-@@iterator"></span>
|
||
<h1><span class="secnum">27.1.3.3.13</span> Iterator.prototype [ %Symbol.iterator% ] ( )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return the <emu-val>this</emu-val> value.</li></ol></emu-alg>
|
||
<p>The value of the <emu-val>"name"</emu-val> property of this function is <emu-val>"[Symbol.iterator]"</emu-val>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-iterator.prototype-%symbol.tostringtag%">
|
||
<h1><span class="secnum">27.1.3.3.14</span> Iterator.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p><code>Iterator.prototype[%Symbol.toStringTag%]</code> is an <emu-xref href="#sec-object-type" id="_ref_15886"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> with attributes { <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }. The <var class="field">[[Get]]</var> and <var class="field">[[Set]]</var> attributes are defined as follows:</p>
|
||
|
||
<emu-clause id="sec-get-iterator.prototype-%symbol.tostringtag%" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.14.1</span> get Iterator.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The value of the <var class="field">[[Get]]</var> attribute is a built-in function that requires no arguments. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return <emu-val>"Iterator"</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-set-iterator.prototype-%symbol.tostringtag%" type="built-in function">
|
||
<h1><span class="secnum">27.1.3.3.14.2</span> set Iterator.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The value of the <var class="field">[[Set]]</var> attribute is a built-in function that takes an argument <var>v</var>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="SetterThatIgnoresPrototypeProperties" id="_ref_15887"><a href="abstract-operations.html#sec-SetterThatIgnoresPrototypeProperties" class="e-user-code">SetterThatIgnoresPrototypeProperties</a></emu-xref>(<emu-val>this</emu-val> value, <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_15888"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">%Iterator.prototype%</a></emu-xref>, <emu-xref href="#sec-well-known-symbols" id="_ref_15889"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref>, <var>v</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Unlike the <emu-xref href="#sec-well-known-symbols" id="_ref_15890"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property on most built-in prototypes, for web-compatibility reasons this property must be an accessor.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asynciteratorprototype">
|
||
<h1><span class="secnum">27.1.4</span> The %AsyncIteratorPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%AsyncIteratorPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15891"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15892"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
</ul>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>All objects defined in this specification that implement the <emu-xref href="#sec-asynciterator-interface" id="_ref_15893"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator interface</a></emu-xref> 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 <emu-xref href="#sec-asynciterator-interface" id="_ref_15894"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator objects</a></emu-xref> may be added.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause oldids="sec-asynciteratorprototype-asynciterator" id="sec-%asynciteratorprototype%-%symbol.asynciterator%" type="built-in function"><span id="sec-asynciteratorprototype-asynciterator"></span>
|
||
<h1><span class="secnum">27.1.4.1</span> %AsyncIteratorPrototype% [ %Symbol.asyncIterator% ] ( )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return the <emu-val>this</emu-val> value.</li></ol></emu-alg>
|
||
<p>The value of the <emu-val>"name"</emu-val> property of this function is <emu-val>"[Symbol.asyncIterator]"</emu-val>.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-from-sync-iterator-objects">
|
||
<h1><span class="secnum">27.1.5</span> Async-from-Sync Iterator Objects</h1>
|
||
<p>An <dfn variants="Async-from-Sync Iterator objects" tabindex="-1">Async-from-Sync Iterator object</dfn> is an <emu-xref href="#sec-asynciterator-interface" id="_ref_15895"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator</a></emu-xref> that adapts a specific synchronous <emu-xref href="#sec-iterator-interface" id="_ref_15896"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref>. Async-from-Sync Iterator objects are never directly accessible to ECMAScript code. There is not a named <emu-xref href="#constructor" id="_ref_15897"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> for Async-from-Sync Iterator objects. Instead, Async-from-Sync Iterator objects are created by the <emu-xref aoid="CreateAsyncFromSyncIterator" id="_ref_15898"><a href="control-abstraction-objects.html#sec-createasyncfromsynciterator">CreateAsyncFromSyncIterator</a></emu-xref> abstract operation as needed.</p>
|
||
|
||
<emu-clause id="sec-createasyncfromsynciterator" type="abstract operation" aoid="CreateAsyncFromSyncIterator">
|
||
<h1><span class="secnum">27.1.5.1</span> CreateAsyncFromSyncIterator ( <var>syncIteratorRecord</var> )</h1>
|
||
<p>The abstract operation CreateAsyncFromSyncIterator takes argument <var>syncIteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_15899"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>) and returns an <emu-xref href="#sec-iterator-records" id="_ref_15900"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>. It is used to create an async <emu-xref href="#sec-iterator-records" id="_ref_15901"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> from a synchronous <emu-xref href="#sec-iterator-records" id="_ref_15902"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>asyncIterator</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_15903"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-%asyncfromsynciteratorprototype%-object" id="_ref_15904"><a href="control-abstraction-objects.html#sec-%asyncfromsynciteratorprototype%-object">%AsyncFromSyncIteratorPrototype%</a></emu-xref>, « <var class="field">[[SyncIteratorRecord]]</var> »).</li><li>Set <var>asyncIterator</var>.<var class="field">[[SyncIteratorRecord]]</var> to <var>syncIteratorRecord</var>.</li><li>Let <var>nextMethod</var> be ! <emu-xref aoid="Get" id="_ref_15905"><a href="abstract-operations.html#sec-get-o-p">Get</a></emu-xref>(<var>asyncIterator</var>, <emu-val>"next"</emu-val>).</li><li>Let <var>iteratorRecord</var> be the <emu-xref href="#sec-iterator-records" id="_ref_15906"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref> { <var class="field">[[Iterator]]</var>: <var>asyncIterator</var>, <var class="field">[[NextMethod]]</var>: <var>nextMethod</var>, <var class="field">[[Done]]</var>: <emu-val>false</emu-val> }.</li><li>Return <var>iteratorRecord</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%asyncfromsynciteratorprototype%-object">
|
||
<h1><span class="secnum">27.1.5.2</span> The %AsyncFromSyncIteratorPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%AsyncFromSyncIteratorPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>has properties that are inherited by all <emu-xref href="#sec-async-from-sync-iterator-objects" id="_ref_15907"><a href="control-abstraction-objects.html#sec-async-from-sync-iterator-objects">Async-from-Sync Iterator objects</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15908"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-asynciteratorprototype" id="_ref_15909"><a href="control-abstraction-objects.html#sec-asynciteratorprototype">%AsyncIteratorPrototype%</a></emu-xref>.</li>
|
||
<li>is never directly accessible to ECMAScript code.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-%asyncfromsynciteratorprototype%.next" type="built-in function">
|
||
<h1><span class="secnum">27.1.5.2.1</span> %AsyncFromSyncIteratorPrototype%.next ( [ <var>value</var> ] )</h1>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li><emu-xref href="#assert" id="_ref_15910"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15911"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref> that has a <var class="field">[[SyncIteratorRecord]]</var> internal slot.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_15912"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_15913"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>syncIteratorRecord</var> be <var>O</var>.<var class="field">[[SyncIteratorRecord]]</var>.</li><li>If <var>value</var> is present, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15914"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorNext" id="_ref_15915"><a href="abstract-operations.html#sec-iteratornext" class="e-user-code">IteratorNext</a></emu-xref>(<var>syncIteratorRecord</var>, <var>value</var>)).</li></ol></li><li>Else,<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15916"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorNext" id="_ref_15917"><a href="abstract-operations.html#sec-iteratornext" class="e-user-code">IteratorNext</a></emu-xref>(<var>syncIteratorRecord</var>)).</li></ol></li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15918"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>Return <emu-xref aoid="AsyncFromSyncIteratorContinuation" id="_ref_15919"><a href="control-abstraction-objects.html#sec-asyncfromsynciteratorcontinuation" class="e-user-code">AsyncFromSyncIteratorContinuation</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>, <var>syncIteratorRecord</var>, <emu-val>true</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%asyncfromsynciteratorprototype%.return" type="built-in function">
|
||
<h1><span class="secnum">27.1.5.2.2</span> %AsyncFromSyncIteratorPrototype%.return ( [ <var>value</var> ] )</h1>
|
||
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li><emu-xref href="#assert" id="_ref_15920"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15921"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref> that has a <var class="field">[[SyncIteratorRecord]]</var> internal slot.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_15922"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_15923"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>syncIteratorRecord</var> be <var>O</var>.<var class="field">[[SyncIteratorRecord]]</var>.</li><li>Let <var>syncIterator</var> be <var>syncIteratorRecord</var>.<var class="field">[[Iterator]]</var>.</li><li>Let <var>return</var> be <emu-xref aoid="Completion" id="_ref_15924"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetMethod" id="_ref_15925"><a href="abstract-operations.html#sec-getmethod" class="e-user-code">GetMethod</a></emu-xref>(<var>syncIterator</var>, <emu-val>"return"</emu-val>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15926"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>return</var>, <var>promiseCapability</var>).</li><li>If <var>return</var> is <emu-val>undefined</emu-val>, then<ol><li>Let <var>iteratorResult</var> be <emu-xref aoid="CreateIteratorResultObject" id="_ref_15927"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>value</var>, <emu-val>true</emu-val>).</li><li>Perform ! <emu-xref aoid="Call" id="_ref_15928"><a href="abstract-operations.html#sec-call" class="e-user-code e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>iteratorResult</var> »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>If <var>value</var> is present, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15929"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15930"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>return</var>, <var>syncIterator</var>, « <var>value</var> »)).</li></ol></li><li>Else,<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15931"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15932"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>return</var>, <var>syncIterator</var>)).</li></ol></li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15933"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>If <var>result</var> <emu-xref href="#sec-object-type" id="_ref_15934"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_15935"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « a newly created <emu-val>TypeError</emu-val> object »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Return <emu-xref aoid="AsyncFromSyncIteratorContinuation" id="_ref_15936"><a href="control-abstraction-objects.html#sec-asyncfromsynciteratorcontinuation" class="e-user-code">AsyncFromSyncIteratorContinuation</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>, <var>syncIteratorRecord</var>, <emu-val>false</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-%asyncfromsynciteratorprototype%.throw" type="built-in function">
|
||
<h1><span class="secnum">27.1.5.2.3</span> %AsyncFromSyncIteratorPrototype%.throw ( [ <var>value</var> ] )</h1>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">In this specification, <var>value</var> is always provided, but is left optional for consistency with <emu-xref title="" href="#sec-%asyncfromsynciteratorprototype%.return" id="_ref_823"><a href="control-abstraction-objects.html#sec-%asyncfromsynciteratorprototype%.return">%AsyncFromSyncIteratorPrototype%.return ( [ <var>value</var> ] )</a></emu-xref>.</div></emu-note>
|
||
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li><emu-xref href="#assert" id="_ref_15937"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> <emu-xref href="#sec-object-type" id="_ref_15938"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref> that has a <var class="field">[[SyncIteratorRecord]]</var> internal slot.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_15939"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_15940"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>syncIteratorRecord</var> be <var>O</var>.<var class="field">[[SyncIteratorRecord]]</var>.</li><li>Let <var>syncIterator</var> be <var>syncIteratorRecord</var>.<var class="field">[[Iterator]]</var>.</li><li>Let <var>throw</var> be <emu-xref aoid="Completion" id="_ref_15941"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetMethod" id="_ref_15942"><a href="abstract-operations.html#sec-getmethod" class="e-user-code">GetMethod</a></emu-xref>(<var>syncIterator</var>, <emu-val>"throw"</emu-val>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15943"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>throw</var>, <var>promiseCapability</var>).</li><li>If <var>throw</var> is <emu-val>undefined</emu-val>, then<ol><li>NOTE: If <var>syncIterator</var> does not have a <code>throw</code> method, close it to give it a chance to clean up before we reject the capability.</li><li>Let <var>closeCompletion</var> be <emu-xref aoid="NormalCompletion" id="_ref_15944"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-const>empty</emu-const>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15945"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_15946"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>syncIteratorRecord</var>, <var>closeCompletion</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15947"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>NOTE: The next step throws a <emu-val>TypeError</emu-val> to indicate that there was a protocol violation: <var>syncIterator</var> does not have a <code>throw</code> method.</li><li>NOTE: If closing <var>syncIterator</var> does not throw then the result of that operation is ignored, even if it yields a rejected promise.</li><li>Perform ! <emu-xref aoid="Call" id="_ref_15948"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « a newly created <emu-val>TypeError</emu-val> object »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>If <var>value</var> is present, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15949"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15950"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>throw</var>, <var>syncIterator</var>, « <var>value</var> »)).</li></ol></li><li>Else,<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_15951"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_15952"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>throw</var>, <var>syncIterator</var>)).</li></ol></li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15953"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>If <var>result</var> <emu-xref href="#sec-object-type" id="_ref_15954"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_15955"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « a newly created <emu-val>TypeError</emu-val> object »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Return <emu-xref aoid="AsyncFromSyncIteratorContinuation" id="_ref_15956"><a href="control-abstraction-objects.html#sec-asyncfromsynciteratorcontinuation" class="e-user-code">AsyncFromSyncIteratorContinuation</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>, <var>syncIteratorRecord</var>, <emu-val>true</emu-val>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-async-from-sync-iterator-instances">
|
||
<h1><span class="secnum">27.1.5.3</span> Properties of Async-from-Sync Iterator Instances</h1>
|
||
<p>Async-from-Sync <emu-xref href="#sec-iterator-interface" id="_ref_15957"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> instances are <emu-xref href="#ordinary-object" id="_ref_15958"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary objects</a></emu-xref> that inherit properties from the <emu-xref href="#sec-%asyncfromsynciteratorprototype%-object" id="_ref_15959"><a href="control-abstraction-objects.html#sec-%asyncfromsynciteratorprototype%-object">%AsyncFromSyncIteratorPrototype%</a></emu-xref> intrinsic object. Async-from-Sync <emu-xref href="#sec-iterator-interface" id="_ref_15960"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> instances are initially created with the internal slots listed in <emu-xref href="#table-async-from-sync-iterator-internal-slots" id="_ref_824"><a href="control-abstraction-objects.html#table-async-from-sync-iterator-internal-slots">Table 84</a></emu-xref>.</p>
|
||
<emu-table id="table-async-from-sync-iterator-internal-slots" caption="Internal Slots of Async-from-Sync Iterator Instances"><figure><figcaption>Table 84: Internal Slots of Async-from-Sync <emu-xref href="#sec-iterator-interface" id="_ref_15961"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> Instances</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Internal Slot
|
||
</th>
|
||
<th>
|
||
Type
|
||
</th>
|
||
<th>
|
||
Description
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[SyncIteratorRecord]]</var>
|
||
</td>
|
||
<td>
|
||
an <emu-xref href="#sec-iterator-records" id="_ref_15962"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
Represents the original synchronous <emu-xref href="#sec-iterator-interface" id="_ref_15963"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> which is being adapted.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncfromsynciteratorcontinuation" type="abstract operation" oldids="sec-async-from-sync-iterator-value-unwrap-functions" aoid="AsyncFromSyncIteratorContinuation"><span id="sec-async-from-sync-iterator-value-unwrap-functions"></span>
|
||
<h1><span class="secnum">27.1.5.4</span> AsyncFromSyncIteratorContinuation ( <var>result</var>, <var>promiseCapability</var>, <var>syncIteratorRecord</var>, <var>closeOnRejection</var> )</h1>
|
||
<p>The abstract operation AsyncFromSyncIteratorContinuation takes arguments <var>result</var> (an Object), <var>promiseCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_15964"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> for an intrinsic <emu-xref href="#sec-promise-constructor" id="_ref_15965"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>), <var>syncIteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_15966"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>), and <var>closeOnRejection</var> (a Boolean) and returns a Promise. It performs the following steps when called:</p>
|
||
|
||
<emu-alg><ol><li>NOTE: Because <var>promiseCapability</var> is derived from the intrinsic <emu-xref href="#sec-promise-constructor" id="_ref_15967"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>, the calls to <var>promiseCapability</var>.<var class="field">[[Reject]]</var> entailed by the use <emu-xref aoid="IfAbruptRejectPromise" id="_ref_15968"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise">IfAbruptRejectPromise</a></emu-xref> below are guaranteed not to throw.</li><li>Let <var>done</var> be <emu-xref aoid="Completion" id="_ref_15969"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorComplete" id="_ref_15970"><a href="abstract-operations.html#sec-iteratorcomplete" class="e-user-code">IteratorComplete</a></emu-xref>(<var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15971"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>done</var>, <var>promiseCapability</var>).</li><li>Let <var>value</var> be <emu-xref aoid="Completion" id="_ref_15972"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorValue" id="_ref_15973"><a href="abstract-operations.html#sec-iteratorvalue" class="e-user-code">IteratorValue</a></emu-xref>(<var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15974"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>value</var>, <var>promiseCapability</var>).</li><li>Let <var>valueWrapper</var> be <emu-xref aoid="Completion" id="_ref_15975"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PromiseResolve" id="_ref_15976"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_15977"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>, <var>value</var>)).</li><li>If <var>valueWrapper</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_15978"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, <var>done</var> is <emu-val>false</emu-val>, and <var>closeOnRejection</var> is <emu-val>true</emu-val>, then<ol><li>Set <var>valueWrapper</var> to <emu-xref aoid="Completion" id="_ref_15979"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_15980"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>syncIteratorRecord</var>, <var>valueWrapper</var>)).</li></ol></li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_15981"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>valueWrapper</var>, <var>promiseCapability</var>).</li><li>Let <var>unwrap</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15982"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>v</var>) that captures <var>done</var> and performs the following steps when called:<ol><li>Return <emu-xref aoid="CreateIteratorResultObject" id="_ref_15983"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>v</var>, <var>done</var>).</li></ol></li><li>Let <var>onFulfilled</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_15984"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>unwrap</var>, 1, <emu-val>""</emu-val>, « »).</li><li>NOTE: <var>onFulfilled</var> is used when processing the <emu-val>"value"</emu-val> property of an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15985"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> in order to wait for its value if it is a promise and re-package the result in a new "unwrapped" <emu-xref href="#sec-iteratorresult-interface" id="_ref_15986"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref>.</li><li>If <var>done</var> is <emu-val>true</emu-val>, or if <var>closeOnRejection</var> is <emu-val>false</emu-val>, then<ol><li>Let <var>onRejected</var> be <emu-val>undefined</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>closeIterator</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_15987"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>error</var>) that captures <var>syncIteratorRecord</var> and performs the following steps when called:<ol><li>Return ? <emu-xref aoid="IteratorClose" id="_ref_15988"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>syncIteratorRecord</var>, <emu-xref aoid="ThrowCompletion" id="_ref_15989"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>error</var>)).</li></ol></li><li>Let <var>onRejected</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_15990"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>closeIterator</var>, 1, <emu-val>""</emu-val>, « »).</li><li>NOTE: <var>onRejected</var> is used to close the <emu-xref href="#sec-iterator-interface" id="_ref_15991"><a href="control-abstraction-objects.html#sec-iterator-interface">Iterator</a></emu-xref> when the <emu-val>"value"</emu-val> property of an <emu-xref href="#sec-iteratorresult-interface" id="_ref_15992"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref> it yields is a rejected promise.</li></ol></li><li>Perform <emu-xref aoid="PerformPromiseThen" id="_ref_15993"><a href="control-abstraction-objects.html#sec-performpromisethen">PerformPromiseThen</a></emu-xref>(<var>valueWrapper</var>, <var>onFulfilled</var>, <var>onRejected</var>, <var>promiseCapability</var>).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise-objects">
|
||
<h1><span class="secnum">27.2</span> Promise Objects</h1>
|
||
<p>A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous) computation.</p>
|
||
<p>Any Promise is in one of three mutually exclusive states: <em>fulfilled</em>, <em>rejected</em>, and <em>pending</em>:</p>
|
||
<ul>
|
||
<li>
|
||
A promise <code>p</code> is fulfilled if <code>p.then(f, r)</code> will immediately enqueue a <emu-xref href="#job" id="_ref_15994"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> to call the function <code>f</code>.
|
||
</li>
|
||
<li>
|
||
A promise <code>p</code> is rejected if <code>p.then(f, r)</code> will immediately enqueue a <emu-xref href="#job" id="_ref_15995"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> to call the function <code>r</code>.
|
||
</li>
|
||
<li>
|
||
A promise is pending if it is neither fulfilled nor rejected.
|
||
</li>
|
||
</ul>
|
||
<p>A promise is said to be <em>settled</em> if it is not pending, i.e. if it is either fulfilled or rejected.</p>
|
||
<p>A promise is <em>resolved</em> 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 <em>unresolved</em> if it is not resolved. An unresolved promise is always in the pending state. A resolved promise may be pending, fulfilled or rejected.</p>
|
||
|
||
<emu-clause id="sec-promise-abstract-operations">
|
||
<h1><span class="secnum">27.2.1</span> Promise Abstract Operations</h1>
|
||
|
||
<emu-clause id="sec-promisecapability-records">
|
||
<h1><span class="secnum">27.2.1.1</span> PromiseCapability Records</h1>
|
||
<p>A <dfn variants="PromiseCapability Records" tabindex="-1">PromiseCapability Record</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15996"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> value used to encapsulate a Promise or promise-like object along with the functions that are capable of resolving or rejecting that promise. PromiseCapability Records are produced by the <emu-xref aoid="NewPromiseCapability" id="_ref_15997"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref> abstract operation.</p>
|
||
<p>PromiseCapability Records have the fields listed in <emu-xref href="#table-promisecapability-record-fields" id="_ref_825"><a href="control-abstraction-objects.html#table-promisecapability-record-fields">Table 85</a></emu-xref>.</p>
|
||
<emu-table id="table-promisecapability-record-fields" caption="PromiseCapability Record Fields" oldids="table-57"><figure><figcaption>Table 85: <emu-xref href="#sec-promisecapability-records" id="_ref_15998"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> Fields</figcaption><span id="table-57"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Field Name
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Meaning
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[Promise]]</var>
|
||
</td>
|
||
<td>
|
||
an Object
|
||
</td>
|
||
<td>
|
||
An object that is usable as a promise.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[Resolve]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#function-object" id="_ref_15999"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The function that is used to resolve the given promise.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[Reject]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#function-object" id="_ref_16000"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The function that is used to reject the given promise.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
|
||
<emu-clause id="sec-ifabruptrejectpromise" aoid="IfAbruptRejectPromise">
|
||
<h1><span class="secnum">27.2.1.1.1</span> IfAbruptRejectPromise ( <var>value</var>, <var>capability</var> )</h1>
|
||
<p>IfAbruptRejectPromise is a shorthand for a sequence of algorithm steps that use a <emu-xref href="#sec-promisecapability-records" id="_ref_16001"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>. An algorithm step of the form:</p>
|
||
<emu-alg><ol><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16002"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>value</var>, <var>capability</var>).</li></ol></emu-alg>
|
||
<p>means the same thing as:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16003"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>value</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16004"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref>.</li><li>If <var>value</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16005"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Perform ? <emu-xref aoid="Call" id="_ref_16006"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>capability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>value</var>.<var class="field">[[Value]]</var> »).</li><li>Return <var>capability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Set <var>value</var> to ! <var>value</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promisereaction-records">
|
||
<h1><span class="secnum">27.2.1.2</span> PromiseReaction Records</h1>
|
||
<p>A <dfn variants="PromiseReaction Records" tabindex="-1">PromiseReaction Record</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16007"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> 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 <emu-xref aoid="PerformPromiseThen" id="_ref_16008"><a href="control-abstraction-objects.html#sec-performpromisethen">PerformPromiseThen</a></emu-xref> abstract operation, and are used by the <emu-xref href="#sec-abstract-closure" id="_ref_16009"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> returned by <emu-xref aoid="NewPromiseReactionJob" id="_ref_16010"><a href="control-abstraction-objects.html#sec-newpromisereactionjob">NewPromiseReactionJob</a></emu-xref>.</p>
|
||
<p>PromiseReaction Records have the fields listed in <emu-xref href="#table-promisereaction-record-fields" id="_ref_826"><a href="control-abstraction-objects.html#table-promisereaction-record-fields">Table 86</a></emu-xref>.</p>
|
||
<emu-table id="table-promisereaction-record-fields" caption="PromiseReaction Record Fields" oldids="table-58"><figure><figcaption>Table 86: <emu-xref href="#sec-promisereaction-records" id="_ref_16011"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Record</a></emu-xref> Fields</figcaption><span id="table-58"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Field Name
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Meaning
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[Capability]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-promisecapability-records" id="_ref_16012"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> or <emu-val>undefined</emu-val>
|
||
</td>
|
||
<td>
|
||
The capabilities of the promise for which this record provides a reaction handler.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[Type]]</var>
|
||
</td>
|
||
<td>
|
||
<emu-const>fulfill</emu-const> or <emu-const>reject</emu-const>
|
||
</td>
|
||
<td>
|
||
The <var class="field">[[Type]]</var> is used when <var class="field">[[Handler]]</var> is <emu-const>empty</emu-const> to allow for behaviour specific to the settlement type.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[Handler]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-jobcallback-records" id="_ref_16013"><a href="executable-code-and-execution-contexts.html#sec-jobcallback-records">JobCallback Record</a></emu-xref> or <emu-const>empty</emu-const>
|
||
</td>
|
||
<td>
|
||
The function that should be applied to the incoming value, and whose return value will govern what happens to the derived promise. If <var class="field">[[Handler]]</var> is <emu-const>empty</emu-const>, a function that depends on the value of <var class="field">[[Type]]</var> will be used instead.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-createresolvingfunctions" oldids="sec-promise-reject-functions,sec-promise-resolve-functions" type="abstract operation" aoid="CreateResolvingFunctions"><span id="sec-promise-resolve-functions"></span><span id="sec-promise-reject-functions"></span>
|
||
<h1><span class="secnum">27.2.1.3</span> CreateResolvingFunctions ( <var>toResolve</var> )</h1>
|
||
<p>The abstract operation CreateResolvingFunctions takes argument <var>toResolve</var> (a Promise) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16014"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> with fields <var class="field">[[Resolve]]</var> (a <emu-xref href="#function-object" id="_ref_16015"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and <var class="field">[[Reject]]</var> (a <emu-xref href="#function-object" id="_ref_16016"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>). It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>promiseOrEmpty</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16017"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Value]]</var>: <var>toResolve</var> }.</li><li>Let <var>resolveSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16018"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>resolution</var>) that captures <var>promiseOrEmpty</var> and performs the following steps when called:<ol><li>If <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var> is <emu-const>empty</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>promise</var> be <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var>.</li><li>Set <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var> to <emu-const>empty</emu-const>.</li><li>If <emu-xref aoid="SameValue" id="_ref_16019"><a href="abstract-operations.html#sec-samevalue">SameValue</a></emu-xref>(<var>resolution</var>, <var>promise</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>selfResolutionError</var> be a newly created <emu-val>TypeError</emu-val> object.</li><li>Perform <emu-xref aoid="RejectPromise" id="_ref_16020"><a href="control-abstraction-objects.html#sec-rejectpromise">RejectPromise</a></emu-xref>(<var>promise</var>, <var>selfResolutionError</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>If <var>resolution</var> <emu-xref href="#sec-object-type" id="_ref_16021"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, then<ol><li>Perform <emu-xref aoid="FulfillPromise" id="_ref_16022"><a href="control-abstraction-objects.html#sec-fulfillpromise">FulfillPromise</a></emu-xref>(<var>promise</var>, <var>resolution</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>then</var> be <emu-xref aoid="Completion" id="_ref_16023"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Get" id="_ref_16024"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>resolution</var>, <emu-val>"then"</emu-val>)).</li><li>If <var>then</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16025"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Perform <emu-xref aoid="RejectPromise" id="_ref_16026"><a href="control-abstraction-objects.html#sec-rejectpromise">RejectPromise</a></emu-xref>(<var>promise</var>, <var>then</var>.<var class="field">[[Value]]</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>thenAction</var> be <var>then</var>.<var class="field">[[Value]]</var>.</li><li>If <emu-xref aoid="IsCallable" id="_ref_16027"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>thenAction</var>) is <emu-val>false</emu-val>, then<ol><li>Perform <emu-xref aoid="FulfillPromise" id="_ref_16028"><a href="control-abstraction-objects.html#sec-fulfillpromise">FulfillPromise</a></emu-xref>(<var>promise</var>, <var>resolution</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>thenJobCallback</var> be <emu-xref aoid="HostMakeJobCallback" id="_ref_16029"><a href="executable-code-and-execution-contexts.html#sec-hostmakejobcallback">HostMakeJobCallback</a></emu-xref>(<var>thenAction</var>).</li><li>Let <var>job</var> be <emu-xref aoid="NewPromiseResolveThenableJob" id="_ref_16030"><a href="control-abstraction-objects.html#sec-newpromiseresolvethenablejob">NewPromiseResolveThenableJob</a></emu-xref>(<var>promise</var>, <var>resolution</var>, <var>thenJobCallback</var>).</li><li>Perform <emu-xref aoid="HostEnqueuePromiseJob" id="_ref_16031"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</a></emu-xref>(<var>job</var>.<var class="field">[[Job]]</var>, <var>job</var>.<var class="field">[[Realm]]</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>resolve</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16032"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>resolveSteps</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Let <var>rejectSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16033"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>reason</var>) that captures <var>promiseOrEmpty</var> and performs the following steps when called:<ol><li>If <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var> is <emu-const>empty</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>promise</var> be <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var>.</li><li>Set <var>promiseOrEmpty</var>.<var class="field">[[Value]]</var> to <emu-const>empty</emu-const>.</li><li>Perform <emu-xref aoid="RejectPromise" id="_ref_16034"><a href="control-abstraction-objects.html#sec-rejectpromise">RejectPromise</a></emu-xref>(<var>promise</var>, <var>reason</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>reject</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16035"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>rejectSteps</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Return the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16036"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Resolve]]</var>: <var>resolve</var>, <var class="field">[[Reject]]</var>: <var>reject</var> }.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-fulfillpromise" type="abstract operation" aoid="FulfillPromise">
|
||
<h1><span class="secnum">27.2.1.4</span> FulfillPromise ( <var>promise</var>, <var>value</var> )</h1>
|
||
<p>The abstract operation FulfillPromise takes arguments <var>promise</var> (a Promise) and <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16037"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16038"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>promise</var>.<var class="field">[[PromiseState]]</var> is <emu-const>pending</emu-const>.</li><li>Let <var>reactions</var> be <var>promise</var>.<var class="field">[[PromiseFulfillReactions]]</var>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseResult]]</var> to <var>value</var>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseFulfillReactions]]</var> to <emu-val>undefined</emu-val>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseRejectReactions]]</var> to <emu-val>undefined</emu-val>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseState]]</var> to <emu-const>fulfilled</emu-const>.</li><li>Perform <emu-xref aoid="TriggerPromiseReactions" id="_ref_16039"><a href="control-abstraction-objects.html#sec-triggerpromisereactions">TriggerPromiseReactions</a></emu-xref>(<var>reactions</var>, <var>value</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-newpromisecapability" type="abstract operation" oldids="sec-getcapabilitiesexecutor-functions" aoid="NewPromiseCapability"><span id="sec-getcapabilitiesexecutor-functions"></span>
|
||
<h1><span class="secnum">27.2.1.5</span> NewPromiseCapability ( <var>C</var> )</h1>
|
||
<p>The abstract operation NewPromiseCapability takes argument <var>C</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16040"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16041"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a <emu-xref href="#sec-promisecapability-records" id="_ref_16042"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16043"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It attempts to use <var>C</var> as a <emu-xref href="#constructor" id="_ref_16044"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> in the fashion of the built-in Promise <emu-xref href="#constructor" id="_ref_16045"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create a promise and extract its <code>resolve</code> and <code>reject</code> functions. The promise plus the <code>resolve</code> and <code>reject</code> functions are used to initialize a new <emu-xref href="#sec-promisecapability-records" id="_ref_16046"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <emu-xref aoid="IsConstructor" id="_ref_16047"><a href="abstract-operations.html#sec-isconstructor">IsConstructor</a></emu-xref>(<var>C</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>NOTE: <var>C</var> is assumed to be a <emu-xref href="#constructor" id="_ref_16048"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16049"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> (see <emu-xref href="#sec-promise-executor" id="_ref_827"><a href="control-abstraction-objects.html#sec-promise-executor">27.2.3.1</a></emu-xref>).</li><li>Let <var>resolvingFunctions</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16050"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Resolve]]</var>: <emu-val>undefined</emu-val>, <var class="field">[[Reject]]</var>: <emu-val>undefined</emu-val> }.</li><li>Let <var>executorClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16051"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>resolve</var>, <var>reject</var>) that captures <var>resolvingFunctions</var> and performs the following steps when called:<ol><li>If <var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var> is not <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>resolvingFunctions</var>.<var class="field">[[Reject]]</var> is not <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Set <var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var> to <var>resolve</var>.</li><li>Set <var>resolvingFunctions</var>.<var class="field">[[Reject]]</var> to <var>reject</var>.</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16052"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>executor</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16053"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>executorClosure</var>, 2, <emu-val>""</emu-val>, « »).</li><li>Let <var>promise</var> be ? <emu-xref aoid="Construct" id="_ref_16054"><a href="abstract-operations.html#sec-construct" class="e-user-code">Construct</a></emu-xref>(<var>C</var>, « <var>executor</var> »).</li><li>If <emu-xref aoid="IsCallable" id="_ref_16055"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsCallable" id="_ref_16056"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>resolvingFunctions</var>.<var class="field">[[Reject]]</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return the <emu-xref href="#sec-promisecapability-records" id="_ref_16057"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> { <var class="field">[[Promise]]</var>: <var>promise</var>, <var class="field">[[Resolve]]</var>: <var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var>, <var class="field">[[Reject]]</var>: <var>resolvingFunctions</var>.<var class="field">[[Reject]]</var> }.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This abstract operation supports Promise subclassing, as it is generic on any <emu-xref href="#constructor" id="_ref_16058"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> that calls a passed executor function argument in the same way as the Promise <emu-xref href="#constructor" id="_ref_16059"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>. It is used to generalize static methods of the Promise <emu-xref href="#constructor" id="_ref_16060"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to any subclass.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-ispromise" type="abstract operation" aoid="IsPromise">
|
||
<h1><span class="secnum">27.2.1.6</span> IsPromise ( <var>x</var> )</h1>
|
||
<p>The abstract operation IsPromise takes argument <var>x</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16061"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns a Boolean. It checks for the promise brand on an object. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>x</var> <emu-xref href="#sec-object-type" id="_ref_16062"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, return <emu-val>false</emu-val>.</li><li>If <var>x</var> does not have a <var class="field">[[PromiseState]]</var> internal slot, return <emu-val>false</emu-val>.</li><li>Return <emu-val>true</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-rejectpromise" type="abstract operation" aoid="RejectPromise">
|
||
<h1><span class="secnum">27.2.1.7</span> RejectPromise ( <var>promise</var>, <var>reason</var> )</h1>
|
||
<p>The abstract operation RejectPromise takes arguments <var>promise</var> (a Promise) and <var>reason</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16063"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16064"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>promise</var>.<var class="field">[[PromiseState]]</var> is <emu-const>pending</emu-const>.</li><li>Let <var>reactions</var> be <var>promise</var>.<var class="field">[[PromiseRejectReactions]]</var>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseResult]]</var> to <var>reason</var>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseFulfillReactions]]</var> to <emu-val>undefined</emu-val>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseRejectReactions]]</var> to <emu-val>undefined</emu-val>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseState]]</var> to <emu-const>rejected</emu-const>.</li><li>If <var>promise</var>.<var class="field">[[PromiseIsHandled]]</var> is <emu-val>false</emu-val>, perform <emu-xref aoid="HostPromiseRejectionTracker" id="_ref_16065"><a href="control-abstraction-objects.html#sec-host-promise-rejection-tracker">HostPromiseRejectionTracker</a></emu-xref>(<var>promise</var>, <emu-val>"reject"</emu-val>).</li><li>Perform <emu-xref aoid="TriggerPromiseReactions" id="_ref_16066"><a href="control-abstraction-objects.html#sec-triggerpromisereactions">TriggerPromiseReactions</a></emu-xref>(<var>reactions</var>, <var>reason</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-triggerpromisereactions" type="abstract operation" aoid="TriggerPromiseReactions">
|
||
<h1><span class="secnum">27.2.1.8</span> TriggerPromiseReactions ( <var>reactions</var>, <var>argument</var> )</h1>
|
||
<p>The abstract operation TriggerPromiseReactions takes arguments <var>reactions</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16067"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-promisereaction-records" id="_ref_16068"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Records</a></emu-xref>) and <var>argument</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16069"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns <emu-const>unused</emu-const>. It enqueues a new <emu-xref href="#job" id="_ref_16070"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> for each record in <var>reactions</var>. Each such <emu-xref href="#job" id="_ref_16071"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> processes the <var class="field">[[Type]]</var> and <var class="field">[[Handler]]</var> of the <emu-xref href="#sec-promisereaction-records" id="_ref_16072"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Record</a></emu-xref>, and if the <var class="field">[[Handler]]</var> is not <emu-const>empty</emu-const>, calls it passing the given argument. If the <var class="field">[[Handler]]</var> is <emu-const>empty</emu-const>, the behaviour is determined by the <var class="field">[[Type]]</var>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>For each element <var>reaction</var> of <var>reactions</var>, do<ol><li>Let <var>job</var> be <emu-xref aoid="NewPromiseReactionJob" id="_ref_16073"><a href="control-abstraction-objects.html#sec-newpromisereactionjob">NewPromiseReactionJob</a></emu-xref>(<var>reaction</var>, <var>argument</var>).</li><li>Perform <emu-xref aoid="HostEnqueuePromiseJob" id="_ref_16074"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</a></emu-xref>(<var>job</var>.<var class="field">[[Job]]</var>, <var>job</var>.<var class="field">[[Realm]]</var>).</li></ol></li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-host-promise-rejection-tracker" type="host-defined abstract operation" aoid="HostPromiseRejectionTracker">
|
||
<h1><span class="secnum">27.2.1.9</span> HostPromiseRejectionTracker ( <var>promise</var>, <var>operation</var> )</h1>
|
||
<p>The <emu-xref href="#host-defined" id="_ref_16075"><a href="overview.html#host-defined">host-defined</a></emu-xref> abstract operation HostPromiseRejectionTracker takes arguments <var>promise</var> (a Promise) and <var>operation</var> (<emu-val>"reject"</emu-val> or <emu-val>"handle"</emu-val>) and returns <emu-const>unused</emu-const>. It allows <emu-xref href="#host-environment" id="_ref_16076"><a href="overview.html#host-environment">host environments</a></emu-xref> to track promise rejections.</p>
|
||
<p>The default implementation of HostPromiseRejectionTracker is to return <emu-const>unused</emu-const>.</p>
|
||
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>HostPromiseRejectionTracker is called in two scenarios:</p>
|
||
|
||
<ul>
|
||
<li>When a promise is rejected without any handlers, it is called with its <var>operation</var> argument set to <emu-val>"reject"</emu-val>.</li>
|
||
<li>When a handler is added to a rejected promise for the first time, it is called with its <var>operation</var> argument set to <emu-val>"handle"</emu-val>.</li>
|
||
</ul>
|
||
|
||
<p>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.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>If <var>operation</var> is <emu-val>"handle"</emu-val>, an implementation should not hold a reference to <var>promise</var> in a way that would interfere with garbage collection. An implementation may hold a reference to <var>promise</var> if <var>operation</var> is <emu-val>"reject"</emu-val>, since it is expected that rejections will be rare and not on hot code paths.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise-jobs">
|
||
<h1><span class="secnum">27.2.2</span> Promise Jobs</h1>
|
||
|
||
<emu-clause id="sec-newpromisereactionjob" type="abstract operation" oldids="sec-promisereactionjob" aoid="NewPromiseReactionJob"><span id="sec-promisereactionjob"></span>
|
||
<h1><span class="secnum">27.2.2.1</span> NewPromiseReactionJob ( <var>reaction</var>, <var>argument</var> )</h1>
|
||
<p>The abstract operation NewPromiseReactionJob takes arguments <var>reaction</var> (a <emu-xref href="#sec-promisereaction-records" id="_ref_16077"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Record</a></emu-xref>) and <var>argument</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16078"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16079"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> with fields <var class="field">[[Job]]</var> (a <emu-xref href="#job" id="_ref_16080"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_16081"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref>) and <var class="field">[[Realm]]</var> (a <emu-xref href="#realm-record" id="_ref_16082"><a href="executable-code-and-execution-contexts.html#realm-record">Realm Record</a></emu-xref> or <emu-val>null</emu-val>). It returns a new <emu-xref href="#job" id="_ref_16083"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_16084"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> 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:</p>
|
||
<emu-alg><ol><li>Let <var>job</var> be a new <emu-xref href="#job" id="_ref_16085"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_16086"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>reaction</var> and <var>argument</var> and performs the following steps when called:<ol><li>Let <var>promiseCapability</var> be <var>reaction</var>.<var class="field">[[Capability]]</var>.</li><li>Let <var>type</var> be <var>reaction</var>.<var class="field">[[Type]]</var>.</li><li>Let <var>handler</var> be <var>reaction</var>.<var class="field">[[Handler]]</var>.</li><li>If <var>handler</var> is <emu-const>empty</emu-const>, then<ol><li>If <var>type</var> is <emu-const>fulfill</emu-const>, then<ol><li>Let <var>handlerResult</var> be <emu-xref aoid="NormalCompletion" id="_ref_16087"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>argument</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16088"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>type</var> is <emu-const>reject</emu-const>.</li><li>Let <var>handlerResult</var> be <emu-xref aoid="ThrowCompletion" id="_ref_16089"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>argument</var>).</li></ol></li></ol></li><li>Else,<ol><li>Let <var>handlerResult</var> be <emu-xref aoid="Completion" id="_ref_16090"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="HostCallJobCallback" id="_ref_16091"><a href="executable-code-and-execution-contexts.html#sec-hostcalljobcallback" class="e-user-code">HostCallJobCallback</a></emu-xref>(<var>handler</var>, <emu-val>undefined</emu-val>, « <var>argument</var> »)).</li></ol></li><li>If <var>promiseCapability</var> is <emu-val>undefined</emu-val>, then<ol><li><emu-xref href="#assert" id="_ref_16092"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>handlerResult</var> is not an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16093"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>.</li><li>Return <emu-const>empty</emu-const>.</li></ol></li><li><emu-xref href="#assert" id="_ref_16094"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>promiseCapability</var> is a <emu-xref href="#sec-promisecapability-records" id="_ref_16095"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>.</li><li>If <var>handlerResult</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16096"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Return ? <emu-xref aoid="Call" id="_ref_16097"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>handlerResult</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Return ? <emu-xref aoid="Call" id="_ref_16098"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>handlerResult</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Let <var>handlerRealm</var> be <emu-val>null</emu-val>.</li><li>If <var>reaction</var>.<var class="field">[[Handler]]</var> is not <emu-const>empty</emu-const>, then<ol><li>Let <var>getHandlerRealmResult</var> be <emu-xref aoid="Completion" id="_ref_16099"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetFunctionRealm" id="_ref_16100"><a href="abstract-operations.html#sec-getfunctionrealm">GetFunctionRealm</a></emu-xref>(<var>reaction</var>.<var class="field">[[Handler]]</var>.<var class="field">[[Callback]]</var>)).</li><li>If <var>getHandlerRealmResult</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16101"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, set <var>handlerRealm</var> to <var>getHandlerRealmResult</var>.<var class="field">[[Value]]</var>.</li><li>Else, set <var>handlerRealm</var> to <emu-xref href="#current-realm" id="_ref_16102"><a href="executable-code-and-execution-contexts.html#current-realm">the current Realm Record</a></emu-xref>.</li><li>NOTE: <var>handlerRealm</var> is never <emu-val>null</emu-val> unless the handler is <emu-val>undefined</emu-val>. When the handler is a revoked Proxy and no ECMAScript code runs, <var>handlerRealm</var> is used to create error objects.</li></ol></li><li>Return the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16103"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Job]]</var>: <var>job</var>, <var class="field">[[Realm]]</var>: <var>handlerRealm</var> }.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-newpromiseresolvethenablejob" type="abstract operation" oldids="sec-promiseresolvethenablejob" aoid="NewPromiseResolveThenableJob"><span id="sec-promiseresolvethenablejob"></span>
|
||
<h1><span class="secnum">27.2.2.2</span> NewPromiseResolveThenableJob ( <var>promiseToResolve</var>, <var>thenable</var>, <var>then</var> )</h1>
|
||
<p>The abstract operation NewPromiseResolveThenableJob takes arguments <var>promiseToResolve</var> (a Promise), <var>thenable</var> (an Object), and <var>then</var> (a <emu-xref href="#sec-jobcallback-records" id="_ref_16104"><a href="executable-code-and-execution-contexts.html#sec-jobcallback-records">JobCallback Record</a></emu-xref>) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16105"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> with fields <var class="field">[[Job]]</var> (a <emu-xref href="#job" id="_ref_16106"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_16107"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref>) and <var class="field">[[Realm]]</var> (a <emu-xref href="#realm-record" id="_ref_16108"><a href="executable-code-and-execution-contexts.html#realm-record">Realm Record</a></emu-xref>). It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>job</var> be a new <emu-xref href="#job" id="_ref_16109"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_16110"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>promiseToResolve</var>, <var>thenable</var>, and <var>then</var> and performs the following steps when called:<ol><li>Let <var>resolvingFunctions</var> be <emu-xref aoid="CreateResolvingFunctions" id="_ref_16111"><a href="control-abstraction-objects.html#sec-createresolvingfunctions">CreateResolvingFunctions</a></emu-xref>(<var>promiseToResolve</var>).</li><li>Let <var>thenCallResult</var> be <emu-xref aoid="Completion" id="_ref_16112"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="HostCallJobCallback" id="_ref_16113"><a href="executable-code-and-execution-contexts.html#sec-hostcalljobcallback" class="e-user-code">HostCallJobCallback</a></emu-xref>(<var>then</var>, <var>thenable</var>, « <var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var>, <var>resolvingFunctions</var>.<var class="field">[[Reject]]</var> »)).</li><li>If <var>thenCallResult</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16114"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Return ? <emu-xref aoid="Call" id="_ref_16115"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resolvingFunctions</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>thenCallResult</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Return ! <var>thenCallResult</var>.</li></ol></li><li>Let <var>getThenRealmResult</var> be <emu-xref aoid="Completion" id="_ref_16116"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetFunctionRealm" id="_ref_16117"><a href="abstract-operations.html#sec-getfunctionrealm">GetFunctionRealm</a></emu-xref>(<var>then</var>.<var class="field">[[Callback]]</var>)).</li><li>If <var>getThenRealmResult</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16118"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, let <var>thenRealm</var> be <var>getThenRealmResult</var>.<var class="field">[[Value]]</var>.</li><li>Else, let <var>thenRealm</var> be <emu-xref href="#current-realm" id="_ref_16119"><a href="executable-code-and-execution-contexts.html#current-realm">the current Realm Record</a></emu-xref>.</li><li>NOTE: <var>thenRealm</var> is never <emu-val>null</emu-val>. When <var>then</var>.<var class="field">[[Callback]]</var> is a revoked Proxy and no code runs, <var>thenRealm</var> is used to create error objects.</li><li>Return the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16120"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Job]]</var>: <var>job</var>, <var class="field">[[Realm]]</var>: <var>thenRealm</var> }.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This <emu-xref href="#job" id="_ref_16121"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> uses the supplied thenable and its <code>then</code> method to resolve the given promise. This process must take place as a <emu-xref href="#job" id="_ref_16122"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> to ensure that the evaluation of the <code>then</code> method occurs after evaluation of any surrounding code has completed.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise-constructor">
|
||
<h1><span class="secnum">27.2.3</span> The Promise Constructor</h1>
|
||
<p>The Promise <emu-xref href="#constructor" id="_ref_16123"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%Promise%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"Promise"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_16124"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>creates and initializes a new Promise when called as a <emu-xref href="#constructor" id="_ref_16125"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</li>
|
||
<li>is not intended to be called as a function and will throw an exception when called in that manner.</li>
|
||
<li>may be used as the value in an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_16126"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified Promise behaviour must include a <code>super</code> call to the Promise <emu-xref href="#constructor" id="_ref_16127"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize the subclass instance with the internal state necessary to support the <code>Promise</code> and <code>Promise.prototype</code> built-in methods.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-promise-executor" type="built-in function">
|
||
<h1><span class="secnum">27.2.3.1</span> Promise ( <var>executor</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If NewTarget is <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsCallable" id="_ref_16128"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>executor</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>promise</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_16129"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(NewTarget, <emu-val>"%Promise.prototype%"</emu-val>, « <var class="field">[[PromiseState]]</var>, <var class="field">[[PromiseResult]]</var>, <var class="field">[[PromiseFulfillReactions]]</var>, <var class="field">[[PromiseRejectReactions]]</var>, <var class="field">[[PromiseIsHandled]]</var> »).</li><li>Set <var>promise</var>.<var class="field">[[PromiseState]]</var> to <emu-const>pending</emu-const>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseResult]]</var> to <emu-const>empty</emu-const>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseFulfillReactions]]</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16130"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseRejectReactions]]</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16131"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Set <var>promise</var>.<var class="field">[[PromiseIsHandled]]</var> to <emu-val>false</emu-val>.</li><li>Let <var>resolvingFunctions</var> be <emu-xref aoid="CreateResolvingFunctions" id="_ref_16132"><a href="control-abstraction-objects.html#sec-createresolvingfunctions">CreateResolvingFunctions</a></emu-xref>(<var>promise</var>).</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_16133"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_16134"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>executor</var>, <emu-val>undefined</emu-val>, « <var>resolvingFunctions</var>.<var class="field">[[Resolve]]</var>, <var>resolvingFunctions</var>.<var class="field">[[Reject]]</var> »)).</li><li>If <var>completion</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16135"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Perform ? <emu-xref aoid="Call" id="_ref_16136"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resolvingFunctions</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>completion</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Return <var>promise</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>The <var>executor</var> argument must be a <emu-xref href="#function-object" id="_ref_16137"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>. It is called for initiating and reporting completion of the possibly deferred action represented by this Promise. The executor is called with two arguments: <var>resolve</var> and <var>reject</var>. These are functions that may be used by the <var>executor</var> 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.</p>
|
||
<p>The <var>resolve</var> function that is passed to an <var>executor</var> function accepts a single argument. The <var>executor</var> code may eventually call the <var>resolve</var> function to indicate that it wishes to resolve the associated Promise. The argument passed to the <var>resolve</var> 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.</p>
|
||
<p>The <var>reject</var> function that is passed to an <var>executor</var> function accepts a single argument. The <var>executor</var> code may eventually call the <var>reject</var> function to indicate that the associated Promise is rejected and will never be fulfilled. The argument passed to the <var>reject</var> function is used as the rejection value of the promise. Typically it will be an Error object.</p>
|
||
<p>The resolve and reject functions passed to an <var>executor</var> function by the Promise <emu-xref href="#constructor" id="_ref_16138"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> have the capability to actually resolve and reject the associated promise. Subclasses may have different <emu-xref href="#constructor" id="_ref_16139"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> behaviour that passes in customized values for resolve and reject.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-promise-constructor">
|
||
<h1><span class="secnum">27.2.4</span> Properties of the Promise Constructor</h1>
|
||
<p>The Promise <emu-xref href="#constructor" id="_ref_16140"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_16141"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-promise.all" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.1</span> Promise.all ( <var>iterable</var> )</h1>
|
||
<p>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 <emu-xref href="#sec-iterable-interface" id="_ref_16142"><a href="control-abstraction-objects.html#sec-iterable-interface">iterable</a></emu-xref> to promises as it runs this algorithm.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16143"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>promiseResolve</var> be <emu-xref aoid="Completion" id="_ref_16144"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetPromiseResolve" id="_ref_16145"><a href="control-abstraction-objects.html#sec-getpromiseresolve" class="e-user-code">GetPromiseResolve</a></emu-xref>(<var>C</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16146"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>promiseResolve</var>, <var>promiseCapability</var>).</li><li>Let <var>iteratorRecord</var> be <emu-xref aoid="Completion" id="_ref_16147"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetIterator" id="_ref_16148"><a href="abstract-operations.html#sec-getiterator" class="e-user-code">GetIterator</a></emu-xref>(<var>iterable</var>, <emu-const>sync</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16149"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>iteratorRecord</var>, <var>promiseCapability</var>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16150"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PerformPromiseAll" id="_ref_16151"><a href="control-abstraction-objects.html#sec-performpromiseall">PerformPromiseAll</a></emu-xref>(<var>iteratorRecord</var>, <var>C</var>, <var>promiseCapability</var>, <var>promiseResolve</var>)).</li><li>If <var>result</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16152"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>If <var>iteratorRecord</var>.<var class="field">[[Done]]</var> is <emu-val>false</emu-val>, set <var>result</var> to <emu-xref aoid="Completion" id="_ref_16153"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_16154"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iteratorRecord</var>, <var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16155"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li></ol></li><li>Return ! <var>result</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function requires its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16156"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16157"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-getpromiseresolve" type="abstract operation" aoid="GetPromiseResolve">
|
||
<h1><span class="secnum">27.2.4.1.1</span> GetPromiseResolve ( <var>promiseConstructor</var> )</h1>
|
||
<p>The abstract operation GetPromiseResolve takes argument <var>promiseConstructor</var> (a <emu-xref href="#constructor" id="_ref_16158"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16159"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a <emu-xref href="#function-object" id="_ref_16160"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16161"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>promiseResolve</var> be ? <emu-xref aoid="Get" id="_ref_16162"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>promiseConstructor</var>, <emu-val>"resolve"</emu-val>).</li><li>If <emu-xref aoid="IsCallable" id="_ref_16163"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>promiseResolve</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return <var>promiseResolve</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-performpromiseall" oldids="sec-promise.all-resolve-element-functions" type="abstract operation" aoid="PerformPromiseAll"><span id="sec-promise.all-resolve-element-functions"></span>
|
||
<h1><span class="secnum">27.2.4.1.2</span> PerformPromiseAll ( <var>iteratorRecord</var>, <var>constructor</var>, <var>resultCapability</var>, <var>promiseResolve</var> )</h1>
|
||
<p>The abstract operation PerformPromiseAll takes arguments <var>iteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_16164"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>), <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_16165"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>), <var>resultCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16166"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), and <var>promiseResolve</var> (a <emu-xref href="#function-object" id="_ref_16167"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16168"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16169"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16170"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>values</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16171"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li declared="remainingElementsCount">NOTE: <var>remainingElementsCount</var> starts at 1 instead of 0 to ensure <var>resultCapability</var>.<var class="field">[[Resolve]]</var> is only called once, even in the presence of a misbehaving <emu-val>"then"</emu-val> which calls the passed callback before the input <emu-xref href="#sec-iterator-interface" id="_ref_16172"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> is exhausted.</li><li>Let <var>remainingElementsCount</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16173"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Value]]</var>: 1 }.</li><li>Let <var>index</var> be 0.</li><li>Repeat,<ol><li>Let <var>next</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_16174"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iteratorRecord</var>).</li><li>If <var>next</var> is <emu-const>done</emu-const>, then<ol><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>valuesArray</var> be <emu-xref aoid="CreateArrayFromList" id="_ref_16175"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>values</var>).</li><li>Perform ? <emu-xref aoid="Call" id="_ref_16176"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>valuesArray</var> »).</li></ol></li><li>Return <var>resultCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Append <emu-val>undefined</emu-val> to <var>values</var>.</li><li>Let <var>nextPromise</var> be ? <emu-xref aoid="Call" id="_ref_16177"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseResolve</var>, <var>constructor</var>, « <var>next</var> »).</li><li>Let <var>fulfilledSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16178"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>value</var>) that captures <var>values</var>, <var>resultCapability</var>, and <var>remainingElementsCount</var> and performs the following steps when called:<ol><li>Let <var>F</var> be the <emu-xref href="#active-function-object" id="_ref_16179"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>F</var>.<var class="field">[[AlreadyCalled]]</var> is <emu-val>true</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Set <var>F</var>.<var class="field">[[AlreadyCalled]]</var> to <emu-val>true</emu-val>.</li><li>Let <var>thisIndex</var> be <var>F</var>.<var class="field">[[Index]]</var>.</li><li>Set <var>values</var>[<var>thisIndex</var>] to <var>value</var>.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>valuesArray</var> be <emu-xref aoid="CreateArrayFromList" id="_ref_16180"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>values</var>).</li><li>Return ? <emu-xref aoid="Call" id="_ref_16181"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>valuesArray</var> »).</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>onFulfilled</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16182"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>fulfilledSteps</var>, 1, <emu-val>""</emu-val>, « <var class="field">[[AlreadyCalled]]</var>, <var class="field">[[Index]]</var> »).</li><li>Set <var>onFulfilled</var>.<var class="field">[[AlreadyCalled]]</var> to <emu-val>false</emu-val>.</li><li>Set <var>onFulfilled</var>.<var class="field">[[Index]]</var> to <var>index</var>.</li><li>Set <var>index</var> to <var>index</var> + 1.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> + 1.</li><li>Perform ? <emu-xref aoid="Invoke" id="_ref_16183"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>nextPromise</var>, <emu-val>"then"</emu-val>, « <var>onFulfilled</var>, <var>resultCapability</var>.<var class="field">[[Reject]]</var> »).</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.allsettled" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.2</span> Promise.allSettled ( <var>iterable</var> )</h1>
|
||
<p>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 <emu-xref href="#sec-iterable-interface" id="_ref_16184"><a href="control-abstraction-objects.html#sec-iterable-interface">iterable</a></emu-xref> to promises as it runs this algorithm.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16185"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>promiseResolve</var> be <emu-xref aoid="Completion" id="_ref_16186"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetPromiseResolve" id="_ref_16187"><a href="control-abstraction-objects.html#sec-getpromiseresolve" class="e-user-code">GetPromiseResolve</a></emu-xref>(<var>C</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16188"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>promiseResolve</var>, <var>promiseCapability</var>).</li><li>Let <var>iteratorRecord</var> be <emu-xref aoid="Completion" id="_ref_16189"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetIterator" id="_ref_16190"><a href="abstract-operations.html#sec-getiterator" class="e-user-code">GetIterator</a></emu-xref>(<var>iterable</var>, <emu-const>sync</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16191"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>iteratorRecord</var>, <var>promiseCapability</var>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16192"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PerformPromiseAllSettled" id="_ref_16193"><a href="control-abstraction-objects.html#sec-performpromiseallsettled">PerformPromiseAllSettled</a></emu-xref>(<var>iteratorRecord</var>, <var>C</var>, <var>promiseCapability</var>, <var>promiseResolve</var>)).</li><li>If <var>result</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16194"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>If <var>iteratorRecord</var>.<var class="field">[[Done]]</var> is <emu-val>false</emu-val>, set <var>result</var> to <emu-xref aoid="Completion" id="_ref_16195"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_16196"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iteratorRecord</var>, <var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16197"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li></ol></li><li>Return ! <var>result</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function requires its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16198"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16199"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-performpromiseallsettled" oldids="sec-promise.allsettled-resolve-element-functions,sec-promise.allsettled-reject-element-functions" type="abstract operation" aoid="PerformPromiseAllSettled"><span id="sec-promise.allsettled-reject-element-functions"></span><span id="sec-promise.allsettled-resolve-element-functions"></span>
|
||
<h1><span class="secnum">27.2.4.2.1</span> PerformPromiseAllSettled ( <var>iteratorRecord</var>, <var>constructor</var>, <var>resultCapability</var>, <var>promiseResolve</var> )</h1>
|
||
<p>The abstract operation PerformPromiseAllSettled takes arguments <var>iteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_16200"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>), <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_16201"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>), <var>resultCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16202"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), and <var>promiseResolve</var> (a <emu-xref href="#function-object" id="_ref_16203"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16204"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16205"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16206"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>values</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16207"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li declared="remainingElementsCount">NOTE: <var>remainingElementsCount</var> starts at 1 instead of 0 to ensure <var>resultCapability</var>.<var class="field">[[Resolve]]</var> is only called once, even in the presence of a misbehaving <emu-val>"then"</emu-val> which calls one of the passed callbacks before the input <emu-xref href="#sec-iterator-interface" id="_ref_16208"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> is exhausted.</li><li>Let <var>remainingElementsCount</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16209"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Value]]</var>: 1 }.</li><li>Let <var>index</var> be 0.</li><li>Repeat,<ol><li>Let <var>next</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_16210"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iteratorRecord</var>).</li><li>If <var>next</var> is <emu-const>done</emu-const>, then<ol><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>valuesArray</var> be <emu-xref aoid="CreateArrayFromList" id="_ref_16211"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>values</var>).</li><li>Perform ? <emu-xref aoid="Call" id="_ref_16212"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>valuesArray</var> »).</li></ol></li><li>Return <var>resultCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Append <emu-val>undefined</emu-val> to <var>values</var>.</li><li>Let <var>nextPromise</var> be ? <emu-xref aoid="Call" id="_ref_16213"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseResolve</var>, <var>constructor</var>, « <var>next</var> »).</li><li>Let <var>alreadyCalled</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16214"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Value]]</var>: <emu-val>false</emu-val> }.</li><li>Let <var>fulfilledSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16215"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>value</var>) that captures <var>values</var>, <var>resultCapability</var>, and <var>remainingElementsCount</var> and performs the following steps when called:<ol><li>Let <var>F</var> be the <emu-xref href="#active-function-object" id="_ref_16216"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>F</var>.<var class="field">[[AlreadyCalled]]</var>.<var class="field">[[Value]]</var> is <emu-val>true</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Set <var>F</var>.<var class="field">[[AlreadyCalled]]</var>.<var class="field">[[Value]]</var> to <emu-val>true</emu-val>.</li><li>Let <var>obj</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_16217"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_16218"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16219"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"status"</emu-val>, <emu-val>"fulfilled"</emu-val>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16220"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"value"</emu-val>, <var>value</var>).</li><li>Let <var>thisIndex</var> be <var>F</var>.<var class="field">[[Index]]</var>.</li><li>Set <var>values</var>[<var>thisIndex</var>] to <var>obj</var>.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>valuesArray</var> be <emu-xref aoid="CreateArrayFromList" id="_ref_16221"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>values</var>).</li><li>Return ? <emu-xref aoid="Call" id="_ref_16222"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>valuesArray</var> »).</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>onFulfilled</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16223"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>fulfilledSteps</var>, 1, <emu-val>""</emu-val>, « <var class="field">[[AlreadyCalled]]</var>, <var class="field">[[Index]]</var> »).</li><li>Set <var>onFulfilled</var>.<var class="field">[[AlreadyCalled]]</var> to <var>alreadyCalled</var>.</li><li>Set <var>onFulfilled</var>.<var class="field">[[Index]]</var> to <var>index</var>.</li><li>Let <var>rejectedSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16224"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>error</var>) that captures <var>values</var>, <var>resultCapability</var>, and <var>remainingElementsCount</var> and performs the following steps when called:<ol><li>Let <var>F</var> be the <emu-xref href="#active-function-object" id="_ref_16225"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>F</var>.<var class="field">[[AlreadyCalled]]</var>.<var class="field">[[Value]]</var> is <emu-val>true</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Set <var>F</var>.<var class="field">[[AlreadyCalled]]</var>.<var class="field">[[Value]]</var> to <emu-val>true</emu-val>.</li><li>Let <var>obj</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_16226"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_16227"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16228"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"status"</emu-val>, <emu-val>"rejected"</emu-val>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16229"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"reason"</emu-val>, <var>error</var>).</li><li>Let <var>thisIndex</var> be <var>F</var>.<var class="field">[[Index]]</var>.</li><li>Set <var>values</var>[<var>thisIndex</var>] to <var>obj</var>.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>valuesArray</var> be <emu-xref aoid="CreateArrayFromList" id="_ref_16230"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>values</var>).</li><li>Return ? <emu-xref aoid="Call" id="_ref_16231"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>valuesArray</var> »).</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>onRejected</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16232"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>rejectedSteps</var>, 1, <emu-val>""</emu-val>, « <var class="field">[[AlreadyCalled]]</var>, <var class="field">[[Index]]</var> »).</li><li>Set <var>onRejected</var>.<var class="field">[[AlreadyCalled]]</var> to <var>alreadyCalled</var>.</li><li>Set <var>onRejected</var>.<var class="field">[[Index]]</var> to <var>index</var>.</li><li>Set <var>index</var> to <var>index</var> + 1.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> + 1.</li><li>Perform ? <emu-xref aoid="Invoke" id="_ref_16233"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>nextPromise</var>, <emu-val>"then"</emu-val>, « <var>onFulfilled</var>, <var>onRejected</var> »).</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.any" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.3</span> Promise.any ( <var>iterable</var> )</h1>
|
||
<p>This function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an <code>AggregateError</code> holding the rejection reasons if all of the given promises are rejected. It resolves all elements of the passed <emu-xref href="#sec-iterable-interface" id="_ref_16234"><a href="control-abstraction-objects.html#sec-iterable-interface">iterable</a></emu-xref> to promises as it runs this algorithm.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16235"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>promiseResolve</var> be <emu-xref aoid="Completion" id="_ref_16236"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetPromiseResolve" id="_ref_16237"><a href="control-abstraction-objects.html#sec-getpromiseresolve" class="e-user-code">GetPromiseResolve</a></emu-xref>(<var>C</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16238"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>promiseResolve</var>, <var>promiseCapability</var>).</li><li>Let <var>iteratorRecord</var> be <emu-xref aoid="Completion" id="_ref_16239"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetIterator" id="_ref_16240"><a href="abstract-operations.html#sec-getiterator" class="e-user-code">GetIterator</a></emu-xref>(<var>iterable</var>, <emu-const>sync</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16241"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>iteratorRecord</var>, <var>promiseCapability</var>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16242"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PerformPromiseAny" id="_ref_16243"><a href="control-abstraction-objects.html#sec-performpromiseany">PerformPromiseAny</a></emu-xref>(<var>iteratorRecord</var>, <var>C</var>, <var>promiseCapability</var>, <var>promiseResolve</var>)).</li><li>If <var>result</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16244"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>If <var>iteratorRecord</var>.<var class="field">[[Done]]</var> is <emu-val>false</emu-val>, set <var>result</var> to <emu-xref aoid="Completion" id="_ref_16245"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_16246"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iteratorRecord</var>, <var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16247"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li></ol></li><li>Return ! <var>result</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function requires its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16248"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the <code>Promise</code> <emu-xref href="#constructor" id="_ref_16249"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-performpromiseany" oldids="sec-promise.any-reject-element-functions" type="abstract operation" aoid="PerformPromiseAny"><span id="sec-promise.any-reject-element-functions"></span>
|
||
<h1><span class="secnum">27.2.4.3.1</span> PerformPromiseAny ( <var>iteratorRecord</var>, <var>constructor</var>, <var>resultCapability</var>, <var>promiseResolve</var> )</h1>
|
||
<p>The abstract operation PerformPromiseAny takes arguments <var>iteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_16250"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>), <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_16251"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>), <var>resultCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16252"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), and <var>promiseResolve</var> (a <emu-xref href="#function-object" id="_ref_16253"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16254"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16255"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16256"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>errors</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16257"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li declared="remainingElementsCount">NOTE: <var>remainingElementsCount</var> starts at 1 instead of 0 to ensure <var>resultCapability</var>.<var class="field">[[Reject]]</var> is only called once, even in the presence of a misbehaving <emu-val>"then"</emu-val> which calls the passed callback before the input <emu-xref href="#sec-iterator-interface" id="_ref_16258"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator</a></emu-xref> is exhausted.</li><li>Let <var>remainingElementsCount</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16259"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[Value]]</var>: 1 }.</li><li>Let <var>index</var> be 0.</li><li>Repeat,<ol><li>Let <var>next</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_16260"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iteratorRecord</var>).</li><li>If <var>next</var> is <emu-const>done</emu-const>, then<ol><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>aggregateError</var> be a newly created <emu-val>AggregateError</emu-val> object.</li><li>Perform ! <emu-xref aoid="DefinePropertyOrThrow" id="_ref_16261"><a href="abstract-operations.html#sec-definepropertyorthrow">DefinePropertyOrThrow</a></emu-xref>(<var>aggregateError</var>, <emu-val>"errors"</emu-val>, PropertyDescriptor { <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Writable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Value]]</var>: <emu-xref aoid="CreateArrayFromList" id="_ref_16262"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>errors</var>) }).</li><li>Perform ? <emu-xref aoid="Call" id="_ref_16263"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>aggregateError</var> »).</li></ol></li><li>Return <var>resultCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Append <emu-val>undefined</emu-val> to <var>errors</var>.</li><li>Let <var>nextPromise</var> be ? <emu-xref aoid="Call" id="_ref_16264"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseResolve</var>, <var>constructor</var>, « <var>next</var> »).</li><li>Let <var>rejectedSteps</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16265"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>error</var>) that captures <var>errors</var>, <var>resultCapability</var>, and <var>remainingElementsCount</var> and performs the following steps when called:<ol><li>Let <var>F</var> be the <emu-xref href="#active-function-object" id="_ref_16266"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>F</var>.<var class="field">[[AlreadyCalled]]</var> is <emu-val>true</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Set <var>F</var>.<var class="field">[[AlreadyCalled]]</var> to <emu-val>true</emu-val>.</li><li>Let <var>thisIndex</var> be <var>F</var>.<var class="field">[[Index]]</var>.</li><li>Set <var>errors</var>[<var>thisIndex</var>] to <var>error</var>.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> - 1.</li><li>If <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> = 0, then<ol><li>Let <var>aggregateError</var> be a newly created <emu-val>AggregateError</emu-val> object.</li><li>Perform ! <emu-xref aoid="DefinePropertyOrThrow" id="_ref_16267"><a href="abstract-operations.html#sec-definepropertyorthrow">DefinePropertyOrThrow</a></emu-xref>(<var>aggregateError</var>, <emu-val>"errors"</emu-val>, PropertyDescriptor { <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Writable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Value]]</var>: <emu-xref aoid="CreateArrayFromList" id="_ref_16268"><a href="abstract-operations.html#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>errors</var>) }).</li><li>Return ? <emu-xref aoid="Call" id="_ref_16269"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>resultCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>aggregateError</var> »).</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></li><li>Let <var>onRejected</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16270"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>rejectedSteps</var>, 1, <emu-val>""</emu-val>, « <var class="field">[[AlreadyCalled]]</var>, <var class="field">[[Index]]</var> »).</li><li>Set <var>onRejected</var>.<var class="field">[[AlreadyCalled]]</var> to <emu-val>false</emu-val>.</li><li>Set <var>onRejected</var>.<var class="field">[[Index]]</var> to <var>index</var>.</li><li>Set <var>index</var> to <var>index</var> + 1.</li><li>Set <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> to <var>remainingElementsCount</var>.<var class="field">[[Value]]</var> + 1.</li><li>Perform ? <emu-xref aoid="Invoke" id="_ref_16271"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>nextPromise</var>, <emu-val>"then"</emu-val>, « <var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <var>onRejected</var> »).</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.prototype">
|
||
<h1><span class="secnum">27.2.4.4</span> Promise.prototype</h1>
|
||
<p>The initial value of <code>Promise.prototype</code> is the <emu-xref href="#sec-properties-of-the-promise-prototype-object" id="_ref_16272"><a href="control-abstraction-objects.html#sec-properties-of-the-promise-prototype-object">Promise prototype object</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.race" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.5</span> Promise.race ( <var>iterable</var> )</h1>
|
||
<p>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 <var>iterable</var> to promises as it runs this algorithm.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16273"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>promiseResolve</var> be <emu-xref aoid="Completion" id="_ref_16274"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetPromiseResolve" id="_ref_16275"><a href="control-abstraction-objects.html#sec-getpromiseresolve" class="e-user-code">GetPromiseResolve</a></emu-xref>(<var>C</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16276"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>promiseResolve</var>, <var>promiseCapability</var>).</li><li>Let <var>iteratorRecord</var> be <emu-xref aoid="Completion" id="_ref_16277"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="GetIterator" id="_ref_16278"><a href="abstract-operations.html#sec-getiterator" class="e-user-code">GetIterator</a></emu-xref>(<var>iterable</var>, <emu-const>sync</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16279"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>iteratorRecord</var>, <var>promiseCapability</var>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16280"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PerformPromiseRace" id="_ref_16281"><a href="control-abstraction-objects.html#sec-performpromiserace" class="e-user-code">PerformPromiseRace</a></emu-xref>(<var>iteratorRecord</var>, <var>C</var>, <var>promiseCapability</var>, <var>promiseResolve</var>)).</li><li>If <var>result</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16282"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>If <var>iteratorRecord</var>.<var class="field">[[Done]]</var> is <emu-val>false</emu-val>, set <var>result</var> to <emu-xref aoid="Completion" id="_ref_16283"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="IteratorClose" id="_ref_16284"><a href="abstract-operations.html#sec-iteratorclose" class="e-user-code">IteratorClose</a></emu-xref>(<var>iteratorRecord</var>, <var>result</var>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16285"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li></ol></li><li>Return ! <var>result</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>If the <var>iterable</var> argument yields no values or if none of the promises yielded by <var>iterable</var> ever settle, then the pending promise returned by this method will never be settled.</p>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>This function expects its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16286"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16287"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>. It also expects that its <emu-val>this</emu-val> value provides a <code>resolve</code> method.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-performpromiserace" type="abstract operation" aoid="PerformPromiseRace">
|
||
<h1><span class="secnum">27.2.4.5.1</span> PerformPromiseRace ( <var>iteratorRecord</var>, <var>constructor</var>, <var>resultCapability</var>, <var>promiseResolve</var> )</h1>
|
||
<p>The abstract operation PerformPromiseRace takes arguments <var>iteratorRecord</var> (an <emu-xref href="#sec-iterator-records" id="_ref_16288"><a href="abstract-operations.html#sec-iterator-records">Iterator Record</a></emu-xref>), <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_16289"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>), <var>resultCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16290"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), and <var>promiseResolve</var> (a <emu-xref href="#function-object" id="_ref_16291"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16292"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16293"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16294"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Repeat,<ol><li>Let <var>next</var> be ? <emu-xref aoid="IteratorStepValue" id="_ref_16295"><a href="abstract-operations.html#sec-iteratorstepvalue" class="e-user-code">IteratorStepValue</a></emu-xref>(<var>iteratorRecord</var>).</li><li>If <var>next</var> is <emu-const>done</emu-const>, then<ol><li>Return <var>resultCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Let <var>nextPromise</var> be ? <emu-xref aoid="Call" id="_ref_16296"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseResolve</var>, <var>constructor</var>, « <var>next</var> »).</li><li>Perform ? <emu-xref aoid="Invoke" id="_ref_16297"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>nextPromise</var>, <emu-val>"then"</emu-val>, « <var>resultCapability</var>.<var class="field">[[Resolve]]</var>, <var>resultCapability</var>.<var class="field">[[Reject]]</var> »).</li></ol></li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.reject" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.6</span> Promise.reject ( <var>r</var> )</h1>
|
||
<p>This function returns a new promise rejected with the passed argument.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16298"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Perform ? <emu-xref aoid="Call" id="_ref_16299"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>r</var> »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function expects its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16300"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16301"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.resolve" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.7</span> Promise.resolve ( <var>x</var> )</h1>
|
||
<p>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 <emu-xref href="#constructor" id="_ref_16302"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>If <var>C</var> <emu-xref href="#sec-object-type" id="_ref_16303"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return ? <emu-xref aoid="PromiseResolve" id="_ref_16304"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<var>C</var>, <var>x</var>).</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function expects its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16305"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16306"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-promise-resolve" type="abstract operation" aoid="PromiseResolve">
|
||
<h1><span class="secnum">27.2.4.7.1</span> PromiseResolve ( <var>C</var>, <var>x</var> )</h1>
|
||
<p>The abstract operation PromiseResolve takes arguments <var>C</var> (an Object) and <var>x</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16307"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16308"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16309"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16310"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It returns a new promise resolved with <var>x</var>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <emu-xref aoid="IsPromise" id="_ref_16311"><a href="control-abstraction-objects.html#sec-ispromise">IsPromise</a></emu-xref>(<var>x</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>xConstructor</var> be ? <emu-xref aoid="Get" id="_ref_16312"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>x</var>, <emu-val>"constructor"</emu-val>).</li><li>If <emu-xref aoid="SameValue" id="_ref_16313"><a href="abstract-operations.html#sec-samevalue">SameValue</a></emu-xref>(<var>xConstructor</var>, <var>C</var>) is <emu-val>true</emu-val>, return <var>x</var>.</li></ol></li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16314"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Perform ? <emu-xref aoid="Call" id="_ref_16315"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>x</var> »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.try" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.8</span> Promise.try ( <var>callback</var>, ...<var>args</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>If <var>C</var> <emu-xref href="#sec-object-type" id="_ref_16316"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16317"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>status</var> be <emu-xref aoid="Completion" id="_ref_16318"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Call" id="_ref_16319"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>callback</var>, <emu-val>undefined</emu-val>, <var>args</var>)).</li><li>If <var>status</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16320"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Perform ? <emu-xref aoid="Call" id="_ref_16321"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>status</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Else,<ol><li>Perform ? <emu-xref aoid="Call" id="_ref_16322"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>status</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function expects its <emu-val>this</emu-val> value to be a <emu-xref href="#constructor" id="_ref_16323"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> function that supports the parameter conventions of the Promise <emu-xref href="#constructor" id="_ref_16324"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.withResolvers" type="built-in function">
|
||
<h1><span class="secnum">27.2.4.9</span> Promise.withResolvers ( )</h1>
|
||
<p>This function returns an object with three properties: a new promise together with the <code>resolve</code> and <code>reject</code> functions associated with it.</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16325"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Let <var>obj</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_16326"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_16327"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16328"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"promise"</emu-val>, <var>promiseCapability</var>.<var class="field">[[Promise]]</var>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16329"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"resolve"</emu-val>, <var>promiseCapability</var>.<var class="field">[[Resolve]]</var>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_16330"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>obj</var>, <emu-val>"reject"</emu-val>, <var>promiseCapability</var>.<var class="field">[[Reject]]</var>).</li><li>Return <var>obj</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-get-promise-@@species" id="sec-get-promise-%symbol.species%" type="built-in function"><span id="sec-get-promise-@@species"></span>
|
||
<h1><span class="secnum">27.2.4.10</span> get Promise [ %Symbol.species% ]</h1>
|
||
<p><code>Promise[%Symbol.species%]</code> is an <emu-xref href="#sec-object-type" id="_ref_16331"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return the <emu-val>this</emu-val> value.</li></ol></emu-alg>
|
||
<p>The value of the <emu-val>"name"</emu-val> property of this function is <emu-val>"get [Symbol.species]"</emu-val>.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Promise prototype methods normally use their <emu-val>this</emu-val> value's <emu-xref href="#constructor" id="_ref_16332"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create a derived object. However, a subclass <emu-xref href="#constructor" id="_ref_16333"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> may over-ride that default behaviour by redefining its <emu-xref href="#sec-well-known-symbols" id="_ref_16334"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.species%</a></emu-xref> property.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-promise-prototype-object">
|
||
<h1><span class="secnum">27.2.5</span> Properties of the Promise Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">Promise prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%Promise.prototype%</dfn>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_16335"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16336"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>does not have a <var class="field">[[PromiseState]]</var> internal slot or any of the other internal slots of Promise instances.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-promise.prototype.catch" type="built-in function">
|
||
<h1><span class="secnum">27.2.5.1</span> Promise.prototype.catch ( <var>onRejected</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>promise</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="Invoke" id="_ref_16337"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>promise</var>, <emu-val>"then"</emu-val>, « <emu-val>undefined</emu-val>, <var>onRejected</var> »).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.prototype.constructor">
|
||
<h1><span class="secnum">27.2.5.2</span> Promise.prototype.constructor</h1>
|
||
<p>The initial value of <code>Promise.prototype.constructor</code> is <emu-xref href="#sec-promise-constructor" id="_ref_16338"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.prototype.finally" oldids="sec-thenfinallyfunctions,sec-catchfinallyfunctions" type="built-in function"><span id="sec-catchfinallyfunctions"></span><span id="sec-thenfinallyfunctions"></span>
|
||
<h1><span class="secnum">27.2.5.3</span> Promise.prototype.finally ( <var>onFinally</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>promise</var> be the <emu-val>this</emu-val> value.</li><li>If <var>promise</var> <emu-xref href="#sec-object-type" id="_ref_16339"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>C</var> be ? <emu-xref aoid="SpeciesConstructor" id="_ref_16340"><a href="abstract-operations.html#sec-speciesconstructor" class="e-user-code">SpeciesConstructor</a></emu-xref>(<var>promise</var>, <emu-xref href="#sec-promise-constructor" id="_ref_16341"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li><emu-xref href="#assert" id="_ref_16342"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsConstructor" id="_ref_16343"><a href="abstract-operations.html#sec-isconstructor">IsConstructor</a></emu-xref>(<var>C</var>) is <emu-val>true</emu-val>.</li><li>If <emu-xref aoid="IsCallable" id="_ref_16344"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>onFinally</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>thenFinally</var> be <var>onFinally</var>.</li><li>Let <var>catchFinally</var> be <var>onFinally</var>.</li></ol></li><li>Else,<ol><li>Let <var>thenFinallyClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16345"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>value</var>) that captures <var>onFinally</var> and <var>C</var> and performs the following steps when called:<ol><li>Let <var>result</var> be ? <emu-xref aoid="Call" id="_ref_16346"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>onFinally</var>, <emu-val>undefined</emu-val>).</li><li>Let <var>p</var> be ? <emu-xref aoid="PromiseResolve" id="_ref_16347"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<var>C</var>, <var>result</var>).</li><li>Let <var>returnValue</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16348"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>value</var> and performs the following steps when called:<ol><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16349"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>).</li></ol></li><li>Let <var>valueThunk</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16350"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>returnValue</var>, 0, <emu-val>""</emu-val>, « »).</li><li>Return ? <emu-xref aoid="Invoke" id="_ref_16351"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>p</var>, <emu-val>"then"</emu-val>, « <var>valueThunk</var> »).</li></ol></li><li>Let <var>thenFinally</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16352"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>thenFinallyClosure</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Let <var>catchFinallyClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16353"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>reason</var>) that captures <var>onFinally</var> and <var>C</var> and performs the following steps when called:<ol><li>Let <var>result</var> be ? <emu-xref aoid="Call" id="_ref_16354"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>onFinally</var>, <emu-val>undefined</emu-val>).</li><li>Let <var>p</var> be ? <emu-xref aoid="PromiseResolve" id="_ref_16355"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<var>C</var>, <var>result</var>).</li><li>Let <var>throwReason</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16356"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>reason</var> and performs the following steps when called:<ol><li>Return <emu-xref aoid="ThrowCompletion" id="_ref_16357"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>reason</var>).</li></ol></li><li>Let <var>thrower</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16358"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>throwReason</var>, 0, <emu-val>""</emu-val>, « »).</li><li>Return ? <emu-xref aoid="Invoke" id="_ref_16359"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>p</var>, <emu-val>"then"</emu-val>, « <var>thrower</var> »).</li></ol></li><li>Let <var>catchFinally</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16360"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>catchFinallyClosure</var>, 1, <emu-val>""</emu-val>, « »).</li></ol></li><li>Return ? <emu-xref aoid="Invoke" id="_ref_16361"><a href="abstract-operations.html#sec-invoke" class="e-user-code">Invoke</a></emu-xref>(<var>promise</var>, <emu-val>"then"</emu-val>, « <var>thenFinally</var>, <var>catchFinally</var> »).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-promise.prototype.then" type="built-in function">
|
||
<h1><span class="secnum">27.2.5.4</span> Promise.prototype.then ( <var>onFulfilled</var>, <var>onRejected</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>promise</var> be the <emu-val>this</emu-val> value.</li><li>If <emu-xref aoid="IsPromise" id="_ref_16362"><a href="control-abstraction-objects.html#sec-ispromise">IsPromise</a></emu-xref>(<var>promise</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>C</var> be ? <emu-xref aoid="SpeciesConstructor" id="_ref_16363"><a href="abstract-operations.html#sec-speciesconstructor" class="e-user-code">SpeciesConstructor</a></emu-xref>(<var>promise</var>, <emu-xref href="#sec-promise-constructor" id="_ref_16364"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>resultCapability</var> be ? <emu-xref aoid="NewPromiseCapability" id="_ref_16365"><a href="control-abstraction-objects.html#sec-newpromisecapability" class="e-user-code">NewPromiseCapability</a></emu-xref>(<var>C</var>).</li><li>Return <emu-xref aoid="PerformPromiseThen" id="_ref_16366"><a href="control-abstraction-objects.html#sec-performpromisethen">PerformPromiseThen</a></emu-xref>(<var>promise</var>, <var>onFulfilled</var>, <var>onRejected</var>, <var>resultCapability</var>).</li></ol></emu-alg>
|
||
|
||
<emu-clause id="sec-performpromisethen" type="abstract operation" aoid="PerformPromiseThen">
|
||
<h1><span class="secnum">27.2.5.4.1</span> PerformPromiseThen ( <var>promise</var>, <var>onFulfilled</var>, <var>onRejected</var> [ , <var>resultCapability</var> ] )</h1>
|
||
<p>The abstract operation PerformPromiseThen takes arguments <var>promise</var> (a Promise), <var>onFulfilled</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16367"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), and <var>onRejected</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16368"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and optional argument <var>resultCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16369"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>) and returns an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16370"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>. It performs the “then” operation on <var>promise</var> using <var>onFulfilled</var> and <var>onRejected</var> as its settlement actions. If <var>resultCapability</var> is passed, the result is stored by updating <var>resultCapability</var>'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:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16371"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsPromise" id="_ref_16372"><a href="control-abstraction-objects.html#sec-ispromise">IsPromise</a></emu-xref>(<var>promise</var>) is <emu-val>true</emu-val>.</li><li>If <var>resultCapability</var> is not present, then<ol><li>Set <var>resultCapability</var> to <emu-val>undefined</emu-val>.</li></ol></li><li>If <emu-xref aoid="IsCallable" id="_ref_16373"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>onFulfilled</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>onFulfilledJobCallback</var> be <emu-const>empty</emu-const>.</li></ol></li><li>Else,<ol><li>Let <var>onFulfilledJobCallback</var> be <emu-xref aoid="HostMakeJobCallback" id="_ref_16374"><a href="executable-code-and-execution-contexts.html#sec-hostmakejobcallback">HostMakeJobCallback</a></emu-xref>(<var>onFulfilled</var>).</li></ol></li><li>If <emu-xref aoid="IsCallable" id="_ref_16375"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>onRejected</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>onRejectedJobCallback</var> be <emu-const>empty</emu-const>.</li></ol></li><li>Else,<ol><li>Let <var>onRejectedJobCallback</var> be <emu-xref aoid="HostMakeJobCallback" id="_ref_16376"><a href="executable-code-and-execution-contexts.html#sec-hostmakejobcallback">HostMakeJobCallback</a></emu-xref>(<var>onRejected</var>).</li></ol></li><li>Let <var>fulfillReaction</var> be the <emu-xref href="#sec-promisereaction-records" id="_ref_16377"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Record</a></emu-xref> { <var class="field">[[Capability]]</var>: <var>resultCapability</var>, <var class="field">[[Type]]</var>: <emu-const>fulfill</emu-const>, <var class="field">[[Handler]]</var>: <var>onFulfilledJobCallback</var> }.</li><li>Let <var>rejectReaction</var> be the <emu-xref href="#sec-promisereaction-records" id="_ref_16378"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Record</a></emu-xref> { <var class="field">[[Capability]]</var>: <var>resultCapability</var>, <var class="field">[[Type]]</var>: <emu-const>reject</emu-const>, <var class="field">[[Handler]]</var>: <var>onRejectedJobCallback</var> }.</li><li>If <var>promise</var>.<var class="field">[[PromiseState]]</var> is <emu-const>pending</emu-const>, then<ol><li>Append <var>fulfillReaction</var> to <var>promise</var>.<var class="field">[[PromiseFulfillReactions]]</var>.</li><li>Append <var>rejectReaction</var> to <var>promise</var>.<var class="field">[[PromiseRejectReactions]]</var>.</li></ol></li><li>Else if <var>promise</var>.<var class="field">[[PromiseState]]</var> is <emu-const>fulfilled</emu-const>, then<ol><li>Let <var>value</var> be <var>promise</var>.<var class="field">[[PromiseResult]]</var>.</li><li>Let <var>fulfillJob</var> be <emu-xref aoid="NewPromiseReactionJob" id="_ref_16379"><a href="control-abstraction-objects.html#sec-newpromisereactionjob">NewPromiseReactionJob</a></emu-xref>(<var>fulfillReaction</var>, <var>value</var>).</li><li>Perform <emu-xref aoid="HostEnqueuePromiseJob" id="_ref_16380"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</a></emu-xref>(<var>fulfillJob</var>.<var class="field">[[Job]]</var>, <var>fulfillJob</var>.<var class="field">[[Realm]]</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16381"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>promise</var>.<var class="field">[[PromiseState]]</var> is <emu-const>rejected</emu-const>.</li><li>Let <var>reason</var> be <var>promise</var>.<var class="field">[[PromiseResult]]</var>.</li><li>If <var>promise</var>.<var class="field">[[PromiseIsHandled]]</var> is <emu-val>false</emu-val>, perform <emu-xref aoid="HostPromiseRejectionTracker" id="_ref_16382"><a href="control-abstraction-objects.html#sec-host-promise-rejection-tracker">HostPromiseRejectionTracker</a></emu-xref>(<var>promise</var>, <emu-val>"handle"</emu-val>).</li><li>Let <var>rejectJob</var> be <emu-xref aoid="NewPromiseReactionJob" id="_ref_16383"><a href="control-abstraction-objects.html#sec-newpromisereactionjob">NewPromiseReactionJob</a></emu-xref>(<var>rejectReaction</var>, <var>reason</var>).</li><li>Perform <emu-xref aoid="HostEnqueuePromiseJob" id="_ref_16384"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</a></emu-xref>(<var>rejectJob</var>.<var class="field">[[Job]]</var>, <var>rejectJob</var>.<var class="field">[[Realm]]</var>).</li></ol></li><li>Set <var>promise</var>.<var class="field">[[PromiseIsHandled]]</var> to <emu-val>true</emu-val>.</li><li>If <var>resultCapability</var> is <emu-val>undefined</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Return <var>resultCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-promise.prototype-@@tostringtag" id="sec-promise.prototype-%symbol.tostringtag%"><span id="sec-promise.prototype-@@tostringtag"></span>
|
||
<h1><span class="secnum">27.2.5.5</span> Promise.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16385"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"Promise"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-promise-instances">
|
||
<h1><span class="secnum">27.2.6</span> Properties of Promise Instances</h1>
|
||
<p>Promise instances are <emu-xref href="#ordinary-object" id="_ref_16386"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary objects</a></emu-xref> that inherit properties from the <emu-xref href="#sec-properties-of-the-promise-prototype-object" id="_ref_16387"><a href="control-abstraction-objects.html#sec-properties-of-the-promise-prototype-object">Promise prototype object</a></emu-xref> (the intrinsic, <emu-xref href="#sec-properties-of-the-promise-prototype-object" id="_ref_16388"><a href="control-abstraction-objects.html#sec-properties-of-the-promise-prototype-object">%Promise.prototype%</a></emu-xref>). Promise instances are initially created with the internal slots described in <emu-xref href="#table-internal-slots-of-promise-instances" id="_ref_828"><a href="control-abstraction-objects.html#table-internal-slots-of-promise-instances">Table 87</a></emu-xref>.</p>
|
||
<emu-table id="table-internal-slots-of-promise-instances" caption="Internal Slots of Promise Instances" oldids="table-59"><figure><figcaption>Table 87: Internal Slots of Promise Instances</figcaption><span id="table-59"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Internal Slot
|
||
</th>
|
||
<th>
|
||
Type
|
||
</th>
|
||
<th>
|
||
Description
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[PromiseState]]</var>
|
||
</td>
|
||
<td>
|
||
<emu-const>pending</emu-const>, <emu-const>fulfilled</emu-const>, or <emu-const>rejected</emu-const>
|
||
</td>
|
||
<td>
|
||
Governs how a promise will react to incoming calls to its <code>then</code> method.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[PromiseResult]]</var>
|
||
</td>
|
||
<td>
|
||
an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16389"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or <emu-const>empty</emu-const>
|
||
</td>
|
||
<td>
|
||
The value with which the promise has been fulfilled or rejected, if any. <emu-const>empty</emu-const> if and only if the <var class="field">[[PromiseState]]</var> is <emu-const>pending</emu-const>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[PromiseFulfillReactions]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16390"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-promisereaction-records" id="_ref_16391"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Records</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
<emu-xref href="#sec-list-and-record-specification-type" id="_ref_16392"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Records</a></emu-xref> to be processed when/if the promise transitions from the <emu-const>pending</emu-const> state to the <emu-const>fulfilled</emu-const> state.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[PromiseRejectReactions]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16393"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-promisereaction-records" id="_ref_16394"><a href="control-abstraction-objects.html#sec-promisereaction-records">PromiseReaction Records</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
<emu-xref href="#sec-list-and-record-specification-type" id="_ref_16395"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Records</a></emu-xref> to be processed when/if the promise transitions from the <emu-const>pending</emu-const> state to the <emu-const>rejected</emu-const> state.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[PromiseIsHandled]]</var>
|
||
</td>
|
||
<td>
|
||
a Boolean
|
||
</td>
|
||
<td>
|
||
Indicates whether the promise has ever had a fulfillment or rejection handler; used in unhandled rejection tracking.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorfunction-objects">
|
||
<h1><span class="secnum">27.3</span> GeneratorFunction Objects</h1>
|
||
<p>GeneratorFunctions are functions that are usually created by evaluating <emu-nt id="_ref_24555"><a href="ecmascript-language-functions-and-classes.html#prod-GeneratorDeclaration">GeneratorDeclaration</a></emu-nt>s, <emu-nt id="_ref_24556"><a href="ecmascript-language-functions-and-classes.html#prod-GeneratorExpression">GeneratorExpression</a></emu-nt>s, and <emu-nt id="_ref_24557"><a href="ecmascript-language-functions-and-classes.html#prod-GeneratorMethod">GeneratorMethod</a></emu-nt>s. They may also be created by calling the <emu-xref href="#sec-generatorfunction-constructor" id="_ref_16396"><a href="control-abstraction-objects.html#sec-generatorfunction-constructor">%GeneratorFunction%</a></emu-xref> intrinsic.</p>
|
||
<emu-figure id="figure-2" caption="Generator Objects Relationships" informative=""><figure><figcaption>Figure 6 (Informative): Generator Objects Relationships</figcaption>
|
||
<img alt="A staggering variety of boxes and arrows." height="700" src="../img/figure-2.svg" width="900">
|
||
</figure></emu-figure>
|
||
|
||
<emu-clause id="sec-generatorfunction-constructor">
|
||
<h1><span class="secnum">27.3.1</span> The GeneratorFunction Constructor</h1>
|
||
<p>The GeneratorFunction <emu-xref href="#constructor" id="_ref_16397"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%GeneratorFunction%</dfn>.</li>
|
||
<li>is a subclass of <code>Function</code>.</li>
|
||
<li>creates and initializes a new GeneratorFunction when called as a function rather than as a <emu-xref href="#constructor" id="_ref_16398"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>. Thus the function call <code>GeneratorFunction (…)</code> is equivalent to the object creation expression <code>new GeneratorFunction (…)</code> with the same arguments.</li>
|
||
<li>may be used as the value of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_16399"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified GeneratorFunction behaviour must include a <code>super</code> call to the GeneratorFunction <emu-xref href="#constructor" id="_ref_16400"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize subclass instances with the internal slots necessary for built-in GeneratorFunction behaviour. All ECMAScript syntactic forms for defining generator <emu-xref href="#function-object" id="_ref_16401"><a href="ecmascript-data-types-and-values.html#function-object">function objects</a></emu-xref> create direct instances of GeneratorFunction. There is no syntactic means to create instances of GeneratorFunction subclasses.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-generatorfunction" type="built-in function">
|
||
<h1><span class="secnum">27.3.1.1</span> GeneratorFunction ( ...<var>parameterArgs</var>, <var>bodyArg</var> )</h1>
|
||
<p>The last argument (if any) specifies the body (executable code) of a generator function; any preceding arguments specify formal parameters.</p>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-xref href="#active-function-object" id="_ref_16402"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>bodyArg</var> is not present, set <var>bodyArg</var> to the empty String.</li><li>Return ? <emu-xref aoid="CreateDynamicFunction" id="_ref_16403"><a href="fundamental-objects.html#sec-createdynamicfunction" class="e-user-code">CreateDynamicFunction</a></emu-xref>(<var>C</var>, NewTarget, <emu-const>generator</emu-const>, <var>parameterArgs</var>, <var>bodyArg</var>).</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>See NOTE for <emu-xref href="#sec-function-p1-p2-pn-body" id="_ref_829"><a href="fundamental-objects.html#sec-function-p1-p2-pn-body">20.2.1.1</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-generatorfunction-constructor">
|
||
<h1><span class="secnum">27.3.2</span> Properties of the GeneratorFunction Constructor</h1>
|
||
<p>The GeneratorFunction <emu-xref href="#constructor" id="_ref_16404"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is a standard built-in <emu-xref href="#function-object" id="_ref_16405"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> that inherits from the Function <emu-xref href="#constructor" id="_ref_16406"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-function-constructor" id="_ref_16407"><a href="fundamental-objects.html#sec-function-constructor">%Function%</a></emu-xref>.</li>
|
||
<li oldids="sec-generatorfunction.length"><span id="sec-generatorfunction.length"></span>has a <emu-val>"length"</emu-val> property whose value is <emu-val>1</emu-val><sub>𝔽</sub>.</li>
|
||
<li>has a <emu-val>"name"</emu-val> property whose value is <emu-val>"GeneratorFunction"</emu-val>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-generatorfunction.prototype">
|
||
<h1><span class="secnum">27.3.2.1</span> GeneratorFunction.prototype</h1>
|
||
<p>The initial value of <code>GeneratorFunction.prototype</code> is the <emu-xref href="#sec-properties-of-the-generatorfunction-prototype-object" id="_ref_16408"><a href="control-abstraction-objects.html#sec-properties-of-the-generatorfunction-prototype-object">GeneratorFunction prototype object</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-generatorfunction-prototype-object">
|
||
<h1><span class="secnum">27.3.3</span> Properties of the GeneratorFunction Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">GeneratorFunction prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%GeneratorFunction.prototype%</dfn> (see <emu-xref href="#figure-2" id="_ref_830"><a href="control-abstraction-objects.html#figure-2">Figure 6</a></emu-xref>).</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16409"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>is not a <emu-xref href="#function-object" id="_ref_16410"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and does not have an <var class="field">[[ECMAScriptCode]]</var> internal slot or any other of the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_831"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref> or <emu-xref href="#table-internal-slots-of-generator-instances" id="_ref_832"><a href="control-abstraction-objects.html#table-internal-slots-of-generator-instances">Table 88</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_16411"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-generatorfunction.prototype.constructor">
|
||
<h1><span class="secnum">27.3.3.1</span> GeneratorFunction.prototype.constructor</h1>
|
||
<p>The initial value of <code>GeneratorFunction.prototype.constructor</code> is <emu-xref href="#sec-generatorfunction-constructor" id="_ref_16412"><a href="control-abstraction-objects.html#sec-generatorfunction-constructor">%GeneratorFunction%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorfunction.prototype.prototype">
|
||
<h1><span class="secnum">27.3.3.2</span> GeneratorFunction.prototype.prototype</h1>
|
||
<p>The initial value of <code>GeneratorFunction.prototype.prototype</code> is <emu-xref href="#sec-properties-of-generator-prototype" id="_ref_16413"><a href="control-abstraction-objects.html#sec-properties-of-generator-prototype">%GeneratorPrototype%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-generatorfunction.prototype-@@tostringtag" id="sec-generatorfunction.prototype-%symbol.tostringtag%"><span id="sec-generatorfunction.prototype-@@tostringtag"></span>
|
||
<h1><span class="secnum">27.3.3.3</span> GeneratorFunction.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16414"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"GeneratorFunction"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorfunction-instances">
|
||
<h1><span class="secnum">27.3.4</span> GeneratorFunction Instances</h1>
|
||
<p>Every GeneratorFunction instance is an ECMAScript <emu-xref href="#function-object" id="_ref_16415"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and has the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_833"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref>. The value of the <var class="field">[[IsClassConstructor]]</var> internal slot for all such instances is <emu-val>false</emu-val>.</p>
|
||
<p>Each GeneratorFunction instance has the following own properties:</p>
|
||
|
||
<emu-clause id="sec-generatorfunction-instances-length">
|
||
<h1><span class="secnum">27.3.4.1</span> length</h1>
|
||
<p>The specification for the <emu-val>"length"</emu-val> property of Function instances given in <emu-xref href="#sec-function-instances-length" id="_ref_834"><a href="fundamental-objects.html#sec-function-instances-length">20.2.4.1</a></emu-xref> also applies to GeneratorFunction instances.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorfunction-instances-name">
|
||
<h1><span class="secnum">27.3.4.2</span> name</h1>
|
||
<p>The specification for the <emu-val>"name"</emu-val> property of Function instances given in <emu-xref href="#sec-function-instances-name" id="_ref_835"><a href="fundamental-objects.html#sec-function-instances-name">20.2.4.2</a></emu-xref> also applies to GeneratorFunction instances.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorfunction-instances-prototype">
|
||
<h1><span class="secnum">27.3.4.3</span> prototype</h1>
|
||
<p>Whenever a GeneratorFunction instance is created another <emu-xref href="#ordinary-object" id="_ref_16416"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref> is also created and is the initial value of the generator function's <emu-val>"prototype"</emu-val> property. The value of the prototype property is used to initialize the <var class="field">[[Prototype]]</var> internal slot of a newly created Generator when the generator <emu-xref href="#function-object" id="_ref_16417"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> is invoked using <var class="field">[[Call]]</var>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Unlike Function instances, the object that is the value of a GeneratorFunction's <emu-val>"prototype"</emu-val> property does not have a <emu-val>"constructor"</emu-val> property whose value is the GeneratorFunction instance.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-objects">
|
||
<h1><span class="secnum">27.4</span> AsyncGeneratorFunction Objects</h1>
|
||
<p>AsyncGeneratorFunctions are functions that are usually created by evaluating <emu-nt id="_ref_24558"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncGeneratorDeclaration">AsyncGeneratorDeclaration</a></emu-nt>, <emu-nt id="_ref_24559"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncGeneratorExpression">AsyncGeneratorExpression</a></emu-nt>, and <emu-nt id="_ref_24560"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncGeneratorMethod">AsyncGeneratorMethod</a></emu-nt> syntactic productions. They may also be created by calling the <emu-xref href="#sec-asyncgeneratorfunction-constructor" id="_ref_16418"><a href="control-abstraction-objects.html#sec-asyncgeneratorfunction-constructor">%AsyncGeneratorFunction%</a></emu-xref> intrinsic.</p>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-constructor">
|
||
<h1><span class="secnum">27.4.1</span> The AsyncGeneratorFunction Constructor</h1>
|
||
<p>The AsyncGeneratorFunction <emu-xref href="#constructor" id="_ref_16419"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%AsyncGeneratorFunction%</dfn>.</li>
|
||
<li>is a subclass of <code>Function</code>.</li>
|
||
<li>creates and initializes a new AsyncGeneratorFunction when called as a function rather than as a <emu-xref href="#constructor" id="_ref_16420"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>. Thus the function call <code>AsyncGeneratorFunction (...)</code> is equivalent to the object creation expression <code>new AsyncGeneratorFunction (...)</code> with the same arguments.</li>
|
||
<li>may be used as the value of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_16421"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified AsyncGeneratorFunction behaviour must include a <code>super</code> call to the AsyncGeneratorFunction <emu-xref href="#constructor" id="_ref_16422"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize subclass instances with the internal slots necessary for built-in AsyncGeneratorFunction behaviour. All ECMAScript syntactic forms for defining async generator <emu-xref href="#function-object" id="_ref_16423"><a href="ecmascript-data-types-and-values.html#function-object">function objects</a></emu-xref> create direct instances of AsyncGeneratorFunction. There is no syntactic means to create instances of AsyncGeneratorFunction subclasses.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction" type="built-in function">
|
||
<h1><span class="secnum">27.4.1.1</span> AsyncGeneratorFunction ( ...<var>parameterArgs</var>, <var>bodyArg</var> )</h1>
|
||
<p>The last argument (if any) specifies the body (executable code) of an async generator function; any preceding arguments specify formal parameters.</p>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-xref href="#active-function-object" id="_ref_16424"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>bodyArg</var> is not present, set <var>bodyArg</var> to the empty String.</li><li>Return ? <emu-xref aoid="CreateDynamicFunction" id="_ref_16425"><a href="fundamental-objects.html#sec-createdynamicfunction" class="e-user-code">CreateDynamicFunction</a></emu-xref>(<var>C</var>, NewTarget, <emu-const>async-generator</emu-const>, <var>parameterArgs</var>, <var>bodyArg</var>).</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>See NOTE for <emu-xref href="#sec-function-p1-p2-pn-body" id="_ref_836"><a href="fundamental-objects.html#sec-function-p1-p2-pn-body">20.2.1.1</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-asyncgeneratorfunction">
|
||
<h1><span class="secnum">27.4.2</span> Properties of the AsyncGeneratorFunction Constructor</h1>
|
||
<p>The AsyncGeneratorFunction <emu-xref href="#constructor" id="_ref_16426"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is a standard built-in <emu-xref href="#function-object" id="_ref_16427"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> that inherits from the Function <emu-xref href="#constructor" id="_ref_16428"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-function-constructor" id="_ref_16429"><a href="fundamental-objects.html#sec-function-constructor">%Function%</a></emu-xref>.</li>
|
||
<li oldids="sec-asyncgeneratorfunction-length"><span id="sec-asyncgeneratorfunction-length"></span>has a <emu-val>"length"</emu-val> property whose value is <emu-val>1</emu-val><sub>𝔽</sub>.</li>
|
||
<li>has a <emu-val>"name"</emu-val> property whose value is <emu-val>"AsyncGeneratorFunction"</emu-val>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-prototype">
|
||
<h1><span class="secnum">27.4.2.1</span> AsyncGeneratorFunction.prototype</h1>
|
||
<p>The initial value of <code>AsyncGeneratorFunction.prototype</code> is the <emu-xref href="#sec-properties-of-asyncgeneratorfunction-prototype" id="_ref_16430"><a href="control-abstraction-objects.html#sec-properties-of-asyncgeneratorfunction-prototype">AsyncGeneratorFunction prototype object</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-asyncgeneratorfunction-prototype">
|
||
<h1><span class="secnum">27.4.3</span> Properties of the AsyncGeneratorFunction Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">AsyncGeneratorFunction prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%AsyncGeneratorFunction.prototype%</dfn>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16431"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>is not a <emu-xref href="#function-object" id="_ref_16432"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and does not have an <var class="field">[[ECMAScriptCode]]</var> internal slot or any other of the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_837"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref> or <emu-xref href="#table-internal-slots-of-asyncgenerator-instances" id="_ref_838"><a href="control-abstraction-objects.html#table-internal-slots-of-asyncgenerator-instances">Table 89</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_16433"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-prototype-constructor">
|
||
<h1><span class="secnum">27.4.3.1</span> AsyncGeneratorFunction.prototype.constructor</h1>
|
||
<p>The initial value of <code>AsyncGeneratorFunction.prototype.constructor</code> is <emu-xref href="#sec-asyncgeneratorfunction-constructor" id="_ref_16434"><a href="control-abstraction-objects.html#sec-asyncgeneratorfunction-constructor">%AsyncGeneratorFunction%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-prototype-prototype">
|
||
<h1><span class="secnum">27.4.3.2</span> AsyncGeneratorFunction.prototype.prototype</h1>
|
||
<p>The initial value of <code>AsyncGeneratorFunction.prototype.prototype</code> is <emu-xref href="#sec-properties-of-asyncgenerator-prototype" id="_ref_16435"><a href="control-abstraction-objects.html#sec-properties-of-asyncgenerator-prototype">%AsyncGeneratorPrototype%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-asyncgeneratorfunction-prototype-tostringtag" id="sec-asyncgeneratorfunction-prototype-%symbol.tostringtag%"><span id="sec-asyncgeneratorfunction-prototype-tostringtag"></span>
|
||
<h1><span class="secnum">27.4.3.3</span> AsyncGeneratorFunction.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16436"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"AsyncGeneratorFunction"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-instances">
|
||
<h1><span class="secnum">27.4.4</span> AsyncGeneratorFunction Instances</h1>
|
||
<p>Every AsyncGeneratorFunction instance is an ECMAScript <emu-xref href="#function-object" id="_ref_16437"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and has the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_839"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref>. The value of the <var class="field">[[IsClassConstructor]]</var> internal slot for all such instances is <emu-val>false</emu-val>.</p>
|
||
<p>Each AsyncGeneratorFunction instance has the following own properties:</p>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-instance-length">
|
||
<h1><span class="secnum">27.4.4.1</span> length</h1>
|
||
<p>The value of the <emu-val>"length"</emu-val> property is an <emu-xref href="#integral-number" id="_ref_16438"><a href="notational-conventions.html#integral-number">integral Number</a></emu-xref> 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 <emu-val>"length"</emu-val> property depends on the function.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-instance-name">
|
||
<h1><span class="secnum">27.4.4.2</span> name</h1>
|
||
<p>The specification for the <emu-val>"name"</emu-val> property of Function instances given in <emu-xref href="#sec-function-instances-name" id="_ref_840"><a href="fundamental-objects.html#sec-function-instances-name">20.2.4.2</a></emu-xref> also applies to AsyncGeneratorFunction instances.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorfunction-instance-prototype">
|
||
<h1><span class="secnum">27.4.4.3</span> prototype</h1>
|
||
<p>Whenever an AsyncGeneratorFunction instance is created, another <emu-xref href="#ordinary-object" id="_ref_16439"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref> is also created and is the initial value of the async generator function's <emu-val>"prototype"</emu-val> property. The value of the prototype property is used to initialize the <var class="field">[[Prototype]]</var> internal slot of a newly created AsyncGenerator when the generator <emu-xref href="#function-object" id="_ref_16440"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> is invoked using <var class="field">[[Call]]</var>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>true</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Unlike function instances, the object that is the value of an AsyncGeneratorFunction's <emu-val>"prototype"</emu-val> property does not have a <emu-val>"constructor"</emu-val> property whose value is the AsyncGeneratorFunction instance.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generator-objects">
|
||
<h1><span class="secnum">27.5</span> Generator Objects</h1>
|
||
<p>A Generator is created by calling a generator function and conforms to both the <emu-xref href="#sec-iterator-interface" id="_ref_16441"><a href="control-abstraction-objects.html#sec-iterator-interface">iterator interface</a></emu-xref> and the <emu-xref href="#sec-iterable-interface" id="_ref_16442"><a href="control-abstraction-objects.html#sec-iterable-interface">iterable interface</a></emu-xref>.</p>
|
||
<p>Generator instances directly inherit properties from the initial value of the <emu-val>"prototype"</emu-val> property of the generator function that created the instance. Generator instances indirectly inherit properties from <emu-xref href="#sec-properties-of-generator-prototype" id="_ref_16443"><a href="control-abstraction-objects.html#sec-properties-of-generator-prototype">%GeneratorPrototype%</a></emu-xref>.</p>
|
||
|
||
<emu-clause id="sec-properties-of-generator-prototype">
|
||
<h1><span class="secnum">27.5.1</span> The %GeneratorPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%GeneratorPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%GeneratorFunction.prototype.prototype%</dfn>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16444"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>is not a Generator instance and does not have a <var class="field">[[GeneratorState]]</var> internal slot.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-%iterator.prototype%-object" id="_ref_16445"><a href="control-abstraction-objects.html#sec-%iterator.prototype%-object">%Iterator.prototype%</a></emu-xref>.</li>
|
||
<li>has properties that are indirectly inherited by all Generator instances.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-generator.prototype.constructor">
|
||
<h1><span class="secnum">27.5.1.1</span> %GeneratorPrototype%.constructor</h1>
|
||
<p>The initial value of <emu-xref href="#sec-properties-of-generator-prototype" id="_ref_16446"><a href="control-abstraction-objects.html#sec-properties-of-generator-prototype">%GeneratorPrototype%</a></emu-xref><code>.constructor</code> is <emu-xref href="#sec-properties-of-the-generatorfunction-prototype-object" id="_ref_16447"><a href="control-abstraction-objects.html#sec-properties-of-the-generatorfunction-prototype-object">%GeneratorFunction.prototype%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generator.prototype.next" type="built-in function">
|
||
<h1><span class="secnum">27.5.1.2</span> %GeneratorPrototype%.next ( <var>value</var> )</h1>
|
||
<emu-alg><ol><li>Return ? <emu-xref aoid="GeneratorResume" id="_ref_16448"><a href="control-abstraction-objects.html#sec-generatorresume" class="e-user-code">GeneratorResume</a></emu-xref>(<emu-val>this</emu-val> value, <var>value</var>, <emu-const>empty</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generator.prototype.return" type="built-in function">
|
||
<h1><span class="secnum">27.5.1.3</span> %GeneratorPrototype%.return ( <var>value</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>g</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>C</var> be <emu-xref aoid="ReturnCompletion" id="_ref_16449"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<var>value</var>).</li><li>Return ? <emu-xref aoid="GeneratorResumeAbrupt" id="_ref_16450"><a href="control-abstraction-objects.html#sec-generatorresumeabrupt" class="e-user-code">GeneratorResumeAbrupt</a></emu-xref>(<var>g</var>, <var>C</var>, <emu-const>empty</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generator.prototype.throw" type="built-in function">
|
||
<h1><span class="secnum">27.5.1.4</span> %GeneratorPrototype%.throw ( <var>exception</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>g</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>C</var> be <emu-xref aoid="ThrowCompletion" id="_ref_16451"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>exception</var>).</li><li>Return ? <emu-xref aoid="GeneratorResumeAbrupt" id="_ref_16452"><a href="control-abstraction-objects.html#sec-generatorresumeabrupt" class="e-user-code">GeneratorResumeAbrupt</a></emu-xref>(<var>g</var>, <var>C</var>, <emu-const>empty</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-generator.prototype-@@tostringtag" id="sec-generator.prototype-%symbol.tostringtag%"><span id="sec-generator.prototype-@@tostringtag"></span>
|
||
<h1><span class="secnum">27.5.1.5</span> %GeneratorPrototype% [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16453"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"Generator"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-generator-instances">
|
||
<h1><span class="secnum">27.5.2</span> Properties of Generator Instances</h1>
|
||
<p>Generator instances are initially created with the internal slots described in <emu-xref href="#table-internal-slots-of-generator-instances" id="_ref_841"><a href="control-abstraction-objects.html#table-internal-slots-of-generator-instances">Table 88</a></emu-xref>.</p>
|
||
<emu-table id="table-internal-slots-of-generator-instances" caption="Internal Slots of Generator Instances" oldids="table-56"><figure><figcaption>Table 88: Internal Slots of Generator Instances</figcaption><span id="table-56"></span>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Internal Slot
|
||
</th>
|
||
<th>
|
||
Type
|
||
</th>
|
||
<th>
|
||
Description
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[GeneratorState]]</var>
|
||
</td>
|
||
<td>
|
||
<emu-const>suspended-start</emu-const>, <emu-const>suspended-yield</emu-const>, <emu-const>executing</emu-const>, or <emu-const>completed</emu-const>
|
||
</td>
|
||
<td>
|
||
The current execution state of the generator.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[GeneratorContext]]</var>
|
||
</td>
|
||
<td>
|
||
an <emu-xref href="#sec-execution-contexts" id="_ref_16454"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The <emu-xref href="#sec-execution-contexts" id="_ref_16455"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is used when executing the code of this generator.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[GeneratorBrand]]</var>
|
||
</td>
|
||
<td>
|
||
a String or <emu-const>empty</emu-const>
|
||
</td>
|
||
<td>
|
||
A brand used to distinguish different kinds of generators. The <var class="field">[[GeneratorBrand]]</var> of generators declared by <emu-xref href="#sec-source-text" id="_ref_16456"><a href="ecmascript-language-source-code.html#sec-source-text">ECMAScript source text</a></emu-xref> is always <emu-const>empty</emu-const>.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generator-abstract-operations">
|
||
<h1><span class="secnum">27.5.3</span> Generator Abstract Operations</h1>
|
||
|
||
<emu-clause id="sec-generatorstart" type="abstract operation" aoid="GeneratorStart">
|
||
<h1><span class="secnum">27.5.3.1</span> GeneratorStart ( <var>generator</var>, <var>generatorBody</var> )</h1>
|
||
<p>The abstract operation GeneratorStart takes arguments <var>generator</var> (a Generator) and <var>generatorBody</var> (a <emu-nt id="_ref_24561"><a href="ecmascript-language-functions-and-classes.html#prod-FunctionBody">FunctionBody</a></emu-nt> <emu-xref href="#sec-syntactic-grammar" id="_ref_16457"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref> or an <emu-xref href="#sec-abstract-closure" id="_ref_16458"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16459"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[GeneratorState]]</var> is <emu-const>suspended-start</emu-const>.</li><li>Let <var>genContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16460"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Set the Generator component of <var>genContext</var> to <var>generator</var>.</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16461"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>generatorBody</var> and performs the following steps when called:<ol><li>Let <var>acGenContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16462"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>acGenerator</var> be the Generator component of <var>acGenContext</var>.</li><li>If <var>generatorBody</var> is a <emu-xref href="#sec-syntactic-grammar" id="_ref_16463"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16464"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Evaluation" id="_ref_16465"><a href="syntax-directed-operations.html#sec-evaluation" class="e-user-code">Evaluation</a></emu-xref> of <var>generatorBody</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16466"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generatorBody</var> is an <emu-xref href="#sec-abstract-closure" id="_ref_16467"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16468"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>generatorBody</var>()).</li></ol></li><li><emu-xref href="#assert" id="_ref_16469"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If we return here, the generator either threw an exception or performed either an implicit or explicit return.</li><li>Remove <var>acGenContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16470"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16471"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16472"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16473"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Set <var>acGenerator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>completed</emu-const>.</li><li>NOTE: Once a generator enters the <emu-const>completed</emu-const> state it never leaves it and its associated <emu-xref href="#sec-execution-contexts" id="_ref_16474"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> is never resumed. Any execution state associated with <var>acGenerator</var> can be discarded at this point.</li><li>If <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16475"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, then<ol><li>Let <var>resultValue</var> be <emu-val>undefined</emu-val>.</li></ol></li><li>Else if <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16476"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, then<ol><li>Let <var>resultValue</var> be <var>result</var>.<var class="field">[[Value]]</var>.</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16477"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16478"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>.</li><li>Return ? <var>result</var>.</li></ol></li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16479"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-xref aoid="CreateIteratorResultObject" id="_ref_16480"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>resultValue</var>, <emu-val>true</emu-val>)).</li></ol></li><li>Set the code evaluation state of <var>genContext</var> such that when evaluation is resumed for that <emu-xref href="#sec-execution-contexts" id="_ref_16481"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>, <var>closure</var> will be called with no arguments.</li><li>Set <var>generator</var>.<var class="field">[[GeneratorContext]]</var> to <var>genContext</var>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorvalidate" type="abstract operation" aoid="GeneratorValidate">
|
||
<h1><span class="secnum">27.5.3.2</span> GeneratorValidate ( <var>generator</var>, <var>generatorBrand</var> )</h1>
|
||
<p>The abstract operation GeneratorValidate takes arguments <var>generator</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16482"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and <var>generatorBrand</var> (a String or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16483"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> one of <emu-const>suspended-start</emu-const>, <emu-const>suspended-yield</emu-const>, or <emu-const>completed</emu-const>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16484"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_16485"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>generator</var>, <var class="field">[[GeneratorState]]</var>).</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_16486"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>generator</var>, <var class="field">[[GeneratorBrand]]</var>).</li><li>If <var>generator</var>.<var class="field">[[GeneratorBrand]]</var> is not <var>generatorBrand</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li><emu-xref href="#assert" id="_ref_16487"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var> has a <var class="field">[[GeneratorContext]]</var> internal slot.</li><li>Let <var>state</var> be <var>generator</var>.<var class="field">[[GeneratorState]]</var>.</li><li>If <var>state</var> is <emu-const>executing</emu-const>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return <var>state</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorresume" type="abstract operation" aoid="GeneratorResume">
|
||
<h1><span class="secnum">27.5.3.3</span> GeneratorResume ( <var>generator</var>, <var>value</var>, <var>generatorBrand</var> )</h1>
|
||
<p>The abstract operation GeneratorResume takes arguments <var>generator</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16488"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16489"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or <emu-const>empty</emu-const>), and <var>generatorBrand</var> (a String or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16490"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16491"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16492"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>state</var> be ? <emu-xref aoid="GeneratorValidate" id="_ref_16493"><a href="control-abstraction-objects.html#sec-generatorvalidate">GeneratorValidate</a></emu-xref>(<var>generator</var>, <var>generatorBrand</var>).</li><li>If <var>state</var> is <emu-const>completed</emu-const>, return <emu-xref aoid="CreateIteratorResultObject" id="_ref_16494"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).</li><li><emu-xref href="#assert" id="_ref_16495"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>state</var> is either <emu-const>suspended-start</emu-const> or <emu-const>suspended-yield</emu-const>.</li><li>Let <var>genContext</var> be <var>generator</var>.<var class="field">[[GeneratorContext]]</var>.</li><li>Let <var>methodContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16496"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Suspend <var>methodContext</var>.</li><li>Set <var>generator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>executing</emu-const>.</li><li>Push <var>genContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16497"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>genContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16498"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>genContext</var></span> using <emu-xref aoid="NormalCompletion" id="_ref_16499"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>) as the result of the operation that suspended it. Let <var>result</var> be the value returned by the resumed computation.</li><li><emu-xref href="#assert" id="_ref_16500"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we return here, <var>genContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16501"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>methodContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16502"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return ? <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatorresumeabrupt" type="abstract operation" aoid="GeneratorResumeAbrupt">
|
||
<h1><span class="secnum">27.5.3.4</span> GeneratorResumeAbrupt ( <var>generator</var>, <var>abruptCompletion</var>, <var>generatorBrand</var> )</h1>
|
||
<p>The abstract operation GeneratorResumeAbrupt takes arguments <var>generator</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16503"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>abruptCompletion</var> (a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16504"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16505"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>), and <var>generatorBrand</var> (a String or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16506"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16507"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16508"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>state</var> be ? <emu-xref aoid="GeneratorValidate" id="_ref_16509"><a href="control-abstraction-objects.html#sec-generatorvalidate">GeneratorValidate</a></emu-xref>(<var>generator</var>, <var>generatorBrand</var>).</li><li>If <var>state</var> is <emu-const>suspended-start</emu-const>, then<ol><li>Set <var>generator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>completed</emu-const>.</li><li>NOTE: Once a generator enters the <emu-const>completed</emu-const> state it never leaves it and its associated <emu-xref href="#sec-execution-contexts" id="_ref_16510"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> is never resumed. Any execution state associated with <var>generator</var> can be discarded at this point.</li><li>Set <var>state</var> to <emu-const>completed</emu-const>.</li></ol></li><li>If <var>state</var> is <emu-const>completed</emu-const>, then<ol><li>If <var>abruptCompletion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16511"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, then<ol><li>Return <emu-xref aoid="CreateIteratorResultObject" id="_ref_16512"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>abruptCompletion</var>.<var class="field">[[Value]]</var>, <emu-val>true</emu-val>).</li></ol></li><li>Return ? <var>abruptCompletion</var>.</li></ol></li><li><emu-xref href="#assert" id="_ref_16513"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>state</var> is <emu-const>suspended-yield</emu-const>.</li><li>Let <var>genContext</var> be <var>generator</var>.<var class="field">[[GeneratorContext]]</var>.</li><li>Let <var>methodContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16514"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Suspend <var>methodContext</var>.</li><li>Set <var>generator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>executing</emu-const>.</li><li>Push <var>genContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16515"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>genContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16516"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>genContext</var></span> using <var>abruptCompletion</var> as the result of the operation that suspended it. Let <var>result</var> be the <emu-xref href="#sec-completion-record-specification-type" id="_ref_16517"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> returned by the resumed computation.</li><li><emu-xref href="#assert" id="_ref_16518"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we return here, <var>genContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16519"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>methodContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16520"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return ? <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getgeneratorkind" type="abstract operation" aoid="GetGeneratorKind">
|
||
<h1><span class="secnum">27.5.3.5</span> GetGeneratorKind ( )</h1>
|
||
<p>The abstract operation GetGeneratorKind takes no arguments and returns <emu-const>non-generator</emu-const>, <emu-const>sync</emu-const>, or <emu-const>async</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>genContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16521"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>If <var>genContext</var> does not have a Generator component, return <emu-const>non-generator</emu-const>.</li><li>Let <var>generator</var> be the Generator component of <var>genContext</var>.</li><li>If <var>generator</var> has an <var class="field">[[AsyncGeneratorState]]</var> internal slot, return <emu-const>async</emu-const>.</li><li>Return <emu-const>sync</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-generatoryield" type="abstract operation" aoid="GeneratorYield">
|
||
<h1><span class="secnum">27.5.3.6</span> GeneratorYield ( <var>iteratorResult</var> )</h1>
|
||
<p>The abstract operation GeneratorYield takes argument <var>iteratorResult</var> (an Object that conforms to the <emu-xref href="#sec-iteratorresult-interface" id="_ref_16522"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult interface</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16523"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16524"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16525"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>genContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16526"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><emu-xref href="#assert" id="_ref_16527"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>genContext</var> is the <emu-xref href="#sec-execution-contexts" id="_ref_16528"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> of a generator.</li><li>Let <var>generator</var> be the value of the Generator component of <var>genContext</var>.</li><li><emu-xref href="#assert" id="_ref_16529"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="GetGeneratorKind" id="_ref_16530"><a href="control-abstraction-objects.html#sec-getgeneratorkind">GetGeneratorKind</a></emu-xref>() is <emu-const>sync</emu-const>.</li><li>Set <var>generator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>suspended-yield</emu-const>.</li><li>Remove <var>genContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16531"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16532"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16533"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16534"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>callerContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16535"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Resume <var>callerContext</var> passing <emu-xref aoid="NormalCompletion" id="_ref_16536"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>iteratorResult</var>). If <var>genContext</var> is ever resumed again, let <var>resumptionValue</var> be the <emu-xref href="#sec-completion-record-specification-type" id="_ref_16537"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> with which it is resumed.</li><li><emu-xref href="#assert" id="_ref_16538"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If control reaches here, then <var>genContext</var> is the <emu-xref href="#running-execution-context" id="_ref_16539"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref> again.</li><li>Return <var>resumptionValue</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-yield" type="abstract operation" aoid="Yield">
|
||
<h1><span class="secnum">27.5.3.7</span> Yield ( <var>value</var> )</h1>
|
||
<p>The abstract operation Yield takes argument <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16540"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16541"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16542"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16543"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>generatorKind</var> be <emu-xref aoid="GetGeneratorKind" id="_ref_16544"><a href="control-abstraction-objects.html#sec-getgeneratorkind">GetGeneratorKind</a></emu-xref>().</li><li>If <var>generatorKind</var> is <emu-const>async</emu-const>, return ? <emu-xref aoid="AsyncGeneratorYield" id="_ref_16545"><a href="control-abstraction-objects.html#sec-asyncgeneratoryield" class="e-user-code">AsyncGeneratorYield</a></emu-xref>(? <emu-xref aoid="Await" id="_ref_16546"><a href="control-abstraction-objects.html#await" class="e-user-code">Await</a></emu-xref>(<var>value</var>)).</li><li>Return ? <emu-xref aoid="GeneratorYield" id="_ref_16547"><a href="control-abstraction-objects.html#sec-generatoryield">GeneratorYield</a></emu-xref>(<emu-xref aoid="CreateIteratorResultObject" id="_ref_16548"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>value</var>, <emu-val>false</emu-val>)).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-createiteratorfromclosure" type="abstract operation" aoid="CreateIteratorFromClosure">
|
||
<h1><span class="secnum">27.5.3.8</span> CreateIteratorFromClosure ( <var>closure</var>, <var>generatorBrand</var>, <var>generatorPrototype</var> [ , <var>extraSlots</var> ] )</h1>
|
||
<p>The abstract operation CreateIteratorFromClosure takes arguments <var>closure</var> (an <emu-xref href="#sec-abstract-closure" id="_ref_16549"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters), <var>generatorBrand</var> (a String or <emu-const>empty</emu-const>), and <var>generatorPrototype</var> (an Object) and optional argument <var>extraSlots</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16550"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of names of internal slots) and returns a Generator. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>NOTE: <var>closure</var> can contain uses of the <emu-xref aoid="Yield" id="_ref_16551"><a href="control-abstraction-objects.html#sec-yield">Yield</a></emu-xref> operation to yield an <emu-xref href="#sec-iteratorresult-interface" id="_ref_16552"><a href="control-abstraction-objects.html#sec-iteratorresult-interface">IteratorResult object</a></emu-xref>.</li><li>If <var>extraSlots</var> is not present, set <var>extraSlots</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16553"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Let <var>internalSlotsList</var> be the <emu-xref href="#list-concatenation" id="_ref_16554"><a href="ecmascript-data-types-and-values.html#list-concatenation">list-concatenation</a></emu-xref> of <var>extraSlots</var> and « <var class="field">[[GeneratorState]]</var>, <var class="field">[[GeneratorContext]]</var>, <var class="field">[[GeneratorBrand]]</var> ».</li><li>Let <var>generator</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_16555"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<var>generatorPrototype</var>, <var>internalSlotsList</var>).</li><li>Set <var>generator</var>.<var class="field">[[GeneratorBrand]]</var> to <var>generatorBrand</var>.</li><li>Set <var>generator</var>.<var class="field">[[GeneratorState]]</var> to <emu-const>suspended-start</emu-const>.</li><li>Let <var>callerContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16556"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>calleeContext</var> be a new <emu-xref href="#sec-execution-contexts" id="_ref_16557"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>.</li><li>Set the Function of <var>calleeContext</var> to <emu-val>null</emu-val>.</li><li>Set the <emu-xref href="#realm" id="_ref_16558"><a href="executable-code-and-execution-contexts.html#realm">Realm</a></emu-xref> of <var>calleeContext</var> to <emu-xref href="#current-realm" id="_ref_16559"><a href="executable-code-and-execution-contexts.html#current-realm">the current Realm Record</a></emu-xref>.</li><li>Set the ScriptOrModule of <var>calleeContext</var> to <var>callerContext</var>'s ScriptOrModule.</li><li>If <var>callerContext</var> is not already suspended, suspend <var>callerContext</var>.</li><li>Push <var>calleeContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16560"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>calleeContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16561"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Perform <emu-xref aoid="GeneratorStart" id="_ref_16562"><a href="control-abstraction-objects.html#sec-generatorstart">GeneratorStart</a></emu-xref>(<var>generator</var>, <var>closure</var>).</li><li>Remove <var>calleeContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16563"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore <var>callerContext</var> as the <emu-xref href="#running-execution-context" id="_ref_16564"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return <var>generator</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgenerator-objects">
|
||
<h1><span class="secnum">27.6</span> AsyncGenerator Objects</h1>
|
||
<p>An AsyncGenerator is created by calling an async generator function and conforms to both the <emu-xref href="#sec-asynciterator-interface" id="_ref_16565"><a href="control-abstraction-objects.html#sec-asynciterator-interface">async iterator interface</a></emu-xref> and the <emu-xref href="#sec-asynciterable-interface" id="_ref_16566"><a href="control-abstraction-objects.html#sec-asynciterable-interface">async iterable interface</a></emu-xref>.</p>
|
||
|
||
<p>AsyncGenerator instances directly inherit properties from the initial value of the <emu-val>"prototype"</emu-val> property of the async generator function that created the instance. AsyncGenerator instances indirectly inherit properties from <emu-xref href="#sec-properties-of-asyncgenerator-prototype" id="_ref_16567"><a href="control-abstraction-objects.html#sec-properties-of-asyncgenerator-prototype">%AsyncGeneratorPrototype%</a></emu-xref>.</p>
|
||
|
||
<emu-clause id="sec-properties-of-asyncgenerator-prototype">
|
||
<h1><span class="secnum">27.6.1</span> The %AsyncGeneratorPrototype% Object</h1>
|
||
<p>The <dfn tabindex="-1">%AsyncGeneratorPrototype%</dfn> object:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%AsyncGeneratorFunction.prototype.prototype%</dfn>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16568"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>is not an AsyncGenerator instance and does not have an <var class="field">[[AsyncGeneratorState]]</var> internal slot.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-asynciteratorprototype" id="_ref_16569"><a href="control-abstraction-objects.html#sec-asynciteratorprototype">%AsyncIteratorPrototype%</a></emu-xref>.</li>
|
||
<li>has properties that are indirectly inherited by all AsyncGenerator instances.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-asyncgenerator-prototype-constructor">
|
||
<h1><span class="secnum">27.6.1.1</span> %AsyncGeneratorPrototype%.constructor</h1>
|
||
<p>The initial value of <emu-xref href="#sec-properties-of-asyncgenerator-prototype" id="_ref_16570"><a href="control-abstraction-objects.html#sec-properties-of-asyncgenerator-prototype">%AsyncGeneratorPrototype%</a></emu-xref><code>.constructor</code> is <emu-xref href="#sec-properties-of-asyncgeneratorfunction-prototype" id="_ref_16571"><a href="control-abstraction-objects.html#sec-properties-of-asyncgeneratorfunction-prototype">%AsyncGeneratorFunction.prototype%</a></emu-xref>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgenerator-prototype-next" type="built-in function">
|
||
<h1><span class="secnum">27.6.1.2</span> %AsyncGeneratorPrototype%.next ( <var>value</var> )</h1>
|
||
<emu-alg><ol><li>Let <var>generator</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_16572"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_16573"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16574"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="AsyncGeneratorValidate" id="_ref_16575"><a href="control-abstraction-objects.html#sec-asyncgeneratorvalidate">AsyncGeneratorValidate</a></emu-xref>(<var>generator</var>, <emu-const>empty</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16576"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>Let <var>state</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var>.</li><li>If <var>state</var> is <emu-const>completed</emu-const>, then<ol><li>Let <var>iteratorResult</var> be <emu-xref aoid="CreateIteratorResultObject" id="_ref_16577"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).</li><li>Perform ! <emu-xref aoid="Call" id="_ref_16578"><a href="abstract-operations.html#sec-call" class="e-user-code e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>iteratorResult</var> »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Let <var>completion</var> be <emu-xref aoid="NormalCompletion" id="_ref_16579"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorEnqueue" id="_ref_16580"><a href="control-abstraction-objects.html#sec-asyncgeneratorenqueue">AsyncGeneratorEnqueue</a></emu-xref>(<var>generator</var>, <var>completion</var>, <var>promiseCapability</var>).</li><li>If <var>state</var> is either <emu-const>suspended-start</emu-const> or <emu-const>suspended-yield</emu-const>, then<ol><li>Perform <emu-xref aoid="AsyncGeneratorResume" id="_ref_16581"><a href="control-abstraction-objects.html#sec-asyncgeneratorresume" class="e-user-code">AsyncGeneratorResume</a></emu-xref>(<var>generator</var>, <var>completion</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16582"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>state</var> is either <emu-const>executing</emu-const> or <emu-const>draining-queue</emu-const>.</li></ol></li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgenerator-prototype-return" type="built-in function">
|
||
<h1><span class="secnum">27.6.1.3</span> %AsyncGeneratorPrototype%.return ( <var>value</var> )</h1>
|
||
<emu-alg><ol><li>Let <var>generator</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_16583"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_16584"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16585"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="AsyncGeneratorValidate" id="_ref_16586"><a href="control-abstraction-objects.html#sec-asyncgeneratorvalidate">AsyncGeneratorValidate</a></emu-xref>(<var>generator</var>, <emu-const>empty</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16587"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>Let <var>completion</var> be <emu-xref aoid="ReturnCompletion" id="_ref_16588"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<var>value</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorEnqueue" id="_ref_16589"><a href="control-abstraction-objects.html#sec-asyncgeneratorenqueue">AsyncGeneratorEnqueue</a></emu-xref>(<var>generator</var>, <var>completion</var>, <var>promiseCapability</var>).</li><li>Let <var>state</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var>.</li><li>If <var>state</var> is either <emu-const>suspended-start</emu-const> or <emu-const>completed</emu-const>, then<ol><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>draining-queue</emu-const>.</li><li>Perform <emu-xref aoid="AsyncGeneratorAwaitReturn" id="_ref_16590"><a href="control-abstraction-objects.html#sec-asyncgeneratorawaitreturn" class="e-user-code">AsyncGeneratorAwaitReturn</a></emu-xref>(<var>generator</var>).</li></ol></li><li>Else if <var>state</var> is <emu-const>suspended-yield</emu-const>, then<ol><li>Perform <emu-xref aoid="AsyncGeneratorResume" id="_ref_16591"><a href="control-abstraction-objects.html#sec-asyncgeneratorresume" class="e-user-code">AsyncGeneratorResume</a></emu-xref>(<var>generator</var>, <var>completion</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16592"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>state</var> is either <emu-const>executing</emu-const> or <emu-const>draining-queue</emu-const>.</li></ol></li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgenerator-prototype-throw" type="built-in function">
|
||
<h1><span class="secnum">27.6.1.4</span> %AsyncGeneratorPrototype%.throw ( <var>exception</var> )</h1>
|
||
<emu-alg><ol><li>Let <var>generator</var> be the <emu-val>this</emu-val> value.</li><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_16593"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_16594"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16595"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="AsyncGeneratorValidate" id="_ref_16596"><a href="control-abstraction-objects.html#sec-asyncgeneratorvalidate">AsyncGeneratorValidate</a></emu-xref>(<var>generator</var>, <emu-const>empty</emu-const>)).</li><li><emu-xref aoid="IfAbruptRejectPromise" id="_ref_16597"><a href="control-abstraction-objects.html#sec-ifabruptrejectpromise" class="e-user-code">IfAbruptRejectPromise</a></emu-xref>(<var>result</var>, <var>promiseCapability</var>).</li><li>Let <var>state</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var>.</li><li>If <var>state</var> is <emu-const>suspended-start</emu-const>, then<ol><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>completed</emu-const>.</li><li>Set <var>state</var> to <emu-const>completed</emu-const>.</li></ol></li><li>If <var>state</var> is <emu-const>completed</emu-const>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_16598"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>exception</var> »).</li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></li><li>Let <var>completion</var> be <emu-xref aoid="ThrowCompletion" id="_ref_16599"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>exception</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorEnqueue" id="_ref_16600"><a href="control-abstraction-objects.html#sec-asyncgeneratorenqueue">AsyncGeneratorEnqueue</a></emu-xref>(<var>generator</var>, <var>completion</var>, <var>promiseCapability</var>).</li><li>If <var>state</var> is <emu-const>suspended-yield</emu-const>, then<ol><li>Perform <emu-xref aoid="AsyncGeneratorResume" id="_ref_16601"><a href="control-abstraction-objects.html#sec-asyncgeneratorresume" class="e-user-code">AsyncGeneratorResume</a></emu-xref>(<var>generator</var>, <var>completion</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16602"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>state</var> is either <emu-const>executing</emu-const> or <emu-const>draining-queue</emu-const>.</li></ol></li><li>Return <var>promiseCapability</var>.<var class="field">[[Promise]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-asyncgenerator-prototype-tostringtag" id="sec-asyncgenerator-prototype-%symbol.tostringtag%"><span id="sec-asyncgenerator-prototype-tostringtag"></span>
|
||
<h1><span class="secnum">27.6.1.5</span> %AsyncGeneratorPrototype% [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16603"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"AsyncGenerator"</emu-val>.</p>
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-asyncgenerator-intances">
|
||
<h1><span class="secnum">27.6.2</span> Properties of AsyncGenerator Instances</h1>
|
||
<p>AsyncGenerator instances are initially created with the internal slots described below:</p>
|
||
<emu-table id="table-internal-slots-of-asyncgenerator-instances" caption="Internal Slots of AsyncGenerator Instances"><figure><figcaption>Table 89: Internal Slots of AsyncGenerator Instances</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Internal Slot</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><var class="field">[[AsyncGeneratorState]]</var></td>
|
||
<td><emu-const>suspended-start</emu-const>, <emu-const>suspended-yield</emu-const>, <emu-const>executing</emu-const>, <emu-const>draining-queue</emu-const>, or <emu-const>completed</emu-const></td>
|
||
<td>The current execution state of the async generator.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[AsyncGeneratorContext]]</var></td>
|
||
<td>an <emu-xref href="#sec-execution-contexts" id="_ref_16604"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref></td>
|
||
<td>The <emu-xref href="#sec-execution-contexts" id="_ref_16605"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is used when executing the code of this async generator.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[AsyncGeneratorQueue]]</var></td>
|
||
<td>a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16606"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-asyncgeneratorrequest-records" id="_ref_16607"><a href="control-abstraction-objects.html#sec-asyncgeneratorrequest-records">AsyncGeneratorRequest</a></emu-xref> <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16608"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Records</a></emu-xref></td>
|
||
<td><emu-xref href="#sec-list-and-record-specification-type" id="_ref_16609"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Records</a></emu-xref> which represent requests to resume the async generator. Except during state transitions, it is non-empty if and only if <var class="field">[[AsyncGeneratorState]]</var> is either <emu-const>executing</emu-const> or <emu-const>draining-queue</emu-const>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[GeneratorBrand]]</var></td>
|
||
<td>a String or <emu-const>empty</emu-const></td>
|
||
<td>A brand used to distinguish different kinds of async generators. The <var class="field">[[GeneratorBrand]]</var> of async generators declared by <emu-xref href="#sec-source-text" id="_ref_16610"><a href="ecmascript-language-source-code.html#sec-source-text">ECMAScript source text</a></emu-xref> is always <emu-const>empty</emu-const>.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgenerator-abstract-operations">
|
||
<h1><span class="secnum">27.6.3</span> AsyncGenerator Abstract Operations</h1>
|
||
|
||
<emu-clause id="sec-asyncgeneratorrequest-records">
|
||
<h1><span class="secnum">27.6.3.1</span> AsyncGeneratorRequest Records</h1>
|
||
<p>An <dfn variants="AsyncGeneratorRequests" tabindex="-1">AsyncGeneratorRequest</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16611"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> value used to store information about how an async generator should be resumed and contains capabilities for fulfilling or rejecting the corresponding promise.</p>
|
||
<p>They have the following fields:</p>
|
||
<emu-table caption="AsyncGeneratorRequest Record Fields"><figure><figcaption>Table 90: AsyncGeneratorRequest <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16612"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> Fields</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field Name</th>
|
||
<th>Value</th>
|
||
<th>Meaning</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><var class="field">[[Completion]]</var></td>
|
||
<td>a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16613"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref></td>
|
||
<td>The <emu-xref href="#sec-completion-record-specification-type" id="_ref_16614"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> which should be used to resume the async generator.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[Capability]]</var></td>
|
||
<td>a <emu-xref href="#sec-promisecapability-records" id="_ref_16615"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref></td>
|
||
<td>The promise capabilities associated with this request.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorstart" type="abstract operation" aoid="AsyncGeneratorStart">
|
||
<h1><span class="secnum">27.6.3.2</span> AsyncGeneratorStart ( <var>generator</var>, <var>generatorBody</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorStart takes arguments <var>generator</var> (an AsyncGenerator) and <var>generatorBody</var> (a <emu-nt id="_ref_24562"><a href="ecmascript-language-functions-and-classes.html#prod-FunctionBody">FunctionBody</a></emu-nt> <emu-xref href="#sec-syntactic-grammar" id="_ref_16616"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref> or an <emu-xref href="#sec-abstract-closure" id="_ref_16617"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16618"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is <emu-const>suspended-start</emu-const>.</li><li>Let <var>genContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16619"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Set the Generator component of <var>genContext</var> to <var>generator</var>.</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16620"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>generatorBody</var> and performs the following steps when called:<ol><li>Let <var>acGenContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16621"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>acGenerator</var> be the Generator component of <var>acGenContext</var>.</li><li>If <var>generatorBody</var> is a <emu-xref href="#sec-syntactic-grammar" id="_ref_16622"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16623"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Evaluation" id="_ref_16624"><a href="syntax-directed-operations.html#sec-evaluation" class="e-user-code">Evaluation</a></emu-xref> of <var>generatorBody</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16625"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generatorBody</var> is an <emu-xref href="#sec-abstract-closure" id="_ref_16626"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16627"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>generatorBody</var>()).</li></ol></li><li><emu-xref href="#assert" id="_ref_16628"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If we return here, the async generator either threw an exception or performed either an implicit or explicit return.</li><li>Remove <var>acGenContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16629"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16630"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16631"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16632"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Set <var>acGenerator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>draining-queue</emu-const>.</li><li>If <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16633"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, set <var>result</var> to <emu-xref aoid="NormalCompletion" id="_ref_16634"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li><li>If <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16635"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, set <var>result</var> to <emu-xref aoid="NormalCompletion" id="_ref_16636"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>result</var>.<var class="field">[[Value]]</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16637"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>acGenerator</var>, <var>result</var>, <emu-val>true</emu-val>).</li><li>Perform <emu-xref aoid="AsyncGeneratorDrainQueue" id="_ref_16638"><a href="control-abstraction-objects.html#sec-asyncgeneratordrainqueue" class="e-user-code">AsyncGeneratorDrainQueue</a></emu-xref>(<var>acGenerator</var>).</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16639"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Set the code evaluation state of <var>genContext</var> such that when evaluation is resumed for that <emu-xref href="#sec-execution-contexts" id="_ref_16640"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>, <var>closure</var> will be called with no arguments.</li><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorContext]]</var> to <var>genContext</var>.</li><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_16641"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorvalidate" type="abstract operation" aoid="AsyncGeneratorValidate">
|
||
<h1><span class="secnum">27.6.3.3</span> AsyncGeneratorValidate ( <var>generator</var>, <var>generatorBrand</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorValidate takes arguments <var>generator</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16642"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and <var>generatorBrand</var> (a String or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16643"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> <emu-const>unused</emu-const> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16644"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_16645"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>generator</var>, <var class="field">[[AsyncGeneratorContext]]</var>).</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_16646"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>generator</var>, <var class="field">[[AsyncGeneratorState]]</var>).</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_16647"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>generator</var>, <var class="field">[[AsyncGeneratorQueue]]</var>).</li><li>If <var>generator</var>.<var class="field">[[GeneratorBrand]]</var> is not <var>generatorBrand</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorenqueue" type="abstract operation" aoid="AsyncGeneratorEnqueue">
|
||
<h1><span class="secnum">27.6.3.4</span> AsyncGeneratorEnqueue ( <var>generator</var>, <var>completion</var>, <var>promiseCapability</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorEnqueue takes arguments <var>generator</var> (an AsyncGenerator), <var>completion</var> (a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16648"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref>), and <var>promiseCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16649"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>request</var> be <emu-xref href="#sec-asyncgeneratorrequest-records" id="_ref_16650"><a href="control-abstraction-objects.html#sec-asyncgeneratorrequest-records">AsyncGeneratorRequest</a></emu-xref> { <var class="field">[[Completion]]</var>: <var>completion</var>, <var class="field">[[Capability]]</var>: <var>promiseCapability</var> }.</li><li>Append <var>request</var> to <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorcompletestep" type="abstract operation" aoid="AsyncGeneratorCompleteStep">
|
||
<h1><span class="secnum">27.6.3.5</span> AsyncGeneratorCompleteStep ( <var>generator</var>, <var>completion</var>, <var>done</var> [ , <var>realm</var> ] )</h1>
|
||
<p>The abstract operation AsyncGeneratorCompleteStep takes arguments <var>generator</var> (an AsyncGenerator), <var>completion</var> (a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16651"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref>), and <var>done</var> (a Boolean) and optional argument <var>realm</var> (a <emu-xref href="#realm-record" id="_ref_16652"><a href="executable-code-and-execution-contexts.html#realm-record">Realm Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16653"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var> is not empty.</li><li>Let <var>next</var> be the first element of <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li>Remove the first element from <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li>Let <var>promiseCapability</var> be <var>next</var>.<var class="field">[[Capability]]</var>.</li><li>Let <var>value</var> be <var>completion</var>.<var class="field">[[Value]]</var>.</li><li>If <var>completion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16654"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_16655"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>value</var> »).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16656"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>completion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16657"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>.</li><li>If <var>realm</var> is present, then<ol><li>Let <var>oldRealm</var> be the <emu-xref href="#running-execution-context" id="_ref_16658"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>'s <emu-xref href="#realm" id="_ref_16659"><a href="executable-code-and-execution-contexts.html#realm">Realm</a></emu-xref>.</li><li>Set the <emu-xref href="#running-execution-context" id="_ref_16660"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>'s <emu-xref href="#realm" id="_ref_16661"><a href="executable-code-and-execution-contexts.html#realm">Realm</a></emu-xref> to <var>realm</var>.</li><li>Let <var>iteratorResult</var> be <emu-xref aoid="CreateIteratorResultObject" id="_ref_16662"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>value</var>, <var>done</var>).</li><li>Set the <emu-xref href="#running-execution-context" id="_ref_16663"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>'s <emu-xref href="#realm" id="_ref_16664"><a href="executable-code-and-execution-contexts.html#realm">Realm</a></emu-xref> to <var>oldRealm</var>.</li></ol></li><li>Else,<ol><li>Let <var>iteratorResult</var> be <emu-xref aoid="CreateIteratorResultObject" id="_ref_16665"><a href="abstract-operations.html#sec-createiterresultobject">CreateIteratorResultObject</a></emu-xref>(<var>value</var>, <var>done</var>).</li></ol></li><li>Perform ! <emu-xref aoid="Call" id="_ref_16666"><a href="abstract-operations.html#sec-call" class="e-user-code e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>iteratorResult</var> »).</li></ol></li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorresume" type="abstract operation" aoid="AsyncGeneratorResume">
|
||
<h1><span class="secnum">27.6.3.6</span> AsyncGeneratorResume ( <var>generator</var>, <var>completion</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorResume takes arguments <var>generator</var> (an AsyncGenerator) and <var>completion</var> (a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16667"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16668"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is either <emu-const>suspended-start</emu-const> or <emu-const>suspended-yield</emu-const>.</li><li>Let <var>genContext</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorContext]]</var>.</li><li>Let <var>callerContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16669"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Suspend <var>callerContext</var>.</li><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>executing</emu-const>.</li><li>Push <var>genContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16670"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>genContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16671"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>genContext</var></span> using <var>completion</var> as the result of the operation that suspended it. Let <var>result</var> be the <emu-xref href="#sec-completion-record-specification-type" id="_ref_16672"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> returned by the resumed computation.</li><li><emu-xref href="#assert" id="_ref_16673"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>result</var> is never an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16674"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>.</li><li><emu-xref href="#assert" id="_ref_16675"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we return here, <var>genContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16676"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>callerContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16677"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorunwrapyieldresumption" type="abstract operation" aoid="AsyncGeneratorUnwrapYieldResumption">
|
||
<h1><span class="secnum">27.6.3.7</span> AsyncGeneratorUnwrapYieldResumption ( <var>resumptionValue</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorUnwrapYieldResumption takes argument <var>resumptionValue</var> (a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16678"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16679"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16680"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16681"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>resumptionValue</var> is not a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16682"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, return ? <var>resumptionValue</var>.</li><li>Let <var>awaited</var> be <emu-xref aoid="Completion" id="_ref_16683"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Await" id="_ref_16684"><a href="control-abstraction-objects.html#await" class="e-user-code">Await</a></emu-xref>(<var>resumptionValue</var>.<var class="field">[[Value]]</var>)).</li><li>If <var>awaited</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16685"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>, return ? <var>awaited</var>.</li><li><emu-xref href="#assert" id="_ref_16686"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>awaited</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16687"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>.</li><li>Return <emu-xref aoid="ReturnCompletion" id="_ref_16688"><a href="ecmascript-data-types-and-values.html#sec-returncompletion">ReturnCompletion</a></emu-xref>(<var>awaited</var>.<var class="field">[[Value]]</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratoryield" type="abstract operation" aoid="AsyncGeneratorYield">
|
||
<h1><span class="secnum">27.6.3.8</span> AsyncGeneratorYield ( <var>value</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorYield takes argument <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16689"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16690"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16691"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16692"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>genContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16693"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><emu-xref href="#assert" id="_ref_16694"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>genContext</var> is the <emu-xref href="#sec-execution-contexts" id="_ref_16695"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> of a generator.</li><li>Let <var>generator</var> be the value of the Generator component of <var>genContext</var>.</li><li><emu-xref href="#assert" id="_ref_16696"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="GetGeneratorKind" id="_ref_16697"><a href="control-abstraction-objects.html#sec-getgeneratorkind">GetGeneratorKind</a></emu-xref>() is <emu-const>async</emu-const>.</li><li>Let <var>completion</var> be <emu-xref aoid="NormalCompletion" id="_ref_16698"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>).</li><li><emu-xref href="#assert" id="_ref_16699"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#execution-context-stack" id="_ref_16700"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> has at least two elements.</li><li>Let <var>previousContext</var> be the second to top element of the <emu-xref href="#execution-context-stack" id="_ref_16701"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>.</li><li>Let <var>previousRealm</var> be <var>previousContext</var>'s <emu-xref href="#realm" id="_ref_16702"><a href="executable-code-and-execution-contexts.html#realm">Realm</a></emu-xref>.</li><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16703"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>generator</var>, <var>completion</var>, <emu-val>false</emu-val>, <var>previousRealm</var>).</li><li>Let <var>queue</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li>If <var>queue</var> is not empty, then<ol><li>NOTE: Execution continues without suspending the generator.</li><li>Let <var>toYield</var> be the first element of <var>queue</var>.</li><li>Let <var>resumptionValue</var> be <emu-xref aoid="Completion" id="_ref_16704"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>toYield</var>.<var class="field">[[Completion]]</var>).</li><li>Return ? <emu-xref aoid="AsyncGeneratorUnwrapYieldResumption" id="_ref_16705"><a href="control-abstraction-objects.html#sec-asyncgeneratorunwrapyieldresumption" class="e-user-code">AsyncGeneratorUnwrapYieldResumption</a></emu-xref>(<var>resumptionValue</var>).</li></ol></li><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>suspended-yield</emu-const>.</li><li>Remove <var>genContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16706"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16707"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16708"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16709"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>callerContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16710"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Resume <var>callerContext</var> passing <emu-val>undefined</emu-val>. If <var>genContext</var> is ever resumed again, let <var>resumptionValue</var> be the <emu-xref href="#sec-completion-record-specification-type" id="_ref_16711"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> with which it is resumed.</li><li><emu-xref href="#assert" id="_ref_16712"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If control reaches here, then <var>genContext</var> is the <emu-xref href="#running-execution-context" id="_ref_16713"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref> again.</li><li>Return ? <emu-xref aoid="AsyncGeneratorUnwrapYieldResumption" id="_ref_16714"><a href="control-abstraction-objects.html#sec-asyncgeneratorunwrapyieldresumption" class="e-user-code">AsyncGeneratorUnwrapYieldResumption</a></emu-xref>(<var>resumptionValue</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratorawaitreturn" type="abstract operation" aoid="AsyncGeneratorAwaitReturn">
|
||
<h1><span class="secnum">27.6.3.9</span> AsyncGeneratorAwaitReturn ( <var>generator</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorAwaitReturn takes argument <var>generator</var> (an AsyncGenerator) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16715"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is <emu-const>draining-queue</emu-const>.</li><li>Let <var>queue</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li><emu-xref href="#assert" id="_ref_16716"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>queue</var> is not empty.</li><li>Let <var>next</var> be the first element of <var>queue</var>.</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_16717"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>next</var>.<var class="field">[[Completion]]</var>).</li><li><emu-xref href="#assert" id="_ref_16718"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>completion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16719"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>.</li><li>Let <var>promiseCompletion</var> be <emu-xref aoid="Completion" id="_ref_16720"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="PromiseResolve" id="_ref_16721"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_16722"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>, <var>completion</var>.<var class="field">[[Value]]</var>)).</li><li>If <var>promiseCompletion</var> is an <emu-xref href="#sec-completion-record-specification-type" id="_ref_16723"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">abrupt completion</a></emu-xref>, then<ol><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16724"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>generator</var>, <var>promiseCompletion</var>, <emu-val>true</emu-val>).</li><li>Perform <emu-xref aoid="AsyncGeneratorDrainQueue" id="_ref_16725"><a href="control-abstraction-objects.html#sec-asyncgeneratordrainqueue" class="e-user-code">AsyncGeneratorDrainQueue</a></emu-xref>(<var>generator</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></li><li><emu-xref href="#assert" id="_ref_16726"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>promiseCompletion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16727"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>.</li><li>Let <var>promise</var> be <var>promiseCompletion</var>.<var class="field">[[Value]]</var>.</li><li>Let <var>fulfilledClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16728"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>value</var>) that captures <var>generator</var> and performs the following steps when called:<ol><li><emu-xref href="#assert" id="_ref_16729"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is <emu-const>draining-queue</emu-const>.</li><li>Let <var>result</var> be <emu-xref aoid="NormalCompletion" id="_ref_16730"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>value</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16731"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>generator</var>, <var>result</var>, <emu-val>true</emu-val>).</li><li>Perform <emu-xref aoid="AsyncGeneratorDrainQueue" id="_ref_16732"><a href="control-abstraction-objects.html#sec-asyncgeneratordrainqueue" class="e-user-code">AsyncGeneratorDrainQueue</a></emu-xref>(<var>generator</var>).</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16733"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>onFulfilled</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16734"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>fulfilledClosure</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Let <var>rejectedClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16735"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>reason</var>) that captures <var>generator</var> and performs the following steps when called:<ol><li><emu-xref href="#assert" id="_ref_16736"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is <emu-const>draining-queue</emu-const>.</li><li>Let <var>result</var> be <emu-xref aoid="ThrowCompletion" id="_ref_16737"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>reason</var>).</li><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16738"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>generator</var>, <var>result</var>, <emu-val>true</emu-val>).</li><li>Perform <emu-xref aoid="AsyncGeneratorDrainQueue" id="_ref_16739"><a href="control-abstraction-objects.html#sec-asyncgeneratordrainqueue" class="e-user-code">AsyncGeneratorDrainQueue</a></emu-xref>(<var>generator</var>).</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16740"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>onRejected</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16741"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>rejectedClosure</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Perform <emu-xref aoid="PerformPromiseThen" id="_ref_16742"><a href="control-abstraction-objects.html#sec-performpromisethen">PerformPromiseThen</a></emu-xref>(<var>promise</var>, <var>onFulfilled</var>, <var>onRejected</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncgeneratordrainqueue" type="abstract operation" aoid="AsyncGeneratorDrainQueue">
|
||
<h1><span class="secnum">27.6.3.10</span> AsyncGeneratorDrainQueue ( <var>generator</var> )</h1>
|
||
<p>The abstract operation AsyncGeneratorDrainQueue takes argument <var>generator</var> (an AsyncGenerator) and returns <emu-const>unused</emu-const>. It drains the generator's AsyncGeneratorQueue until it encounters an <emu-xref href="#sec-asyncgeneratorrequest-records" id="_ref_16743"><a href="control-abstraction-objects.html#sec-asyncgeneratorrequest-records">AsyncGeneratorRequest</a></emu-xref> which holds a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16744"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_16745"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> is <emu-const>draining-queue</emu-const>.</li><li>Let <var>queue</var> be <var>generator</var>.<var class="field">[[AsyncGeneratorQueue]]</var>.</li><li>Repeat, while <var>queue</var> is not empty,<ol><li>Let <var>next</var> be the first element of <var>queue</var>.</li><li>Let <var>completion</var> be <emu-xref aoid="Completion" id="_ref_16746"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>next</var>.<var class="field">[[Completion]]</var>).</li><li>If <var>completion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16747"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, then<ol><li>Perform <emu-xref aoid="AsyncGeneratorAwaitReturn" id="_ref_16748"><a href="control-abstraction-objects.html#sec-asyncgeneratorawaitreturn" class="e-user-code">AsyncGeneratorAwaitReturn</a></emu-xref>(<var>generator</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></li><li>If <var>completion</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16749"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, then<ol><li>Set <var>completion</var> to <emu-xref aoid="NormalCompletion" id="_ref_16750"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Perform <emu-xref aoid="AsyncGeneratorCompleteStep" id="_ref_16751"><a href="control-abstraction-objects.html#sec-asyncgeneratorcompletestep" class="e-user-code">AsyncGeneratorCompleteStep</a></emu-xref>(<var>generator</var>, <var>completion</var>, <emu-val>true</emu-val>).</li></ol></li><li>Set <var>generator</var>.<var class="field">[[AsyncGeneratorState]]</var> to <emu-const>completed</emu-const>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-function-objects">
|
||
<h1><span class="secnum">27.7</span> AsyncFunction Objects</h1>
|
||
<p>AsyncFunctions are functions that are usually created by evaluating <emu-nt id="_ref_24563"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncFunctionDeclaration">AsyncFunctionDeclaration</a></emu-nt>s, <emu-nt id="_ref_24564"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncFunctionExpression">AsyncFunctionExpression</a></emu-nt>s, <emu-nt id="_ref_24565"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncMethod">AsyncMethod</a></emu-nt>s, and <emu-nt id="_ref_24566"><a href="ecmascript-language-functions-and-classes.html#prod-AsyncArrowFunction">AsyncArrowFunction</a></emu-nt>s. They may also be created by calling the <emu-xref href="#sec-async-function-constructor" id="_ref_16752"><a href="control-abstraction-objects.html#sec-async-function-constructor">%AsyncFunction%</a></emu-xref> intrinsic.</p>
|
||
|
||
<emu-clause id="sec-async-function-constructor">
|
||
<h1><span class="secnum">27.7.1</span> The AsyncFunction Constructor</h1>
|
||
|
||
<p>The AsyncFunction <emu-xref href="#constructor" id="_ref_16753"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%AsyncFunction%</dfn>.</li>
|
||
<li>is a subclass of <code>Function</code>.</li>
|
||
<li>creates and initializes a new AsyncFunction when called as a function rather than as a <emu-xref href="#constructor" id="_ref_16754"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>. Thus the function call <code>AsyncFunction(…)</code> is equivalent to the object creation expression <code>new AsyncFunction(…)</code> with the same arguments.</li>
|
||
<li>may be used as the value of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_16755"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified AsyncFunction behaviour must include a <code>super</code> call to the AsyncFunction <emu-xref href="#constructor" id="_ref_16756"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> 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 <emu-xref href="#function-object" id="_ref_16757"><a href="ecmascript-data-types-and-values.html#function-object">function objects</a></emu-xref> create direct instances of AsyncFunction. There is no syntactic means to create instances of AsyncFunction subclasses.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-async-function-constructor-arguments" type="built-in function">
|
||
<h1><span class="secnum">27.7.1.1</span> AsyncFunction ( ...<var>parameterArgs</var>, <var>bodyArg</var> )</h1>
|
||
<p>The last argument (if any) specifies the body (executable code) of an async function. Any preceding arguments specify formal parameters.</p>
|
||
<p>This function performs the following steps when called:</p>
|
||
|
||
<emu-alg><ol><li>Let <var>C</var> be the <emu-xref href="#active-function-object" id="_ref_16758"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>If <var>bodyArg</var> is not present, set <var>bodyArg</var> to the empty String.</li><li>Return ? <emu-xref aoid="CreateDynamicFunction" id="_ref_16759"><a href="fundamental-objects.html#sec-createdynamicfunction" class="e-user-code">CreateDynamicFunction</a></emu-xref>(<var>C</var>, NewTarget, <emu-const>async</emu-const>, <var>parameterArgs</var>, <var>bodyArg</var>).</li></ol></emu-alg>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">See NOTE for <emu-xref href="#sec-function-p1-p2-pn-body" id="_ref_842"><a href="fundamental-objects.html#sec-function-p1-p2-pn-body">20.2.1.1</a></emu-xref>.</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-function-constructor-properties">
|
||
<h1><span class="secnum">27.7.2</span> Properties of the AsyncFunction Constructor</h1>
|
||
|
||
<p>The AsyncFunction <emu-xref href="#constructor" id="_ref_16760"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is a standard built-in <emu-xref href="#function-object" id="_ref_16761"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> that inherits from the Function <emu-xref href="#constructor" id="_ref_16762"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-function-constructor" id="_ref_16763"><a href="fundamental-objects.html#sec-function-constructor">%Function%</a></emu-xref>.</li>
|
||
<li oldids="sec-async-function-constructor-length"><span id="sec-async-function-constructor-length"></span>has a <emu-val>"length"</emu-val> property whose value is <emu-val>1</emu-val><sub>𝔽</sub>.</li>
|
||
<li>has a <emu-val>"name"</emu-val> property whose value is <emu-val>"AsyncFunction"</emu-val>.</li>
|
||
<li>has the following properties:</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-async-function-constructor-prototype">
|
||
<h1><span class="secnum">27.7.2.1</span> AsyncFunction.prototype</h1>
|
||
<p>The initial value of <code>AsyncFunction.prototype</code> is the <emu-xref href="#sec-async-function-prototype-properties" id="_ref_16764"><a href="control-abstraction-objects.html#sec-async-function-prototype-properties">AsyncFunction prototype object</a></emu-xref>.</p>
|
||
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-function-prototype-properties">
|
||
<h1><span class="secnum">27.7.3</span> Properties of the AsyncFunction Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">AsyncFunction prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%AsyncFunction.prototype%</dfn>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_16765"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>is not a <emu-xref href="#function-object" id="_ref_16766"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and does not have an <var class="field">[[ECMAScriptCode]]</var> internal slot or any other of the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_843"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref>.</li>
|
||
<li>has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_16767"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-async-function-prototype-properties-constructor">
|
||
<h1><span class="secnum">27.7.3.1</span> AsyncFunction.prototype.constructor</h1>
|
||
|
||
<p>The initial value of <code>AsyncFunction.prototype.constructor</code> is <emu-xref href="#sec-async-function-constructor" id="_ref_16768"><a href="control-abstraction-objects.html#sec-async-function-constructor">%AsyncFunction%</a></emu-xref>.</p>
|
||
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-async-function-prototype-properties-toStringTag" id="sec-async-function-prototype-%symbol.tostringtag%"><span id="sec-async-function-prototype-properties-toStringTag"></span>
|
||
<h1><span class="secnum">27.7.3.2</span> AsyncFunction.prototype [ %Symbol.toStringTag% ]</h1>
|
||
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_16769"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"AsyncFunction"</emu-val>.</p>
|
||
|
||
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-function-instances">
|
||
<h1><span class="secnum">27.7.4</span> AsyncFunction Instances</h1>
|
||
|
||
<p>Every AsyncFunction instance is an ECMAScript <emu-xref href="#function-object" id="_ref_16770"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> and has the internal slots listed in <emu-xref href="#table-internal-slots-of-ecmascript-function-objects" id="_ref_844"><a href="ordinary-and-exotic-objects-behaviours.html#table-internal-slots-of-ecmascript-function-objects">Table 25</a></emu-xref>. The value of the <var class="field">[[IsClassConstructor]]</var> internal slot for all such instances is <emu-val>false</emu-val>. AsyncFunction instances are not <emu-xref href="#constructor" id="_ref_16771"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> and do not have a <var class="field">[[Construct]]</var> internal method. AsyncFunction instances do not have a prototype property as they are not constructable.</p>
|
||
<p>Each AsyncFunction instance has the following own properties:</p>
|
||
|
||
<emu-clause id="sec-async-function-instances-length">
|
||
<h1><span class="secnum">27.7.4.1</span> length</h1>
|
||
<p>The specification for the <emu-val>"length"</emu-val> property of Function instances given in <emu-xref href="#sec-function-instances-length" id="_ref_845"><a href="fundamental-objects.html#sec-function-instances-length">20.2.4.1</a></emu-xref> also applies to AsyncFunction instances.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-function-instances-name">
|
||
<h1><span class="secnum">27.7.4.2</span> name</h1>
|
||
<p>The specification for the <emu-val>"name"</emu-val> property of Function instances given in <emu-xref href="#sec-function-instances-name" id="_ref_846"><a href="fundamental-objects.html#sec-function-instances-name">20.2.4.2</a></emu-xref> also applies to AsyncFunction instances.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-async-functions-abstract-operations">
|
||
<h1><span class="secnum">27.7.5</span> Async Functions Abstract Operations</h1>
|
||
|
||
<emu-clause id="sec-async-functions-abstract-operations-async-function-start" type="abstract operation" aoid="AsyncFunctionStart">
|
||
<h1><span class="secnum">27.7.5.1</span> AsyncFunctionStart ( <var>promiseCapability</var>, <var>asyncFunctionBody</var> )</h1>
|
||
<p>The abstract operation AsyncFunctionStart takes arguments <var>promiseCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16772"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>) and <var>asyncFunctionBody</var> (a <emu-nt id="_ref_24567"><a href="ecmascript-language-functions-and-classes.html#prod-FunctionBody">FunctionBody</a></emu-nt> <emu-xref href="#sec-syntactic-grammar" id="_ref_16773"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>, an <emu-nt id="_ref_24568"><a href="ecmascript-language-functions-and-classes.html#prod-ExpressionBody">ExpressionBody</a></emu-nt> <emu-xref href="#sec-syntactic-grammar" id="_ref_16774"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>, or an <emu-xref href="#sec-abstract-closure" id="_ref_16775"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>runningContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16776"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>asyncContext</var> be a copy of <var>runningContext</var>.</li><li>NOTE: Copying the execution state is required for <emu-xref aoid="AsyncBlockStart" id="_ref_16777"><a href="control-abstraction-objects.html#sec-asyncblockstart">AsyncBlockStart</a></emu-xref> to resume its execution. It is ill-defined to resume a currently executing context.</li><li>Perform <emu-xref aoid="AsyncBlockStart" id="_ref_16778"><a href="control-abstraction-objects.html#sec-asyncblockstart" class="e-user-code">AsyncBlockStart</a></emu-xref>(<var>promiseCapability</var>, <var>asyncFunctionBody</var>, <var>asyncContext</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-asyncblockstart" type="abstract operation" aoid="AsyncBlockStart">
|
||
<h1><span class="secnum">27.7.5.2</span> AsyncBlockStart ( <var>promiseCapability</var>, <var>asyncBody</var>, <var>asyncContext</var> )</h1>
|
||
<p>The abstract operation AsyncBlockStart takes arguments <var>promiseCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_16779"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), <var>asyncBody</var> (a <emu-xref href="#sec-syntactic-grammar" id="_ref_16780"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref> or an <emu-xref href="#sec-abstract-closure" id="_ref_16781"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters), and <var>asyncContext</var> (an <emu-xref href="#sec-execution-contexts" id="_ref_16782"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>runningContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16783"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>closure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16784"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>promiseCapability</var> and <var>asyncBody</var> and performs the following steps when called:<ol><li>Let <var>acAsyncContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16785"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>If <var>asyncBody</var> is a <emu-xref href="#sec-syntactic-grammar" id="_ref_16786"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>, then<ol><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16787"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<emu-xref aoid="Evaluation" id="_ref_16788"><a href="syntax-directed-operations.html#sec-evaluation" class="e-user-code">Evaluation</a></emu-xref> of <var>asyncBody</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16789"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>asyncBody</var> is an <emu-xref href="#sec-abstract-closure" id="_ref_16790"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters.</li><li>Let <var>result</var> be <emu-xref aoid="Completion" id="_ref_16791"><a href="notational-conventions.html#sec-completion-ao">Completion</a></emu-xref>(<var>asyncBody</var>()).</li></ol></li><li><emu-xref href="#assert" id="_ref_16792"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If we return here, the async function either threw an exception or performed an implicit or explicit return; all awaiting is done.</li><li>Remove <var>acAsyncContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16793"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16794"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16795"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16796"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>If <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16797"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_16798"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <emu-val>undefined</emu-val> »).</li></ol></li><li>Else if <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16799"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">return completion</a></emu-xref>, then<ol><li>Perform ! <emu-xref aoid="Call" id="_ref_16800"><a href="abstract-operations.html#sec-call" class="e-user-code e-user-code">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>result</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_16801"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16802"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>.</li><li>Perform ! <emu-xref aoid="Call" id="_ref_16803"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Reject]]</var>, <emu-val>undefined</emu-val>, « <var>result</var>.<var class="field">[[Value]]</var> »).</li></ol></li><li id="step-asyncblockstart-return-undefined">Return <emu-xref aoid="NormalCompletion" id="_ref_16804"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-const>unused</emu-const>).</li></ol></li><li>Set the code evaluation state of <var>asyncContext</var> such that when evaluation is resumed for that <emu-xref href="#sec-execution-contexts" id="_ref_16805"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref>, <var>closure</var> will be called with no arguments.</li><li>Push <var>asyncContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16806"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>asyncContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16807"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>asyncContext</var></span>. Let <var>result</var> be the value returned by the resumed computation.</li><li><emu-xref href="#assert" id="_ref_16808"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we return here, <var>asyncContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16809"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>runningContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16810"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><emu-xref href="#assert" id="_ref_16811"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>result</var> is a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16812"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion</a></emu-xref> with a value of <emu-const>unused</emu-const>. The possible sources of this value are <emu-xref aoid="Await" id="_ref_16813"><a href="control-abstraction-objects.html#await">Await</a></emu-xref> or, if the async function doesn't await anything, step <emu-xref href="#step-asyncblockstart-return-undefined" id="_ref_847"><a href="control-abstraction-objects.html#step-asyncblockstart-return-undefined">2.i</a></emu-xref> above.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="await" oldids="await-fulfilled,await-rejected" type="abstract operation" aoid="Await"><span id="await-rejected"></span><span id="await-fulfilled"></span>
|
||
<h1><span class="secnum">27.7.5.3</span> Await ( <var>value</var> )</h1>
|
||
<p>The abstract operation Await takes argument <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16814"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16815"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either an <emu-xref href="#sec-ecmascript-language-types" id="_ref_16816"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or <emu-const>empty</emu-const>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_16817"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>asyncContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16818"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>promise</var> be ? <emu-xref aoid="PromiseResolve" id="_ref_16819"><a href="control-abstraction-objects.html#sec-promise-resolve" class="e-user-code">PromiseResolve</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_16820"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>, <var>value</var>).</li><li>Let <var>fulfilledClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16821"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>v</var>) that captures <var>asyncContext</var> and performs the following steps when called:<ol><li>Let <var>prevContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16822"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Suspend <var>prevContext</var>.</li><li>Push <var>asyncContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16823"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>asyncContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16824"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>asyncContext</var></span> using <emu-xref aoid="NormalCompletion" id="_ref_16825"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<var>v</var>) as the result of the operation that suspended it.</li><li><emu-xref href="#assert" id="_ref_16826"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we reach this step, <var>asyncContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16827"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>prevContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16828"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16829"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>onFulfilled</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16830"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>fulfilledClosure</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Let <var>rejectedClosure</var> be a new <emu-xref href="#sec-abstract-closure" id="_ref_16831"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with parameters (<var>reason</var>) that captures <var>asyncContext</var> and performs the following steps when called:<ol><li>Let <var>prevContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16832"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Suspend <var>prevContext</var>.</li><li>Push <var>asyncContext</var> onto the <emu-xref href="#execution-context-stack" id="_ref_16833"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref>; <var>asyncContext</var> is now the <emu-xref href="#running-execution-context" id="_ref_16834"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li><span class="e-user-code">Resume the suspended evaluation of <var>asyncContext</var></span> using <emu-xref aoid="ThrowCompletion" id="_ref_16835"><a href="ecmascript-data-types-and-values.html#sec-throwcompletion">ThrowCompletion</a></emu-xref>(<var>reason</var>) as the result of the operation that suspended it.</li><li><emu-xref href="#assert" id="_ref_16836"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: When we reach this step, <var>asyncContext</var> has already been removed from the <emu-xref href="#execution-context-stack" id="_ref_16837"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and <var>prevContext</var> is the currently <emu-xref href="#running-execution-context" id="_ref_16838"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Return <emu-xref aoid="NormalCompletion" id="_ref_16839"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-val>undefined</emu-val>).</li></ol></li><li>Let <var>onRejected</var> be <emu-xref aoid="CreateBuiltinFunction" id="_ref_16840"><a href="ordinary-and-exotic-objects-behaviours.html#sec-createbuiltinfunction">CreateBuiltinFunction</a></emu-xref>(<var>rejectedClosure</var>, 1, <emu-val>""</emu-val>, « »).</li><li>Perform <emu-xref aoid="PerformPromiseThen" id="_ref_16841"><a href="control-abstraction-objects.html#sec-performpromisethen">PerformPromiseThen</a></emu-xref>(<var>promise</var>, <var>onFulfilled</var>, <var>onRejected</var>).</li><li>Remove <var>asyncContext</var> from the <emu-xref href="#execution-context-stack" id="_ref_16842"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> and restore the <emu-xref href="#sec-execution-contexts" id="_ref_16843"><a href="executable-code-and-execution-contexts.html#sec-execution-contexts">execution context</a></emu-xref> that is at the top of the <emu-xref href="#execution-context-stack" id="_ref_16844"><a href="executable-code-and-execution-contexts.html#execution-context-stack">execution context stack</a></emu-xref> as the <emu-xref href="#running-execution-context" id="_ref_16845"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Let <var>callerContext</var> be the <emu-xref href="#running-execution-context" id="_ref_16846"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref>.</li><li>Resume <var>callerContext</var> passing <emu-const>empty</emu-const>. If <var>asyncContext</var> is ever resumed again, let <var>completion</var> be the <emu-xref href="#sec-completion-record-specification-type" id="_ref_16847"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Record</a></emu-xref> with which it is resumed.</li><li><emu-xref href="#assert" id="_ref_16848"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: If control reaches here, then <var>asyncContext</var> is the <emu-xref href="#running-execution-context" id="_ref_16849"><a href="executable-code-and-execution-contexts.html#running-execution-context">running execution context</a></emu-xref> again.</li><li>Return <var>completion</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
</emu-clause></div></body></html> |