Types union en TypeScript : l'opérateur | avec exemples

Un type union liste des alternatives avec | : une valeur de type string | number est soit une chaîne, soit un nombre. Les unions sont la façon dont TypeScript décrit les valeurs qui peuvent légitimement prendre plusieurs formes, et le compilateur vous oblige à vérifier quelle forme vous avez avant d'utiliser quoi que ce soit qui lui soit propre.

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

Dans chaque branche de la vérification typeof, id n'a qu'un seul type. Cette étape s'appelle le narrowing, et c'est elle qui rend les unions utilisables.

Seuls les membres communs sont autorisés

Avant le narrowing, vous ne pouvez utiliser que ce que chaque membre de l'union permet. toString() existe sur les chaînes comme sur les nombres, il ne pose donc pas de problème ; toUpperCase() n'existe que sur les chaînes :

// 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 seconde ligne nomme le membre auquel manque la propriété. La même règle s'applique dans l'autre sens : une valeur string | number ne peut pas être passée à un paramètre typé string (TS2345), car ce pourrait être un nombre. Une union accepte plus de valeurs et, en contrepartie, vous laisse faire moins de choses avec elles tant que vous n'avez pas vérifié.

Affiner une union

Le narrowing utilise des vérifications JavaScript ordinaires. TypeScript suit le flux de contrôle et retire les membres à mesure qu'ils sont écartés, si bien qu'après la dernière vérification il ne reste qu'un membre :

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 liste complète des formes de narrowing se trouve sur la page consacrée au narrowing.

Unions de types littéraux

Une union de valeurs littérales est un ensemble fermé de valeurs autorisées. C'est l'union la plus courante dans du vrai code :

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

Comparer à un littéral affine : après if (current === "error"), la branche else sait que current est l'une des trois autres valeurs. Les unions de littéraux remplacent les enums dans beaucoup de bases de code ; voir types littéraux pour as const et la façon de dériver une telle union d'un tableau.

Unions de types objet

Quand les membres sont des types objet, les propriétés qu'ils partagent tous sont directement disponibles. Pour les autres, vérifiez que la propriété existe avec 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

Pour les unions de plusieurs formes d'objets, le motif le plus propre est une propriété littérale commune comme kind: "cat" / kind: "fish". Vérifier cette seule propriété affine tout l'objet, et un switch sur elle peut être vérifié pour l'exhaustivité. Ce motif s'appelle une union discriminée.

Tableaux et unions

L'emplacement des parenthèses change complètement le sens :

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

En parcourant un (string | number)[], chaque élément est l'union et doit être affiné, comme dans le callback de reduce ci-dessus. Des méthodes comme map et filter fonctionnent aussi sur un string[] | number[], le callback recevant alors string | number.

Unions avec null et undefined

L'union la plus courante de toutes est « une valeur ou rien » : string | null, User | undefined. C'est ce que renvoient Array.prototype.find et Map.prototype.get, et une propriété optionnelle name?: string se lit comme string | undefined. Traiter ces cas avec ?., ?? et des vérifications de null a sa propre page : null et undefined.

Pour retirer des membres d'une union existante au niveau des types, utilisez les utilitaires intégrés : Exclude<"a" | "b" | "c", "a"> vaut "b" | "c", et NonNullable<string | null> vaut string.