Merge branch 'rescript-association:main' into date-format-functions-with-options

Author: dkirchhof

CHANGELOG.md

@@ -1,3 +1,23 @@
 # @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
+- Add `Array.at` binding for returning an array item by its index. https://github.com/rescript-association/rescript-core/pull/48
+- Fixed type signatures of `Array.fromArrayLikeWithMap` and `Array.fromIteratorWithMap`. https://github.com/rescript-association/rescript-core/pull/50
+- Remove internal async/await helpers that do not need to be exposed in `Core`.
+
+### 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__Array.res

@@ -6,10 +6,10 @@ external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set"
 
 @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from"
 @val
-external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'a> = "Array.from"
+external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from"
 
 @val external fromIterator: Core__Iterator.t<'a> => array<'a> = "Array.from"
-@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'c) => array<'a> = "Array.from"
+@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'b) => array<'b> = "Array.from"
 
 @val external isArray: 'a => bool = "Array.isArray"
 
@@ -196,3 +196,5 @@ let filterMap = (a, f) => filterMapU(a, (. a) => f(a))
 
 // TODO: Change this implementation?
 let flatMap = (a, f) => []->concatMany(map(a, f))
+
+@send external at: (array<'a>, int) => option<'a> = "at"

src/Core__Array.resi

@@ -2,9 +2,9 @@
 @val external fromWithMap: ('a, 'b => 'c) => array<'c> = "Array.from"
 @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from"
 @val
-external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'a> = "Array.from"
+external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from"
 @val external fromIterator: Core__Iterator.t<'a> => array<'a> = "Array.from"
-@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'c) => array<'a> = "Array.from"
+@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'b) => array<'b> = "Array.from"
 @val external isArray: 'a => bool = "Array.isArray"
 @get external length: array<'a> => int = "length"
 @send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
@@ -103,3 +103,21 @@ let filterMap: (array<'a>, 'a => option<'b>) => array<'b>
 let shuffle: array<'a> => array<'a>
 let shuffleInPlace: array<'a> => unit
 let flatMap: (array<'a>, 'a => array<'b>) => array<'b>
+
+
+/** 
+  `at(array, index)`
+
+  Get an element by its index. Negative indices count backwards from the last item.
+
+  ## Examples
+  ```rescript
+  ["a", "b", "c"]->Array.at(0) // Some("a")
+  ["a", "b", "c"]->Array.at(2) // Some("c")
+  ["a", "b", "c"]->Array.at(3) // None
+  ["a", "b", "c"]->Array.at(-1) // Some("c")
+  ["a", "b", "c"]->Array.at(-3) // Some("a")
+  ["a", "b", "c"]->Array.at(-4) // None
+  ```
+*/
+@send external at: (array<'a>, int) => option<'a> = "at"

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"