require-await Potential pitfall if used. Doc update maybe?

[KpjComp]

Been using ESLint for a while, most rules are great.
But I would like to point out there is a major problem in enabling this rule.

The problem, take the code below.

async function test() { throw new Error("test"); }

There is no await, but what the async does here is guarantee a Promise. So the following code will return got.

test().catch(function (e) { console.log("got"); })

Take away the async and the above code is going to fail big time Now if you can guarantee you are always going to call test with await, you are ok again as await will check if it's a Promise, but if you sent this to any other other Promise based consumers you have the above issue.

I'm mainly pointing this out as the Doc's say nothing of this issue, and could potential cause hard to debug issues for people who are currently mixing Promise & async / await. So I wonder if a big warning of this potential pitfall should be put in the Doc's.

[not-an-aardvark]

Seems reasonable to me. There was more discussion on potential pitfalls in #6820.

[GCrispino]

Is there anything else that could be done about this issue?

The docs have a "When Not To Use It" section, that apparently warns the user that this rule may bring some harm to their code. So it seems to me that this is a matter of using or not using the rule.

Any more thoughts?

[santanaG]

Given @GCrispino 's point. What should be done about this?

[dhruvdutt]

I would love to work on this. ✋ Can someone please describe the spec and point to some code?

[kaicataldo]

@dhruvdutt Great! The documentation file in question is here. What do you mean by "describe the spec"?

[NYCJacob]

What if you just added a couple of sentences to the rule details explaining the danger?

[nzakas]

I'll take a stab at this.