Как получить тип результата async-функции через Awaited в TypeScript

Awaited<T> моделирует результат ожидания значения в системе типов TypeScript. Если функция возвращает Promise, с его помощью можно получить тип успешного результата. В разборе Mentoring.digital свяжем Awaited с ReturnType на небольшом примере.

Выводим тип из функции

async function loadUser() {
  return { id: 7, name: "Ada" };
}

type PendingUser = ReturnType<typeof loadUser>;
type User = Awaited<PendingUser>;

const example: User = { id: 9, name: "Lin" };

ReturnType получает тип возвращаемого значения функции. У loadUser это Promise с объектом, содержащим числовой id и строковое name. Awaited извлекает тип этого объекта.

Полную запись можно сократить до Awaited<ReturnType<typeof loadUser>>. Это удобно, если тип результата должен следовать за объявлением функции. При изменении её возвращаемых данных связанные места кода будут проверяться по обновлённому типу.

Учитываем вложенность и объединения

type Text = Awaited<Promise<Promise<string>>>;
// string

type MaybeAsync = Awaited<boolean | Promise<number>>;
// boolean | number

Утилита разворачивает вложенные Promise рекурсивно. Для объединения она сохраняет обычную часть и раскрывает ожидаемую. В примере возможным результатом остаётся либо логическое значение, либо число.

Awaited доступен начиная с TypeScript 4.5. Перед использованием убедитесь, что проект использует подходящий компилятор. В примерах нет зависимости от нового синтаксиса конкретной последующей версии.

Сохраняем границу между типом и данными

Эти преобразования выполняются при анализе типов. Для получения значения во время работы программы по-прежнему нужен await или обработка Promise. Отклонение операции также требует отдельной обработки.

Если функция возвращает непроверенный JSON с типом any, добавление Awaited не восстановит достоверную структуру данных. Проверяйте внешний ответ и описывайте результат после проверки. Тип успешного значения сам по себе не описывает все возможные сетевые ошибки.

Практическое задание

Измените функцию так, чтобы она возвращала список пользователей. Получите тип всего результата и тип одного элемента списка. Затем добавьте ещё одно поле и посмотрите, какие места кода потребуют обновления. Отдельно объясните, как программа обработает отклонённый Promise.

Работу с типами интерфейсов можно изучать на курсах frontend-разработки с наставником. Тип результата вашего API разберите с ментором по TypeScript.