Dev RunningLeituras e prática

Node.js · Aprender fazendo

Em que ordem o Node.js executa este código?

A ordem das linhas no arquivo nem sempre é a ordem das mensagens no terminal. Acompanhe uma situação de trabalho, execute dois experimentos e corrija uma consulta simulada que anuncia o fim antes de receber os dados.

Uma cena fictícia do trabalho em TI

O painel disse que terminou. Os dados discordaram.

É começo de expediente. Helena, desenvolvedora de uma equipe de suporte, abre o painel de chamados antes da reunião. Há duas pendências conhecidas, mas a última atualização exibe uma quantidade indefinida. Ao lado, a mensagem tranquilizadora: “Consulta concluída”.

O primeiro impulso é culpar o serviço. Talvez o banco tenha demorado. Talvez a rede esteja oscilando. Helena acrescenta algumas mensagens ao código e repete a operação no terminal. O aviso de conclusão aparece antes de o serviço informar que os chamados estão disponíveis.

O serviço respondeu. A aplicação é que anunciou o fim cedo demais. A variável que deveria conter a lista ainda guardava uma Promise.

Meu caro, uma mensagem de sucesso tem de prestar contas ao que realmente aconteceu. Vamos investigar a ordem de execução com dois experimentos pequenos e depois voltar ao painel para reproduzir e corrigir o problema.

O que você precisa

Node.js instalado e noções de funções em JavaScript. Salve os arquivos com a extensão .cjs e execute no terminal. Os exemplos usam CommonJS e dispensam pacotes npm.

1. Execute antes de decorar

Salve o código abaixo como 01-ordem.cjs. A função passada a setTimeout é um callback: uma função entregue para ser chamada depois. O .then() também recebe uma função, que será chamada quando a Promise estiver resolvida.

01-ordem.cjs
console.log("1. Inicio");

setTimeout(() => {
  console.log("4. Temporizador");
}, 0);

Promise.resolve().then(() => {
  console.log("3. Promise");
});

console.log("2. Fim do trecho principal");

No terminal, dentro da pasta do arquivo, execute:

node 01-ordem.cjs
Ver a saída conferida
1. Inicio
2. Fim do trecho principal
3. Promise
4. Temporizador

Compare a ordem com a posição dos trechos no arquivo. A mensagem do temporizador aparece por último, embora seu agendamento venha antes da Promise.

2. Separe o trecho atual das continuações

O programa imprime a primeira mensagem, registra o temporizador, registra a reação da Promise e imprime o fim do trecho principal. Essas ações acontecem antes de o callback do temporizador ser chamado.

01Trecho principal

Imprime Inicio e Fim do trecho principal.

02Reação da Promise

A função do then entra como microtarefa.

03Temporizador

O callback ganha sua oportunidade depois.

Uma microtarefa é uma continuação curta processada em pontos específicos depois do código em execução. Neste exemplo isolado, a reação da Promise é processada antes do callback do temporizador. A documentação do Node.js mostra essa distinção entre a fila de Promises e temporizadores.

O zero passado a setTimeout não interrompe o trecho atual. A documentação informa que atrasos abaixo de 1 são ajustados para 1 milissegundo. O instante efetivo de execução depende do trabalho que o processo está realizando; o valor não é uma garantia de horário exato.

Ponto de conhecimento

Registrar uma operação e executar sua continuação são momentos diferentes. Anote os dois ao acompanhar um programa assíncrono.

3. O await pausa qual parte?

Agora salve 02-await.cjs. A função começa a executar quando é chamada. Ao encontrar o await, suspende sua continuação; o trecho fora dela pode prosseguir. Mesmo com uma Promise já resolvida, essa retomada ocorre depois.

02-await.cjs
async function carregarConfiguracao() {
  console.log("2. Entrou na funcao");
  const configuracao = await Promise.resolve({ ambiente: "estudo" });
  console.log("4. Retomou depois do await");
  return configuracao;
}

console.log("1. Inicio");
const tarefa = carregarConfiguracao();
console.log("3. Continuou fora da funcao");

