Awaited

The Awaited utility type for unwrapping Promise and thenable types, including nested promises and the difference from runtime Promise methods.

テーマページの本文は現在英語です。

Awaited<T> is the type you get by awaiting a value of type T. It was added in TypeScript 4.5. It recursively unwraps Promise types, so Awaited<Promise<Promise<string>>> is string. A non-thenable type is left alone: Awaited<number> is number.

Awaited is a compile-time type. It is not Promise.then, Promise.all, or any other JavaScript Promise method. Those runtime APIs are covered in the JavaScript Promise reference. Using Promise.resolve on a Promise also flattens at runtime, so a value of type Promise<Promise<string>> is uncommon in practice; the nested form is still useful as a type.

Examples were checked with TypeScript 5.9.3 using tsc --strict. See the TypeScript handbook for the complete utility-type catalog.

TypeScript reference overview →

API index

APISummary
AwaitedCompute the type of awaiting T. Promises and thenables are unwrapped recursively; non-thenable types are unchanged. This is a type alias, not a runtime await.

Awaited and async types

A common pattern is Awaited<ReturnType<typeof load>> for an async function, which is the type of the resolved value. Awaited does not rewrite fields inside that value: if the resolved object has id: number, a string is still not assignable to id.

The lib definition unwraps objects with a callable then, recursively. If then is present but is not a function that accepts a callback, the official typings resolve the type to never. null and undefined are preserved, so Awaited<null | Promise<string>> is string | null.

Awaited

type Awaited<T> = T extends null | undefined ? T :
    T extends object & { then(onfulfilled: infer F, ...args: infer _): any } ?
        F extends ((value: infer V, ...args: infer _) => any) ?
            Awaited<V> :
        never :
    T;

Compute the type of awaiting T. Promises and thenables are unwrapped recursively; non-thenable types are unchanged. This is a type alias, not a runtime await.

Type parameterDescription
TUsually a Promise type, an async function's return type, or a union that includes a thenable. Plain types such as number are returned as themselves.

Produces: The awaited type. For Promise<Promise<string>> this is string. For number this is number.

Type errors

  • type error — Assigning a value that does not match the unwrapped type is a type error. Awaited does not loosen the fields of the resolved value.
  • The signature is the declaration from TypeScript 5.9.3's lib.es5.d.ts, formatted for reading. See that file for the inline comments on thenables.
  • Promise.resolve(Promise.resolve("done")) is typed as Promise<string>, not Promise<Promise<string>>, because Promise.resolve flattens thenables at the type level too.
typescript
async function load(): Promise<{ id: number }> {
  return { id: 1 };
}

type Loaded = Awaited<ReturnType<typeof load>>;
type Nested = Awaited<Promise<Promise<string>>>;
type Plain = Awaited<number>;

const loaded: Loaded = { id: 1 };
const nested: Nested = "ok";
const plain: Plain = 7;
// @ts-expect-error Awaited unwraps the Promise, not the field types inside the value
const wrong: Loaded = { id: "1" };

async function main() {
  const value: Loaded = await load();
  console.log(loaded.id, nested, plain, value.id);
}
main();

Expected output

1 ok 7 1

Related: JavaScript Promise reference, Official Awaited

Official documentation →