Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: improve return-await description about motivation #9201

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jun 17, 2024
Merged

docs: improve return-await description about motivation #9201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions packages/eslint-plugin/docs/rules/return-await.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
description: 'Enforce consistent returning of awaited values.'
description: 'Enforce consistent awaiting of returned promises.'
---

import Tabs from '@theme/Tabs';
Expand All @@ -9,12 +9,14 @@ import TabItem from '@theme/TabItem';
>
> See **https://typescript-eslint.io/rules/return-await** for documentation.

Returning an awaited promise can make sense for better stack trace information as well as for consistent error handling (returned promises will not be caught in an async function try/catch).

This rule builds on top of the [`eslint/no-return-await`](https://eslint.org/docs/rules/no-return-await) rule.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i kinda think we should drop this, as well as the comments around the naming. the base rule has been deprecated for some time, and this rule has an independent life of its own now.

I think, instead, it would be better to relegate the reference to the base rule to a little info box saying (approximaely) "this was originally conceived as an extension rule associated with the eslint rule no-return-await, but that's no longer the case. The base rule became deprecated because it was realized that it did more harm than good, due to limitations of not having access to type information. If you're interested in reading on the history of that decision, see <insert link>"

What do you think?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, the base rule was deprecated because it was based on the false premise that return promise; is faster than return await promise;, which may be true for some time but not anymore. return await promise; is desirable in all other regards. It's totally possible to build a type-unaware rule that changes return await something; to return something;, but not in the other direction.

I think we should keep it at least for another ESLint major version, as people are still familiar with this rule.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, the base rule was deprecated because it was based on the false premise that return promise; is faster than return await promise;

Right, performance was the once-believed-but-now-debunked good.

return await promise; is desirable in all other regards. It's totally possible to build a type-unaware rule that changes return await something; to return something;, but not in the other direction.

harm, due to limitations of not having access to type information.

That's where I get my summary that it was doing more harm than good due to the limitations of not having access to type information 🙂 But no need to use this wording if you feel otherwise!

It expands upon the base rule to add support for optionally requiring `return await` in certain cases.

The extended rule is named `return-await` instead of `no-return-await` because the extended rule can enforce the positive or the negative. Additionally, while the core rule is now deprecated, the extended rule is still useful in many contexts.
The extended rule is named `return-await` instead of `no-return-await` because the extended rule can enforce the positive or the negative. Additionally, while the core rule is now deprecated, the extended rule is still useful in many contexts:

- Returning an awaited promise [improves stack trace information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#improving_stack_trace).
- When the `return` statement is in `try...catch`, awaiting the promise also allows the promise's rejection to be caught instead of leaving the error to the caller.
- Contrary to popular belief, `return await promise;` is [at least as fast as directly returning the promise](https://github.com/tc39/proposal-faster-promise-adoption).

## Options

Expand Down
2 changes: 1 addition & 1 deletion packages/eslint-plugin/src/rules/return-await.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ export default createRule({
name: 'return-await',
meta: {
docs: {
description: 'Enforce consistent returning of awaited values',
description: 'Enforce consistent awaiting of returned promises',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(praise) much better than the old text!

requiresTypeChecking: true,
extendsBaseRule: 'no-return-await',
},
Expand Down
Loading