Add iterator and asyncIterator forEach helpers (#175)

* add iterator and asyncIterator forEach helpers

* changelog + fix docstrings

* fix docstring errors

Author: zth

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Remove internal xxxU helper functions that are not needed anymore in uncurried mode. https://github.com/rescript-association/rescript-core/pull/191
 - Rename `Object.empty` to `Object.make` for consistency.
 - Add dynamic `import`. https://github.com/rescript-association/rescript-core/pull/178
+- Add `Iterator.forEach` and `AsyncIterator.forEach` helpers for iterators. https://github.com/rescript-association/rescript-core/pull/175
 
 ## 1.0.0
 

src/Core__AsyncIterator.mjs

@@ -1,2 +1,16 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
-/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */
+
+
+async function forEach(iterator, f) {
+  var iteratorDone = false;
+  while(!iteratorDone) {
+    var match = await iterator.next();
+    f(match.value);
+    iteratorDone = match.done;
+  };
+}
+
+export {
+  forEach ,
+}
+/* No side effect */

src/Core__AsyncIterator.res

@@ -6,3 +6,13 @@ type value<'a> = {
 }
 
 @send external next: t<'a> => promise<value<'a>> = "next"
+
+let forEach = async (iterator, f) => {
+  let iteratorDone = ref(false)
+
+  while !iteratorDone.contents {
+    let {done, value} = await iterator->next
+    f(value)
+    iteratorDone := done
+  }
+}

src/Core__AsyncIterator.resi

