From e58a8d8a6b89ac309bb0cfee1516daf415a76802 Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Wed, 13 Mar 2024 11:35:06 -0230 Subject: [PATCH] docs: Add caution about suppressing errors (#174) The TSDoc comment for `createDeferredPromise` has been updated to include a caution about using the `suppressUnhandledRejection` option. The comment now explains in more detail why this option is useful, and why it can be dangerous and should be treated with caution. --- src/promise.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/promise.ts b/src/promise.ts index af4a168d9..e30565100 100644 --- a/src/promise.ts +++ b/src/promise.ts @@ -23,6 +23,16 @@ export type DeferredPromise = { /** * Create a defered Promise. * + * If the Promise is rejected prior to a handler being added, this can result in an + * `UnhandledPromiseRejection` error. Optionally this can be suppressed with the + * `suppressUnhandledRejection` flag, as it's common to belatedly handle deferred Promises, or to + * ignore them if they're no longer relevant (e.g. related to a cancelled request). + * + * However, be very careful that you have handled the Promise if you do this. Suppressing these + * errors is dangerous, they exist for good reason. An unhandled rejection can hide errors, making + * debugging extremely difficult. They should only be suppressed if you're confident that the + * Promise is always handled correctly, in both the success and failure cases. + * * @param args - The arguments. * @param args.suppressUnhandledRejection - This option adds an empty error handler * to the Promise to suppress the UnhandledPromiseRejection error. This can be