Declare a function with a Promise return type in TypeScript

avatar
Borislav Hadzhiev

Last updated: Jan 21, 2023
4 min

banner

# Table of Contents

  1. Declare a function with a Promise return type in TypeScript
  2. Get the return type of a Promise in TypeScript

# Declare a function with a Promise return type in TypeScript

To declare a function with a promise return type, set the return type of the function to a promise right after the function's parameter list.

If the return type of the function is not set, TypeScript will infer it.

index.ts
// โœ… Named function function getPromise(): Promise<number> { return Promise.resolve(5); } // ๐Ÿ‘‡๏ธ Unwrap promise type if necessary // ๐Ÿ‘‡๏ธ type T = number type T = Awaited<ReturnType<typeof getPromise>>; // โœ… Named async function async function getPromise2(): Promise<number> { return 10; } // โœ… Arrow function const getPromise3 = (): Promise<string> => { return Promise.resolve('bobbyhadz.com'); };

declare function with promise return type in typescript

Here are 3 more examples.

index.js
// โœ… Class method class A { async getPromise(): Promise<string> { return 'bobbyhadz.com'; } } // โœ… Using a type as Promise<Type> type Person = { name: string; age: number; }; async function getPromise4(): Promise<Person[]> { return [ { name: 'Bobby Hadz', age: 30, }, ]; }

You can set the return type of a function right after its parameter list.

index.ts
function getPromise(a: number): Promise<number> { return Promise.resolve(a); }

# Unwrapping the type of a Promise from a function's return type

If you need to unwrap the type of the Promise from a function's return type, use the Awaited utility type.

index.ts
function getPromise(a: number): Promise<number> { return Promise.resolve(a); } // ๐Ÿ‘‡๏ธ Unwrap promise type if necessary // ๐Ÿ‘‡๏ธ type T = number type T = Awaited<ReturnType<typeof getPromise>>;

The Awaited utility type recursively unwraps a promise and returns its type.

index.ts
// ๐Ÿ‘‡๏ธ type A = string type A = Awaited<Promise<string>>;

The examples above show how to set the return type of a function to a promise containing different values.

The advantage of setting the return type of the function explicitly is that the type checker would throw an error if you try to return a promise of a different type.

index.ts
async function getPromise2(): Promise<number> { // โ›”๏ธ Type 'string' is not assignable to type 'number'.ts(2322) return 'bobbyhadz.com'; }

If you don't explicitly set the return type of the function, TypeScript will infer it.

index.ts
// ๐Ÿ‘‡๏ธ function getPromise2(): Promise<string> async function getPromise2() { return 'bobbyhadz.com'; }

# Use a union type of the function returns a Promise of multiple types

If your function returns a Promise that may contain different values, use a union to specify the function's return type.

index.ts
async function getPromise2(): Promise<string | null> { if (Math.random() > 0.5) { return null; } return 'bobbyhadz.com'; }

function returning promise of multiple types

The function above returns a Promise that contains a string or a null value.

If your function returns a Promise that unwraps to an array of objects, it's more readable to use a type or an interface.

index.ts
type Person = { name: string; age: number; }; async function getPromise4(): Promise<Person[]> { return [ { name: 'Bobby Hadz', age: 30, }, ]; }

The function above returns a Promise that contains an array of objects of type Person.

# Get the return type of a Promise in TypeScript

Use the Awaited utility type to get the return type of a promise in TypeScript.

The Awaited utility type is used to recursively unwrap Promises and get their return type.

index.ts
// ๐Ÿ‘‡๏ธ type A = string type A = Awaited<Promise<string>>; // ๐Ÿ‘‡๏ธ type B = string type B = Awaited<Promise<Promise<string>>>; // ๐Ÿ‘‡๏ธ C = boolean | number type C = Awaited<boolean | Promise<number>>; async function sum(a: number, b: number): Promise<number> { return a + b; } // ๐Ÿ‘‡๏ธ type D = number type D = Awaited<ReturnType<typeof sum>>;

We used the Awaited utility type to get the return type of a couple of Promises in the examples.

The type is used to recursively unwrap a Promise and get its return type.

The second example shows that we can unwrap the type of the promise even if it's nested.

index.ts
// ๐Ÿ‘‡๏ธ type B = string type B = Awaited<Promise<Promise<string>>>;

# Unwrap the return type of a Promise from a function's return type

If you need to unwrap the return type of a promise from a function's return type, use the ReturnType utility type.

index.ts
function multiply(a: number, b: number): Promise<number> { return Promise.resolve(a * b); } // ๐Ÿ‘‡๏ธ type E = number type E = Awaited<ReturnType<typeof multiply>>;

The ReturnType utility type constructs a type consisting of the function's return type.

# Unwrap the return type of an async function

You can use the same approach to unwrap the return type of an async function. Note that async functions always return a Promise.

index.ts
async function sum(a: number, b: number): Promise<number> { return a + b; } // ๐Ÿ‘‡๏ธ type D = number type D = Awaited<ReturnType<typeof sum>>;

This approach also works with built-in methods like Promise.all and Promise.race.

index.ts
async function getArr(a: number, b: number): Promise<[number, string]> { const result = await Promise.all([ Promise.resolve(5), Promise.resolve('bobbyhadz.com'), ]); return result; } // ๐Ÿ‘‡๏ธ [number, string] type E = Awaited<ReturnType<typeof getArr>>;

If you need to pass a function as a parameter, check out the following article.

# 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.

Copyright ยฉ 2024 Borislav Hadzhiev