Промисы в JavaScript: от исполнителя до async и await
Промис — это значение, которое обозначает результат, которого ещё нет. Так JavaScript называет одну операцию, которая завершится позже: таймер, чтение файла, запрос к серверу. Работа запускается, промис возвращается сразу, а результат приходит в колбэк, который выполнится, когда работа закончится. В этой статье модель разобрана целиком, от конструктора до async и await: три состояния, цепочка, четыре комбинатора, обработка ошибок и порядок, в котором выполняются колбэки.
Каждая программа ниже — отдельный файл, запущенный в Node.js на Linux, и блок под ней — настоящий вывод этого запуска. Цепочки, собранные здесь руками, — те же, что разбирает курс JavaScript (он есть только на английском) в уроке о промисах и следующих за ним.
Зачем нужны промисы
До промисов асинхронный результат передавался в колбэк: функцию, которую вызывает вызывающий код, а работа вызывает её, когда закончит. Один шаг — нормально. Два шага означают колбэк внутри колбэка, у каждого свой аргумент ошибки, и код, который относится к одной задаче, уезжает вправо за край экрана. Программа ниже загружает пользователя, а затем его заказы.
The file callbacks.mjs:
function loadUser(id, callback) {
setTimeout(() => callback(null, { id, name: 'Ada' }), 10);
}
function loadOrders(user, callback) {
setTimeout(() => callback(null, [{ id: 1, total: 42 }]), 10);
}
loadUser(7, (error, user) => {
if (error) {
console.log('user:', error.message);
return;
}
loadOrders(user, (ordersError, orders) => {
if (ordersError) {
console.log('orders:', ordersError.message);
return;
}
console.log('the callback style:', user.name, orders.length, 'order(s)');
});
});
node callbacks.mjs
the callback style: Ada 1 order(s)
Каждый шаг повторяет одну и ту же проверку if (error), и поймать отказ всей последовательности в одном месте негде. Промис это выравнивает: работа возвращает объект, следующий шаг цепляется к этому объекту, и один обработчик в конце видит любую ошибку. Функции перестают принимать колбэки и начинают возвращать значение, которое означает «позже».
Три состояния
В каждый момент промис находится ровно в одном из трёх состояний: pending, пока работа идёт, fulfilled со значением или rejected с причиной. Выйти можно только из pending, и выходит он один раз: после этого промис settled и больше не меняется. Публичного свойства с состоянием нет, но util.inspect его показывает, а обработчики ведут себя соответственно.
The file states.mjs:
import { inspect } from 'node:util';
const pending = new Promise(() => {});
const fulfilled = Promise.resolve('a value');
const rejected = Promise.reject('a reason');
void rejected.catch(() => {});
console.log('pending: ', inspect(pending));
console.log('fulfilled:', inspect(fulfilled));
console.log('rejected: ', inspect(rejected));
node states.mjs
pending: Promise { <pending> }
fulfilled: Promise { 'a value' }
rejected: Promise { <rejected> 'a reason' }
Первый промис никогда не завершится, потому что его исполнитель ничего не вызывает; два других уже были завершены к моменту, когда программа на них посмотрела. Повторный вызов resolve или reject игнорируется, как и throw после завершения: когда состояние решено, значение и причина зафиксированы.
Создание промиса
new Promise(executor) принимает одну функцию и вызывает её сразу, до того как конструктор вернёт объект. Исполнитель получает две функции: resolve для значения и reject для причины, а throw внутри него отклоняет промис, а не улетает вызывающему коду. Это весь конструктор: метода start нет, и сам промис ничего не запускает.
The file executor.mjs:
const promise = new Promise((resolve) => {
console.log('the executor runs at once');
resolve('the value');
});
console.log('the constructor has already returned');
const handlers = [
promise.then((value) => console.log('the then callback is a microtask:', value)),
new Promise((resolve, reject) => {
reject(new Error('the work failed'));
}).catch((error) => console.log('reject hands over the reason:', error.message)),
new Promise(() => {
throw new Error('a throw in the executor');
}).catch((error) => console.log('a throw rejects the promise too:', error.message)),
];
await Promise.all(handlers);
node executor.mjs
the executor runs at once
the constructor has already returned
the then callback is a microtask: the value
reject hands over the reason: the work failed
a throw rejects the promise too: a throw in the executor
Строка исполнителя напечаталась раньше строки после конструктора, то есть работа уже началась, когда промис был возвращён. Колбэки then и catch дождались очереди микрозадач — это то правило, которое объясняет весь порядок в остальной статье. Отказ доходит до catch с причиной, откуда бы он ни пришёл: из вызова reject или из throw.
then, catch и finally
then(onFulfilled, onRejected) регистрирует колбэк для значения и возвращает новый промис. catch(onRejected) — то же самое без первого аргумента, и именно сюда обычно попадает отказ. finally(onFinally) принимает колбэк без аргументов, выполняет его на обоих путях и передаёт значение или отказ дальше без изменений: это место для уборки, а не для чтения результата.
The file finally.mjs:
function load(ok) {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (ok) {
resolve('the contents');
} else {
reject(new Error('the load failed'));
}
}, 10);
});
}
await load(true)
.finally(() => console.log('cleanup after a success'))
.then((value) => console.log('the value:', value));
await load(false)
.finally(() => console.log('cleanup after a failure'))
.catch((error) => console.log('the error:', error.message));
node finally.mjs
cleanup after a success
the value: the contents
cleanup after a failure
the error: the load failed
Обе уборки выполнились раньше обработчиков, которые использовали результат, и отказ всё равно дошёл до своего catch. Колбэк finally не может изменить значение: то, что он возвращает, игнорируется, если только он не бросит исключение или не вернёт отклонённый промис — тогда результат заменится.
Цепочка
Цепочка работает потому, что then возвращает новый промис, и то, что вернёт его колбэк, решает значение этого промиса. Важны три вида возврата: обычное значение выполняет следующий промис им; промис заставляет следующий шаг ждать его и получить его значение; throw отклоняет следующий промис. Поэтому цепочка — это последовательность шагов с одним путём ошибки, а не набор вложенных колбэков.
The file chain.mjs:
function double(value) {
return new Promise((resolve) => {
setTimeout(() => resolve(value * 2), 10);
});
}
await double(1)
.then((value) => {
console.log('the first step:', value);
return value + 1;
})
.then((value) => {
console.log('the second step:', value);
return double(value);
})
.then((value) => {
console.log('the third step:', value);
throw new Error('the fourth step failed');
})
.catch((error) => {
console.log('the catch:', error.message);
return 'recovered';
})
.then((value) => console.log('after the catch:', value));
node chain.mjs
the first step: 2
the second step: 3
the third step: 6
the catch: the fourth step failed
after the catch: recovered
Первый шаг удвоил полученную единицу, второй вернул обычное число, третий вернул промис, поэтому четвёртый шаг дождался его и получил шесть. throw закончил этот шаг, управление взял catch, а возвращённое им значение снова выполнило цепочку: последний then получил recovered. catch в середине — точка восстановления, а не конец цепочки.
Распространение ошибок и необработанный отказ
Отказ пропускает каждый then без обработчика отказа и останавливается на первом catch. Если цепочка заканчивается без него, промис отклонён, и никто его не слушает. В конце проверки микрозадач Node.js порождает событие unhandledRejection; программа ниже его слушает — так процесс записывает такой отказ в лог перед тем, как завершиться.
The file rejection-event.mjs:
process.on('unhandledRejection', (reason) => {
console.log('the process saw an unhandled rejection:', reason.message);
});
void Promise.reject(new Error('nobody listens'));
setTimeout(() => console.log('the program kept running'), 10);
node rejection-event.mjs
the process saw an unhandled rejection: nobody listens
the program kept running
Слушатель — это крайняя мера для логирования и аккуратной остановки, а не способ восстановиться: значение уже потеряно. Без слушателя поведение по умолчанию, начиная с Node.js 15, — сообщить причину и выйти с ненулевым кодом. Та же программа без слушателя заканчивается так:
Файл bare-rejection.mjs:
void Promise.reject(new Error('nobody listens'));
node bare-rejection.mjs > /dev/null 2>&1; echo "exit code: $?"
exit code: 1
Сообщение в стандартном потоке ошибок называет причину и файл, а код выхода равен 1, поэтому тест-раннер или контейнер видят отказ. Давайте каждой цепочке последний catch, даже если он умеет только записать ошибку в лог и бросить её дальше.
Promise.all, allSettled, race и any
Четыре статических метода запускают несколько промисов вместе, и различаются они двумя вопросами: заканчивает ли всё одна ошибка и какое значение считается ответом. Каждый принимает массив промисов или обычных значений, возвращает один промис и сохраняет порядок вызовов в результате.
The file combinators.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
const values = await Promise.all([delay('a', 10), delay('b', 30), 'c']);
console.log('all:', values.join(','));
const results = await Promise.allSettled([
delay('the answer', 10),
Promise.reject(new Error('the second call failed')),
]);
console.log('allSettled:', results.map((result) => result.status).join(','));
console.log('the reason:', results[1].reason.message);
const winner = await Promise.race([delay('slow', 30), delay('fast', 10)]);
console.log('race:', winner);
const first = await Promise.any([Promise.reject(new Error('no')), delay('later value', 10)]);
console.log('any:', first);
try {
await Promise.any([Promise.reject(new Error('one')), Promise.reject(new Error('two'))]);
} catch (error) {
console.log('any rejects with:', error.name, error.errors.map((item) => item.message).join(','));
}
node combinators.mjs
all: a,b,c
allSettled: fulfilled,rejected
the reason: the second call failed
race: fast
any: later value
any rejects with: AggregateError one,two
all вернул три значения в порядке вызовов, включая обычную строку, которая вовсе не была промисом. allSettled вернул оба исхода как данные, поэтому отчёт может напечатать причину неудачного элемента без исключения. race взял первый завершившийся промис, а any пропустил отказ и взял первое значение; когда отклоняются все, any отклоняется с AggregateError, в котором лежат все причины.
| Метод | Выполняется, когда | Отклоняется, когда | Значение | Для чего |
|---|---|---|---|---|
| Promise.all | выполнились все промисы | отклонился первый | массив значений в порядке вызовов | шаги, которые должны удаться все: страница с тремя запросами |
| Promise.allSettled | завершились все промисы | никогда | массив {status, value} или {status, reason} | отчёт по многим элементам, где отказ — это данные |
| Promise.race | выполнился первый промис | отклонился первый промис | значение или причина первого завершившегося | таймаут или выбор между зеркалами |
| Promise.any | выполнился первый промис | отклонились все промисы | первое пришедшее значение | резервные источники, где достаточно одного ответа |
all не отменяет проигравшие промисы. Они продолжают работать, их значения отбрасываются, а поздний отказ среди них не сообщается объединённому промису, который уже завершён. Программа ниже показывает ранний отказ и работу, которая идёт дальше без него.
The file all-rejects.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
try {
await Promise.all([
delay('a', 10),
Promise.reject(new Error('the second call failed')),
delay('c', 30),
]);
} catch (error) {
console.log('all rejected at once:', error.message);
}
console.log('the other two calls were still running');
node all-rejects.mjs
all rejected at once: the second call failed
the other two calls were still running
Отказ пришёл, не дожидаясь тридцатимиллисекундного вызова, и программа пошла дальше, пока этот вызов ещё выполнялся. Если остальные результаты важны даже при одной ошибке, используйте allSettled; если работу можно отменить, передайте ей AbortSignal, как показано в разделе о таймаутах.
Promise.resolve, Promise.reject и Promise.withResolvers
Promise.resolve(value) возвращает промис, выполненный этим значением, а Promise.reject(reason) — отклонённый причиной. Первый нужен функции, у которой ответ иногда уже есть, а иногда надо подождать: тип возврата остаётся одним. Он же принимает thenable — обычный объект с методом then. Promise.withResolvers, стандарт с ES2024, возвращает промис вместе с его resolve и reject — для случаев, когда они должны выйти за пределы исполнителя.
The file statics.mjs:
const value = await Promise.resolve('a plain value');
console.log('resolve:', value);
const array = await Promise.resolve([1, 2, 3]);
console.log('the unwrap is shallow:', Array.isArray(array), array.length);
try {
await Promise.reject(new Error('a reason'));
} catch (error) {
console.log('reject:', error.message);
}
const thenable = {
then(resolve) {
resolve('from a thenable');
},
};
console.log('a thenable is adopted:', await Promise.resolve(thenable));
const { promise, resolve } = Promise.withResolvers();
setTimeout(() => resolve('resolved from outside'), 10);
console.log('withResolvers:', await promise);
node statics.mjs
resolve: a plain value
the unwrap is shallow: true 3
reject: a reason
a thenable is adopted: from a thenable
withResolvers: resolved from outside
Массив вернулся одним значением, а не тремя: resolve выполняет промис тем, что ему дали, и не разворачивает массивы. Thenable был принят, и его метод then выполнился как часть разрешения. withResolvers дал функции разрешения имя вне конструктора — именно это нужно обработчику события или колбэку другой библиотеки.
Превращение колбэков в промисы
В Node.js до сих пор есть API с колбэками, и у колбэка принято получать ошибку первым аргументом, а значение вторым. util.promisify превращает такую функцию в функцию, возвращающую промис, а многие модули уже поставляют версию с промисами: node:fs/promises — это node:fs с промисами. Когда API не следует соглашению, обёртка занимает три строки и один new Promise.
The file promisify.mjs:
import { promisify } from 'node:util';
import { readFile } from 'node:fs';
const readFileAsync = promisify(readFile);
const text = await readFileAsync(new URL(import.meta.url), 'utf8');
console.log('the first line of this file:', text.split('\n')[0]);
function loadUser(id) {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (id > 0) {
resolve({ id, name: 'Ada' });
} else {
reject(new Error('no such user'));
}
}, 10);
});
}
const user = await loadUser(7);
console.log('the user:', user.name);
try {
await loadUser(0);
} catch (error) {
console.log('the failure:', error.message);
}
node promisify.mjs
the first line of this file: import { promisify } from 'node:util';
the user: Ada
the failure: no such user
Промисифицированный readFile выполнился текстом и отклонился исходным объектом ошибки, у которого остались code, errno и прочее. Написанная руками обёртка сделала то же для колбэка, который не следует соглашению: new Promise и есть адаптер, а колбэку остаётся только вызвать resolve или reject. Если метод использует this, привяжите его до промисификации.
async и await: та же цепочка, записанная сверху вниз
Функция с async всегда возвращает промис, а await приостанавливает эту функцию до завершения промиса, а затем отдаёт его значение или бросает его причину. Больше ничего не останавливается: остальная программа работает, пока функция ждёт. Это в точности цепочка, только шаги записаны в порядке чтения, а вместо catch стоит try/catch. Программа ниже — цепочка из предыдущего раздела, переписанная так.
The file async-await.mjs:
function double(value) {
return new Promise((resolve) => {
setTimeout(() => resolve(value * 2), 10);
});
}
async function run() {
try {
const first = await double(1);
console.log('the first step:', first);
const second = first + 1;
console.log('the second step:', second);
const third = await double(second);
console.log('the third step:', third);
throw new Error('the fourth step failed');
} catch (error) {
console.log('the catch:', error.message);
return 'recovered';
}
}
console.log('after the call:', await run());
async function answer() {
return 42;
}
console.log('an async function returns a promise:', answer() instanceof Promise);
console.log('await unwraps it:', await answer());
node async-await.mjs
the first step: 2
the second step: 3
the third step: 6
the catch: the fourth step failed
after the call: recovered
an async function returns a promise: true
await unwraps it: 42
Вывод — та же последовательность значений, а throw стал исключением, которое поймал try, поэтому функция снова смогла вернуть обычное значение. Последние две строки показывают вторую половину правила: функция, объявленная async, возвращает промис даже тогда, когда возвращает число, а await на этом промисе даёт число обратно. await на обычном значении разрешён и стоит одной микрозадачи.
Последовательно и параллельно
await в цикле выполняет шаги один за другим: каждый начинается, когда закончился предыдущий. Это правильно, когда шагу нужен результат предыдущего, и неправильно, когда шаги независимы: тогда общее время равно сумме всех. Если запустить все промисы сразу и ждать их вместе, работа займёт столько же, сколько самый медленный из них.
The file sequence.mjs:
import { setTimeout as sleep } from 'node:timers/promises';
async function work(name) {
console.log('start', name);
await sleep(20);
console.log('finish', name);
}
console.log('one by one:');
await work('a');
await work('b');
console.log('all at once:');
await Promise.all([work('a'), work('b')]);
node sequence.mjs
one by one:
start a
finish a
start b
finish b
all at once:
start a
start b
finish a
finish b
По одному второй старт ждал первого финиша. Все сразу — оба стартовали до того, как кто-то закончил, а результаты собрались в порядке вызовов. То же правило работает в цикле: for (const id of ids) await load(id) — последовательно, а await Promise.all(ids.map((id) => load(id))) — параллельно. Параллельной работе нужен предел, когда список длинный: тысяча одновременных запросов упрётся в ограничение сервера намного раньше, чем в возможности машины.
Таймауты с AbortSignal и race
Промис отменить нельзя, но операции за ним можно сказать остановиться через AbortSignal. AbortSignal.timeout(ms) возвращает сигнал, который прерывается сам через указанное число миллисекунд, а API, принимающие сигнал, отклоняются с AbortError, когда он срабатывает. fetch, файловая система и таймеры-промисы из node:timers/promises принимают его.
The file timeout.mjs:
import { setTimeout as sleep } from 'node:timers/promises';
try {
await sleep(1000, 'too late', { signal: AbortSignal.timeout(20) });
} catch (error) {
console.log('the sleep was aborted:', error.name);
}
const slow = sleep(1000, 'the slow answer');
const timeout = sleep(20).then(() => {
throw new Error('the call took too long');
});
try {
await Promise.race([slow, timeout]);
} catch (error) {
console.log('the race timed out:', error.message);
}
node timeout.mjs
the sleep was aborted: AbortError
the race timed out: the call took too long
Первый сон отклонился с AbortError и перестал ждать. Во второй части вызов соревновался с таймером и намеренно проиграл: race даёт таймаут любому промису, включая тот, который ничего не знает о сигналах, но проигравшего не отменяет. Запрос продолжает работать, пока не закончится или пока не завершится процесс, поэтому там, где у API есть сигнал, лучше использовать его.
Порядок микрозадач и setTimeout
JavaScript выполняет одно действие за раз в стеке вызовов. Асинхронная работа попадает в две очереди: микрозадач, где лежат колбэки промисов, колбэки queueMicrotask и продолжения после await, и макрозадач, где лежат таймеры, ввод-вывод и события. После каждой макрозадачи движок опустошает всю очередь микрозадач, прежде чем взять следующую; новые микрозадачи, добавленные во время этого опустошения, выполняются в том же проходе.
The file order.mjs:
console.log('1 script start');
setTimeout(() => console.log('2 setTimeout'), 0);
void Promise.resolve().then(() => console.log('3 promise then'));
queueMicrotask(() => console.log('4 queueMicrotask'));
void (async () => {
console.log('5 async function start');
await null;
console.log('6 after await');
})();
console.log('7 script end');
node order.mjs
1 script start
5 async function start
7 script end
3 promise then
4 queueMicrotask
6 after await
2 setTimeout
Сначала скрипт дошёл до конца и напечатал 1, 5 и 7: асинхронная функция начала выполняться синхронно и остановилась на своём await. Затем очередь микрозадач была опустошена в порядке регистрации: then уже выполненного промиса (3), явный queueMicrotask (4) и продолжение асинхронной функции (6). И только когда очередь опустела, сработал таймер (2). Если эта задача новая, уроки о цикле событий и таймерах в курсе JavaScript собирают её со стека.
Частые ошибки
Забытый return
Колбэк then, который ничего не возвращает, выполняет следующий промис значением undefined, даже если он поработал со значением. Следующий шаг читает undefined, и ошибка молчит, потому что ничего не было брошено.
The file forgotten-return.mjs:
await Promise.resolve('a value')
.then((value) => {
value.toUpperCase();
})
.then((value) => {
console.log('the next step got:', value);
});
node forgotten-return.mjs
the next step got: undefined
Исправление — одно слово: return value.toUpperCase();. Та же ошибка прячет возвращённый промис: без return следующий шаг его не ждёт.
then внутри then вместо цепочки
then внутри then запускает вторую цепочку, о которой внешняя ничего не знает. Внешняя идёт дальше с undefined, а ошибка внутри вложенной работы никогда не доходит до внешнего catch.
The file nested-then.mjs:
const slow = (value) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), 20);
});
void Promise.resolve(1)
.then((value) => {
void slow(value + 1).then((inner) => {
console.log('the nested chain finished:', inner);
});
})
.then((value) => {
console.log('the outer chain moved on with:', value);
});
await slow(0);
await Promise.resolve(1)
.then((value) => slow(value + 1))
.then((inner) => {
console.log('the returned promise is waited for:', inner);
});
await slow(0);
node nested-then.mjs
the outer chain moved on with: undefined
the nested chain finished: 2
the returned promise is waited for: 2
Внешняя цепочка напечатала undefined раньше, чем вложенная работа закончилась, а отказ внутри вложенной работы ушёл бы в процесс, а не во внешний обработчик. Возвращённый внутренний промис соединяет две цепочки: последняя строка показывает, что внешняя цепочка дождалась значения.
await в цикле
await внутри цикла for правилен, когда шагу нужен результат предыдущего, и неправилен, когда шаги независимы. Программа считает, сколько вызовов выполняется одновременно.
The file loop.mjs:
import { setTimeout as sleep } from 'node:timers/promises';
let inFlight = 0;
let mostAtOnce = 0;
const work = async () => {
inFlight += 1;
mostAtOnce = Math.max(mostAtOnce, inFlight);
await sleep(20);
inFlight -= 1;
};
for (let i = 0; i < 3; i += 1) {
await work();
}
console.log('one at a time, at most in flight:', mostAtOnce);
mostAtOnce = 0;
await Promise.all([work(), work(), work()]);
console.log('all at once, at most in flight:', mostAtOnce);
node loop.mjs
one at a time, at most in flight: 1
all at once, at most in flight: 3
По одному счётчик не поднимался выше единицы: каждый вызов ждал предыдущий, и общее время равно сумме. Исправление — сначала запустить все вызовы, а потом ждать их вместе: порядок результатов сохранится, а работать они будут одновременно.
Проглоченные ошибки
catch, который печатает готовую фразу, выбрасывает причину. В логе сказано, что что-то упало, но не что именно, и вызывающий код не может ни повторить операцию, ни сообщить о ней.
The file swallowed.mjs:
await Promise.reject(new Error('the real problem')).catch(() => {
console.log('something went wrong');
});
await Promise.reject(new Error('the real problem')).catch((error) => {
console.log('the real problem:', error.message);
});
node swallowed.mjs
something went wrong
the real problem: the real problem
Вторая версия сохраняет сообщение; обработчик в рабочем коде сохраняет ещё и стек, записывает операцию и либо бросает ошибку дальше, либо возвращает значение, понятное вызывающему коду. Молчание хуже падения: падение хотя бы говорит, где оно случилось.
Куда дальше
Остальные статьи раздела собраны на странице JavaScript: основы, ошибки, Express, React и Vue. Асинхронный код проверяют тестами, и для этого есть раздел Mocha; о среде выполнения — Node.js. Полный курс с уроками, задачами и вопросами есть только на английском.
Код на этой странице запущен в Node.js 24.22.1 и проверен ESLint 10.15.0 (flat config, рекомендованные правила и no-floating-promises) на Alpine Linux 3.24.3 (x86_64) в контейнере Docker.
Автор статьи: Arthur Isaev