From 98c579f68d7e5cec4cc72f568fe7e4397e6fbe69 Mon Sep 17 00:00:00 2001 From: Osyris Date: Sun, 23 Jun 2024 22:23:50 -0400 Subject: [PATCH] Update types/Promise.d.ts Co-authored-by: Sasial <44125644+sasial-dev@users.noreply.github.com> --- types/Promise.d.ts | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/types/Promise.d.ts b/types/Promise.d.ts index 82e856e..cc42757 100644 --- a/types/Promise.d.ts +++ b/types/Promise.d.ts @@ -110,7 +110,25 @@ interface Promise { * * 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` will run in the case of cancellation. + * > 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 that: + - resolves with the same values that this Promise resolves with. + - rejects with the same values that this Promise rejects with. + - is cancelled if this Promise is cancelled. + If the value you return from the handler is a Promise: + - We wait for the Promise to resolve, but we ultimately discard the resolved value. + - If the returned Promise rejects, the Promise returned from `finally` will reject with the rejected value from the + *returned* promise. + - If the `finally` Promise is cancelled, and you returned a Promise from the handler, we cancel that Promise too. + Otherwise, the return value from the `finally` handler is entirely discarded. + :::note Cancellation + As of Promise v4, `Promise:finally` does not count as a consumer of the parent Promise for cancellation purposes. + This means that if all of a Promise's consumers are cancelled and the only remaining callbacks are finally handlers, + the Promise is cancelled and the finally callbacks run then and there. + Cancellation still propagates through the `finally` Promise though: if you cancel the `finally` Promise, it can cancel + its parent Promise if it had no other consumers. Likewise, if the parent Promise is cancelled, the `finally` Promise + will also be cancelled. * ```lua * local thing = createSomething() *