Tipos unión en TypeScript: el operador | con ejemplos

Un tipo unión enumera alternativas con |: un valor de tipo string | number es o un string o un número. Las uniones son la forma en que TypeScript describe valores que pueden tener legítimamente más de una forma, y el compilador te obliga a comprobar cuál tienes antes de usar nada específico de ella.

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 rama de la comprobación con typeof, id tiene un solo tipo. Ese paso se llama estrechamiento, y es lo que hace prácticas las uniones.

Solo se permiten los miembros comunes

Antes de estrechar, solo puedes usar lo que admiten todos los miembros de la unión. toString() existe en strings y en números, así que está bien; toUpperCase() solo existe en los 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'.

La segunda línea nombra el miembro al que le falta la propiedad. La misma regla se aplica en el otro sentido: un valor string | number no se puede pasar a un parámetro de tipo string (TS2345), porque podría ser un número. Una unión acepta más valores y, a cambio, te deja hacer menos con ellos hasta que compruebas.

Estrechar una unión

El estrechamiento usa comprobaciones normales de JavaScript. TypeScript sigue el flujo de control y va quitando miembros a medida que se descartan, así que tras la última comprobación solo queda uno:

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)

La lista completa de formas de estrechar está en la página de estrechamiento de tipos.

Uniones de tipos literales

Una unión de valores literales es un conjunto cerrado de valores permitidos. Es la unión más habitual en 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 con un literal estrecha: tras if (current === "error"), la rama else sabe que current es uno de los otros tres. Las uniones de literales sustituyen a los enums en muchos proyectos; consulta tipos literales para ver as const y cómo derivar una unión así de un array.

Uniones de tipos objeto

Cuando los miembros son tipos objeto, las propiedades que comparten todos están disponibles directamente. Para las demás, comprueba que la propiedad existe con 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 uniones de varias formas de objeto, el patrón más limpio es una propiedad literal compartida como kind: "cat" / kind: "fish". Comprobar esa propiedad estrecha todo el objeto, y un switch sobre ella se puede comprobar de forma exhaustiva. Ese patrón es una unión discriminada.

Arrays y uniones

Dónde van los paréntesis cambia por completo el 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

Al recorrer un (string | number)[], cada elemento es la unión y necesita estrecharse, como en el callback de reduce de arriba. Métodos como map y filter también funcionan sobre un string[] | number[], y el callback recibe string | number.

Uniones con null y undefined

La unión más habitual de todas es «un valor o nada»: string | null, User | undefined. Es lo que devuelven Array.prototype.find y Map.prototype.get, y una propiedad opcional name?: string se lee como string | undefined. Manejarlas con ?., ?? y comprobaciones de null tiene su propia página: null y undefined.

Para quitar miembros de una unión existente a nivel de tipos, usa las utilidades integradas: Exclude<"a" | "b" | "c", "a"> es "b" | "c", y NonNullable<string | null> es string.