Что такое top-level await?

Top-level await — это возможность писать await прямо в теле ES-модуля, вне какой-либо async-функции. Раньше для этого приходилось оборачивать код в (async () => { ... })() или использовать .then(). Теперь модуль сам может быть асинхронным: пока его await не завершится, импортирующий модуль не начнёт выполняться.

Как это работает

Когда модуль содержит top-level await, движок помечает его как асинхронный. Все модули, которые его импортируют, ждут завершения. Это создаёт естественный порядок инициализации без ручной синхронизации.

// config.mjs
const res = await fetch('/api/config');
export const config = await res.json();

// app.mjs
import { config } from './config.mjs';
console.log(config); // уже загружен

Где применяется

• Загрузка конфигурации или переменных окружения при старте.
• Инициализация подключения к БД или внешнему сервису.
• Динамический импорт модулей по условию.
• Упрощение кода в Node.js-скриптах и сборках.

Ограничения

• Работает только в ES-модулях, не в CommonJS и не в классических скриптах.
• Может замедлить загрузку, если await долгий — блокирует зависимые модули.
• Циклические зависимости с top-level await могут привести к дедлоку.

Итог: применяйте top-level await для чистой асинхронной инициализации модулей, но следите за временем ожидания и циклическими импортами.