promise

Low-level Promise constructor and combinators that back the async/await runtime.

Import

import promise

Functions

promise.new(fn: (resolve, reject) -> void) -> Promise

Construct a new promise. Call resolve(val) or reject(err) from within fn to settle it.

promise.resolve(val: any) -> Promise

Create an already-resolved promise with the given value.

promise.reject(err: any) -> Promise

Create an already-rejected promise with the given error.

promise.all(promises: [Promise]) -> Promise

Resolve when all promises resolve; reject as soon as any rejects. Result is an array of values.

promise.race(promises: [Promise]) -> Promise

Settle with the first promise to settle (resolve or reject).

promise.any(promises: [Promise]) -> Promise

Resolve with the first promise to resolve; reject only if all reject.

promise.all_settled(promises: [Promise]) -> Promise

Wait for all promises to settle, returning an array of result maps regardless of outcome.

promise.then(p: Promise, on_resolve: fn, on_reject?: fn) -> Promise

Attach fulfillment and optional rejection handlers, returning a new promise.

promise.catch_err(p: Promise, on_reject: fn) -> Promise

Attach a rejection handler.

promise.finally_do(p: Promise, fn: () -> void) -> Promise

Run fn when the promise settles, regardless of outcome.

promise.sleep(ms: int) -> Promise

Return a promise that resolves after ms milliseconds.

promise.timeout(p: Promise, ms: int) -> Promise

Return a promise that rejects with a timeout error if p doesn't settle within ms milliseconds.

promise.state(p: Promise) -> str

Return the current state: "pending", "resolved", or "rejected".

promise.value(p: Promise) -> any

Return the resolved value or rejection error if settled, null if still pending.

promise.drain()

Flush the microtask queue, running all pending callbacks. Normally called automatically.

Examples

import promise

-- construct manually
let p = promise.new(fn(resolve, reject) {
    resolve(42)
})
println(promise.state(p))   -- resolved
println(promise.value(p))   -- 42

-- combinators
let a = promise.resolve(1)
let b = promise.resolve(2)
let both = promise.all([a, b])
promise.drain()
println(promise.value(both))  -- [1, 2]

-- chaining
let result = promise.then(
    promise.resolve(10),
    fn(v) { v * 2 }
)
promise.drain()
println(promise.value(result))  -- 20