gleam/javascript/promise

Types

Promise

</>

JavaScript promises represent the result of an asynchronous operation which returns a value, either now or at some point in the future. In practice they are the foundation of concurrency in JavaScript.

This library assumes you have some familiarity with JavaScript promises. If you are not then you may want to take the time to learn about them outside of Gleam.

The Gleam promise type is generic over the type of value it resolves. It is not generic over the error type as any Gleam panic or JavaScript exception could alter the error value in an way that undermines the type, making it unsound and untypable. If you want to represent success and failure with promises use a Gleam Result inside of a promise.

For further information view the MDN documentation: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

pub type Promise(value)

Functions

await

</>

pub fn await(a: Promise(a), b: fn(a) -> Promise(b)) -> Promise(b)

Chain a second asynchronous operation onto a promise, so it runs after the promise has resolved.

This is the equivilent of the promise.then JavaScript method.

await2

</>

pub fn await2(a: Promise(a), b: Promise(b)) -> Promise(#(a, b))

Chain an asynchronous operation onto 2 promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await3

</>

pub fn await3(
  a: Promise(a),
  b: Promise(b),
  c: Promise(c),
) -> Promise(#(a, b, c))

Chain an asynchronous operation onto 3 promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await4

</>

pub fn await4(
  a: Promise(a),
  b: Promise(b),
  c: Promise(c),
  d: Promise(d),
) -> Promise(#(a, b, c, d))

Chain an asynchronous operation onto 4 promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await5

</>

pub fn await5(
  a: Promise(a),
  b: Promise(b),
  c: Promise(c),
  d: Promise(d),
  e: Promise(e),
) -> Promise(#(a, b, c, d, e))

Chain an asynchronous operation onto 5 promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await6

</>

pub fn await6(
  a: Promise(a),
  b: Promise(b),
  c: Promise(c),
  d: Promise(d),
  e: Promise(e),
  f: Promise(f),
) -> Promise(#(a, b, c, d, e, f))

Chain an asynchronous operation onto 6 promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await_array

</>

pub fn await_array(a: Array(Promise(a))) -> Promise(Array(a))

Chain an asynchronous operation onto an array of promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

await_list

</>

pub fn await_list(xs: List(Promise(a))) -> Promise(List(a))

Chain an asynchronous operation onto an list of promises, so it runs after the promises have resolved.

This is the equivilent of the Promise.all JavaScript static method.

map

</>

pub fn map(a: Promise(a), b: fn(a) -> b) -> Promise(b)

Run a function on the value a promise resolves to, after it has resolved. The value returned becomes the new value contained by the promise.

map_try

</>

pub fn map_try(
  promise: Promise(Result(a, b)),
  callback: fn(a) -> Result(c, b),
) -> Promise(Result(c, b))

Run a function on the value a promise resolves to, after it has resolved.

The function is only called if the value is Ok, and the returned becomes the new value contained by the promise.

This is a convenience functin that combines the map function with result.try.

new

</>

pub fn new(a: fn(fn(a) -> Nil) -> Nil) -> Promise(a)

Create a new promise from a callback function. The callback function itself takes a second function as an argument, and when that second function is called with a value then the promise resolves with that value.

This function is useful for converting code that uses callbacks into code that uses promises.

race2

</>

pub fn race2(a: Promise(a), b: Promise(a)) -> Promise(a)

race3

</>

pub fn race3(
  a: Promise(a),
  b: Promise(a),
  c: Promise(a),
) -> Promise(a)

race4

</>

pub fn race4(
  a: Promise(a),
  b: Promise(a),
  c: Promise(a),
  d: Promise(a),
) -> Promise(a)

race5

</>

pub fn race5(
  a: Promise(a),
  b: Promise(a),
  c: Promise(a),
  d: Promise(a),
  e: Promise(a),
) -> Promise(a)

race6

</>

pub fn race6(
  a: Promise(a),
  b: Promise(a),
  c: Promise(a),
  d: Promise(a),
  e: Promise(a),
  f: Promise(a),
) -> Promise(a)

race_array

</>

pub fn race_array(a: Array(Promise(a))) -> Promise(a)

race_list

</>

pub fn race_list(a: List(Promise(a))) -> Promise(a)

rescue

</>

pub fn rescue(a: Promise(a), b: fn(Dynamic) -> a) -> Promise(a)

If the promise is in an error state then apply a function to convert the error value back into valid value, making the promise healthy again.

This is the equivilent of the promise.catch JavaScript method.

resolve

</>

pub fn resolve(a: a) -> Promise(a)

Create a promise that resolves immediately.

start

</>

pub fn start() -> #(Promise(a), fn(a) -> Nil)

Create a new promise and resolve function. The first time the resolve function is called the promise resolves with that value.

This function is useful in cases where a reference to the promise and resolver are needed.

tap

</>

pub fn tap(
  promise: Promise(a),
  callback: fn(a) -> b,
) -> Promise(a)

Run a function on the value a promise resolves to, after it has resolved. The value returned is discarded.

try_await

</>

pub fn try_await(
  promise: Promise(Result(a, b)),
  callback: fn(a) -> Promise(Result(c, b)),
) -> Promise(Result(c, b))

Run a promise returning function on the value a promise resolves to, after it has resolved.

The function is only called if the value is Ok, and the returned becomes the new value contained by the promise.

This is a convenience functin that combines the await function with result.try.

wait

</>

pub fn wait(delay: Int) -> Promise(Nil)

Create a promise that will resolve after a delay. The delay is specified in milliseconds

✨