JS with Types Start

Type expression

Awaited<T>

  • Utility types
  • Since TypeScript 4.5

Awaited<T> unwraps a promise type the way await does: Awaited<Promise<string>> is string, and nested promises are unwrapped all the way. Its most common use is with ReturnType on an async function, Awaited<ReturnType<typeof loadAccount>>, which names the resolved value. TypeScript 4.5 added it.

Without Awaited, the ReturnType of an async function is the Promise itself, so reading account.name from it is TS2339, as the second example shows.

At a glance

JSDoc in a .js file TypeScript in a .ts file
/** @type {Awaited<ReturnType<typeof loadAccount>>} */ : Awaited<ReturnType<typeof loadAccount>>

Examples

account.js account.ts TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
/** @param {string} id */
export async function loadAccount(id) {
  return { id, name: "Jane", orders: /** @type {string[]} */ ([]) };
}

/** @typedef {Awaited<ReturnType<typeof loadAccount>>} Account */

/** @param {Account} account */
export function greeting(account) {
  return `Hello, ${account.name}`;
}

loadAccount("u_1").then(greeting);
export async function loadAccount(id: string) {
  return { id, name: "Jane", orders: [] as string[] };
}

type Account = Awaited<ReturnType<typeof loadAccount>>;

export function greeting(account: Account) {
  return `Hello, ${account.name}`;
}

loadAccount("u_1").then(greeting);
Awaited<T>: the value a promise resolves to.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
account.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: account.js(11,28): error TS2339: Property 'name' does not exist on type 'Promise<{ id: string; name: string; }>'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. account.js(11,28): error TS2339: Property 'name' does not exist on type 'Promise<{ id: string; name: string; }>'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. account.js(11,28): error TS2339: Property 'name' does not exist on type 'Promise<{ id: string; name: string; }>'. checked 21 October 2026 
/** @param {string} id */
export async function loadAccount(id) {
  return { id, name: "Jane" };
}

/** @typedef {ReturnType<typeof loadAccount>} Pending */

/** @param {Pending} account */
export function greeting(account) {
  return `Hello, ${account.name}`;error TS2339: Property 'name' does not exist on type 'Promise<{ id: string; name: string; }>'.
}
Without Awaited, ReturnType of an async function is a Promise.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

Where it shows up

TypeScript uses Awaited itself in the types of Promise.all, Promise.race and async function returns, so it appears in hovers and messages even if you never write it. Values that are not promises pass through unchanged: Awaited<number> is number.

Gotchas

  • Before TypeScript 4.5, the usual workaround was a hand-written conditional type with infer; Awaited replaces it.
  • Awaited unwraps any object with a then method that looks like a promise, not only native promises.

Questions

How do I get the resolved type of an async function in JSDoc?

{Awaited<ReturnType<typeof yourAsyncFunction>>}.

  • Type expression

    Promise and async functions

    Typing promises and async functions in JSDoc: @returns {Promise<T>}, typing fetch().json() results, new Promise, and the missing-await error TypeScript catches.

  • Type expression

    ReturnType<T>

    ReturnType<typeof fn> is the type a function returns. In JSDoc it names a factory's result without writing it twice; .js files also accept it without typeof.

  • Type expression

    Conditional types

    A conditional type chooses between two types by testing a third: T extends string ? A : B. In JSDoc it lives in a generic @typedef. infer and unions explained.

  • JSDoc tag

    @async

    The JSDoc @async tag does not make TypeScript treat a function as async. The async keyword does, and @returns {Promise<T>} gives the resolved type.

Sources

Last reviewed 20 October 2026.