Union types in TypeScript: l'operatore | con esempi

Uno union type elenca delle alternative con |: un valore di tipo string | number è una stringa oppure un numero. Le union sono il modo in cui TypeScript descrive valori che possono legittimamente assumere più di una forma, e il compilatore ti obbliga a verificare quale forma hai prima di usare qualcosa di specifico.

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 ogni ramo del controllo typeof, id ha un solo tipo. Questo passaggio si chiama narrowing, ed è ciò che rende le union utilizzabili in pratica.

Sono ammessi solo i membri comuni

Prima del narrowing, puoi usare solo ciò che supportano tutti i membri della union. toString() esiste sia sulle stringhe sia sui numeri, quindi va bene; toUpperCase() esiste solo sulle stringhe:

// 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'.

La seconda riga indica il membro a cui manca la proprietà. La stessa regola vale nella direzione opposta: un valore string | number non si può passare a un parametro tipizzato string (TS2345), perché potrebbe essere un numero. Una union accetta più valori e, in cambio, ti lascia fare meno con essi finché non controlli.

Restringere una union

Il narrowing usa normali controlli JavaScript. TypeScript segue il flusso di controllo e toglie i membri man mano che vengono esclusi, quindi dopo l'ultimo controllo resta un solo 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)

L'elenco completo delle forme di narrowing è nella pagina sul type narrowing.

Union di tipi letterali

Una union di valori letterali è un insieme chiuso di valori ammessi. È la union più comune nel codice reale:

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'.

Il confronto con un letterale restringe il tipo: dopo if (current === "error"), il ramo else sa che current è uno degli altri tre. In molte codebase le union di letterali sostituiscono gli enum; vedi i literal types per as const e per come ricavare una union di questo tipo da un array.

Union di tipi oggetto

Quando i membri sono tipi oggetto, le proprietà che hanno tutti in comune sono disponibili direttamente. Per le altre, verifica con in che la proprietà esista:

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

Per le union di più forme di oggetti, il pattern più pulito è una proprietà letterale condivisa come kind: "cat" / kind: "fish". Controllare quell'unica proprietà restringe l'intero oggetto, e su uno switch basato su di essa si può verificare l'esaustività. Questo pattern si chiama discriminated union.

Array e union

La posizione delle parentesi cambia del tutto il significato:

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

Quando iteri su un (string | number)[], ogni elemento è la union e va ristretto, come nella callback di reduce qui sopra. Anche metodi come map e filter funzionano su uno string[] | number[], con la callback che riceve string | number.

Union con null e undefined

La union più comune in assoluto è "un valore o niente": string | null, User | undefined. È ciò che restituiscono Array.prototype.find e Map.prototype.get, e una proprietà opzionale name?: string si legge come string | undefined. Gestirle con ?., ?? e i controlli su null ha una pagina dedicata: null e undefined.

Per togliere membri da una union esistente a livello di tipi, usa le utility integrate: Exclude<"a" | "b" | "c", "a"> è "b" | "c", e NonNullable<string | null> è string.