tarefa.then((configuracao) => {
  console.log("5. Ambiente: " + configuracao.ambiente);
});
node 02-await.cjs
Ver a saída do segundo experimento
1. Inicio
2. Entrou na funcao
3. Continuou fora da funcao
4. Retomou depois do await
5. Ambiente: estudo

A função imprime a mensagem 2 antes de devolver o controle ao trecho externo. A mensagem 3 vem antes da retomada indicada pela mensagem 4. Ao final, a reação registrada em tarefa.then recebe o objeto retornado pela função.

Perceba o limite da experiência: a Promise deste exemplo entrega um objeto de estudo; não há uma consulta real à rede ou a um banco. Ela permite observar a sequência sem depender de outro serviço.

4. Faça uma alteração que você consiga explicar

  1. No primeiro exemplo, troque o atraso de 0 para 1000. Observe a espera e compare a ordem.
  2. Remova apenas o bloco Promise.resolve().then(...). Execute e explique quais mensagens permaneceram.
  3. No segundo exemplo, identifique o que está antes e depois do await. Registre quais mensagens vêm do trecho externo.
Conferir o que observar

Com 1000, o temporizador continua sendo o último destes callbacks, mas sua mensagem espera pelo menos o atraso configurado antes de poder executar. Sem o bloco da Promise, restam as mensagens 1, 2 e 4. No segundo experimento, a mensagem 2 pertence à parte da função anterior ao await; a 4 pertence à continuação.

5. De volta ao painel de chamados

Agora podemos reproduzir a situação de Helena. O exemplo abaixo simula a espera por uma consulta usando um temporizador. Os dois chamados são objetos fictícios em memória; não há conexão com banco, rede ou sistema real.

Salve como 03-chamados-sem-await.cjs. Execute e acompanhe a mensagem de conclusão e a quantidade:

03-chamados-sem-await.cjs
function consultarChamados() {
  return new Promise((resolve) => {
    setTimeout(() => {
      const chamados = [{ id: 101 }, { id: 102 }];
      console.log("Servico: " + chamados.length + " chamados disponiveis");
      resolve(chamados);
    }, 50);
  });
}

console.log("Inicio da consulta");
const chamados = consultarChamados();
console.log("Consulta concluida");
console.log("Quantidade: " + chamados.length);
node 03-chamados-sem-await.cjs
Ver o problema no terminal
Inicio da consulta
Consulta concluida
Quantidade: undefined
Servico: 2 chamados disponiveis

A mensagem de conclusão veio cedo. A função devolveu uma Promise, não o array que será entregue por ela. Essa Promise não tem a propriedade length que o código tentou ler, por isso aparece undefined. Isso não significa que existem zero chamados.

O diagnóstico: pedido iniciado não é resultado disponível

Helena localiza a linha que chama consultarChamados(). O programa registra a operação e segue para as próximas instruções. O dado só fica disponível quando o temporizador entrega o array com resolve. O erro está na relação entre essas etapas.

Uma Promise representa um resultado que pode chegar ou uma falha que pode ocorrer. Para este painel, a quantidade e a mensagem de conclusão dependem do sucesso da consulta. O código precisa expressar essa dependência.

A correção: aguardar o resultado antes de confirmar

Salve a versão abaixo como 04-chamados-com-await.cjs. A função atualizarPainel usa await para obter a lista antes de anunciar a conclusão. O tratamento com .catch() registra uma eventual falha. No exemplo de terminal, o código de saída 1 sinaliza que a execução falhou.

04-chamados-com-await.cjs
function consultarChamados() {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (process.argv.includes("--falhar")) {
        reject(new Error("Servico temporariamente indisponivel"));
        return;
      }
      const chamados = [{ id: 101 }, { id: 102 }];
      console.log("Servico: " + chamados.length + " chamados disponiveis");
      resolve(chamados);
    }, 50);
  });
}

async function atualizarPainel() {
  console.log("Inicio da consulta");
  const chamados = await consultarChamados();
  console.log("Consulta concluida");
  console.log("Quantidade: " + chamados.length);
}

