Document hidden Iterator/AsyncIterator object (#25892)

files/en-us/web/javascript/reference/functions/arguments/@@iterator/index.md

@@ -7,7 +7,7 @@ browser-compat: javascript.functions.arguments.@@iterator
 
 {{jsSidebar("Functions")}}
 
-The **`@@iterator`** method of the [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `arguments` to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an iterator that yields the value of each index in the `arguments` object.
+The **`[@@iterator]()`** method of the [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `arguments` to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the `arguments` object.
 
 The initial value of this property is the same function object as the initial value of the {{jsxref("Array.prototype.values")}} property (and also the same as [`Array.prototype[@@iterator]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator)).
 
@@ -19,7 +19,7 @@ arguments[Symbol.iterator]()
 
 ### Return value
 
-The same return value as {{jsxref("Array.prototype.values()")}}: a new iterable iterator object that yields the value of each index in the `arguments` object.
+The same return value as {{jsxref("Array.prototype.values()")}}: a new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the `arguments` object.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/array/@@iterator/index.md

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Array.@@iterator
 
 {{JSRef}}
 
-The **`@@iterator`** method of an `Array` object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an iterator that yields the value of each index in the array.
+The **`[@@iterator]()`** method of an `Array` object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows arrays to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an [array iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the array.
 
 The initial value of this property is the same function object as the initial value of the {{jsxref("Array.prototype.values")}} property.
 
@@ -19,7 +19,7 @@ array[Symbol.iterator]()
 
 ### Return value
 
-The same return value as {{jsxref("Array.prototype.values()")}}: a new iterable iterator object that yields the value of each index in the array.
+The same return value as {{jsxref("Array.prototype.values()")}}: a new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields the value of each index in the array.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/array/entries/index.md

@@ -7,9 +7,7 @@ browser-compat: javascript.builtins.Array.entries
 
 {{JSRef}}
 
-The **`entries()`** method returns a new **Array
-Iterator** object that contains the key/value pairs for each index in the
-array.
+The **`entries()`** method returns a new _[array iterator](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)_ object that contains the key/value pairs for each index in the array.
 
 {{EmbedInteractiveExample("pages/js/array-entries.html")}}
 
@@ -21,7 +19,7 @@ entries()
 
 ### Return value
 
-A new {{jsxref("Array")}} iterator object.
+A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator).
 
 ## Description
 

files/en-us/web/javascript/reference/global_objects/array/keys/index.md

@@ -7,8 +7,7 @@ browser-compat: javascript.builtins.Array.keys
 
 {{JSRef}}
 
-The **`keys()`** method returns a new **Array
-Iterator** object that contains the keys for each index in the array.
+The **`keys()`** method returns a new _[array iterator](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)_ object that contains the keys for each index in the array.
 
 {{EmbedInteractiveExample("pages/js/array-keys.html")}}
 
@@ -20,7 +19,7 @@ keys()
 
 ### Return value
 
-A new {{jsxref("Array")}} iterator object.
+A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator).
 
 ## Description
 

files/en-us/web/javascript/reference/global_objects/array/values/index.md

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Array.values
 
 {{JSRef}}
 
-The **`values()`** method returns a new _array [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol)_ object that iterates the value of each item in the array.
+The **`values()`** method returns a new _[array iterator](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)_ object that iterates the value of each item in the array.
 
 {{EmbedInteractiveExample("pages/js/array-values.html")}}
 
@@ -19,7 +19,7 @@ values()
 
 ### Return value
 
-A new iterable iterator object.
+A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator).
 
 ## Description
 

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

@@ -11,6 +11,8 @@ The **`AsyncGenerator`** object is returned by an {{jsxref("Statements/async_fun
 
 Async generator methods always yield {{jsxref("Promise")}} objects.
 
+`AsyncGenerator` is a subclass of the hidden {{jsxref("AsyncIterator")}} class.
+
 {{EmbedInteractiveExample("pages/js/expressions-async-function-asterisk.html", "taller")}}
 
 ## Constructor
@@ -32,6 +34,8 @@ asyncGen.next()
   .then((res) => console.log(res.value)); // 3
 ```
 
+In fact, there's no JavaScript entity that corresponds to the `AsyncGenerator` constructor. There's only a hidden object which is the prototype object shared by all objects created by async generator functions. This object is often stylized as `AsyncGenerator.prototype` to make it look like a class, but it should be more appropriately called [`AsyncGeneratorFunction.prototype.prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGeneratorFunction), because `AsyncGeneratorFunction` is an actual JavaScript entity.
+
 ## Instance properties
 
 These properties are defined on `AsyncGenerator.prototype` and shared by all `AsyncGenerator` instances.
@@ -47,6 +51,8 @@ These properties are defined on `AsyncGenerator.prototype` and shared by all `As
 
 ## Instance methods
 
+_Also inherits instance methods from its parent {{jsxref("AsyncIterator")}}_.
+
 - {{jsxref("AsyncGenerator.prototype.next()")}}
   - : Returns a {{jsxref("Promise")}} which will be resolved with the given value yielded by the {{jsxref("Operators/yield", "yield")}} expression.
 - {{jsxref("AsyncGenerator.prototype.return()")}}

files/en-us/web/javascript/reference/global_objects/asynciterator/@@asynciterator/index.md

@@ -0,0 +1,54 @@
+---
+title: AsyncIterator.prototype[@@iterator]()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.AsyncIterator.@@asyncIterator
+---
+
+{{JSRef}}
+
+The **`[@@asyncIterator]()`** method of an `AsyncIterator` object implements the [async iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) and allows built-in async iterators to be consumed by most syntaxes expecting async iterables, such as [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the async iterator object itself.
+
+{{EmbedInteractiveExample("pages/js/map-prototype-@@iterator.html")}}
+
+## Syntax
+
+```js-nolint
+asyncIterator[Symbol.asyncIterator]()
+```
+
+### Return value
+
+The value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the async iterator object itself.
+
+## Examples
+
+### Iteration using for await...of loop
+
+Note that you seldom need to call this method directly. The existence of the `@@asyncIterator` method makes all built-in async iterators [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), and iterating syntaxes like the `for await...of` loop automatically calls this method to obtain the async iterator to loop over.
+
+```js
+const asyncIterator = (async function* () {
+  yield 1;
+  yield 2;
+  yield 3;
+})();
+(async () => {
+  for await (const value of asyncIterator) {
+    console.log(value);
+  }
+})();
+// Logs: 1, 2, 3
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`for await...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)

files/en-us/web/javascript/reference/global_objects/asynciterator/index.md

@@ -0,0 +1,64 @@
+---
+title: AsyncIterator
+slug: Web/JavaScript/Reference/Global_Objects/AsyncIterator
+page-type: javascript-class
+browser-compat: javascript.builtins.AsyncIterator
+---
+
+{{JSRef}}
+
+An **`AsyncIterator`** object is an object that conforms to the [async iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) by providing a `next()` method that returns a promise fulfilling to an iterator result object. The `AsyncIterator.prototype` object is a hidden global object that all built-in async iterators inherit from. It provides an [`@@asyncIterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols).
+
+Note that `AsyncIterator` is _not_ a global object, although it will be in the future with the [async iterator helpers proposal](https://github.com/tc39/proposal-async-iterator-helpers). The `AsyncIterator.prototype` object shared by all built-in async iterators can be obtained with the following code:
+
+```js
+const AsyncIteratorPrototype = Object.getPrototypeOf(
+  Object.getPrototypeOf(Object.getPrototypeOf((async function* () {})())),
+);
+```
+
+## Description
+
+Currently, the only built-in JavaScript async iterator is the {{jsxref("AsyncGenerator")}} object returned by [async generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/async_function*). There are some other built-in async iterators in web API, such as the one of a {{domxref("ReadableStream")}}.
+
+Each of these async iterators have a distinct prototype object, which defines the `next()` method used by the particular async iterator. All of these prototype objects inherit from `AsyncIterator.prototype`, which provides am [`@@asyncIterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) method that returns the async iterator object itself, making the async iterator also [async iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols).
+
+> **Note:** `AsyncIterator.prototype` does not implement [`@@iterator`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator), so async iterators are not [sync iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) by default.
+
+## Instance methods
+
+- [`AsyncIterator.prototype[@@asyncIterator]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator/@@asyncIterator)
+  - : Returns the async iterator object itself. This allows async iterator objects to also be async iterable.
+
+## Examples
+
+### Using an async iterator as an async iterable
+
+All built-in async iterators are also async iterable, so you can use them in a `for await...of` loop:
+
+```js
+const asyncIterator = (async function* () {
+  yield 1;
+  yield 2;
+  yield 3;
+})();
+(async () => {
+  for await (const value of asyncIterator) {
+    console.log(value);
+  }
+})();
+// Logs: 1, 2, 3
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{JSxRef("Statements/async_function*", "async function*")}}
+- [The Iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)

files/en-us/web/javascript/reference/global_objects/generator/index.md

@@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Generator
 
 The **`Generator`** object is returned by a {{JSxRef("Statements/function*", "generator function", "", 1)}} and it conforms to both the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) and the [iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol).
 
+`Generator` is a subclass of the hidden {{jsxref("Iterator")}} class.
+
 {{EmbedInteractiveExample("pages/js/expressions-functionasteriskexpression.html", "taller")}}
 
 ## Constructor
@@ -29,6 +31,8 @@ console.log(gen.next().value); // 2
 console.log(gen.next().value); // 3
 ```
 
+In fact, there's no JavaScript entity that corresponds to the `Generator` constructor. There's only a hidden object which is the prototype object shared by all objects created by generator functions. This object is often stylized as `Generator.prototype` to make it look like a class, but it should be more appropriately called [`GeneratorFunction.prototype.prototype`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction), because `GeneratorFunction` is an actual JavaScript entity.
+
 ## Instance properties
 
 These properties are defined on `Generator.prototype` and shared by all `Generator` instances.
@@ -44,6 +48,8 @@ These properties are defined on `Generator.prototype` and shared by all `Generat
 
 ## Instance methods
 
+_Also inherits instance methods from its parent {{jsxref("Iterator")}}_.
+
 - {{JSxRef("Generator.prototype.next()")}}
   - : Returns a value yielded by the {{JSxRef("Operators/yield", "yield")}} expression.
 - {{JSxRef("Generator.prototype.return()")}}

files/en-us/web/javascript/reference/global_objects/index.md

@@ -129,6 +129,8 @@ These objects interact with the garbage collection mechanism.
 
 Control abstractions can help to structure code, especially async code (without using deeply nested callbacks, for example).
 
+- {{JSxRef("Iterator")}}
+- {{JSxRef("AsyncIterator")}}
 - {{JSxRef("Promise")}}
 - {{JSxRef("GeneratorFunction")}}
 - {{JSxRef("AsyncGeneratorFunction")}}

files/en-us/web/javascript/reference/global_objects/intl/segmenter/segment/segments/@@iterator/index.md

@@ -8,7 +8,7 @@ browser-compat: javascript.builtins.Intl.Segments.@@iterator
 
 {{JSRef}}
 
-The **`@@iterator`** method of a `Segments` object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Segments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an iterator that yields data about each segment.
+The **`[@@iterator]()`** method of a `Segments` object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows `Segments` objects to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns an [segments iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields data about each segment.
 
 {{EmbedInteractiveExample("pages/js/intl-segments-prototype-@@iterator.html")}}
 
@@ -20,7 +20,7 @@ segments[Symbol.iterator]()
 
 ### Return value
 
-A new iterable iterator object that yields data about each segment. Each yielded object has the same properties as the object returned by the [`containing()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/containing) method.
+A new [iterable iterator object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator) that yields data about each segment. Each yielded object has the same properties as the object returned by the [`containing()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/containing) method.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/iterator/@@iterator/index.md

@@ -0,0 +1,48 @@
+---
+title: Iterator.prototype[@@iterator]()
+slug: Web/JavaScript/Reference/Global_Objects/Iterator/@@iterator
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.Iterator.@@iterator
+---
+
+{{JSRef}}
+
+The **`[@@iterator]()`** method of a `Iterator` object implements the [iterable protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and allows built-in iterators to be consumed by most syntaxes expecting iterables, such as the [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops. It returns the value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the iterator object itself.
+
+{{EmbedInteractiveExample("pages/js/map-prototype-@@iterator.html")}}
+
+## Syntax
+
+```js-nolint
+iterator[Symbol.iterator]()
+```
+
+### Return value
+
+The value of [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), which is the iterator object itself.
+
+## Examples
+
+### Iteration using for...of loop
+
+Note that you seldom need to call this method directly. The existence of the `@@iterator` method makes all built-in iterators [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), and iterating syntaxes like the `for...of` loop automatically calls this method to obtain the iterator to loop over.
+
+```js
+const arrIterator = [1, 2, 3].values();
+for (const value of arrIterator) {
+  console.log(value);
+}
+// Logs: 1, 2, 3
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of)