Сетевые запросы, чтение файлов и таймеры завершаются позже, но JavaScript не может просто остановиться и ждать, иначе страница зависнет. Обещания JavaScript дают вам аккуратный способ сказать: «Когда это закончится, сделайте это, а если не получится, сделайте вместо этого это».

Даже если вы в основном пишете async и await, вы используете промисы внизу, поэтому их понимание значительно упрощает отладку. Мы запускали эти примеры на Node.js 24, и показанный результат получен в результате этого запуска. В современных браузерах они ведут себя так же.

Что такое обещание?

Обещание — это заполнитель для будущего значения. Подумайте о звонке, который вам вручают в ресторане, когда вы делаете заказ. У вас еще нет еды, но вы держите в руках что-то, что подскажет вам, когда она будет готова или что возникла проблема, а тем временем вы можете заниматься другими делами.

В коде асинхронная функция немедленно возвращает обещание, и вы добавляете, что должно произойти дальше:

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

Три обещания гласят

Обещание, которое выполнено или отклонено, называется выполненным. Обещание может быть выполнено только один раз. После этого его состояние и значение фиксируются, а последующие вызовы resolve или reject игнорируются.

Создать обещание

Обычно вы используете обещания из API, таких как fetch, но создание одного показывает, как они работают. Конструктор получает две функции: resolve и reject:

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

Немедленная регистрация обещания показывает, что оно все еще находится в состоянии ожидания, поскольку таймер не сработал. Значение может быть достигнуто только через обработчик или await. Всегда отклоняйте объект Error, а не строку, поскольку Error содержит трассировку стека, которая помогает при отладке.

затем поймай и, наконец,

Эти три метода присоединяют обработчики к обещанию:

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then выполняется в случае успеха, catch выполняется в случае сбоя и finally выполняется в любом случае. Это делает finally подходящим местом для очистки, например, для скрытия индикатора загрузки. Он не получает аргументов, поскольку его не должен волновать результат.

Объединение обещаний

Ключевая идея заключается в том, что then всегда возвращает новое обещание. Все, что возвращает ваш обработчик, становится значением нового обещания:

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

Если обработчик возвращает другое обещание, цепочка ждет, пока оно стабилизируется, прежде чем двигаться дальше. Именно это превращает вложенные обратные вызовы в плоскую последовательность шагов:

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

Как ошибки перемещаются по цепочке

Отклоненное обещание пропускает каждый then, пока не достигнет catch. Выброс внутри обработчика также считается отклонением. И возвращаемый catch обычно возвращает цепочку в нужное русло:

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

Думайте об этом как об асинхронной версии try и catch. Один catch в конце обычно охватывает всю цепочку. Если вы хотите зарегистрировать только ошибку и все равно потерпеть неудачу, создайте ее еще раз изнутри catch.

Promise.all, allSettled, раса и любые

Эти статические методы координируют сразу несколько промисов. Все они принимают массив и возвращают одно обещание.

Чтобы протестировать их, мы использовали два небольших помощника: один завершается успешно после задержки, а другой завершается сбоем после задержки:

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

Две детали, на которые стоит обратить внимание. Результаты сохраняют порядок ввода, хотя b закончил первым. И общее время составило около 300 мс, время самой медленной задачи, а не сумма 600 мс, потому что все три уже работали одновременно. Если кто-нибудь из них отвергнет, то сразу отвергнет все:

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

Он ожидает всего и сообщает о каждом результате, поэтому одна ошибка не теряет остальных. Он подходит для панели мониторинга, где каждый виджет загружается независимо:

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promise.race и Promise.any

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

Разница в том, что race принимает решение первым, даже если оно не удалось, тогда как any игнорирует неудачи, пока что-то удается. Классическое использование race — добавление тайм-аута к медленному запросу, хотя более медленная задача продолжает выполняться в фоновом режиме, пока вы не отмените ее.

Обещания и async/await

async и await — более читабельный способ работы с теми же промисами. Функция async всегда возвращает обещание, а await приостанавливает выполнение этой функции до тех пор, пока обещание не будет выполнено:

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

Отклонения становятся выброшенными ошибками, поэтому работают обычные try и catch. Вам все равно понадобится Promise.all для параллельной работы, потому что ожидание одного вызова за другим запускает их последовательно. В нашем руководстве по асинхронному/ожидающему использованию JavaScript эта тема рассматривается более подробно.

Обещания и цикл событий

Обработчики промисов никогда не вызываются немедленно, даже если промис уже выполнен. Они запускаются после завершения текущего кода и до таймеров. Вот доказательство:

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

Синхронный код выполняется первым. Далее идет очередь микрозадач, в которой хранятся обработчики обещаний. Только после этого цикл событий выбирает следующую задачу, например таймер. Это популярный вопрос на собеседованиях, и он объясняет, почему нулевой результат setTimeout не является немедленным.

Обещания против обратных вызовов

Распространенные ошибки

• Забываем вернуться внутрь then. Без return следующий шаг получает undefined и не ждет вашего внутреннего обещания.
• Нет catch вообще. Это приводит к необработанному отклонению, а в Node.js это останавливает процесс по умолчанию.
• Вложение вместо цепочки. Помещение then внутрь then воссоздает ад обратного вызова. Верните обещание и продолжите цепочку.
• Обертывание обещания в new Promise. Если функция уже возвращает обещание, просто используйте его.
• Использование forEach с асинхронными обратными вызовами. Он не ждет. Используйте for...of или Promise.all с map, как показано в нашем руководстве по методам массивов JavaScript.
• Думаю, что обещание можно отменить. Само по себе оно не может быть отменено. Для запросов используйте AbortController.

Итоги

Промисы сводятся к нескольким правилам: обещание выполняется один раз, then возвращает новое обещание, а ошибки перемещаются по цепочке, пока что-то их не перехватит. Как только эти правила станут естественными, async и await перестанут быть волшебством. Для практики перепишите одну функцию обратного вызова, используя промисы, затем получите две конечные точки с помощью Promise.all и правильно обработайте ошибку.

Часто задаваемые вопросы

Продолжайте учиться