Encadeamento Opcional em JavaScript (?.)

O operador de encadeamento opcional ?. é uma forma curta e segura de ler um valor no fundo de uma cadeia de objects conectados quando um dos elos dessa cadeia pode não existir. Em vez de lançar um erro, ele simplesmente para e retorna undefined. Este capítulo percorre o problema que ele resolve, as três formas que ele assume e as poucas regras que você precisa para usá-lo corretamente.

O Problema: Lendo Propriedades Ausentes

Imagine que você tem um object user e quer ler a cidade de um object address aninhado. Se address estiver ausente, acessar uma propriedade nele lança um erro:

let user = {}; // a user without an address

console.log(user.address.city);
// TypeError: Cannot read properties of undefined (reading 'city')

O motivo é que user.address é undefined, e tentar ler .city de undefined não é permitido. Essa é uma situação comum quando os dados vêm de uma API, de um formulário ou de um banco de dados onde alguns campos são opcionais.

Antes de ?. existir, os desenvolvedores contornavam isso com cadeias && ou verificações aninhadas. Isso funciona, mas é verboso e repete os nomes das propriedades:

let user = {};

// The old way with the && operator
let city = user && user.address && user.address.city;
console.log(city); // undefined

// Or with an even longer ternary
let city2 = user ? (user.address ? user.address.city : undefined) : undefined;
console.log(city2); // undefined

Como o Encadeamento Opcional Funciona

O operador de encadeamento opcional ?. interrompe a avaliação se o valor antes dele for null ou undefined, e retorna undefined em vez de lançar um erro. Esse comportamento é chamado de curto-circuito.

Veja a mesma consulta, agora segura e legível:

Quando user.address é undefined, a expressão user?.address?.city retorna undefined silenciosamente. Quando os dados estão presentes, a cadeia lê até o city.

Ele Protege Apenas o Valor à Sua Esquerda

Esta é a regra mais importante, e a que os iniciantes erram com mais frequência. O ?. verifica apenas o valor imediatamente à sua esquerda, não a cadeia inteira.

Considere a?.b.c:

• Se a for null ou undefined, a expressão inteira entra em curto-circuito e retorna undefined.
• Mas se a existir e b for null ou undefined, então .c ainda é um acesso simples — e lança um erro.

let a = { b: null };

console.log(a?.b);    // null — fine, a exists
console.log(a?.b.c);  // TypeError: Cannot read properties of null (reading 'c')

A correção é colocar ?. em cada ponto onde um valor pode legitimamente estar ausente:

let a = { b: null };

console.log(a?.b?.c); // undefined — no error

Portanto, a regra é simples: coloque ?. diretamente após cada valor que pode não estar lá, não apenas no início da cadeia.

O Curto-Circuito Interrompe Toda a Cadeia

Quando a parte antes de ?. é null ou undefined, o restante da expressão não é avaliado de forma alguma. Isso inclui quaisquer chamadas de função e quaisquer acessos de propriedade adicionais que vierem depois.

Essa é uma garantia útil: nada após um elo ausente tem a chance de executar ou causar efeitos colaterais.

As Três Formas do Encadeamento Opcional

?. não é um operador por si só — é uma construção de sintaxe que vem em três formas, uma para cada maneira de acessar um valor.

?. para Acesso a Propriedades

Use obj?.prop para ler uma propriedade quando obj pode ser null ou undefined.

let user = { name: 'John' };

console.log(user?.name);    // John
console.log(user?.surname); // undefined (key missing, but no error)

?.() para Chamar Métodos

Use obj.method?.() para chamar um método somente se ele existir. Isso é útil quando um object pode ou não implementar um determinado método.

Se greet não for uma função (porque está ausente), ?.() ignora a chamada e retorna undefined em vez de lançar TypeError: greet is not a function.

?.[] para Chaves Dinâmicas

Use obj?.[key] quando você lê uma propriedade com notação de colchetes — por exemplo, uma chave dinâmica armazenada em uma variável.

let user = { name: 'Alice' };
let key = 'name';

console.log(user?.[key]); // Alice

let nobody = null;
console.log(nobody?.[key]); // undefined (no error)

O Encadeamento Opcional É para Leitura, Não para Escrita

Você pode usar ?. para ler um valor e até mesmo para delete uma propriedade com segurança. Mas não pode usá-lo no lado esquerdo de uma atribuição.

let user = null;

// Reading is fine
console.log(user?.name); // undefined

// Deleting is fine — delete is skipped if user is null
delete user?.name; // no error

// Assignment does NOT work — this is a syntax error
// user?.name = 'John'; // SyntaxError

O motivo é que não há nada significativo para atribuir quando o lado esquerdo está ausente, então a linguagem não permite isso.

Não Abuse do Encadeamento Opcional

?. é uma ferramenta precisa: use-o apenas onde o valor à sua esquerda é genuinamente opcional. Usá-lo em todos os lugares é um erro, pois pode ocultar bugs reais.

Por exemplo, se você digitar errado o nome de uma propriedade, ?. retornará undefined silenciosamente em vez de deixar você notar o problema:

let user = { name: 'John' };

console.log(user?.nmae); // undefined — typo hidden, no error to alert you

Combinando com Coalescência Nula

O encadeamento opcional retorna undefined quando um elo está ausente, o que combina perfeitamente com o operador de coalescência nula ?? para fornecer um valor padrão.

Aqui user?.name avalia para undefined, e ?? então entra para fornecer o fallback 'Anonymous'. Essa combinação é um dos usos reais mais comuns de ?..

Suporte nos Navegadores

O encadeamento opcional faz parte da especificação ES2020. É suportado em todos os navegadores modernos (Chrome, Firefox, Safari e Edge) e no Node.js 14 e versões posteriores, portanto você pode usá-lo sem um transpilador nos ambientes atuais. Para se aprofundar nos valores que ele verifica, consulte tipos de dados JavaScript e métodos de object e this.

Teste Seu Conhecimento