Promise

Functions for interacting with JavaScript Promise. See: Promise.

resolve(value) creates a resolved Promise with a given value. See Promise.resolve on MDN.

Examples

RESCRIPT
let p = Promise.resolve(5) // promise<int>

reject(exn) reject a Promise. See Promise.reject on MDN.

Examples

RESCRIPT
exception TestError(string)

let p = Promise.reject(TestError("some rejected value"))

make(callback) creates a new Promise based on a callback that receives two uncurried functions resolve and reject for defining the Promise's result.

Examples

RESCRIPT
open Promise

let n = 4
Promise.make((resolve, reject) => {
  if(n < 5) {
    resolve(. "success")
  }
  else {
    reject(. "failed")
  }
})
->then(str => {
  Console.log(str)->resolve
})
->catch(_ => {
  Console.log("Error occurred")
  resolve()
})
->ignore

catch(promise, errorCallback) registers an exception handler in a promise chain. The errorCallback receives an exn value that can later be refined into a JS error or ReScript error. The errorCallback needs to return a promise with the same type as the consumed promise. See Promise.catch on MDN.

Examples

RESCRIPT
open Promise

exception SomeError(string)

reject(SomeError("this is an error"))
->then(_ => {
  Ok("This result will never be returned")->resolve
})
->catch(e => {
  let msg = switch(e) {
    | SomeError(msg) => "ReScript error occurred: " ++ msg
    | Exn.Error(obj) =>
      switch Exn.message(obj) {
        | Some(msg) => "JS exception occurred: " ++ msg
        | None => "Some other JS value has been thrown"
      }
    | _ => "Unexpected error occurred"
  }

  Error(msg)->resolve
})
->then(result => {
  switch result {
  | Ok(r) => Console.log2("Operation successful: ", r)
  | Error(msg) => Console.log2("Operation failed: ", msg)
  }->resolve
})
->ignore // Ignore needed for side-effects

In case you want to return another promise in your callback, consider using then instead.

then(promise, callback) returns a new promise based on the result of promise's value. The callback needs to explicitly return a new promise via resolve. It is not allowed to resolve a nested promise (like resolve(resolve(1))). See Promise.then on MDN.

Examples

RESCRIPT
open Promise
resolve(5)
->then(num => {
  resolve(num + 5)
})
->then(num => {
  Console.log2("Your lucky number is: ", num)
  resolve()
})
->ignore

thenResolve(promise, callback) converts an encapsulated value of a promise into another promise wrapped value. It is not allowed to return a promise within the provided callback (e.g. thenResolve(value => resolve(value))).

Examples

RESCRIPT
open Promise
resolve("Anna")
->thenResolve(str => {
  "Hello " ++ str
})
->thenResolve(str => {
  Console.log(str)
})
->ignore // Ignore needed for side-effects

In case you want to return another promise in your callback, consider using then instead.

finally(promise, callback) is used to execute a function that is called no matter if a promise was resolved or rejected. It will return the same promise it originally received. See Promise.finally on MDN.

Examples

RESCRIPT
open Promise
exception SomeError(string)
let isDone = ref(false)

resolve(5)
->then(_ => {
  reject(SomeError("test"))
})
->then(v => {
  Console.log2("final result", v)
  resolve()
})
->catch(_ => {
  Console.log("Error handled")
  resolve()
})
->finally(() => {
  Console.log("finally")
  isDone := true
})
->then(() => {
  Console.log2("isDone:", isDone.contents)
  resolve()
})
->ignore

race(arr) combining array of promises. See Promise.race on MDN.

Examples

RESCRIPT
open Promise
let racer = (ms, name) => {
  Promise.make((resolve, _) => {
    setTimeout(() => {
      resolve(name)
    }, ms)->ignore
  })
}

let promises = [racer(1000, "Turtle"), racer(500, "Hare"), racer(100, "Eagle")]

race(promises)->then(winner => {
  Console.log("The winner is " ++ winner)
  resolve()
})

all(promises) runs all promises in parallel and returns a new promise resolving all gathered results in a unified array. See Promise.all on MDN.

RESCRIPT
open Promise
let promises = [resolve(1), resolve(2), resolve(3)]

all(promises)
->then((results) => {
  results->Array.forEach(num => {
    Console.log2("Number: ", num)
  })

  resolve()
})
->ignore

all2((p1, p2)). Like all(), but with a fixed size tuple of 2

all3((p1, p2, p3)). Like all(), but with a fixed size tuple of 3

all4((p1, p2, p3, p4)). Like all(), but with a fixed size tuple of 4

all5((p1, p2, p3, p4, p5)). Like all(), but with a fixed size tuple of 5

all6((p1, p2, p4, p5, p6)). Like all(), but with a fixed size tuple of 6 ")

done(p) is a safe way to ignore a promise. If a value is anything else than a promise, it will raise a type error.