Document “AsyncGenerator” & “AsyncGeneratorFunction”

files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.html

@@ -0,0 +1,99 @@
+---
+title: AsyncGenerator
+slug: Web/JavaScript/Reference/Global_Objects/AsyncGenerator
+tags:
+  - Class
+  - ECMAScript 2018
+  - Generator
+  - JavaScript
+  - Async Generator
+  - Async Iterator
+  - Reference
+browser-compat: javascript.builtins.AsyncGenerator
+---
+<div>{{JSRef}}</div>
+
+<p>The <code><strong>AsyncGenerator</strong></code> object is returned by an {{jsxref("Statements/async_function*", "async generator function")}} and it conforms to both the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol">iterable protocol</a> and the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol">iterator protocol</a>.</p>
+
+<h2 id="Constructor">Constructor</h2>
+
+<p>This object cannot be instantiated directly. Instead, an <code>AsyncGenerator</code> instance can be returned from an {{jsxref("Statements/async_function*", "async generator function")}}:</p>
+
+<p>Async generators always yield a {{jsxref("Promise")}} object.</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  yield await Promise.resolve(1);
+  yield await Promise.resolve(2);
+  yield await Promise.resolve(3);
+}
+
+const asyncGen = createAsyncGenerator(); // "AsyncGenerator { }"
+
+asyncGen.next()
+  .then(res => console.log(res.value)); // 1
+asyncGen.next()
+  .then(res => console.log(res.value)); // 2
+asyncGen.next()
+  .then(res => console.log(res.value)); // 3</pre>
+
+<h2 id="Instance_methods">Instance methods</h2>
+
+<dl>
+  <dt>{{jsxref("AsyncGenerator.prototype.next()")}}</dt>
+  <dd>Returns a {{jsxref("Promise")}} which will be resolved with the given value yielded by the {{jsxref("Operators/yield", "yield")}} expression.</dd>
+  <dt>{{jsxref("AsyncGenerator.prototype.return()")}}</dt>
+  <dd>Returns a {{jsxref("Promise")}} which will be resolved with the given value yielded by the {{jsxref("Operators/yield", "yield")}} expression and finishes the generator.</dd>
+  <dt>{{jsxref("AsyncGenerator.prototype.throw()")}}</dt>
+  <dd>Returns a {{jsxref("Promise")}} that is rejected with an exception thrown from (or uncaught from) within the async generator function and finishes the generator unless the exception is caught within that generator.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<h3 id="async_generator_iteration">Async generator iteration</h3>
+
+<p>The following example iterates over an async generator logging values 1 - 6 to the console, at decreasing time intervals.</p>
+
+<pre class="brush: js;">
+function waitFor(time, value) {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => resolve(value), time);
+  });
+}
+
+async function* generate() {
+  yield await waitFor(1000, 1);
+  yield await waitFor(2000, 2);
+  yield await waitFor(400, 3);
+  yield await waitFor(800, 4);
+  yield await waitFor(150, 5);
+  yield await waitFor(50, 6);
+  console.log('All done!');
+}
+
+async function main() {
+  for await (const value of generate()) {
+    console.log('value', value);
+  }
+}
+
+main()
+  .catch((e) => console.error('error', e));</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+{{Specifications}}
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li>{{jsxref("Statements/function*", "function*")}}</li>
+ <li>{{jsxref("Statements/async_function*", "async function*")}}</li>
+ <li>{{jsxref("Operators/function*", '<code>function*</code> expression', "", 1)}}</li>
+ <li>{{jsxref("GeneratorFunction")}}</li>
+ <li>{{jsxref("AsyncGeneratorFunction")}}</li>
+ <li><a href="/en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol">The Iterator protocol</a></li>
+</ul>

files/en-us/web/javascript/reference/global_objects/asyncgenerator/next/index.html

