backport Iterator.prototype.join

CHANGELOG.md

@@ -15,6 +15,9 @@
 - [`Iterator` includes stage 3 proposal](https://github.com/tc39/proposal-iterator-includes):
   - Added built-in:
     - `Iterator.prototype.includes`
+- [`Iterator` join stage 3 proposal](https://github.com/tc39/proposal-iterator-join):
+  - Added built-in:
+    - `Iterator.prototype.join`
 - Ensure opaque paths always roundtrip in URL polyfill (still without adding to feature detection), [whatwg/url#844](https://github.com/whatwg/url/pull/844)
 - Fixed possible crash on some keys in `Symbol.for`
 - Some `get-iterator` / `get-iterator-method` fixes

README.md

@@ -174,6 +174,7 @@ structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
     - [Stage 3 proposals](#stage-3-proposals)
       - [`Iterator` chunking](#iterator-chunking)
       - [`Iterator` includes](#iterator-includes)
+      - [`Iterator` join](#iterator-join)
     - [Stage 2.7 proposals](#stage-27-proposals)
       - [`Symbol.metadata` for decorators metadata proposal](#symbolmetadata-for-decorators-metadata-proposal)
     - [Stage 2 proposals](#stage-2-proposals)
@@ -2922,6 +2923,24 @@ core-js(-pure)/actual|full/iterator/includes
 [1, 2, 3].values().includes(1, 1);  // => false
 ```
 
+##### [`Iterator` join](https://github.com/tc39/proposal-iterator-join)[⬆](#index)
+Module [`esnext.iterator.join`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.iterator.join.js)
+```ts
+class Iterator {
+  join(separator?: string): string;
+}
+```
+[*CommonJS entry points:*](#commonjs-api)
+```
+core-js/proposals/iterator-join
+core-js(-pure)/actual|full/iterator/join
+```
+```js
+[1, 2, 3].values().join();     // => '1,2,3'
+[1, 2, 3].values().join('-');  // => '1-2-3'
+[1, null, 3].values().join();  // => '1,,3'
+```
+
 #### Stage 2.7 proposals[⬆](#index)
 [*CommonJS entry points:*](#commonjs-api)
 ```

docs/web/docs/features/proposals/iterator-join.md

@@ -0,0 +1,26 @@
+# Iterator join
+[Specification](https://tc39.es/proposal-iterator-join/)\
+[Proposal repo](https://github.com/tc39/proposal-iterator-join)
+
+## Modules
+[`esnext.iterator.join`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.iterator.join.js)
+
+## Built-ins signatures
+```ts
+class Iterator {
+  join(separator?: string): string;
+}
+```
+
+## [Entry points]({docs-version}/docs/usage#h-entry-points)
+```plaintext
+core-js/proposals/iterator-join
+core-js(-pure)/actual|full/iterator/join
+```
+
+## Examples
+```js
+[1, 2, 3].values().join();     // => '1,2,3'
+[1, 2, 3].values().join('-');  // => '1-2-3'
+[1, null, 3].values().join();  // => '1,,3'
+```

docs/web/docs/menu.json

@@ -261,6 +261,10 @@
               {
                 "title": "Iterator includes",
                 "url": "{docs-version}/docs/features/proposals/iterator-includes"
+              },
+              {
+                "title": "Iterator join",
+                "url": "{docs-version}/docs/features/proposals/iterator-join"
               }
             ]
           },

packages/core-js-compat/src/data.mjs

@@ -2636,6 +2636,8 @@ export const data = {
   },
   'esnext.iterator.indexed': {
   },
+  'esnext.iterator.join': {
+  },
   // TODO: Remove from `core-js@4`
   'esnext.iterator.map': null,
   'esnext.iterator.range': {

packages/core-js-compat/src/modules-by-versions.mjs

@@ -327,5 +327,6 @@ export default {
     'es.iterator.zip',
     'es.iterator.zip-keyed',
     'esnext.iterator.includes',
+    'esnext.iterator.join',
   ],
 };

packages/core-js/actual/iterator/concat.js

@@ -3,6 +3,7 @@ var parent = require('../../stable/iterator/concat');
 require('../../modules/esnext.iterator.chunks');
 require('../../modules/esnext.iterator.concat');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.windows');
 
 module.exports = parent;

packages/core-js/actual/iterator/from.js

@@ -12,6 +12,7 @@ require('../../modules/esnext.iterator.flat-map');
 require('../../modules/esnext.iterator.for-each');
 require('../../modules/esnext.iterator.from');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.map');
 require('../../modules/esnext.iterator.reduce');
 require('../../modules/esnext.iterator.some');

packages/core-js/actual/iterator/index.js

@@ -14,6 +14,7 @@ require('../../modules/esnext.iterator.flat-map');
 require('../../modules/esnext.iterator.for-each');
 require('../../modules/esnext.iterator.from');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.map');
 require('../../modules/esnext.iterator.reduce');
 require('../../modules/esnext.iterator.some');

packages/core-js/actual/iterator/join.js

@@ -0,0 +1,8 @@
+'use strict';
+require('../../modules/es.object.to-string');
+require('../../modules/es.iterator.constructor');
+require('../../modules/esnext.iterator.join');
+
+var entryUnbind = require('../../internals/entry-unbind');
+
+module.exports = entryUnbind('Iterator', 'join');

packages/core-js/actual/iterator/zip-keyed.js

@@ -2,6 +2,7 @@
 var parent = require('../../stable/iterator/zip');
 require('../../modules/esnext.iterator.chunks');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.windows');
 require('../../modules/esnext.iterator.zip-keyed');
 

packages/core-js/actual/iterator/zip.js

@@ -2,6 +2,7 @@
 var parent = require('../../stable/iterator/zip');
 require('../../modules/esnext.iterator.chunks');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.windows');
 require('../../modules/esnext.iterator.zip');
 

packages/core-js/full/iterator/join.js

@@ -0,0 +1,4 @@
+'use strict';
+var parent = require('../../actual/iterator/join');
+
+module.exports = parent;

packages/core-js/full/iterator/range.js

@@ -18,6 +18,7 @@ require('../../modules/es.iterator.to-array');
 require('../../modules/esnext.iterator.constructor');
 require('../../modules/esnext.iterator.chunks');
 require('../../modules/esnext.iterator.includes');
+require('../../modules/esnext.iterator.join');
 require('../../modules/esnext.iterator.range');
 require('../../modules/esnext.iterator.sliding');
 require('../../modules/esnext.iterator.windows');

packages/core-js/modules/esnext.iterator.join.js

@@ -0,0 +1,31 @@
+'use strict';
+var $ = require('../internals/export');
+var $toString = require('../internals/to-string');
+var anObject = require('../internals/an-object');
+var isNullOrUndefined = require('../internals/is-null-or-undefined');
+var iterate = require('../internals/iterate');
+var iteratorClose = require('../internals/iterator-close');
+var uncurryThis = require('../internals/function-uncurry-this');
+var IS_PURE = require('../internals/is-pure');
+
+var $join = uncurryThis([].join);
+var push = uncurryThis([].push);
+
+// `Iterator.prototype.join` method
+// https://github.com/tc39/proposal-iterator-join
+$({ target: 'Iterator', proto: true, real: true, forced: IS_PURE }, {
+  join: function join(separator) {
+    anObject(this);
+    var sep;
+    try {
+      sep = separator === undefined ? ',' : $toString(separator);
+    } catch (error) {
+      iteratorClose(this, 'throw', error);
+    }
+    var result = [];
+    iterate(this, function (value) {
+      push(result, isNullOrUndefined(value) ? '' : $toString(value));
+    }, { IS_ITERATOR: true });
+    return $join(result, sep);
+  }
+});

packages/core-js/proposals/iterator-join.js

@@ -0,0 +1,3 @@
+'use strict';
+// https://github.com/tc39/proposal-iterator-join
+require('../modules/esnext.iterator.join');

packages/core-js/stage/3.js

@@ -3,6 +3,7 @@ var parent = require('./4');
 
 require('../proposals/decorator-metadata-v2');
 require('../proposals/iterator-includes');
+require('../proposals/iterator-join');
 require('../proposals/joint-iteration');
 // TODO: Obsolete versions, remove from `core-js@4`
 require('../proposals/array-grouping-stage-3');

tests/compat/tests.js

@@ -1958,6 +1958,9 @@ GLOBAL.tests = {
   'esnext.iterator.includes': function () {
     return Iterator.prototype.includes;
   },
+  'esnext.iterator.join': function () {
+    return Iterator.prototype.join;
+  },
   'esnext.iterator.range': function () {
     return Iterator.range;
   },

tests/entries/unit.mjs

@@ -722,6 +722,7 @@ for (PATH of ['core-js-pure', 'core-js']) {
     ok(load(NS, 'function/metadata') === null);
     ok(typeof load(NS, 'iterator/chunks') == 'function');
     ok(load(NS, 'iterator/includes')([1, 2].values(), 2) === true);
+    ok(load(NS, 'iterator/join')([1, 2].values()) === '1,2');
     ok(typeof load(NS, 'iterator/to-async') == 'function');
     ok(typeof load(NS, 'iterator/windows') == 'function');
     ok(load(NS, 'symbol/metadata'));
@@ -958,6 +959,7 @@ for (PATH of ['core-js-pure', 'core-js']) {
   load('proposals/iterator-chunking');
   load('proposals/iterator-chunking-v2');
   load('proposals/iterator-includes');
+  load('proposals/iterator-join');
   load('proposals/joint-iteration');
   load('proposals/json-parse-with-source');
   load('proposals/keys-composition');

tests/eslint/eslint.config.js

@@ -1301,6 +1301,7 @@ const forbidCompletelyNonExistentBuiltIns = {
   'es/no-nonstandard-iterator-prototype-properties': [ERROR, { allow: [
     'chunks',
     'includes',
+    'join',
     'sliding',
     'toAsync',
     'windows',

tests/unit-global/esnext.iterator.join.js

@@ -0,0 +1,43 @@
+import { STRICT } from '../helpers/constants.js';
+import { createIterator } from '../helpers/helpers.js';
+
+QUnit.test('Iterator#join', assert => {
+  const { join } = Iterator.prototype;
+  const symbol = Symbol('a');
+
+  assert.isFunction(join);
+  assert.arity(join, 1);
+  assert.name(join, 'join');
+  assert.looksNative(join);
+  assert.nonEnumerable(Iterator.prototype, 'join');
+
+  const observableReturn = {
+    return() {
+      this.called = true;
+      return { done: true, value: undefined };
+    },
+  };
+
+  const itObservable1 = createIterator([1, 2, 3], observableReturn);
+  assert.strictEqual(join.call(itObservable1), '1,2,3', 'without separator attribute');
+  assert.true(itObservable1.called, 'iterator closes');
+  assert.strictEqual(join.call(createIterator([1, 2, 3]), '-'), '1-2-3', 'with separator attribute');
+  assert.strictEqual(join.call(createIterator([1, null, 3]), '-'), '1--3', 'skips nullish values');
+  assert.strictEqual(join.call(createIterator([1, undefined, 3]), '-'), '1--3', 'skips undefined values');
+  assert.strictEqual(join.call(createIterator([])), '', 'empty iterator');
+
+  if (STRICT) {
+    assert.throws(() => join.call(''), TypeError, 'iterable non-object this');
+    assert.throws(() => join.call(undefined), TypeError, 'non-iterable-object this #1');
+    assert.throws(() => join.call(null), TypeError, 'non-iterable-object this #2');
+    assert.throws(() => join.call(5), TypeError, 'non-iterable-object this #3');
+  }
+
+  const itObservable2 = createIterator([1, 2, 3], observableReturn);
+  assert.throws(() => join.call(itObservable2, symbol), TypeError, 'throws on symbol separator');
+  assert.true(itObservable2.called, 'iterator closes on argument validation error');
+
+  const itObservable3 = createIterator([1, symbol, 3], observableReturn);
+  assert.throws(() => join.call(itObservable3), TypeError, 'throws on non-stringable value');
+  assert.true(itObservable3.called, 'iterator closes on value conversion error');
+});

tests/unit-pure/esnext.iterator.includes.js

@@ -1,7 +1,7 @@
 import { STRICT } from '../helpers/constants.js';
 import { createIterator } from '../helpers/helpers.js';
 
-import Iterator from 'core-js-pure/full/iterator';
+import Iterator from 'core-js-pure/actual/iterator';
 
 QUnit.test('Iterator#includes', assert => {
   const { includes } = Iterator.prototype;

tests/unit-pure/esnext.iterator.join.js

@@ -0,0 +1,45 @@
+import { STRICT } from '../helpers/constants.js';
+import { createIterator } from '../helpers/helpers.js';
+
+import Iterator from 'core-js-pure/actual/iterator';
+import Symbol from 'core-js-pure/es/symbol';
+
+QUnit.test('Iterator#join', assert => {
+  const { join } = Iterator.prototype;
+
+  assert.isFunction(join);
+  assert.arity(join, 1);
+  assert.name(join, 'join');
+  assert.nonEnumerable(Iterator.prototype, 'join');
+
+  const observableReturn = {
+    return() {
+      this.called = true;
+      return { done: true, value: undefined };
+    },
+  };
+
+  const itObservable1 = createIterator([1, 2, 3], observableReturn);
+  assert.strictEqual(join.call(itObservable1), '1,2,3', 'without separator attribute');
+  assert.true(itObservable1.called, 'iterator closes');
+  assert.strictEqual(join.call(createIterator([1, 2, 3]), '-'), '1-2-3', 'with separator attribute');
+  assert.strictEqual(join.call(createIterator([1, null, 3]), '-'), '1--3', 'skips nullish values');
+  assert.strictEqual(join.call(createIterator([1, undefined, 3]), '-'), '1--3', 'skips undefined values');
+  assert.strictEqual(join.call(createIterator([])), '', 'empty iterator');
+
+  if (STRICT) {
+    assert.throws(() => join.call(''), TypeError, 'iterable non-object this');
+    assert.throws(() => join.call(undefined), TypeError, 'non-iterable-object this #1');
+    assert.throws(() => join.call(null), TypeError, 'non-iterable-object this #2');
+    assert.throws(() => join.call(5), TypeError, 'non-iterable-object this #3');
+  }
+
+  const symbol = Symbol('a');
+  const itObservable2 = createIterator([1, 2, 3], observableReturn);
+  assert.throws(() => join.call(itObservable2, symbol), TypeError, 'throws on symbol separator');
+  assert.true(itObservable2.called, 'iterator closes on argument validation error');
+
+  const itObservable3 = createIterator([1, symbol, 3], observableReturn);
+  assert.throws(() => join.call(itObservable3), TypeError, 'throws on non-stringable value');
+  assert.true(itObservable3.called, 'iterator closes on value conversion error');
+});