How to type an async Function in TypeScript

avatar
Borislav Hadzhiev

Last updated: Jan 20, 2023
3 min

banner

# Type an async Function in TypeScript

To type an async function in TypeScript, set its return type to Promise<type>.

Functions marked as async are guaranteed to return a Promise even if you don't explicitly return a value, so the Promise generic should be used when specifying the function's return type.

index.ts
// ✅ Arrow function with Type type GetNumber = (num: number) => Promise<number>; const getNumber: GetNumber = async (num) => { const result = await Promise.resolve(num); return result; }; // -------------------------------------------- // ✅ Arrow function with Interface interface IGetNumber { (num: number): Promise<number>; } const getNumber2: IGetNumber = async (num) => { const result = await Promise.resolve(num); return result; };

type async function in typescript

The code sample shows how to add type definitions to async arrow functions using a type alias or an interface.

Here are 2 more examples.

index.ts
// ✅ Arrow function inline const getNumber3 = async (num: number): Promise<number> => { const result = await Promise.resolve(num); return result; }; // --------------------------------------------------- // ✅ Named function inline async function getNumber4(num: number): Promise<number> { const result = await Promise.resolve(num); return result; }

The first two examples use a type and an interface to type the async function.

The syntax is different, but the concept is the same.

Async functions always return a promise that resolves with the return value of the async function.

If the async function throws an error, it returns a Promise, that is rejected with the exception thrown from the async function.

The type we passed to the Promise generic is the type of the value that the async function returns.

# Use Promise<void> for async functions that don't return a value

If the async function doesn't return a value, you should set the return type of the async function to be Promise<void>.

index.ts
async function logNumber(num: number): Promise<void> { await Promise.resolve(); console.log(num); }

use promise void for async functions that dont return value

# Use Promise<never> for async functions that throw an error

If the async function throws an error, you should set its return type to Promise<never>.

index.ts
async function logNumber(num: number): Promise<never> { await Promise.resolve(); throw new Error('Something went wrong'); }

If you forget to set use the Promise generic when specifying the return type of an async function, you would get a clear error message.

index.ts
// ⛔️ Error: The return type of an async function or method // must be the global Promise<T> type. // Did you mean to write 'Promise<never>'? async function logNumber(num: number): never { await Promise.resolve(); throw new Error('Something went wrong'); }
The only thing to note when typing an async function is that its return type will always be a promise, regardless if it returns a value, doesn't return a value or throws an error.

This is why you should always use the Promise generic when typing an async function's return value.

I've also written a detailed guide on how to declare a function with a Promise return type.

If you forget to mark the function as async, you'd get the 'await' expression is only allowed within an async function error.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.