Reference for stage 3 iterator-join (#44886)

* Reference for stage 3 iterator-join

* Consistent descriptions

Author: Josh-Cena

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

@@ -326,7 +326,7 @@ These properties are own properties of each `Array` instance.
 - {{jsxref("Array.prototype.indexOf()")}}
   - : Returns the first (least) index at which a given element can be found in the calling array.
 - {{jsxref("Array.prototype.join()")}}
-  - : Joins all elements of an array into a string.
+  - : Returns a new string that is the concatenation of all elements in this array, separated by commas or a specified separator string.
 - {{jsxref("Array.prototype.keys()")}}
   - : Returns a new [_array iterator_](/en-US/docs/Web/JavaScript/Guide/Iterators_and_generators) that contains the keys for each index in the calling array.
 - {{jsxref("Array.prototype.lastIndexOf()")}}

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

@@ -7,10 +7,7 @@ browser-compat: javascript.builtins.Array.join
 sidebar: jsref
 ---
 
-The **`join()`** method of {{jsxref("Array")}} instances creates and
-returns a new string by concatenating all of the elements in this array,
-separated by commas or a specified separator string. If the array has
-only one item, then that item will be returned without using the separator.
+The **`join()`** method of {{jsxref("Array")}} instances returns a new string that is the concatenation of all elements in this array, separated by commas or a specified separator string. If the array has only one item, that item's stringification is returned without using the separator.
 
 {{InteractiveExample("JavaScript Demo: Array.prototype.join()")}}
 

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

@@ -85,6 +85,7 @@ You will find many iterator methods analogous to array methods, such as:
 | {{jsxref("Iterator.prototype.flatMap()")}}  | {{jsxref("Array.prototype.flatMap()")}}  |
 | {{jsxref("Iterator.prototype.forEach()")}}  | {{jsxref("Array.prototype.forEach()")}}  |
 | {{jsxref("Iterator.prototype.includes()")}} | {{jsxref("Array.prototype.includes()")}} |
+| {{jsxref("Iterator.prototype.join()")}}     | {{jsxref("Array.prototype.join()")}}     |
 | {{jsxref("Iterator.prototype.map()")}}      | {{jsxref("Array.prototype.map()")}}      |
 | {{jsxref("Iterator.prototype.reduce()")}}   | {{jsxref("Array.prototype.reduce()")}}   |
 | {{jsxref("Iterator.prototype.some()")}}     | {{jsxref("Array.prototype.some()")}}     |
@@ -175,6 +176,8 @@ These properties are defined on `Iterator.prototype` and shared by all `Iterator
   - : Executes a provided function once for each element produced by the iterator.
 - {{jsxref("Iterator.prototype.includes()")}} {{experimental_inline}}
   - : Returns `true` if an element produced by the iterator is equal to the given value. Otherwise, if the iterator is exhausted without finding such an element, it returns `false`.
+- {{jsxref("Iterator.prototype.join()")}}
+  - : Returns a string that is the concatenation of all elements produced by the iterator, separated by commas or a specified separator string.
 - {{jsxref("Iterator.prototype.map()")}}
   - : Returns a new iterator helper object that yields elements of the iterator, each transformed by a mapping function.
 - {{jsxref("Iterator.prototype.reduce()")}}

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

@@ -0,0 +1,64 @@
+---
+title: Iterator.prototype.join()
+short-title: join()
+slug: Web/JavaScript/Reference/Global_Objects/Iterator/join
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.Iterator.join
+sidebar: jsref
+---
+
+The **`join()`** method of {{jsxref("Iterator")}} instances is similar to {{jsxref("Array.prototype.join()")}}: it returns a string that is the concatenation of all elements produced by the iterator, separated by commas or a specified separator string. If the iterator has only one item, that item's stringification is returned without using the separator.
+
+## Syntax
+
+```js-nolint
+join()
+join(separator)
+```
+
+### Parameters
+
+- `separator` {{optional_inline}}
+  - : A string to separate each pair of adjacent elements of the iterator. If omitted, the elements are separated with a comma (",").
+
+### Return value
+
+A string joining all yielded elements. The elements are [converted to strings](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion). If an element is `undefined` or `null`, it is converted to an empty string instead of the string `"null"` or `"undefined"`. If the iterator is empty, the empty string is returned.
+
+## Description
+
+See {{jsxref("Array.prototype.join()")}} for details about how `join()` works. Unlike most other iterator helper methods, it does not work well with infinite iterators, because it is not lazy.
+
+## Examples
+
+### Using join()
+
+```js
+function* fibonacci() {
+  let current = 1;
+  let next = 1;
+  while (true) {
+    yield current;
+    [current, next] = [next, current + next];
+  }
+}
+
+console.log(fibonacci().take(5).join()); // "1,1,2,3,5"
+console.log(fibonacci().take(5).join(" - ")); // "1 - 1 - 2 - 3 - 5"
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Polyfill of `Iterator.prototype.join` in `core-js`](https://github.com/zloirock/core-js#iterator-join)
+- [es-shims polyfill of `Iterator.prototype.join`](https://www.npmjs.com/package/es-iterator-helpers)
+- {{jsxref("Iterator")}}
+- {{jsxref("Iterator.prototype.reduce()")}}
+- {{jsxref("Array.prototype.join()")}}

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

@@ -252,7 +252,7 @@ These methods are defined on the `TypedArray` prototype object and are thus shar
 - {{jsxref("TypedArray.prototype.indexOf()")}}
   - : Returns the first (least) index of an element within the array equal to the specified value, or `-1` if none is found. See also {{jsxref("Array.prototype.indexOf()")}}.
 - {{jsxref("TypedArray.prototype.join()")}}
-  - : Joins all elements of an array into a string. See also {{jsxref("Array.prototype.join()")}}.
+  - : Returns a new string that is the concatenation of all elements in this typed array, separated by commas or a specified separator string. See also {{jsxref("Array.prototype.join()")}}.
 - {{jsxref("TypedArray.prototype.keys()")}}
   - : Returns a new array iterator that contains the keys for each index in the array. See also {{jsxref("Array.prototype.keys()")}}.
 - {{jsxref("TypedArray.prototype.lastIndexOf()")}}

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.TypedArray.join
 sidebar: jsref
 ---
 
-The **`join()`** method of {{jsxref("TypedArray")}} instances creates and returns a new string by concatenating all of the elements in this typed array, separated by commas or a specified separator string. If the typed array has only one item, then that item will be returned without using the separator. This method has the same algorithm as {{jsxref("Array.prototype.join()")}}.
+The **`join()`** method of {{jsxref("TypedArray")}} instances returns a new string that is the concatenation of all elements in this typed array, separated by commas or a specified separator string. If the typed array has only one item, that item's stringification is returned without using the separator. This method has the same algorithm as {{jsxref("Array.prototype.join()")}}.
 
 {{InteractiveExample("JavaScript Demo: TypedArray.prototype.join()")}}