REPL no Node.js: Guia Prático

O REPL no Node.js é um ambiente interativo que lê uma instrução, executa o código, imprime o resultado e repete o ciclo. A sigla significa Read, Evaluate, Print e Loop. Ele é útil para experimentar APIs, validar expressões, investigar objetos, testar pequenos algoritmos e criar consoles administrativos sem precisar salvar um arquivo a cada mudança.

O REPL padrão aparece ao executar node sem informar um script. Além desse modo pronto, o módulo node:repl permite incorporar uma sessão interativa em uma aplicação, personalizar o prompt, controlar o contexto, adicionar comandos e definir como os resultados são exibidos.

Neste guia, você aprenderá a usar o console interativo, navegar pelo histórico, trabalhar com comandos especiais, carregar módulos, criar um REPL personalizado, proteger consoles administrativos e evitar riscos como exposição de credenciais ou execução remota sem autenticação.

O que é o REPL do Node.js?

O REPL recebe uma linha de JavaScript, compila a expressão no contexto da sessão e exibe o valor retornado. A documentação oficial do módulo REPL descreve o comportamento, os comandos internos e as opções da classe. As opções da linha de comando relacionadas ao runtime aparecem na documentação oficial da CLI do Node.js.

Para revisar a base da plataforma, consulte o que é Node.js. O artigo sobre Console no Node.js explica stdout, stderr e inspeção de objetos, recursos diretamente relacionados ao REPL.

Iniciando uma sessão

node

O terminal exibe um prompt semelhante a >. Digite uma expressão:

2 + 2
'node'.toUpperCase()
[1, 2, 3].map(value => value * 2)

O resultado é mostrado imediatamente. Declarações permanecem disponíveis enquanto a sessão estiver ativa:

const tax = 0.12
const subtotal = 250
subtotal * (1 + tax)

Esse contexto persistente facilita experimentar uma sequência de operações.

Expressões de várias linhas

Quando uma instrução está incompleta, o REPL continua aguardando:

function calculateTotal(items) {
  return items.reduce((sum, item) => {
    return sum + item.price;
  }, 0);
}

O prompt secundário indica que a expressão ainda não terminou. Fechar chaves, parênteses ou colchetes conclui a avaliação.

Variável de último resultado

O caractere sublinhado costuma representar o último valor calculado:

10 * 5
_ + 2

Esse recurso é conveniente para cálculos exploratórios. Se você declarar uma variável chamada _, o comportamento automático pode ser alterado.

Último erro

Em versões que oferecem essa convenção, _error pode apontar para o último erro não capturado:

JSON.parse('{invalid')
_error.message

Não dependa desse valor em código de produção. Ele existe para investigação interativa.

Comandos especiais

Comandos iniciados por ponto controlam a sessão:

• .help: mostra ajuda;
• .exit: encerra;
• .clear: limpa o contexto;
• .break: abandona uma expressão de várias linhas;
• .save arquivo.js: salva o conteúdo da sessão;
• .load arquivo.js: carrega um arquivo;
• .editor: entra em modo editor.

Os comandos disponíveis podem variar conforme a versão. Use .help como fonte direta.

Modo editor

.editor

O modo editor permite escrever um bloco maior antes de executar. Após concluir, use a combinação indicada pelo terminal para avaliar o conteúdo. Esse modo é útil para funções e objetos extensos, mas um arquivo com testes continua sendo melhor para código que precisa ser mantido.

Carregando módulos CommonJS

const fs = require('node:fs')
const path = require('node:path')

Você pode experimentar APIs nativas e dependências instaladas. Veja CommonJS no Node.js para entender resolução e cache de módulos.

ES Modules no modo interativo

Importações estáticas possuem regras específicas no REPL. Uma alternativa é o carregamento dinâmico:

const fs = await import('node:fs/promises')
await fs.readdir('.')

O suporte a top-level await e outros recursos depende da versão do Node.js. Consulte ES Modules no Node.js para diferenças entre import e require.

Histórico

O REPL pode persistir comandos em um arquivo de histórico. Isso melhora produtividade, mas também pode armazenar tokens, senhas e dados sensíveis digitados por engano. Evite colar credenciais em sessões interativas e proteja as permissões do arquivo de histórico.

Em máquinas compartilhadas, revise a configuração do ambiente e remova entradas sensíveis. A melhor prática é usar variáveis de ambiente ou gerenciadores de segredos sem imprimir valores.

Inspecionando objetos

process.memoryUsage()
process.versions
new URL('https://example.com/path?q=1')

O REPL usa mecanismos de inspeção do módulo Util. Objetos profundos podem ser resumidos. Consulte Módulo Util no Node.js para inspect(), profundidade e formatação.

Criando um REPL personalizado

const repl = require('node:repl');

const server = repl.start({
  prompt: 'admin> ',
  useColors: true
});

server.context.applicationName = 'Minha API';
server.context.health = () => ({
  status: 'ok',
  uptime: process.uptime()
});

