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.
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.
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.
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.cjsVer 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.
Imprime Inicio e Fim do trecho principal.
A função do then entra como microtarefa.
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.
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.
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.cjsVer 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
- No primeiro exemplo, troque o atraso de
0para1000. Observe a espera e compare a ordem. - Remova apenas o bloco
Promise.resolve().then(...). Execute e explique quais mensagens permaneceram. - 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:
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.
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 consulta | O que o painel pode informar |
|---|---|
| Em andamento | Consultando chamados. |
| Sucesso com dois registros | Dois chamados encontrados. |
| Sucesso com lista vazia | Nenhum chamado encontrado. |
| Falha | Nã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.
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.
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.
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 ZIPReferências para continuar
- Node.js: Understanding setImmediate() — filas e ordem de execução.
- Node.js: Discover Promises — Promises e async/await.
- Node.js: Timers — comportamento de setTimeout.
- Node.js: Don't Block the Event Loop — limites de trabalho nos callbacks.
Exemplos originais do portal, executados em v24.22.1. Referências consultadas em 16 de novembro de 2026.