docs: improve return-await description about motivation #9201
Conversation
|
Thanks for the PR, @Josh-Cena! typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community. The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately. Thanks again! 🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. |
✅ Deploy Preview for typescript-eslint ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| @@ -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', | |||
There was a problem hiding this comment.
(praise) much better than the old text!
| @@ -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. | |||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
FWIW, the base rule was deprecated because it was based on the false premise that
return promise;is faster thanreturn 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 changesreturn await something;toreturn 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!
There was a problem hiding this comment.
Despite only being a ~dozen added lines, this somehow makes the rule's doc page much more clear & informative. Very nicely done @Josh-Cena! 👏 😍
PR Checklist
Overview