From c7892c927c23db841c5113421b073b4648e5b4d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Thu, 23 Apr 2020 11:28:49 +0100 Subject: [PATCH 1/4] Docs: improve documentation of no-return-await --- docs/rules/no-return-await.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/rules/no-return-await.md b/docs/rules/no-return-await.md index a79a46d8483..773f3e4f6cc 100644 --- a/docs/rules/no-return-await.md +++ b/docs/rules/no-return-await.md @@ -1,6 +1,8 @@ # Disallows unnecessary `return await` (no-return-await) -Inside an `async function`, `return await` is seldom useful. Since the return value of an `async function` is always wrapped in `Promise.resolve`, `return await` doesn’t actually do anything except add extra time before the overarching Promise resolves or rejects. The only valid exception is if `return await` is used in a try/catch statement to catch errors from another Promise-based function. +Using `return await` inside an `async function`keeps the current function in the call stack until the Promise that is being awaited have resolved. You can take a shortcut and just return the Promise right away to avoid this, saving an extra microtask before resolving the overarching Promise. + +The only visible change when doing this is that the function will no longer be a part of the stack trace, if an error is thrown asyncrously from the Promise being returned. ## Rule Details @@ -42,7 +44,11 @@ In the last example the `await` is necessary to be able to catch errors thrown f ## When Not To Use It -If you want to use `await` to denote a value that is a thenable, even when it is not necessary; or if you do not want the performance benefit of avoiding `return await`, you can turn off this rule. +There are a few reasons you might want to turn this rule off: + +- If you want to use `await` to denote a value that is a thenable +- If you do not want the performance benefit of avoiding `return await` +- If you still want the functions to show up in stack traces ## Further Reading From 712a646b3c2a8b5a2d6d376d83f368f9d36c246f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Sat, 25 Apr 2020 10:57:49 +0100 Subject: [PATCH 2/4] Docs: add try/catch caveat to no-return-await Co-Authored-By: Kai Cataldo --- docs/rules/no-return-await.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/no-return-await.md b/docs/rules/no-return-await.md index 773f3e4f6cc..e10dea68a5c 100644 --- a/docs/rules/no-return-await.md +++ b/docs/rules/no-return-await.md @@ -1,6 +1,6 @@ # Disallows unnecessary `return await` (no-return-await) -Using `return await` inside an `async function`keeps the current function in the call stack until the Promise that is being awaited have resolved. You can take a shortcut and just return the Promise right away to avoid this, saving an extra microtask before resolving the overarching Promise. +Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited have resolved. You can take a shortcut and just return the Promise right away to avoid this, saving an extra microtask before resolving the overarching Promise. `return await` can also be used in a try/catch statement to catch errors from another Promise-based function. The only visible change when doing this is that the function will no longer be a part of the stack trace, if an error is thrown asyncrously from the Promise being returned. From 73ee1336b7f074f7ae3eaf3f99582409fe86485d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Sat, 25 Apr 2020 10:58:04 +0100 Subject: [PATCH 3/4] Docs: fix typo in documentation of no-return-await Co-Authored-By: Kai Cataldo --- docs/rules/no-return-await.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/no-return-await.md b/docs/rules/no-return-await.md index e10dea68a5c..c53971f8d68 100644 --- a/docs/rules/no-return-await.md +++ b/docs/rules/no-return-await.md @@ -2,7 +2,7 @@ Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited have resolved. You can take a shortcut and just return the Promise right away to avoid this, saving an extra microtask before resolving the overarching Promise. `return await` can also be used in a try/catch statement to catch errors from another Promise-based function. -The only visible change when doing this is that the function will no longer be a part of the stack trace, if an error is thrown asyncrously from the Promise being returned. +The only visible change when doing this is that the function will no longer be a part of the stack trace, if an error is thrown asynchronously from the Promise being returned. ## Rule Details From 96079d07cea45a126efe01de694d46ba96a91501 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Thu, 14 May 2020 20:09:29 +0100 Subject: [PATCH 4/4] Docs: apply suggestions from code review Co-authored-by: Kai Cataldo --- docs/rules/no-return-await.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/rules/no-return-await.md b/docs/rules/no-return-await.md index c53971f8d68..b1c60f092ae 100644 --- a/docs/rules/no-return-await.md +++ b/docs/rules/no-return-await.md @@ -1,8 +1,8 @@ # Disallows unnecessary `return await` (no-return-await) -Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited have resolved. You can take a shortcut and just return the Promise right away to avoid this, saving an extra microtask before resolving the overarching Promise. `return await` can also be used in a try/catch statement to catch errors from another Promise-based function. +Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited has resolved, at the cost of an extra microtask before resolving the outer Promise. `return await` can also be used in a try/catch statement to catch errors from another function that returns a Promise. -The only visible change when doing this is that the function will no longer be a part of the stack trace, if an error is thrown asynchronously from the Promise being returned. +You can avoid the extra microtask by not awaiting the return value, with the trade off of the function no longer being a part of the stack trace if an error is thrown asynchronously from the Promise being returned. This can make debugging more difficult. ## Rule Details @@ -48,7 +48,7 @@ There are a few reasons you might want to turn this rule off: - If you want to use `await` to denote a value that is a thenable - If you do not want the performance benefit of avoiding `return await` -- If you still want the functions to show up in stack traces +- If you want the functions to show up in stack traces (useful for debugging purposes) ## Further Reading