Interface Promise<T>

Chains onto an existing Promise and returns a new Promise.

Within the failure handler, you should never assume that the rejection value is a string. Some rejections within the Promise library are represented by Error objects. If you want to treat it as a string for debugging, you should call tostring on it first.

Return a Promise from the success or failure handler and it will be chained onto.

Attaches an andThen handler to this Promise that calls the given callback with the predefined arguments. The resolved value is discarded.

promise:andThenCall(someFunction, "some", "arguments")
Copy

This is sugar for

promise:andThen(function()
    return someFunction("some", "arguments")
end)
Copy

Attaches an andThen handler to this Promise that discards the resolved value and returns the given value from it.

promise:andThenReturn("value")
Copy

This is sugar for

promise:andThen(function()
    return "value"
end)
Copy

Promises are eager, so if you pass a Promise to andThenReturn, it will begin executing before andThenReturn is reached in the chain. Likewise, if you pass a Promise created from Promise.reject into andThenReturn, it's possible that this will trigger the unhandled rejection warning. If you need to return a Promise, it's usually best practice to use Promise.andThen.

Yields the current thread until the given Promise completes. Returns true if the Promise resolved, followed by the values that the promise resolved or rejected with.

If the Promise gets cancelled, this function will return false, which is indistinguishable from a rejection. If you need to differentiate, you should use Promise.awaitStatus instead.

Yields the current thread until the given Promise completes. Returns the Promise's status, followed by the values that the promise resolved or rejected with.

Cancels this promise, preventing the promise from resolving or rejecting. Does not do anything if the promise is already settled.

Cancellations will propagate upwards and downwards through chained promises.

Promises will only be cancelled if all of their consumers are also cancelled. This is to say that if you call andThen twice on the same promise, and you cancel only one of the child promises, it will not cancel the parent promise until the other child promise is also cancelled.

promise:cancel()
Copy

Shorthand for Promise:andThen(nil, failureHandler).

Returns a Promise that resolves if the failureHandler worked without encountering an additional error.

Set a handler that will be called only if the Promise resolves or is cancelled. This method is similar to finally, except it doesn't catch rejections.

done should be reserved specifically when you want to perform some operation after the Promise is finished (like finally), but you don't want to consume rejections (like in this example). You should use andThen instead if you only care about the Resolved case.

Like finally, if the Promise is cancelled, any Promises chained off of it with andThen won't run. Only Promises chained with done and finally will run in the case of cancellation.

Returns a new promise chained from this promise.

Same as andThenCall, except for done.

Attaches a done handler to this Promise that calls the given callback with the predefined arguments.

Attaches a done handler to this Promise that discards the resolved value and returns the given value from it.

promise:doneReturn("value")
Copy

This is sugar for

promise:done(function()
    return "value"
end)
Copy

Yields the current thread until the given Promise completes. Returns the values that the promise resolved with.

local worked = pcall(function()
    print("got", getTheValue():expect())
end)

if not worked then
    warn("it failed")
end
Copy

This is essentially sugar for:

select(2, assert(promise:await()))
Copy

Errors if the Promise rejects or gets cancelled.

Set a handler that will be called regardless of the promise's fate. The handler is called when the promise is resolved, rejected, or cancelled.

Returns a new promise chained from this promise.

If the Promise is cancelled, any Promises chained off of it with andThen won't run. Only Promises chained with finally or done will run in the case of cancellation.

local thing = createSomething()

doSomethingWith(thing)
    :andThen(function()
    print("It worked!")
        -- do something..
    end)
    :catch(function()
        warn("Oh no it failed!")
    end)
    :finally(function()
        -- either way, destroy thing

        thing:Destroy()
    end)
Copy

Same as andThenCall, except for finally.

Attaches a finally handler to this Promise that calls the given callback with the predefined arguments.

Attaches a finally handler to this Promise that discards the resolved value and returns the given value from it.

promise:finallyReturn("value")
Copy

This is sugar for

promise:finally(function()
    return "value"
end)
Copy

Returns the current Promise status.

Chains a Promise from this one that is resolved if this Promise is already resolved, and rejected if it is not resolved at the time of calling :now(). This can be used to ensure your andThen handler occurs on the same frame as the root Promise execution.

doSomething()
    :now()
    :andThen(function(value)
        print("Got", value, "synchronously.")
    end)
Copy

If this Promise is still running, Rejected, or Cancelled, the Promise returned from :now() will reject with the rejectionValue if passed, otherwise with a Promise.Error(Promise.Error.Kind.NotResolvedInTime). This can be checked with Error.isKind.

Similar to Promise.andThen, except the return value is the same as the value passed to the handler. In other words, you can insert a :tap into a Promise chain without affecting the value that downstream Promises receive.

getTheValue()
    :tap(print)
    :andThen(function(theValue))
        print("Got", theValue, "even though print returns nil!")
    end)
Copy

If you return a Promise from the tap handler callback, its value will be discarded but tap will still wait until it resolves before passing the original value through.

Chains onto an existing Promise and returns a new Promise.

Within the failure handler, you should never assume that the rejection value is a string. Some rejections within the Promise library are represented by Error objects. If you want to treat it as a string for debugging, you should call tostring on it first.

Return a Promise from the success or failure handler and it will be chained onto.

Returns a new Promise that resolves if the chained Promise resolves within seconds seconds, or rejects if execution time exceeds seconds. The chained Promise will be cancelled if the timeout is reached.

Rejects with rejectionValue if it is non-nil. If a rejectionValue is not given, it will reject with a Promise.Error(Promise.Error.Kind.TimedOut). This can be checked with Error.isKind.

getSomething():timeout(5):andThen(function(something)
    -- got something and it only took at max 5 seconds
end):catch(function(e)
    -- Either getting something failed or the time was exceeded.

    if Promise.Error.isKind(e, Promise.Error.Kind.TimedOut) then
        warn("Operation timed out!")
    else
        warn("Operation encountered an error!")
    end
end)
Copy

Sugar for:

Promise.race({
    Promise.delay(seconds):andThen(function()
        return Promise.reject(rejectionValue == nil and Promise.Error.new({ kind = Promise.Error.Kind.TimedOut }) or rejectionValue)
    end),
    promise
})
Copy