API / Core / Asynciterator

AsyncIterator

Bindings to async iterators, a way to do async iteration in JavaScript.

See async iterator protocols on MDN.

t

RESCRIPT

type t<'a>

The type representing an async iterator.

value

RESCRIPT

type value<'a> = {done: bool, value: option<'a>}

make

RESCRIPT

let make: (unit => promise<value<'value>>) => t<'value>

make(nextFn)

Creates an async iterator from a function that returns the next value of the iterator.

Examples

A simple example, creating an async iterator that returns 1, 2, 3:

RESCRIPT
let context = ref(0)

let asyncIterator = AsyncIterator.make(async () => {
  let currentValue = context.contents
  // Increment current value
  context := currentValue + 1
  
  {
    AsyncIterator.value: Some(currentValue),
    done: currentValue >= 3
  }
})

// This will log 1, 2, 3
await asyncIterator->AsyncIterator.forEach(value =>
  switch value {
  | Some(value) => Console.log(value)
  | None => ()
  }
)

value

RESCRIPT

let value: 'value => value<'value>

value(value)

Shorthand for creating a value object with the provided value, and the done property set to false.

Examples

RESCRIPT
let context = ref(0)

let asyncIterator = AsyncIterator.make(async () => {
  let currentValue = context.contents
  // Increment current value
  context := currentValue + 1
  
  if currentValue >= 3 {
    AsyncIterator.done()
  } else {
    AsyncIterator.value(currentValue)
  }
})

done

RESCRIPT

let done: (~finalValue: 'value=?) => value<'value>

done(~finalValue=?)

Shorthand for creating a value object with the done property set to true, and the provided value as the final value, if any.

Examples

RESCRIPT
let context = ref(0)

let asyncIterator = AsyncIterator.make(async () => {
  let currentValue = context.contents
  // Increment current value
  context := currentValue + 1
  
  if currentValue >= 3 {
    AsyncIterator.done()
  } else {
    AsyncIterator.value(currentValue)
  }
})

RESCRIPT

let next: t<'a> => promise<value<'a>>

next(asyncIterator)

Returns the next value of the iterator, if any.

See async iterator protocols on MDN.

Examples

A simple example, getting the next value:

RESCRIPT
@val external asyncIterator: AsyncIterator.t<int> = "someAsyncIterator"
let value = await asyncIterator->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)
  }
}

forEach

RESCRIPT

let forEach: (t<'a>, option<'a> => unit) => promise<unit>

forEach(iterator, fn) consumes all values in the async iterator and runs the callback fn for each value.

See iterator 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!")
  | _ => ()
  }
)