O top-level await
(TLA) é um novo recurso do JavaScript que permite a utilização do operador await
no escopo mais superior de módulos ECMAScript (ESM). Esse escopo mais superior chama-se top-level.
O comportamento do await
no module top-level é o mesmo de quando é utilizado em funções assíncronas. Em resumo:
- No caso da promessa ser resolvida, o
await
retorna o valor da resolução.
- No caso da promessa ser rejeitada, o
await
lança o valor da rejeição.
O que justifica o top-level await
?
Em alguns casos, pode ser necessário carregar algum recurso assincronamente durante a inicialização de um módulo. Para que isso seja feito de forma própria, os export
s do módulo, no mundo ideal, não devem ser efetivados até que todo o trabalho assíncrono de inicialização tenha sido concluído.
É isso que, basicamente, o top-level await
resolve. Quando utilizado no module top-level, barrará a execução do resto do módulo (inclusive os export
s do módulo) até que a promessa tenha sido resolvida.
Isso garante que o módulo só exportará seu conteúdo quando todas as promessas aguardadas em top-level tenham sido resolvidas ou uma qualquer delas tenha sido rejeitada. Esse comportamento de "curto-circuito" é similar ao Promise.all
.
É claro que esse recurso não deve ser sobre-utilizado (veremos a seguir alguns pontos negativos de se fazer essa inicialização de recursos assincronamente). Mas, quando necessário, decerto pode ser bastante útil. O repositório da proposta (ainda em estágio três) menciona alguns casos de uso em que o top-level await
pode fazer sentido.
Quais são os cuidados a serem tomados ao utilizar o top-level await
?
1. O top-level await
trava um módulo e seus descendentes
Esse talvez seja o pior dos problemas facilitados pelo top-level await
. Devo ressaltar que o problema não se deve ao TLA em si, mas pelo fato de se fazer carregamento assíncrono de recursos no top-level de módulos.
Não tem como fugir disto – se um módulo A faz inicialização assíncrona, ele travará até a conclusão das promessas aguardadas. E, por conta desse bloqueio, todos os outros módulos que importam A (utilizando a sintaxe import ... from 'A'
) também serão travados.
Esse travamento por descendência pode ser extremamente prolongado em longas cadeias de importação. Em alguns casos, utilizar dynamic imports pode evitar esse problema se o módulo puder ser carregado de modo lazy.
Supondo que a.mjs
contenha algum tipo de inicialização assíncrona, este módulo, que depende de A, também será bloqueado:
// Só será executado quando `A` terminar a inicialização...
import * as A from './a.mjs';
console.log(A);
Mas se a importação for feita utilizando dynamic import, que é assíncrono, este módulo não será bloqueado. Note que, neste caso, a importação deve ser feita dentro de uma função assíncrona. Se o await
fosse feito em top-level, o comportamento seria o mesmo do exemplo anterior.
// Note agora que o carregamento do módulo `A` é lazy.
// Desse modo, este módulo não será bloqueado em detrimento de `A`.
//
// O módulo `A` será carregado somente quando a função `doStuff` for invocada.
export async function doStuff() {
const A = await import('./a.mjs');
console.log(A);
}