Operador de Coalescência Nula do JavaScript (??)

O operador de coalescência nula (??) é uma forma concisa e expressiva de fornecer um valor padrão em JavaScript. Ele retorna seu operando à direita apenas quando o operando à esquerda é nulo — ou seja, null ou undefined — e caso contrário devolve o valor à esquerda sem alterações. Introduzido no ES2020, ele resolve um problema antigo com o uso do operador || para valores padrão, e funciona em conjunto com o encadeamento opcional e os operadores lógicos que você já conhece.

O Que "Nulo" Significa

Um valor é considerado nulo quando é exatamente null ou undefined. Todos os outros valores — incluindo os falsos como 0, '', false e NaN — são tratados como valores reais e intencionais pelo ??.

null ?? 'default'       // 'default'
undefined ?? 'default'  // 'default'

0 ?? 'default'          // 0
'' ?? 'default'         // ''
false ?? 'default'      // false
NaN ?? 'default'        // NaN

A regra é simples: se o lado esquerdo é null ou undefined, você obtém o lado direito; caso contrário, obtém o lado esquerdo.

Como ?? Difere de ||

Este é o motivo mais importante para a existência do ??. O operador OR lógico (||) retorna o lado direito sempre que o lado esquerdo é qualquer valor falso — 0, '', false, NaN, null e undefined contam todos. Esse comportamento é adequado até que 0 ou uma string vazia seja um valor legítimo, momento em que || silenciosamente produz o resultado errado.

Considere um contador cujo valor válido pode ser 0:

let count = 0;

let withOr = count || 100;   // 100  — errado! 0 foi substituído
let withNullish = count ?? 100; // 0   — correto, 0 foi preservado

Como 0 é falso, || o trata da mesma forma que "sem valor" e cai para 100. O operador ?? reconhece que 0 não é nulo e o mantém. A mesma armadilha se aplica a strings vazias:

Precedência e Parênteses

O operador ?? tem precedência baixa — aproximadamente no mesmo nível de || e menor que os operadores aritméticos e de comparação. Na prática, isso significa que o valor de fallback é resolvido antes de ser usado em uma expressão maior, mas você ainda deve agrupar com parênteses para manter a intenção clara.

let height = null;
let width;

// Each ?? is evaluated, then the products are multiplied
let area = (height ?? 100) * (width ?? 50);
console.log(area); // 100 * 50 = 5000

Sem os parênteses, a multiplicação se ligaria mais fortemente do que você poderia esperar, então envolver cada padrão em ( ... ) mantém a matemática sem ambiguidade e legível.

Combinar ?? Com && ou || É Proibido

JavaScript deliberadamente recusa permitir que você misture ?? com && ou || na mesma expressão sem parênteses. Fazer isso é um SyntaxError, porque a precedência entre eles seria ambígua e fácil de interpretar errado.

// SyntaxError: Unexpected token '||'
let result = a ?? b || c;

// Fix it by grouping explicitly:
let safe = (a ?? b) || c;   // valid
let other = a ?? (b || c);  // also valid, different meaning

As duas formas válidas têm significados diferentes, e é exatamente por isso que a linguagem faz você escolher. Adicione os parênteses e declare precisamente o que você pretende.

Operadores de Atribuição Lógica

O ES2021 adicionou três operadores de atribuição lógica que combinam uma atribuição com uma verificação lógica. Eles atribuem à variável à esquerda apenas quando uma condição é satisfeita, o que os torna perfeitos para preencher valores padrão e atualizações condicionais.

Atribuição de Coalescência Nula (??=)

x ??= y atribui y a x somente se x for atualmente null ou undefined. É a forma de atribuição de ?? e o mais comum dos três para definir padrões em um object.

let settings = { theme: 'dark' };

settings.theme ??= 'light';   // already set → stays 'dark'
settings.fontSize ??= 16;     // missing → becomes 16

console.log(settings); // { theme: 'dark', fontSize: 16 }

Atribuição OR Lógico (||=)

x ||= y atribui y a x quando x é falso (0, '', false, null, undefined, NaN). Como ||, pode sobrescrever valores falsos válidos, portanto use-o apenas quando qualquer valor falso realmente significa "substitua-me".

Atribuição AND Lógico (&&=)

x &&= y atribui y a x somente quando x é verdadeiro. É útil para atualizar um valor que já existe sem criá-lo.

let config = { token: 'abc123' };

config.token &&= config.token.trim(); // truthy → trimmed and reassigned
config.missing &&= 'never set';        // undefined → left untouched

console.log(config); // { token: 'abc123' }

Cada operador também realiza curto-circuito: ele apenas avalia e atribui o lado direito quando a condição o exige, portanto os efeitos colaterais à direita são ignorados quando a atribuição não ocorre.

Usos no Mundo Real

O operador ?? se destaca em qualquer situação em que um valor pode estar legitimamente ausente enquanto 0 ou '' devem ser respeitados. Cenários típicos incluem leitura de configurações, definição de padrões em parâmetros de função opcionais e extração de campos de respostas de API.

// 1. Default options merged with user input
function createButton(options) {
  let label = options.label ?? 'Submit';
  let count = options.count ?? 0; // 0 stays 0, never becomes a default
  return { label, count };
}

// 2. Reading a possibly-missing API field
let response = { data: { user: { nickname: null } } };
let name = response.data.user.nickname ?? 'Guest';
console.log(name); // 'Guest'

Ele combina especialmente bem com o encadeamento opcional (?.). O encadeamento opcional retorna com segurança undefined quando parte de um caminho está ausente, e ?? então fornece o valor de fallback em uma linha limpa:

let city = user?.address?.city ?? 'Unknown';

Isso se lê como: "Use a cidade do usuário se toda a cadeia existir, caso contrário use 'Unknown'." Para decidir qual dos dois caminhos tomar com base em uma condição, o operador condicional (ternário) ainda é a melhor ferramenta — ?? é especificamente para fornecer valores padrão para valores nulos.

Resumo

• ?? retorna o operando direito somente quando o esquerdo é null ou undefined; caso contrário, retorna o esquerdo.
• Prefira ?? a || para valores padrão quando 0, '' ou false são valores válidos.
• ?? tem precedência baixa — agrupe com parênteses e nunca o coloque diretamente ao lado de && ou || sem parênteses (isso é um SyntaxError).
• ??=, ||= e &&= atribuem condicionalmente: em nulo, em falso e em verdadeiro, respectivamente.
• Combine ?? com encadeamento opcional (?.) para ler dados possivelmente ausentes e definir um valor padrão em uma única expressão.

Teste Seu Conhecimento