Ooperador de coalescência nula (??) é um operador lógico que retorna o seu operando do lado direito quando o seu operador do lado esquerdo énull ouundefined. Caso contrário, ele retorna o seu operando do lado esquerdo.

Ao contrário dooperador lógico OR (||), o operando esquerdo é retornado se houver um valorfalsy (falso) que não sejanull ouundefined. Em outras palavras, se você usar|| para obter algum valor padrão para outra variávelfoo, você pode enfrentar comportamentos inesperados se você considerar algum valor falseável como utilizável (eg.'' ou0). Veja abaixo alguns exemplos:

Experimente

const foo = null ?? "default string";console.log(foo);// Expected output: "default string"const baz = 0 ?? 42;console.log(baz);// Expected output: 0

Sintaxe

exprEsq ?? exprDir

Descrição

O operador de coalescência nula retorna os resultados da expressão de seu lado direito se a expressão de seu lado esquerdo fornull ouundefined.

Endereçando um valor padrão à variável

Inicialmente, quando se deseja endereçar um valor padrão à variável, um padrão comum é utilizar o operador lógico OR (||):

let foo;//  foo nunca é endereçado a nenhum valor, portanto, ainda está indefinidolet someDummyText = foo || "Hello!";

Entretanto, devido ao|| ser um operador lógico booleano, o operando do lado esquerdo é coagido para um valor booleano para sua avaliação e qualquer valorfalseável (0,'',NaN,null,undefined) não é retornado. Este comportamento pode causar consequencias inesperadas se você considerar0,'', ouNaN como valores válidos.

let count = 0;let text = "";let qty = count || 42;let message = text || "Olá!";console.log(qty); // 42 e não 0console.log(message); // "Olá!" e não ""

O operador de coalescência nula evita esta cilada pois retorna o segundo operando apenas quando o primeiro é avaliado entre os valoresnull ouundefined (mas nehum outro valor falseável):

let myText = ""; // Uma string vazia (que também é um valor falseável)let notFalsyText = myText || "Olá mundo";console.log(notFalsyText); // Olá mundolet preservingFalsy = myText ?? "Olá vizinhança";console.log(preservingFalsy); // '' (Pois myText não é undefined e nem null)

Curto-circuito

Assim como os operadores lógicos OR e AND, a expressão do lado direito não é avaliada se o lado esquerdo não for avaliado entrenull e nemundefined.

function A() {  console.log("A foi chamado");  return undefined;}function B() {  console.log("B foi chamado");  return false;}function C() {  console.log("C foi chamado");  return "foo";}console.log(A() ?? C());// Imprime "A foi chamado" então "C foi chamado" e por fim "foo"// Como A() retornou undefined então ambas expressões foram avaliadasconsole.log(B() ?? C());// Imprime "B foi chamado" então "false"// Como B() retornou false (e não null ou undefined), a expressão// do lado direito não foi avaliada.

Sem encadeamento com os operadores AND e OR

Não é possível encadear ambos operadores AND (&&) e OR (||) diretamente com o??. UmSyntaxError será disparado nesse tipo de caso.

null || undefined ?? "foo"; // Dispara um SyntaxErrortrue || undefined ?? "foo"; // Dispara um SyntaxError

Entretanto, explicitar diretamente a precedência por meio de parênteses resulta no comportamento correto:

(null || undefined) ?? "foo"; // retorna "foo"

Relacionamento com o operador de encadeamento opcional (?.)

O operador de coalescêcia nula trataundefined enull como valores específicos e então executa ooperador de encadeamento opcional (?.) o qual é útil para acessar uma propriedade de um objeto, o qual pode sernull ouundefined.

let foo = { someFooProp: "oi" };console.log(foo.someFooProp?.toUpperCase()); // "OI"console.log(foo.someBarProp?.toUpperCase()); // undefined

Exemplo

Neste exemplo, nós iremos prover valores padrão, mas manter valores que não sejam (advinha???)null ouundefined.

const nullValue = null;const emptyText = ""; // falseável (falsy)const someNumber = 42;const valA = nullValue ?? "padrão para A";const valB = emptyText ?? "padrão para B";const valC = someNumber ?? 0;console.log(valA); // "padrão para A"console.log(valB); // "" (pois a string vazia não é null ou undefined)console.log(valC); // 42

Especificações

Compatibilidade com navegadores

Veja também

• The optional chaining operator
• The logical OR (||) operator
• Default parameters in functions