promise

Provides typed Promise composition at the JavaScript FFI boundary.

Compatible operations delegate to gleam/javascript/promise so their behavior stays owned by that package. Only rejected-Promise construction and Promise-returning recovery keep a minimal handwritten adapter, because the package has no primitive that preserves their current contract.

Types

PromiseRejection

</>

Represents a JavaScript Promise rejection reason.

pub type PromiseRejection

Values

all

</>

pub fn all(
  promises promises: List(promise.Promise(value)),
) -> promise.Promise(List(value))

Waits for every Promise to fulfill, preserving input order.

await_

</>

pub fn await_(
  promise promise: promise.Promise(value),
  then callback: fn(value) -> Nil,
) -> Nil

Runs a callback exactly once after a Promise fulfills without blocking.

catch_

</>

pub fn catch_(
  promise promise: promise.Promise(value),
  with callback: fn(PromiseRejection) -> promise.Promise(value),
) -> promise.Promise(value)

Recovers from a Promise rejection.

Keeps a custom adapter because gleam/javascript/promise.rescue recovers with a plain value, so it cannot preserve this helper’s Promise-returning recovery, its opaque PromiseRejection reason, or its automatic flattening.

map

</>

pub fn map(
  promise promise: promise.Promise(value),
  with callback: fn(value) -> next,
) -> promise.Promise(next)

Maps a fulfilled Promise value.

race

</>

pub fn race(
  promises promises: List(promise.Promise(value)),
) -> promise.Promise(value)

Resolves or rejects with the first completed Promise.

reject

</>

pub fn reject(reason reason: String) -> promise.Promise(value)

Creates a rejected Promise with an error message.

Keeps a custom adapter because gleam/javascript/promise exposes no rejection constructor. The reason is wrapped in a JavaScript Error, which is the contract callers depend on.

resolve

</>

pub fn resolve(value value: value) -> promise.Promise(value)

Creates an already fulfilled Promise.

then_

</>

pub fn then_(
  promise promise: promise.Promise(value),
  with callback: fn(value) -> promise.Promise(next),
) -> promise.Promise(next)

Chains a Promise-producing callback.