Handle union type of void and Promise<void> in return types

[MattiasMartens]

Suggestion

🔍 Search Terms

void, async, second-order functions

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion (and motivating example)

(I apologize if there is already discussion around this; I haven't been able to find it.)

It is sometimes convenient for a second-order function to receive a function that may or may not be asynchronous:

function mySecondOrderFn(firstOrderFn: () => void | Promise<void>) {
  return async () => {
    console.log("Calling firstOrderFn()")
    const output = await firstOrderFn()
    console.log("Finished calling firstOrderFn()")
  } 
}

// @ts-expect-error I'd like to be able to do this:
mySecondOrderFn(() => 2)

// @ts-expect-error Or this, for that matter:
mySecondOrderFn(async () => 2)

Unfortunately () => void | Promise<void> seems to cancel TS's normal type inference around () => void:

const x: () => void = () => 2
// @ts-expect-error Type 'number' is not assignable to type 'void | Promise<void>
const y: () => void | Promise<void> = () => 2

In addition (this is probably the root cause): () => Promise<void> by itself is pickier than I would expect since only () => Promise<undefined> and () => Promise<any> are assignable to it. I understand that void is not an inferrable type but this case does not require void to be inferred, does it?

I suspect this problem exists because of how void interacts with parameterized types. Maybe there isn't a general solution to that, but at least I think () => Promise<2> extends () => Promise<void> would be desirable to support as a special case, given the ubiquity of the async/await pattern.

💻 Use Cases

In my case, I'm writing an implementation of forEach. It is a context that applies backpressure so I want the first-order function to be able to return a Promise, but otherwise I don't care about the output.

() => any does suffice here; () => any | Promise<any> is marginally more expressive, although from a type perspective it is exactly the same. In either case I am exposed to the pitfalls of the any type, in particular that is easy to assign such output to a value by mistake (precisely what void exists to prevent you from doing).

[MartinJohns]

Related: #42709

[Lioness100]

Any updates on this?

[pig800509]

SonarLint rule
Promises should not be misused (typescript:S6544)

[rotu]

I don't think void return type actually fits what you're trying to accomplish here. I think you're better served by using a type parameter:

function mySecondOrderFn<T>(firstOrderFn: () => T | Promise<T>) {
  return async () => {
    console.log("Calling firstOrderFn()")
    const output = await firstOrderFn()
    console.log("Finished calling firstOrderFn()")
  } 
}

As for avoiding any, you could also use unknown instead, which is safer since it prevents accidentally doing anything with the value (though unknown | Promise<unknown> still reduces to unknown)

[HoldYourWaffle]

Worth mentioning that this problem breaks/contradicts the Do's and Don'ts section on return types of callbacks.

[rotu]

@HoldYourWaffle
I think you're referring to this:

✅ Do use the return type void for callbacks whose value will be ignored

I'm not sure it's in contradiction. That's guidance for callbacks whose value will be ignored. But this is a callback whose value won't be ignored.

But ()=>(Promise<void>|void) is less useful than it appears, since ()=>Promise<void> is already assignable to ()=>void.

---

Another few solutions to the original problem:

1. Use (() => void) | (()=>Promise<void>) instead of ()=>(void|Promise<void>).
2. Use ()=>void as the argument type and a typecast inside the implementation (to silence the warning about await not having any effect on an expression of type void)
3. My preferred version is still using generic ()=>T, or ()=>unknown and eschewing void entirely.