As you mentioned - the rule docs explicitly state this and they also include a workaround if it is your intention to return a non-promise and a promise:

If it is intentional, make the return type explicitly to allow the rule to pass.

The change requested is unsafe as it changes the signature/type of the function entirely.

The change requested is a suggestion fixer which must be manually applied by a user. Suggestion fixers (unlike autofixers) are allowed to be unsafe or incomplete as they must be manually actioned.

If it is intentional, make the return type explicitly to allow the rule to pass.

But this is not what the error says: "Functions that return promises must be async."

The error message, as is, is incomplete/incorrect because the function does not return only a promise.

The reason why I opened this issue is specifically because I found an eslint-disable promise-function-async explanation that missed this subtlety.

Changes suggested, one or more:

1. improve error message for this case
   • e.g. "Functions that return promises must be async or have an explicit return type"
2. remove this exception, report regardless of return type presence
   • because I don’t think inference should validate or invalidate this rule
3. add a fixer to append the return type instead of adding async
4. extract A | Promise<B> reporting to its own rule
   • e.g. Rule proposal: check that function is not returning promise and non-promise #9296 to say "you should only return promises"
5. stop reporting on functions that return non-promises
   • because, once again, this function does not return only a promise, so it should not be reported

Regarding the point 5: the rule appears to be enforcing three separate issues:

• use async so that the promise-returning functions only throw synchronously (as the name implies)
• specify the return type (as suggested by the docs)
• do not use A | Promise<B> (as suggested by the fixer)

remove this exception, report regardless of return type presence
because I don’t think inference should validate or invalidate this rule

In the vast, vast, vast majority of cases the developer intent is to just return a promise and not to have a hybrid return type - and if you asyncify the function then you get that exact behaviour - so the rule reporting is correct and guides the user towards better code.

But there are cases where you needs to intentionally NOT asyncify the function because you NEED a hybrid output. Instead of just relying on a disable comment here we chose to take the return type as explicit developer intent that a hybrid return type was desired.

So put another way:

1. no explicit return type + hybrid return type = highly likely wanted just promise
2. explicit return type + hybrid return type = definitely wanted a hybrid return type
3. promise return type (with or without an explicit return type) = definitely wanted just promise

So the rule reports in (1) and (3) and not in (2).

• no explicit return type + hybrid return type = highly likely wanted just promise

Right, but that's what I meant in my last point, the rule is broad and it enforces something that is not in the explicit intent of the rule.

Even if you don't agree to change that, suggestions 1 and 3 still apply (error message + additional fixer)

Instead of just relying on a disable comment

Yeah, that's why it would be great to update the error message to suggest this. Most developers barely read the error messages, let alone googling the rule name to read its docs.

stop reporting on functions that return non-promises
because, once again, this function does not return only a promise, so it should not be reported

Again I want to stress that in the vast, vast, vast majority of cases a user DOES NOT WANT A HYBRID RETURN TYPE and instead the hybrid return type is an inference error caused by a function that returns a plain and a promise value.

Eg cases like this:

function doSomethingAsync(): Promise<number>;

function doSomething(condition: boolean) {
  if (condition) {
    return 1;
  }
  return doSomethingAsync();
}

Generally the intent here is "this function returns Promise<number>" because you generally can't pass number | Promise<number> anywhere and you can't call promise methods on it. And thus generally speaking users want the Promise return type.

My 2c is that

• this is and "always"[1] has been the intended behaviour for many, many years
• most users expect this case to be reported because most usecases don't want a hybrid return type.

So removing the behaviour goes against that established and expected practice.

I'd be okay with us updating the error message if the function has a hybrid return type to mention that an explicit annotation will silence the rule.

[1] iirc this case was added after the rule was first created but regardless it's near enough to "always".