RegExp.escape() — Escapando Strings para Regex Nativamente

Construir uma expressão regular a partir de uma string vinda do usuário sempre foi um problema: caracteres como ., * ou ( têm significado especial em regex, e usá-los sem escapar pode quebrar o padrão ou, pior, causar um comportamento inesperado. O método estático RegExp.escape(), que chegou ao ECMAScript 2025, resolve isso de forma nativa: recebe uma string qualquer e devolve uma cópia com todos os caracteres especiais de regex escapados, pronta para ser usada dentro de um padrão.

O problema que ele resolve

Antes do RegExp.escape(), não existia nenhuma função nativa para isso. Era comum recorrer a uma regex auxiliar escrita à mão, repetida em projeto após projeto:

function escapar(texto) {
    return texto.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

const termoDoUsuario = 'preço: R$ 10.00 (promoção)';
const padrao = new RegExp(escapar(termoDoUsuario));

console.log(padrao.test('preço: R$ 10.00 (promoção) disponível')); // true

Funciona, mas é fácil esquecer um caractere especial, copiar uma versão desatualizada da regex de outro projeto, ou simplesmente não saber que o escape é necessário até o padrão quebrar em produção.

Como usar RegExp.escape()

A API é direta: passe uma string e receba de volta a mesma string com os caracteres especiais de regex precedidos por \:

const termoDoUsuario = 'preço: R$ 10.00 (promoção)';

const escapado = RegExp.escape(termoDoUsuario);
console.log(escapado); // 'preço: R\$ 10\.00 \(promoção\)'

const padrao = new RegExp(escapado);
console.log(padrao.test('preço: R$ 10.00 (promoção) disponível')); // true

O resultado é uma string comum, não uma regex já compilada — por isso ainda é necessário passá-la para o construtor RegExp (ou interpolá-la dentro de um literal construído dinamicamente).

Exemplo prático: busca "destacar termo"

Um caso de uso muito comum é destacar, dentro de um texto, as ocorrências de um termo digitado pelo usuário em um campo de busca. Sem escapar o termo, caracteres como ( ou + digitados pelo usuário quebrariam a busca:

function destacar(texto, termo) {
    const padrao = new RegExp(RegExp.escape(termo), 'gi');
    return texto.replace(padrao, trecho => `<mark>${trecho}</mark>`);
}

const resultado = destacar(
    'Promoção: C++ para iniciantes (edição revisada)',
    'C++ (edição'
);

console.log(resultado);
// 'Promoção: <mark>C++ (edição</mark> revisada)'

Exemplo prático: validação de domínio permitido

Outro caso frequente é montar uma regex de validação a partir de uma lista de valores conhecidos em tempo de execução, como domínios configurados em um painel administrativo:

const dominiosPermitidos = ['meusite.com.br', 'sub.meusite.com.br'];

const padrao = new RegExp(
    `^https://(${dominiosPermitidos.map(RegExp.escape).join('|')})/`
);

console.log(padrao.test('https://sub.meusite.com.br/painel')); // true
console.log(padrao.test('https://meusite.com.br.evil.com/'));  // false

Aqui o escape é essencial: o . de meusite.com.br não deveria casar com qualquer caractere, apenas com o ponto literal — sem RegExp.escape(), um domínio malicioso como meusiteXcomXbr passaria pela validação.

Quando usar

• Montar regex a partir de entrada do usuário, como campos de busca ou filtros.
• Construir padrões dinamicamente a partir de listas de valores conhecidos apenas em tempo de execução (domínios, tags, nomes de arquivo).
• Qualquer lugar que hoje usa uma função de escape "caseira" copiada entre projetos.
• Evitar vulnerabilidades de ReDoS ou bypass de validação causadas por caracteres de regex não escapados.

Cuidados

RegExp.escape() escapa caracteres para uso dentro de uma regex com sintaxe Unicode-aware (equivalente à flag u/v). Isso significa que o resultado é seguro para ser usado tanto em padrões comuns quanto nos que utilizam essas flags mais novas. Além disso, o método lança um erro se receber algo que não seja uma string primitiva — não tente passar números ou objetos diretamente sem converter antes com String().

Compatibilidade

A proposta alcançou o Stage 4 no TC39 em fevereiro de 2025 e já faz parte da especificação ECMAScript 2025. O suporte está chegando aos motores mais recentes de Safari, Firefox e Chrome; para ambientes mais antigos ou Node.js em versões anteriores, o polyfill do pacote regexp.escape cobre a lacuna.

caniuse

Conclusão

RegExp.escape() fecha uma lacuna que existia desde os primórdios do JavaScript: uma forma nativa, correta e padronizada de transformar qualquer string em um trecho seguro de regex. É pouco código, mas elimina uma fonte recorrente de bugs sutis e de brechas de segurança em padrões construídos dinamicamente.