Iterator Helpers

features.txt

@@ -104,6 +104,10 @@ String.prototype.toWellFormed
 # https://github.com/tc39/proposal-json-parse-with-source
 json-parse-with-source
 
+# Iterator Helpers
+# https://github.com/tc39/proposal-iterator-helpers
+iterator-helpers
+
 ## Standard language features
 #
 # Language features that have been included in a published version of the

test/built-ins/Iterator/constructor.js

@@ -0,0 +1,11 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+esid: sec-iterator-constructor
+description: >
+  The Iterator constructor is a built-in function
+features: [iterator-helpers]
+---*/
+
+assert.sameValue(typeof Iterator, 'function', 'The value of `typeof Iterator` is "function"');

test/built-ins/Iterator/from/callable.js

@@ -0,0 +1,12 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from is callable
+features: [iterator-helpers]
+---*/
+function* g() {}
+
+Iterator.from(g());
+Iterator.from.call(null, g());

test/built-ins/Iterator/from/get-next-method-only-once.js

@@ -0,0 +1,46 @@
+// Copyright (C) 2023 Michael Ficarra. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Gets the next method from the underlying iterator only once
+info: |
+  Iterator.from ( O )
+
+  2. Let iteratorRecord be ? GetIteratorFlattenable(O).
+
+features: [iterator-helpers]
+flags: []
+---*/
+let nextGets = 0;
+let nextCalls = 0;
+
+class CountingIterator {
+  get next() {
+    ++nextGets;
+    let iter = (function* () {
+      for (let i = 1; i < 5; ++i) {
+        yield i;
+      }
+    })();
+    return function () {
+      ++nextCalls;
+      return iter.next();
+    };
+  }
+}
+
+let iterator = new CountingIterator();
+
+assert.sameValue(nextGets, 0, 'The value of `nextGets` is 0');
+assert.sameValue(nextCalls, 0, 'The value of `nextCalls` is 0');
+
+iterator = Iterator.from(iterator);
+
+assert.sameValue(nextGets, 1, 'The value of `nextGets` is 1');
+assert.sameValue(nextCalls, 0, 'The value of `nextCalls` is 0');
+
+iterator.toArray();
+
+assert.sameValue(nextGets, 1, 'The value of `nextGets` is 1');
+assert.sameValue(nextCalls, 5, 'The value of `nextCalls` is 5');

test/built-ins/Iterator/from/get-next-method-throws.js

@@ -0,0 +1,25 @@
+// Copyright (C) 2023 Michael Ficarra. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Underlying iterator has throwing next getter
+info: |
+  Iterator.from ( O )
+
+  4. Let iterated be ? GetIteratorDirect(O).
+
+features: [iterator-helpers]
+flags: []
+---*/
+class ThrowingIterator {
+  get next() {
+    throw new Test262Error();
+  }
+}
+
+let iterator = new ThrowingIterator();
+
+assert.throws(Test262Error, function () {
+  Iterator.from(iterator);
+});

test/built-ins/Iterator/from/is-function.js

@@ -0,0 +1,10 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from is a built-in function
+features: [iterator-helpers]
+---*/
+
+assert.sameValue(typeof Iterator.from, 'function', 'The value of `typeof Iterator.from` is "function"');

test/built-ins/Iterator/from/iterable-primitives.js

@@ -0,0 +1,39 @@
+// Copyright (C) 2023 Michael Ficarra. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from does not respect the iterability of any primitive except Strings
+info: |
+  Iterator.from ( O )
+
+  1. If O is a String, set O to ! ToObject(O).
+  2. Let iteratorRecord be ? GetIteratorFlattenable(O).
+
+includes: [compareArray.js]
+features: [iterator-helpers]
+flags: []
+---*/
+
+function* g() {
+  yield 0;
+}
+
+Number.prototype[Symbol.iterator] = function* () {
+  let i = 0;
+  let target = this >>> 0;
+  while (i < target) {
+    yield i;
+    ++i;
+  }
+};
+
+assert.compareArray(Array.from(5), [0, 1, 2, 3, 4]);
+
+assert.throws(TypeError, function () {
+  Iterator.from(5);
+});
+
+assert.compareArray(Array.from(Iterator.from(new Number(5))), [0, 1, 2, 3, 4]);
+
+assert.compareArray(Array.from(Iterator.from('string')), ['s', 't', 'r', 'i', 'n', 'g']);

test/built-ins/Iterator/from/iterable-to-iterator-fallback.js

