Add a new `type Awaitable<T> = T | PromiseLike<T>`

[remcohaszing]

Search Terms

• awaitable

Suggestion

Add an awaitable type for values that will be awaited.

type Awaitable<T> = T | PromiseLike<T>;

This is based on my question and a comment on StackOverflow

Use Cases

Two use cases come in mind immediately:

1. A function accepts a callback that may either return a value synchronously, or may return a promise value. This will then probably be awaited.
2. This is more of a specific version of 1, but this would be the return type of Promise.then() / Promise.catch / Promise.finally callbacks.

Also, this type could replace all 1334 occurrences that come up when running git grep '| Promise' in the current TypeScript code base.

Examples

Callback example:

async function logAnswer(getAnswer: () => Awaitable<number>): Promise<void> {
  const answer = await getAnswer();
  console.log(answer);
}

logAnswer(() => 42);
logAnswer(() => Promise.resolve(42));

Promise example:

Promise.resolve('Hello, world!').then(
  // This type annotation is silly. This is really just to show promise callbacks should accept `Awaitable<T>`.
  (hello): Awaitable<string> => {
    console.log(hello);
    return hello;
  },
);

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.

[fatcerberus]

At first I didn't see the utility of this since everything in JavaScript is awaitable, but I just realized it's good for type inference:

type Awaitable<T> = T | PromiseLike<T>;

declare function foo<T>(callback: () => T): Promise<T>;
declare function bar<T>(callback: () => Awaitable<T>): Promise<T>;

const fun = () => Promise.resolve(812);
let food = foo(fun);  // Promise<Promise<number>>, which is not actually a thing.
let bard = bar(fun);  // Promise<number> - yes!

[fabiospampinato]

I think Promisable would be a better name than Awaitable.

Since any value is awaitable in TS this name seems too generic to me, Promisable on the other hand says to me that the value could be actually a Promise (technically a PromiseLike, but PromiseLikeable or PromiseableLike sound awful to me).

[Vandivier]

I think Promisable and Awaitable are both fair, but I notice that ForAwaitable is another type under discussion and recommend that these two types are aligned regardless of the direction we go.

#36153

[remcohaszing]

Some feedback from future self: I have been using Promisable a lot. I really hope this will be a builtin type.

[remcohaszing]

This was added in #45350 and will be part of TypeScript 4.5.