As propriedades adicionadas em server.context ficam disponíveis como variáveis da sessão. Isso permite criar consoles de diagnóstico com funções controladas.

Não exponha objetos internos demais

Adicionar diretamente clientes de banco, repositórios, caches e configurações oferece poder excessivo:

server.context.database = databaseClient;

Uma pessoa com acesso pode apagar dados, ler credenciais ou bloquear o processo. Prefira funções estreitas e somente leitura:

server.context.getQueueStats = async () => {
  return queue.getSafeStatistics();
};

Comandos personalizados

server.defineCommand('status', {
  help: 'Mostra o estado da aplicação',
  action() {
    this.clearBufferedCommand();
    console.log({
      pid: process.pid,
      uptime: process.uptime(),
      memory: process.memoryUsage()
    });
    this.displayPrompt();
  }
});

O método de ação deve restaurar o prompt mesmo quando ocorre erro. Para operações assíncronas, use try, catch e finally.

Avaliação personalizada

A opção eval permite substituir a avaliação padrão:

const server = repl.start({
  prompt: 'calc> ',
  eval(command, context, filename, callback) {
    try {
      const value = safeCalculate(command);
      callback(null, value);
    } catch (error) {
      callback(error);
    }
  }
});

Essa abordagem pode criar uma linguagem limitada. Não tente tornar JavaScript não confiável seguro apenas filtrando texto. Para riscos de execução, leia Módulo VM no Node.js, lembrando que contextos VM também não são uma sandbox completa.

REPL por socket

É tecnicamente possível conectar um REPL a um socket TCP:

const net = require('node:net');
const repl = require('node:repl');

net.createServer(socket => {
  repl.start({
    prompt: 'remote> ',
    input: socket,
    output: socket,
    terminal: true
  });
}).listen(5001, '127.0.0.1');

Esse exemplo deve permanecer no loopback e em ambiente controlado. Um REPL remoto equivale, na prática, a acesso de execução no processo. Não publique a porta na internet.

Segurança de consoles administrativos

Quando um console remoto é realmente necessário:

• vincule ao loopback ou socket Unix;
• use túnel SSH autenticado;
• restrinja acesso por usuário e rede;
• registre abertura e fechamento da sessão;
• não exponha segredos no contexto;
• desative em produção por padrão;
• defina tempo máximo de sessão;
• mantenha uma allowlist de comandos administrativos.

Mesmo com autenticação, código arbitrário pode destruir dados. Um painel com operações específicas é geralmente mais seguro.

Capturando erros sem encerrar

Erros de sintaxe ou execução são exibidos e a sessão continua. Isso é adequado para experimentação. Em um REPL personalizado, trate erros operacionais e não deixe Promises rejeitadas sem captura.

server.context.runCheck = async () => {
  try {
    return await performCheck();
  } catch (error) {
    return {
      ok: false,
      message: error.message
    };
  }
};

Testando um REPL personalizado

Separe as funções administrativas da interface interativa. Assim, você testa a lógica com o Node Test Runner sem simular um terminal inteiro.

test('retorna status seguro', async () => {
  const status = await getSafeStatus();
  assert.equal(status.ok, true);
  assert.equal('password' in status, false);
});

REPL versus scripts

Use o REPL para descobrir, investigar e validar ideias pequenas. Transforme a solução em script ou módulo quando ela precisar ser reproduzida, revisada, testada ou versionada. Comandos manuais não deixam a mesma trilha de auditoria e podem variar entre operadores.

Erros comuns

• Digitar segredos: valores podem permanecer no histórico.
• Expor REPL remoto: o invasor ganha controle do processo.
• Adicionar cliente de banco ao contexto: operações destrutivas ficam disponíveis.
• Usar sessão como documentação: passos não são reproduzíveis.
• Depender de recursos da versão local: outro runtime pode se comportar diferente.
• Executar tarefas pesadas: o REPL compartilha o event loop da aplicação.
• Confiar em filtros de texto: JavaScript arbitrário continua perigoso.

Boas práticas

• Use o REPL localmente para exploração.
• Não digite credenciais.
• Converta experimentos úteis em testes.
• Exponha funções administrativas estreitas.
• Restrinja consoles remotos ao loopback.
• Use túnel autenticado quando necessário.
• Evite tarefas que bloqueiam o event loop.
• Fixe a versão do Node.js em ambientes críticos.
• Registre ações administrativas importantes.
• Desative o recurso por padrão em produção.

Conclusão

O REPL no Node.js acelera a aprendizagem e a investigação ao permitir testar JavaScript e APIs em uma sessão persistente. Comandos especiais, histórico, top-level await e inspeção de objetos tornam o ambiente útil para pequenas experiências e diagnósticos.

Ao incorporar um REPL em uma aplicação, a prioridade muda para segurança. O contexto deve conter apenas operações necessárias, o acesso precisa ser restrito e sessões remotas nunca devem ser expostas diretamente. Usado localmente e com disciplina, o REPL é uma ferramenta produtiva; usado como porta administrativa sem controles, torna-se um risco de execução arbitrária.