Declare a function with a Promise return type in TypeScript

# Table of Contents

# 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

Copied!
// ✅ 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

The code for this article is available on GitHub

Here are 3 more examples.

index.js

Copied!
// ✅ 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

Copied!
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

Copied!
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 code for this article is available on GitHub

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

index.ts

Copied!
// 👇️ 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

Copied!
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

Copied!
// 👇️ 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

Copied!
async function getPromise2(): Promise<string | null> {
  if (Math.random() > 0.5) {
    return null;
  }

  return 'bobbyhadz.com';
}

function returning promise of multiple types

The code for this article is available on GitHub

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

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

index.ts

Copied!
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

Copied!
// 👇️ 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>>;

The code for this article is available on GitHub

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

Copied!
// 👇️ 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

Copied!
function multiply(a: number, b: number): Promise<number> {
  return Promise.resolve(a * b);
}

// 👇️ type E = number
type E = Awaited<ReturnType<typeof multiply>>;

The code for this article is available on GitHub

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

Copied!
async function sum(a: number, b: number): Promise<number> {
  return a + b;
}

// 👇️ type D = number
type D = Awaited<ReturnType<typeof sum>>;

The code for this article is available on GitHub

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

index.ts

Copied!
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.

You can use the search field on my Home Page to filter through all of my articles.

Declare a function with a Promise return type in TypeScript

# Table of Contents