Reference

Promise

Promise.luau is a small, self-contained A+-ish implementation. It exists mainly so Thread.Start()/Thread.OnStart() have something to return, but it's a fully general-purpose async primitive you can use anywhere.

Instance methods

Called on a promise you already have.

MethodDescription
promise:andThen(onResolve?, onReject?)Standard chaining. Returns a new promise.
promise:catch(onReject)Shorthand for :andThen(nil, onReject).
promise:finally(callback)Runs callback() regardless of outcome, then passes the original result/error through.
promise:timeout(seconds, err?)Rejects if promise hasn't settled within seconds. Doesn't cancel the underlying work, just stops waiting for it.
promise:await()Yields the current thread until settled; returns the value or error()s with the rejection reason.
promise:getState()Returns "Pending", "Resolved", "Rejected", or "Cancelled".
promise:cancel(reason?)Cancels pending work, runs registered cleanup, and enters the "Cancelled" state.

Static constructors

FunctionWhen to use it
Promise.new(function(resolve, reject, onCancel) ... end)Wrap async work and optionally register cancellation cleanup.
Promise.resolve(value) / Promise.reject(err)Build an already-settled promise.
Promise.cancelled(reason?)Build a cancelled Promise.
Promise.all({...})Every promise must succeed; one failure rejects the whole batch immediately.
Promise.allSettled({...})Run several things, never reject — get a per-entry {Status, Value}/{Status, Error} report.
Promise.race({...})Settles with whichever promise finishes first (success or failure).
Promise.some({...}, count)Resolves once count of the promises have resolved; rejects if that becomes mathematically impossible.
Promise.delay(seconds)Resolves with no value after seconds — useful purely for chaining.
Promise.retry(fn, attempts)Calls fn() (must return a promise) up to attempts times, stopping at the first success.
Promise.fromEvent(signal, predicate?)Wraps any RBXScriptSignal (or a Thread.Signal) into a one-shot promise that resolves the next time it fires.
Promise.is(value)true if value is a Promise instance.
Promise.isCancelledError(value)Distinguishes cancellation from ordinary rejection.
Promise.setUnhandledRejectionHandler(fn?)Configures reporting for rejected Promises with no observer.

Common patterns

-- Retry a flaky DataStore call:
Promise.retry(function()
    return Promise.new(function(resolve, reject)
        local ok, result = pcall(dataStore.GetAsync, dataStore, "key")
        if ok then resolve(result) else reject(result) end
    end)
end, 5):andThen(print):catch(warn)

-- Don't let a slow operation hang forever:
someSlowPromise:timeout(5):catch(warn)

-- Wait for the next CharacterAdded, as a promise instead of a callback:
Promise.fromEvent(player.CharacterAdded):andThen(function(character)
    print(character.Name, "spawned")
end)

-- First to settle wins:
Promise.race({ promiseA, promiseB }):andThen(print)

-- Resolve once N of many resolve:
Promise.some({ p1, p2, p3 }, 2):andThen(print)