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.
| Method | Description |
|---|---|
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
| Function | When 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)