Allow async functions to return union type T | Promise<T>

Search Terms

“the return type of an async function or method must be the global Promise type” “typescript promise union type”

Suggestion

You can explicitly declare a function’s return type as a union that includes a Promise<T>. While this works when manually managing promises, it results in a compiler error when using the async/await syntax.

For example, a function can have a return type T | Promise<T>. As the developer of an abstraction layer, this allows you to have an abstract return type that can be handled in a typesafe way but doesn’t dictate implementation to consumers.

This improves developer ergonomics for consumers of a library without reducing the safety of the type system by allowing developers to change implementation as the system evolves while still meeting the requirements of the abstraction layer.

This only works, currently, if the developer explicitly manages the promises. A developer may start with something like this:

type ActionResponse<T> = T | Promise<T>;

function getCurrentUsername(): ActionResponse<string> {
  return 'Constant Username';
}

async function logResponse<T>(response: ActionResponse<T>): Promise<void> {
  const responseValue = await response;
  console.log(responseValue);
}

logResponse(getCurrentUsername());
// Constant Username

Then, if the consumer of logResponse switches to a promise based method, there’s no need to change the explicit return type:

function getCurrentUsername(): ActionResponse<string> {
  // return 'Constant Username';
  return Promise.resolve('Username from Database');
}

// Username from Database

However, if the consumer of logResponse prefers to use async/await instead of manually managing promises, this no longer works, yielding a compiler error instead:

The return type of an async function or method must be the global Promise<T> type.

One workaround is to always return promises even when dealing non-async code:

async function getCurrentUsername(): Promise<string> {
  return 'Constant Username';
  // return Promise.resolve('Username from Database');
}

Another workaround is to use an implicit return type:

async function getCurrentUsername() {
  return Promise.resolve('Username from Database');
}

These do get around the issue for sure, but they impose restrictions on consumers of the abstraction layer causing it to leak into implementation.

It seems valuable for the behavior to be consistent between using async/await and using Promise directly.

Use Cases

This feature would be useful for developers who are building abstraction layers and would like to provide an abstract return type that could include promises. Some likely examples are middlewares, IoC containers, ORMs, etc.

In my particular case, it’s with inversify-express-utils where the action invoked can be either async or not and the resulting behavior doesn’t change.

Examples

// this type
type ActionResponse<T> = T | Promise<T>;

// supports this function
function getCurrentUsername(): ActionResponse<string> {
  return 'Constant Username';
}

// as it evolves over time into this function
async function getCurrentUsername(): ActionResponse<string> {
  return Promise.resolve('Username from Database');
}

// and is handled transparently by functions like this
async function logResponse<T>(response: ActionResponse<T>): Promise<void> {
  const responseValue = await response;
  console.log(responseValue);
}

logResponse(getCurrentUsername());

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, etc.)
• This feature would agree with the rest of TypeScript’s Design Goals.

[yortus]

Or more briefly, TypeScript has a structural type system and pretty consistently applies it, except with async function return types, where it does a nominal, not structural, check.

Usually when you specify parameter and return type annotations on a function in TypeScript, the caller can pass in anything that is assignment-compatible with the parameter types, and the function can return anything that is assignment compatible with the return type. Likewise with variable assignments, property assignments, etc etc. Async function return types are a rare exception to this rule.

Even generator functions, which just like async functions always return a known system type, can be annotated with assignment-compatible return types which are checked structurally.

IMO there is an inconsistency here. The consequences are arguably not huge, but have been reported in a number of issues over the years so do affect at least some users. I can’t really see the downsides of removing this inconsistency.

[RyanCavanaugh]

I don’t understand the need for this. Why does the second getCurrentUsername have the async modifier? It works perfectly without it.

You only need the async modifier if you use the await operator in the function body, in which case the function never returns a bare T (even an immediate return triggers an event loop tick, per ES spec) and it makes more sense to just write Promise<string> as the return type.