How to type an async Function in TypeScript

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

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

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.

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

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

Copied!
async function logNumber(num: number): Promise<void> {
  await Promise.resolve();

  console.log(num);
}

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

Copied!
async function logNumber(num: number): Promise<never> {
  await Promise.resolve();

  throw new Error('Something went wrong');
}

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

Copied!
// ⛔️ 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');
}

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 will 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:

• Declare functions returning Object or Array in TypeScript
• How to Declare a Function that throws an Error in TypeScript
• Top-level await expressions are only allowed when the module option is set to es2022
• Type 'Promise' is not assignable to type in TypeScript