Promise<T> / async / await Types

function fn(): Promise<T> { /* ... */ }

// async function (return type is automatically Promise<T>)
async function fn(): Promise<T> {
  const result = await somePromise; // result: T
  return result;
}

// Extract the resolved type with Awaited
type Resolved = Awaited<Promise<T>>; // => T

interface User {
  id: number;
  name: string;
}

// Explicit type annotation with Promise<T>
function fetchUser(id: number): Promise<User> {
  return fetch(`/api/users/${id}`).then(res => res.json());
}

// Using async/await syntax
async function getUser(id: number): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const user: User = await res.json();
  return user;
}

// Error handling
async function safeGetUser(id: number): Promise<User | null> {
  try {
    return await getUser(id);
  } catch {
    return null;
  }
}

// Extracting a type with Awaited
type UserResult = Awaited<ReturnType<typeof getUser>>;
// => User

// Type inference with Promise.all
async function loadAll(): Promise<void> {
  const [user1, user2] = await Promise.all([
    getUser(1),
    getUser(2),
  ]);
  // user1 and user2 are both of type User
  console.log(user1.name, user2.name);
}

The return type of an async function is automatically wrapped in a Promise. For example, even if you write the return type as string, the actual type becomes Promise<string>. It is common practice to write the annotation explicitly as async function fn(): Promise<string>.

Awaited<T> is especially useful in combination with ReturnType<T> to obtain the resolved return type of an async function.

In TypeScript 4.0 and later, the catch block parameter is typed as unknown. To access properties such as an error message, you need to narrow the type using an instanceof guard.