Union types em TypeScript: o operador | com exemplos

Um union type lista alternativas com |: um valor do tipo string | number é uma string ou um número. Unions são o jeito de o TypeScript descrever valores que podem legitimamente ter mais de uma forma, e o compilador obriga você a verificar qual forma tem antes de usar algo específico dela.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

Dentro de cada ramo da verificação typeof, id tem um único tipo. Esse passo se chama narrowing, e é ele que torna as unions práticas.

Só os membros em comum são permitidos

Antes do narrowing, você só pode usar o que todos os membros da union suportam. toString() existe em strings e em números, então tudo bem; toUpperCase() só existe em strings:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

A segunda linha indica o membro que não tem a propriedade. A mesma regra vale no sentido contrário: um valor string | number não pode ser passado para um parâmetro tipado como string (TS2345), porque pode ser um número. Uma union aceita mais valores e, em troca, deixa você fazer menos com eles até verificar.

Narrowing de uma union

O narrowing usa verificações comuns de JavaScript. O TypeScript acompanha o fluxo de controle e remove membros à medida que são descartados, então depois da última verificação sobra só um membro:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

A lista completa de formas de narrowing está na página sobre type narrowing.

Unions de literal types

Uma union de valores literais é um conjunto fechado de valores permitidos. É a union mais comum em código real:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

Comparar com um literal faz narrowing: depois de if (current === "error"), o else sabe que current é um dos outros três. Unions de literais substituem enums em muitas bases de código; veja literal types para o as const e como derivar uma union dessas a partir de um array.

Unions de tipos de objeto

Quando os membros são tipos de objeto, as propriedades que todos compartilham ficam disponíveis diretamente. Para o resto, verifique se a propriedade existe com in:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

Para unions de vários formatos de objeto, o padrão mais limpo é uma propriedade literal compartilhada, como kind: "cat" / kind: "fish". Verificar essa única propriedade estreita o objeto inteiro, e um switch sobre ela pode ter a exaustividade verificada. Esse padrão é uma discriminated union.

Arrays e unions

Onde ficam os parênteses muda completamente o significado:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

Ao percorrer um (string | number)[], cada elemento é a union e precisa de narrowing, como no callback do reduce acima. Métodos como map e filter também funcionam em um string[] | number[], com o callback recebendo string | number.

Unions com null e undefined

A union mais comum de todas é "um valor ou nada": string | null, User | undefined. É o que Array.prototype.find e Map.prototype.get retornam, e uma propriedade opcional name?: string é lida como string | undefined. Tratar esses casos com ?., ?? e verificações de null tem uma página própria: null e undefined.

Para remover membros de uma union existente no nível dos tipos, use os utilitários nativos: Exclude<"a" | "b" | "c", "a"> é "b" | "c", e NonNullable<string | null> é string.