Aula 90 — Top-level await

Até agora, sempre usamos await dentro de funções async.

Isso funciona muito bem — mas criava uma limitação artificial:

por que não posso usar await diretamente no arquivo?

O top-level await veio exatamente para resolver isso.

🎯 Objetivo da aula

Ao final desta aula, você será capaz de:

• Entender o que é top-level await
• Saber onde ele pode ser usado
• Usar await fora de funções
• Evitar erros comuns de ambiente
• Escrever módulos mais simples e legíveis

O problema antes do top-level await

Antes, se quiséssemos usar await, precisávamos fazer algo assim:

 
  async function iniciar() 
  { 
    const resposta = await fetch("/api/dados"); 
    const dados = await resposta.json(); 
    console.log(dados); 
  }
  iniciar();

Isso criava:

• funções artificiais
• mais indentação
• código menos direto

O que é top-level await?

Top-level await permite usar await:

diretamente no escopo principal de um módulo JavaScript.

Sem precisar envolver em uma função async.

Exemplo simples

 
  const resposta = await fetch("/api/dados"); 
  const dados = await resposta.json();
  console.log(dados);

Isso agora é válido — desde que este arquivo seja um módulo.

Onde o top-level await funciona?

Ele funciona apenas em:

• arquivos JavaScript tratados como módulos
• <script type="module">
• módulos ES no Node.js

Exemplo no navegador

 
  <script type="module"> const resposta = await fetch("/api/dados"); 
  const dados = await resposta.json();
  console.log(dados);

Aqui, o navegador entende que o código é modular e permite o uso de await.

O que acontece por baixo dos panos?

Quando você usa top-level await:

• o módulo é carregado
• a execução é pausada no await
• outros módulos aguardam a finalização

Exemplo com import dependente

Arquivo config.js:

 
  export const config = await fetch("/config.json").then(r => r.json()); 

Arquivo app.js:

 
    import { config } from "./config.js";
    console.log(config);
    // Saída será o conteúdo do config.json

O JavaScript garante que config esteja pronto antes do uso.

Vantagens reais

• menos código cerimonial
• arquivos mais legíveis
• fluxo linear de execução
• melhor organização de módulos

Cuidados importantes

Use top-level await com consciência:

• não abuse em módulos muito grandes
• evite esperas longas no carregamento inicial
• trate erros adequadamente

Comparação mental

• await em função → controle local
• top-level await → controle de módulo

Cada um tem seu lugar.

Na próxima aula, vamos conhecer estruturas especiais para memória e performance: WeakMap e WeakSet.