@@ -58,3 +58,23 @@ let processMyAsyncIterator = async () => {
 */
 @send
 external next: t<'a> => promise<value<'a>> = "next"
+
+/**
+`forEach(iterator, fn)` consumes all values in the async iterator and runs the callback `fn` for each value.
+
+See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN.
+
+## Examples
+```rescript
+// Let's pretend we get an async iterator returning ints from somewhere.
+@val external asyncIterator: AsyncIterator.t<int> = "someAsyncIterator"
+
+await asyncIterator->AsyncIterator.forEach(value =>
+  switch value {
+  | Some(value) if value > 10 => Console.log("More than 10!")
+  | _ => ()
+  }
+)
+```
+*/
+let forEach: (t<'a>, option<'a> => unit) => promise<unit>

src/Core__Iterator.mjs

@@ -1,2 +1,16 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
-/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */
+
+
+function forEach(iterator, f) {
+  var iteratorDone = false;
+  while(!iteratorDone) {
+    var match = iterator.next();
+    f(match.value);
+    iteratorDone = match.done;
+  };
+}
+
+export {
+  forEach ,
+}
+/* No side effect */

src/Core__Iterator.res

@@ -8,3 +8,13 @@ type value<'a> = {
 @send external next: t<'a> => value<'a> = "next"
 external toArray: t<'a> => array<'a> = "Array.from"
 external toArrayWithMapper: (t<'a>, 'a => 'b) => array<'b> = "Array.from"
+
+let forEach = (iterator, f) => {
+  let iteratorDone = ref(false)
+
+  while !iteratorDone.contents {
+    let {done, value} = iterator->next
+    f(value)
+    iteratorDone := done
+  }
+}

src/Core__Iterator.resi

@@ -31,6 +31,7 @@ See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript
 ## Examples
 ```rescript
 @val external someIterator: Iterator.t<int> = "someIterator"
+
 // Pulls out the next value of the iterator
 let {Iterator.done, value} = someIterator->Iterator.next
 ```
@@ -79,3 +80,22 @@ Console.log(mapKeysAsArray) // Logs [7, 8] to the console.
 ```
 */
 external toArrayWithMapper: (t<'a>, 'a => 'b) => array<'b> = "Array.from"
+
+/**
+`forEach(iterator, fn)` consumes all values in the iterator and runs the callback `fn` for each value.
+
+See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN.
+
+## Examples
+```rescript
+@val external someIterator: Iterator.t<int> = "someIterator"
+
+someIterator->Iterator.forEach(value =>
+  switch value {
+  | Some(value) if value > 10 => Console.log("More than 10!")
+  | _ => ()
+  }
+)
+```
+*/
+let forEach: (t<'a>, option<'a> => unit) => unit

src/Core__List.resi

@@ -185,9 +185,9 @@ with `f`. Returns an empty list if `length` is negative.
 ## Examples
 
 ```rescript
-List.fromInitializer(5, i => i) // list{0, 1, 2, 3, 4}
+List.fromInitializer(~length=5, i => i) // list{0, 1, 2, 3, 4}
 
-List.fromInitializer(5, i => i * i) // list{0, 1, 4, 9, 16}
+List.fromInitializer(~length=5, i => i * i) // list{0, 1, 4, 9, 16}
 ```
 */
 let fromInitializer: (~length: int, int => 'a) => t<'a>

src/RescriptCore.res

@@ -59,31 +59,36 @@ value.
 
 ## Examples
 
-`MathUtils.res` file:
+`Core__Array.res` file:
 
 ```rescript
-let add = (a, b) => a + b
-let sub = (a, b) => a - b
+@send external indexOf: (array<'a>, 'a) => int = "indexOf"
+
+let indexOfOpt = (arr, item) =>
+  switch arr->indexOf(item) {
+  | -1 => None
+  | index => Some(index)
+  }
 ```
-In other file you can import the `add` value defined in `MathUtils.res`
+In other file you can import the `indexOfOpt` value defined in `Core__Array.res`
 
 ```rescript
 let main = async () => {
-  let add = await import(MathUtils.add)
-  let onePlusOne = add(1, 1)
-  Console.log(onePlusOne)
+  let indexOfOpt = await import(Core__Array.indexOfOpt)
+  let index = indexOfOpt([1, 2], 2)
+  Console.log(index)
 }
 ```
 
 Compiles to:
 
 ```javascript
 async function main() {
-  var add = await import("./MathUtils.mjs").then(function(m) {
-    return m.add;
+  var add = await import("./Core__Array.mjs").then(function(m) {
+    return m.indexOfOpt;
   });
-  var onePlusOne = add(1, 1);
-  console.log(onePlusOne);
+  var index = indexOfOpt([1, 2], 2);
+  console.log(index);
 }
 ```
 */

test/IteratorTests.mjs

@@ -0,0 +1,77 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Test from "./Test.mjs";
+import * as Caml_obj from "rescript/lib/es6/caml_obj.js";
+import * as Core__Iterator from "../src/Core__Iterator.mjs";
+import * as Core__AsyncIterator from "../src/Core__AsyncIterator.mjs";
+
+var eq = Caml_obj.equal;
+
+var iterator = ((() => {
+    var array1 = ['a', 'b', 'c'];
+    var iterator1 = array1[Symbol.iterator]();
+    return iterator1
+  })());
+
+var syncResult = {
+  contents: undefined
+};
+
+Core__Iterator.forEach(iterator, (function (v) {
+        if (v === "b") {
+          syncResult.contents = "b";
+          return ;
+        }
+        
+      }));
+
+Test.run([
+      [
+        "IteratorTests.res",
+        21,
+        20,
+        34
+      ],
+      "Sync forEach"
+    ], syncResult.contents, eq, "b");
+
+var asyncIterator = ((() => {
+    var map1 = new Map();
+
+    map1.set('first', '1');
+    map1.set('second', '2');
+
+    var iterator1 = map1[Symbol.iterator]();
+    return iterator1;
+  })());
+
+var asyncResult = {
+  contents: undefined
+};
+
+await Core__AsyncIterator.forEach(asyncIterator, (function (v) {
+        if (v !== undefined && v[0] === "second") {
+          asyncResult.contents = "second";
+          return ;
+        }
+        
+      }));
+
+Test.run([
+      [
+        "IteratorTests.res",
+        44,
+        20,
+        35
+      ],
+      "Async forEach"
+    ], asyncResult.contents, eq, "second");
+
+export {
+  eq ,
+  iterator ,
+  syncResult ,
+  asyncIterator ,
+  asyncResult ,
+}
+/* iterator Not a pure module */

test/IteratorTests.res

@@ -0,0 +1,44 @@
+open RescriptCore
+
+let eq = (a, b) => a == b
+
+let iterator: Iterator.t<string> = %raw(`
+  (() => {
+    var array1 = ['a', 'b', 'c'];
+    var iterator1 = array1[Symbol.iterator]();
+    return iterator1
+  })()
+`)
+
+let syncResult = ref(None)
+
+iterator->Iterator.forEach(v => {
+  if v === Some("b") {
+    syncResult.contents = Some("b")
+  }
+})
+
+Test.run(__POS_OF__("Sync forEach"), syncResult.contents, eq, Some("b"))
+
+let asyncIterator: AsyncIterator.t<(string, string)> = %raw(`
+  (() => {
+    var map1 = new Map();
+
+    map1.set('first', '1');
+    map1.set('second', '2');
+
+    var iterator1 = map1[Symbol.iterator]();
+    return iterator1;
+  })()
+`)
+
+let asyncResult = ref(None)
+
+await asyncIterator->AsyncIterator.forEach(v => {
+  switch v {
+  | Some(("second", _value)) => asyncResult.contents = Some("second")
+  | _ => ()
+  }
+})
+
+Test.run(__POS_OF__("Async forEach"), asyncResult.contents, eq, Some("second"))

test/TestSuite.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as IntTests from "./IntTests.mjs";
+import * as DictTests from "./DictTests.mjs";
 import * as JsonTests from "./JsonTests.mjs";
 import * as TestTests from "./TestTests.mjs";
 import * as ArrayTests from "./ArrayTests.mjs";
@@ -9,6 +10,7 @@ import * as FloatTests from "./FloatTests.mjs";
 import * as ObjectTests from "./ObjectTests.mjs";
 import * as PromiseTest from "./PromiseTest.mjs";
 import * as ResultTests from "./ResultTests.mjs";
+import * as IteratorTests from "./IteratorTests.mjs";
 import * as NullableTests from "./NullableTests.mjs";
 import * as TypedArrayTests from "./TypedArrayTests.mjs";
 
@@ -66,12 +68,20 @@ var areSame = TypedArrayTests.areSame;
 
 var o = TypedArrayTests.o;
 
-var eq = FloatTests.eq;
-
 var decodeJsonTest = JsonTests.decodeJsonTest;
 
 var shouldHandleNullableValues = NullableTests.shouldHandleNullableValues;
 
+var eq = IteratorTests.eq;
+
+var iterator = IteratorTests.iterator;
+
+var syncResult = IteratorTests.syncResult;
+
+var asyncIterator = IteratorTests.asyncIterator;
+
+var asyncResult = IteratorTests.asyncResult;
+
 export {
   bign ,
   TestError ,
@@ -100,8 +110,12 @@ export {
   assertWillThrow ,
   areSame ,
   o ,
-  eq ,
   decodeJsonTest ,
   shouldHandleNullableValues ,
+  eq ,
+  iterator ,
+  syncResult ,
+  asyncIterator ,
+  asyncResult ,
 }
 /* IntTests Not a pure module */

test/TestSuite.res

@@ -9,3 +9,5 @@ include TypedArrayTests
 include FloatTests
 include JsonTests
 include NullableTests
+include DictTests
+include IteratorTests