diff --git a/lib/README.md b/lib/README.md index 9cc5d9f..2283e6f 100644 --- a/lib/README.md +++ b/lib/README.md @@ -543,6 +543,7 @@ docs: 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. - name: await + tags: [ 'yields' ] desc: | 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. @@ -556,17 +557,25 @@ docs: type: ...any? - name: awaitStatus + tags: [ 'yields' ] desc: 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. returns: - type: PromiseStatus desc: The Promise's status. - type: ...any? desc: The values that the Promise resolved or rejected with. - - name: awaitValue + - name: expect + tags: [ 'yields' ] desc: | Yields the current thread until the given Promise completes. Returns the the values that the promise resolved with. + + This is essentially sugar for: + + ```lua + select(2, assert(promise:await())) + ``` - Errors if the Promise rejects or gets cancelled. + **Errors** if the Promise rejects or gets cancelled. returns: - type: ...any? desc: The values that the Promise resolved with. diff --git a/lib/init.lua b/lib/init.lua index 94afab4..f5a5521 100644 --- a/lib/init.lua +++ b/lib/init.lua @@ -875,7 +875,7 @@ end Calls await and only returns if the Promise resolves. Throws if the Promise rejects or gets cancelled. ]] -function Promise.prototype:awaitValue(...) +function Promise.prototype:expect(...) local length, result = pack(self:awaitStatus(...)) local status = table.remove(result, 1) @@ -887,6 +887,8 @@ function Promise.prototype:awaitValue(...) return unpack(result, 1, length - 1) end +Promise.prototype.awaitValue = Promise.prototype.expect + --[[ Intended for use in tests.