Merge branch 'main' into date-format-functions-with-options

Author: dkirchhof

CHANGELOG.md

@@ -1,3 +1,20 @@
 # @rescript/core Changelog
 
-## master
+## main
+
+### API changes
+
+- Change `Map.set` to not return self, to indicate that it's mutable. https://github.com/rescript-association/rescript-core/pull/34
+- Change `Set.add` to not return self, to indicate that it's mutable. https://github.com/rescript-association/rescript-core/pull/35
+- Change `Iterator` bindings to have the same shape as `AsyncIterator` for consistency. https://github.com/rescript-association/rescript-core/pull/34
+- Add `Iterator.toArray` binding for turning an iterator into an array. https://github.com/rescript-association/rescript-core/pull/34
+
+### Documentation
+
+- Docstrings for `Map` and `Iterator`. https://github.com/rescript-association/rescript-core/pull/34
+- Docstrings for `Global`. https://github.com/rescript-association/rescript-core/pull/39
+- Docstrings for `Set`. https://github.com/rescript-association/rescript-core/pull/35
+- Docstrings for `AsyncIterator`. https://github.com/rescript-association/rescript-core/pull/33
+- Docstrings for `Type`. https://github.com/rescript-association/rescript-core/pull/32
+- Docstrings for `Int`. https://github.com/rescript-association/rescript-core/pull/37
+- Docstrings for `Dict`. https://github.com/rescript-association/rescript-core/pull/40

src/Core__AsyncIterator.resi

@@ -0,0 +1,59 @@
+/***
+Bindings to async iterators, a way to do async iteration in JavaScript.
+
+See [async iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) on MDN.*/
+
+/**
+The type representing an async iterator.
+*/
+type t<'a>
+
+type value<'a> = {
+  /**
+  Whether there are more values to iterate on before the iterator is done.
+  */
+  done: bool,
+  /**
+  The value of this iteration, if any.
+  */
+  value: option<'a>,
+}
+
+/**
+`next(asyncIterator)`
+
+Returns the next value of the iterator, if any.
+
+See [async iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) on MDN.
+
+## Examples
+- A simple example, getting the next value:
+```rescript
+let {done, value} = await someAsyncIterator->AsyncIterator.next
+```
+
+- Complete example, including looping over all values:
+```rescript
+// Let's pretend we get an async iterator returning ints from somewhere.
+@val external asyncIterator: AsyncIterator.t<int> = "someAsyncIterator"
+
+
+let processMyAsyncIterator = async () => {
+  // ReScript doesn't have `for ... of` loops, but it's easy to mimic using a while loop.
+  let break = ref(false)
+
+  while !break.contents {
+    // Await the next iterator value
+    let {value, done} = await asyncIterator->AsyncIterator.next
+
+    // Exit the while loop if the iterator says it's done
+    break := done
+
+    // This will log the (int) value of the current async iteration, if a value was returned.
+    Console.log(value)
+  }
+}
+```
+*/
+@send
+external next: t<'a> => promise<value<'a>> = "next"

src/Core__Console.res

@@ -24,5 +24,5 @@
 
 @val external trace: unit => unit = "console.trace"
 
-@val external timeStart: string => unit = "console.timeStart"
+@val external time: string => unit = "console.time"
 @val external timeEnd: string => unit = "console.timeEnd"