@@ -0,0 +1,122 @@
+---
+title: AsyncGenerator.prototype.next()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncGenerator/next
+tags:
+  - ECMAScript 2018
+  - AsyncGenerator
+  - JavaScript
+  - Method
+  - Prototype
+  - Reference
+browser-compat: javascript.builtins.AsyncGenerator.next
+---
+<div>{{JSRef}}</div>
+
+<p><span class="seoSummary">The <strong><code>next()</code></strong> method returns an object with two properties <code>done</code> and <code>value</code>. You can also provide a parameter to the <code>next</code> method to send a value to the generator.</span></p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="brush: js"><var>asyncGen</var>.next(<var>value</var>)</pre>
+
+<h3 id="Parameters">Parameters</h3>
+
+<dl>
+  <dt><code><var>value</var></code></dt>
+  <dd>The value to send to the generator.</dd>
+  <dd>The value will be assigned as a result of a <code>yield</code> expression. For example, in <code><var>variable</var> = yield <var>expression</var></code>, the value passed to the <code>.next()</code> function will be assigned to <code><var>variable</var></code>.</dd>
+</dl>
+
+<h3 id="Return_value">Return value</h3>
+
+<p>An {{jsxref("Object")}} with two properties:</p>
+
+<dl>
+  <dt><code>done</code> (boolean)</dt>
+  <dd>Has the value <code>true</code> if the iterator is past the end of the iterated sequence. In this case <code>value</code> optionally specifies the <em>return value</em> of the iterator.</dd>
+  <dd>Has the value <code>false</code> if the iterator was able to produce the next value in the sequence. This is equivalent of not specifying the <code>done</code> property altogether.</dd>
+  <dt><code>value</code></dt>
+  <dd>Any JavaScript value returned by the iterator. Can be omitted when <code>done</code> is <code>true</code>.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<h3 id="Using_next">Using next()</h3>
+
+<p>The following example shows a simple generator and the object that the <code>next</code> method returns:</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  yield await Promise.resolve(1);
+  yield await Promise.resolve(2);
+  yield await Promise.resolve(3);
+}
+
+const asyncGen = createAsyncGenerator();            // "AsyncGenerator { }"
+asyncGen.next().then(res => console.log(res));      // "Object { value: 1, done: false }"
+asyncGen.next().then(res => console.log(res));      // "Object { value: 2, done: false }"
+asyncGen.next().then(res => console.log(res));      // "Object { value: 3, done: false }"
+asyncGen.next().then(res => console.log(res));      // "Object { value: undefined, done: true }"
+</pre>
+
+<h3 id="Using_next_with_a_list">Using next() with a list</h3>
+
+<pre class="brush: js">async function* getPage(pageSize = 1, list) {
+    let output = [];
+    let index = 0;
+
+    while (index &lt; list.length) {
+        output = [];
+        for (let i = index; i &lt; index + pageSize; i++) {
+            if (list[i]) {
+                output.push(list[i]);
+            }
+        }
+
+        yield await Promise.resolve(output);
+        index += pageSize;
+    }
+}
+
+const list = [1, 2, 3, 4, 5, 6, 7, 8];
+const page = getPage(3, list);             // AsyncGenerator { }
+
+page.next().then(res => console.log(res)); // Object { value: [1, 2, 3], done: false }
+page.next().then(res => console.log(res)); // Object { value: [4, 5, 6], done: false }
+page.next().then(res => console.log(res)); // Object { value: [7, 8], done: false }
+page.next().then(res => console.log(res)); // Object { value: undefined, done: true }
+</pre>
+
+<h3 id="Sending_values_to_the_generator">Sending values to the generator</h3>
+
+<p>In this example, <code>next</code> is called with a value.</p>
+
+<p>Note that the first call does not log anything, because the generator was not yielding anything initially.</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  while (true) {
+    let value = yield await Promise.resolve(null);
+    console.log(value);
+  }
+}
+
+const asyncGen = createAsyncGenerator();
+asyncGen.next(1).then(res => console.log(res));
+// { value: null, done: false }
+asyncGen.next(2).then(res => console.log(res));
+// 2
+// { value: null, done: false }
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+{{Specifications}}
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+  <li>{{jsxref("Statements/async_function*", "async function*")}}</li>
+  <li><a href="/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators">Iterators and generators</a></li>
+</ul>

files/en-us/web/javascript/reference/global_objects/asyncgenerator/return/index.html