@@ -0,0 +1,51 @@
+// Copyright (C) 2023 Michael Ficarra. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from falls back to treating its parameter as an iterator if the Symbol.iterator property is null/undefined
+info: |
+  Iterator.from ( O )
+
+includes: [compareArray.js]
+features: [iterator-helpers]
+flags: []
+---*/
+
+function* g() {
+  yield 0;
+  yield 1;
+  yield 2;
+}
+
+let iter = (function () {
+  let n = g();
+  return {
+    [Symbol.iterator]: 0,
+    next: () => n.next(),
+  };
+})();
+
+assert.throws(TypeError, function () {
+  Iterator.from(iter);
+});
+
+iter = (function () {
+  let n = g();
+  return {
+    [Symbol.iterator]: null,
+    next: () => n.next(),
+  };
+})();
+
+assert.compareArray(Array.from(Iterator.from(iter)), [0, 1, 2]);
+
+iter = (function () {
+  let n = g();
+  return {
+    [Symbol.iterator]: undefined,
+    next: () => n.next(),
+  };
+})();
+
+assert.compareArray(Array.from(Iterator.from(iter)), [0, 1, 2]);

test/built-ins/Iterator/from/length.js

@@ -0,0 +1,22 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from has a "length" property whose value is 1.
+info: |
+  ECMAScript Standard Built-in Objects
+
+  Unless otherwise specified, the length property of a built-in
+  Function object has the attributes { [[Writable]]: false, [[Enumerable]]:
+  false, [[Configurable]]: true }.
+features: [iterator-helpers]
+includes: [propertyHelper.js]
+---*/
+
+verifyProperty(Iterator.from, 'length', {
+  value: 1,
+  writable: false,
+  enumerable: false,
+  configurable: true,
+});

test/built-ins/Iterator/from/name.js

@@ -0,0 +1,29 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  The "name" property of Iterator.from
+info: |
+  17 ECMAScript Standard Built-in Objects
+
+  Every built-in Function object, including constructors, that is not
+  identified as an anonymous function has a name property whose value is a
+  String. Unless otherwise specified, this value is the name that is given to
+  the function in this specification.
+
+  ...
+
+  Unless otherwise specified, the name property of a built-in Function
+  object, if it exists, has the attributes { [[Writable]]: false,
+  [[Enumerable]]: false, [[Configurable]]: true }.
+features: [iterator-helpers]
+includes: [propertyHelper.js]
+---*/
+
+verifyProperty(Iterator.from, 'name', {
+  value: 'from',
+  writable: false,
+  enumerable: false,
+  configurable: true,
+});

test/built-ins/Iterator/from/non-constructible.js

@@ -0,0 +1,23 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from is not constructible.
+
+  Built-in function objects that are not identified as constructors do not implement the [[Construct]] internal method unless otherwise specified in the description of a particular function.
+features: [iterator-helpers]
+---*/
+function* g() {}
+
+assert.throws(TypeError, () => {
+  new Iterator.from();
+});
+
+assert.throws(TypeError, () => {
+  new Iterator.from(g());
+});
+
+assert.throws(TypeError, () => {
+  new class extends Iterator {}.from(g());
+});

test/built-ins/Iterator/from/primitives.js

@@ -0,0 +1,38 @@
+// Copyright (C) 2023 Michael Ficarra. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Iterator.from throws on primitives (except Strings)
+info: |
+  Iterator.from ( O )
+
+features: [iterator-helpers]
+flags: []
+---*/
+
+assert.throws(TypeError, function () {
+  Iterator.from(null);
+});
+
+assert.throws(TypeError, function () {
+  Iterator.from(undefined);
+});
+
+assert.throws(TypeError, function () {
+  Iterator.from(0);
+});
+
+assert.throws(TypeError, function () {
+  Iterator.from(0n);
+});
+
+assert.throws(TypeError, function () {
+  Iterator.from(true);
+});
+
+assert.throws(TypeError, function () {
+  Iterator.from(Symbol());
+});
+
+Iterator.from('string');

test/built-ins/Iterator/from/prop-desc.js

@@ -0,0 +1,26 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  Property descriptor of Iterator.from
+info: |
+  Iterator.from
+
+  * is the initial value of the Iterator.from property of the global object.
+
+  17 ECMAScript Standard Built-in Objects
+
+  Every other data property described in clauses 18 through 26 and in Annex B.2
+  has the attributes { [[Writable]]: true, [[Enumerable]]: false,
+  [[Configurable]]: true } unless otherwise specified.
+features: [globalThis, iterator-helpers]
+includes: [propertyHelper.js]
+---*/
+
+verifyProperty(Iterator, 'from', {
+  value: Iterator.from,
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

test/built-ins/Iterator/from/proto.js

@@ -0,0 +1,15 @@
+// Copyright (C) 2020 Rick Waldron. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-iterator.from
+description: >
+  The value of the [[Prototype]] internal slot of Iterator.from is the
+  intrinsic object %FunctionPrototype%.
+features: [iterator-helpers]
+---*/
+
+assert.sameValue(
+  Object.getPrototypeOf(Iterator.from),
+  Function.prototype,
+  'Object.getPrototypeOf(Iterator.from) must return the value of Function.prototype'
+);