Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: improve documentation of no-return-await #13215

Merged
merged 4 commits into from May 14, 2020
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
10 changes: 8 additions & 2 deletions 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. `return await` can also be used in a try/catch statement to catch errors from another Promise-based function.
LinusU marked this conversation as resolved.
Show resolved Hide resolved

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.
LinusU marked this conversation as resolved.
Show resolved Hide resolved

## Rule Details

Expand Down Expand Up @@ -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
LinusU marked this conversation as resolved.
Show resolved Hide resolved

## Further Reading

Expand Down