atualizarPainel().catch((erro) => {
  console.error("Falha na consulta: " + erro.message);
  process.exitCode = 1;
});
node 04-chamados-com-await.cjs
Ver a consulta corrigida
Inicio da consulta
Servico: 2 chamados disponiveis
Consulta concluida
Quantidade: 2

Agora o serviço entrega os dados antes da mensagem de conclusão. A variável chamados recebe o array, e sua quantidade pode ser consultada.

E quando o serviço falha?

Helena ainda precisa verificar uma situação: o painel não pode confundir uma consulta malsucedida com uma consulta bem-sucedida sem pendências. O argumento --falhar ativa uma rejeição simulada neste exemplo:

node 04-chamados-com-await.cjs --falhar
Ver a falha simulada
Inicio da consulta
Falha na consulta: Servico temporariamente indisponivel

A execução termina com código 1 e não imprime “Consulta concluida” nem uma quantidade. Em uma interface real, a regra de apresentação precisa distinguir carregamento, sucesso com dados, sucesso com lista vazia e falha.

Situação da consultaO que o painel pode informar
Em andamentoConsultando chamados.
Sucesso com dois registrosDois chamados encontrados.
Sucesso com lista vaziaNenhum chamado encontrado.
FalhaNão foi possível consultar os chamados.

São sugestões de mensagens para a situação fictícia. O exercício continua no terminal; não implementa uma interface de painel.

Ponto de sabedoria

O relatório da manhã pode esperar os dados. A confiança de quem lê não deveria depender de adivinhar se “concluído” significa “começou”.

Seu próximo teste

Na versão corrigida, substitua o array de dois objetos por []. A quantidade deve ser zero com uma consulta concluída com sucesso. Depois execute novamente com --falhar e compare. Escreva por que esses resultados precisam de mensagens diferentes. Essa distinção é o aprendizado que Helena leva da investigação para o sistema que mantém.

Desfecho da cena fictícia

Helena volta ao painel

Com o comportamento reproduzido no terminal, Helena retorna ao código do painel. Ela move a atualização da quantidade e a mensagem de conclusão para depois da obtenção da lista. Também ajusta o tratamento de erro: se a consulta falhar, a interface deve informar a falha, sem apresentar aquele resultado como uma fila vazia.

No ambiente de teste, ela solicita uma nova atualização. O painel mostra “Consultando chamados”. Quando a resposta chega, aparecem os dois registros e a confirmação de conclusão. Desta vez, o aviso acompanha o que aconteceu.

Helena ainda testa a lista vazia e a indisponibilidade do serviço. Na primeira situação, o painel informa que nenhum chamado foi encontrado. Na segunda, avisa que não foi possível consultar. A mesma ausência de registros na tela já não esconde dois acontecimentos diferentes.

Antes da reunião, ela registra o diagnóstico para a equipe: a consulta estava sendo iniciada corretamente, mas a aplicação usava seu retorno antes de obter os dados. A correção organiza essa dependência e dá a cada resultado uma mensagem coerente.

O painel volta a cumprir seu papel. Helena pode explicar o que foi corrigido, mostrar como verificou e seguir para o próximo chamado. É esse o ponto em que o exercício deixa de ser apenas uma ordem de mensagens no terminal e passa a orientar uma decisão no trabalho.

Onde essa distinção ajuda?

Ao ler um arquivo ou consultar um serviço, procure o ponto em que a operação começa e o ponto em que seu resultado fica disponível. APIs assíncronas de entrada e saída permitem que o processo cuide de outro trabalho durante a espera. Isso não transforma automaticamente um cálculo longo em trabalho paralelo: um callback ocupado por muito tempo ainda pode bloquear o Event Loop.

Pratique no seu computador

Os quatro exemplos, prontos para executar

Arquivos .cjs, saídas em .txt e instruções para Windows. Material original deste artigo, separado do conteúdo integral do ebook.

Baixar exemplos em ZIP

Referências para continuar

Exemplos originais do portal, executados em v24.22.1. Referências consultadas em 16 de novembro de 2026.

Seguir o guia de estudoExplorar os materiais