null e undefined em TypeScript: verificações, ?. e ??

Com strictNullChecks ligado (ele faz parte do strict), null e undefined são tipos próprios. Uma string nunca pode ser null; um valor que pode faltar precisa dizer isso no tipo, como string | null, e o TypeScript obriga você a tratar esse caso antes de usar o valor.

function initials(name: string | null | undefined): string {
  if (name == null) return "?"; // handles both null and undefined
  return name
    .split(" ")
    .map((part) => part[0])
    .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(null));           // ?
console.log(initials(undefined));      // ?

Depois da verificação, o compilador sabe que name é uma string, então .split é permitido. O resto desta página mostra os jeitos de fazer essa verificação e os operadores que a encurtam.

strictNullChecks e os erros "possibly null"

Quando um tipo inclui null ou undefined, o TypeScript se recusa a usar o valor como se ele sempre existisse:

// This does not compile: name may be null
function greet(name: string | null) {
  return "Hello, " + name.toUpperCase();
}

console.log(greet("ada"));

index.ts(3,22): error TS18047: 'name' is possibly 'null'.

A versão com undefined é a TS18048, 'x' is possibly 'undefined'. Sem strictNullChecks, null e undefined são aceitos em todo tipo e esse código compila, e depois quebra em tempo de execução com um TypeError na primeira vez em que name for null. Essa classe de bug é o principal motivo para manter o strict ligado.

De onde esses tipos vêm no código do dia a dia:

Verificando null e undefined

Todas as verificações abaixo estreitam o tipo dentro do bloco. Escolha a que corresponde ao que você quer excluir.

function label(value: string | null | undefined): string {
  if (value === undefined) return "undefined";
  if (value === null) return "null";
  return value.toUpperCase(); // value is string here
}

function orNone(value: string | null | undefined): string {
  if (value == null) return "(none)"; // == null matches null AND undefined
  return `"${value}"`;
}

console.log(label(undefined), label(null), label("ok")); // undefined null OK
console.log(orNone(null), orNone(undefined), orNone("")); // (none) (none) ""

== null é o único lugar em que a igualdade frouxa é idiomática: é verdadeira exatamente para null e undefined, e nada mais. Uma verificação de truthiness teria tratado a string vazia como ausente, o que muitas vezes é um bug.

Optional chaining: ?.

a?.b lê b se a não for null nem undefined; caso contrário, para e retorna undefined. O mesmo operador funciona com índices, a?.[i], e com chamadas, fn?.().

interface User {
  name: string;
  address?: { city: string; zip?: string };
  tags?: string[];
  onLogin?: () => string;
}

const ada: User = { name: "Ada", address: { city: "London" }, onLogin: () => "welcome" };
const bob: User = { name: "Bob" };

console.log(ada.address?.city);        // London
console.log(bob.address?.city);        // undefined
console.log(ada.address?.zip?.length); // undefined
console.log(bob.tags?.[0]);            // undefined
console.log(ada.onLogin?.());          // welcome
console.log(bob.onLogin?.());          // undefined

O tipo de bob.address?.city é string | undefined: o optional chaining acrescenta undefined ao resultado, então normalmente você o combina com ??. O comportamento em tempo de execução é JavaScript puro; veja optional chaining para os detalhes do curto-circuito.

A dupla interrogação: ??

a ?? b retorna a, a menos que ele seja null ou undefined; nesse caso retorna b. Ele substitui o idioma antigo a || b, que também descarta 0, "", false e NaN:

function pageSize(input: number | undefined): string {
  const withOr = input || 20;      // 0 is falsy, so it is replaced
  const withNullish = input ?? 20; // only undefined is replaced
  return `${withOr} vs ${withNullish}`;
}

console.log(pageSize(undefined)); // 20 vs 20
console.log(pageSize(0));         // 20 vs 0

const scores = new Map([["Ada", 90]]);
const score: number = scores.get("Linus") ?? 0; // number | undefined becomes number
console.log(score);                             // 0

Nos tipos, ?? remove null e undefined do lado esquerdo e faz a union do resto com o lado direito, e é por isso que scores.get("Linus") ?? 0 pode ser atribuído a um number.

Atribuição nullish: ??=

a ??= b atribui b a a só quando a é null ou undefined. Os irmãos ||= e &&= atribuem quando o lado esquerdo é falsy ou truthy.

interface Options {
  retries?: number;
  label?: string;
}

function withDefaults(opts: Options) {
  opts.retries ??= 3;   // assign only if null or undefined
  opts.label ||= "job"; // assign if falsy, so "" is replaced too
  return opts;
}

console.log(withDefaults({}));                       // { retries: 3, label: 'job' }
console.log(withDefaults({ retries: 0, label: "" })); // { retries: 0, label: 'job' }

retries: 0 sobrevive ao ??=, enquanto o label vazio é substituído pelo ||=. Depois de opts.retries ??= 3, o TypeScript estreita opts.retries para number no resto da função.

Propriedades opcionais vs | undefined

nickname?: string e nickname: string | undefined se leem igual, mas diferem em se a chave precisa existir:

interface WithOptional { nickname?: string }            // key may be missing
interface WithUndefined { nickname: string | undefined } // key must be present

const a: WithOptional = {};
const b: WithUndefined = { nickname: undefined };

// @ts-expect-error: Property 'nickname' is missing in type '{}' but required in type 'WithUndefined'.
const c: WithUndefined = {};

console.log("nickname" in a, "nickname" in b); // false true
console.log(a.nickname === b.nickname);        // true: both read as undefined

Use ? quando quem chama pode omitir a propriedade, e | undefined quando você quer que todos a passem explicitamente, mesmo que o valor seja undefined. A opção exactOptionalPropertyTypes (que não faz parte do strict) aperta ainda mais o ?: nickname?: string passa a rejeitar { nickname: undefined } e só aceita uma chave ausente ou uma string. Parâmetros opcionais de função (x?: number) se comportam como propriedades opcionais: dentro da função, x é number | undefined.

null ou undefined: qual usar

O TypeScript não impõe uma escolha, mas misturar os dois em uma base de código faz toda verificação ter que tratar dois casos. Uma convenção comum:

• Use undefined (e propriedades opcionais) para "não definido" nos seus próprios tipos. É o que o JavaScript produz por padrão: propriedades ausentes, argumentos omitidos, find e Map.get sem resultado.
• Aceite null onde uma API o entrega: JSON não tem undefined, e String.prototype.match e muitos métodos do DOM retornam null.
• Verifique com == null quando o valor pode ser qualquer um dos dois.

A indexação de arrays é a única brecha: users[5] tem o tipo do elemento mesmo quando o índice está fora do intervalo. A opção noUncheckedIndexedAccess (que não faz parte do strict) acrescenta | undefined a todo acesso por índice, para que o compilador pegue isso também.