@@ -0,0 +1,84 @@
+---
+title: AsyncGenerator.prototype.return()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncGenerator/return
+tags:
+  - ECMAScript 2018
+  - AsyncGenerator
+  - JavaScript
+  - Method
+  - Prototype
+  - Reference
+browser-compat: javascript.builtins.AsyncGenerator.return
+---
+<div>{{JSRef}}</div>
+
+<p>The <strong><code>return()</code></strong> method returns the given value and finishes the generator.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="brush: js"><var>asyncGen</var>.return(<var>value</var>)</pre>
+
+<h3 id="Parameters">Parameters</h3>
+
+<dl>
+  <dt><code><var>value</var></code></dt>
+  <dd>The value to return.</dd>
+</dl>
+
+<h3 id="Return_value">Return value</h3>
+
+<p>The value that is given as an argument.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<h3 id="Using_return">Using return()</h3>
+
+<p>The following example shows a simple async generator and the <code>return</code> method.</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  yield await Promise.resolve(1);
+  yield await Promise.resolve(2);
+  yield await Promise.resolve(3);
+}
+
+const asyncGen = createAsyncGenerator();
+
+asyncGen.next().then(res => console.log(res));        // { value: 1, done: false }
+asyncGen.return('foo').then(res => console.log(res)); // { value: "foo", done: true }
+asyncGen.next().then(res => console.log(res));        // { value: undefined, done: true }
+</pre>
+
+<p>If <code>return(<var>value</var>)</code> is called on a generator that is already in "completed" state, the generator will remain in "completed" state.</p>
+
+<p>If no argument is provided, the <code>value</code> property of returned object is the same as if <code>.next()</code>. If an argument is provided, it will be set to the value of the <code>value</code> property of the returned object.</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  yield await Promise.resolve(1);
+  yield await Promise.resolve(2);
+  yield await Promise.resolve(3);
+}
+
+const asyncGen = createAsyncGenerator();
+
+asyncGen.next().then(res => console.log(res));    // { value: 1, done: false }
+asyncGen.next().then(res => console.log(res));    // { value: 2, done: false }
+asyncGen.next().then(res => console.log(res));    // { value: 3, done: false }
+asyncGen.next().then(res => console.log(res));    // { value: undefined, done: true }
+asyncGen.return().then(res => console.log(res));  // { value: undefined, done: true }
+asyncGen.return(1).then(res => console.log(res)); // { value: 1, done: true }
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+{{Specifications}}
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+  <li>{{jsxref("Statements/async_function*", "async function*")}}</li>
+  <li><a href="/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators">Iterators and generators</a></li>
+</ul>

files/en-us/web/javascript/reference/global_objects/asyncgenerator/throw/index.html

@@ -0,0 +1,81 @@
+---
+title: AsyncGenerator.prototype.throw()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncGenerator/throw
+tags:
+  - ECMAScript 2018
+  - AsyncGenerator
+  - JavaScript
+  - Method
+  - Prototype
+  - Reference
+browser-compat: javascript.builtins.AsyncGenerator.throw
+---
+<div>{{JSRef}}</div>
+
+<p><span class="seoSummary">The <strong><code>throw()</code></strong> method resumes the execution of a generator by throwing an error into it and returns an object with two properties <code>done</code> and <code>value</code>.</span></p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="brush: js"><code><var>asyncGen</var>.throw(<var>exception</var>)</code></pre>
+
+<h3 id="Parameters">Parameters</h3>
+
+<dl>
+  <dt><code><var>exception</var></code></dt>
+  <dd>The exception to throw. For debugging purposes, it is useful to make it an <code>instanceof</code> {{jsxref("Error")}}.</dd>
+</dl>
+
+<h3 id="Return_value">Return value</h3>
+
+<p>An {{jsxref("Global_Objects/Object", "Object")}} with two properties:</p>
+
+<dl>
+  <dt><code>done</code> (boolean)</dt>
+  <dd>
+    <ul>
+      <li>Has the value <code>true</code> if the iterator is past the end of the iterated sequence. In this case <code>value</code> optionally specifies the <em>return value</em> of the iterator.</li>
+      <li>Has the value <code>false</code> if the iterator was able to produce the next value in the sequence. This is equivalent of not specifying the <code>done</code> property altogether.</li>
+    </ul>
+  </dd>
+  <dt><code>value</code></dt>
+  <dd>Any JavaScript value returned by the iterator. Can be omitted when <code>done</code> is <code>true</code>.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<h3 id="Using_throw">Using throw()</h3>
+
+<p>The following example shows a simple generator and an error that is thrown using the <code>throw</code> method. An error can be caught by a {{jsxref("Statements/try...catch", "try...catch")}} block as usual.</p>
+
+<pre class="brush: js">async function* createAsyncGenerator() {
+  while(true) {
+    try {
+       yield 42;
+    } catch(e) {
+      console.log('Error caught!');
+    }
+  }
+}
+
+const asyncGen = createAsyncGenerator();
+asyncGen.next(1).then(res => console.log(res));
+// { value: 42, done: false }
+asyncGen.throw(new Error('Something went wrong')).then(res => console.log(res));
+// "Error caught!"
+// { value: 42, done: false }
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+{{Specifications}}
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+  <li>{{jsxref("Statements/async_function*", "async function*")}}</li>
+  <li><a href="/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators">Iterators and generators</a></li>
+</ul>