Types intersection en TypeScript : combiner des types avec &

Un type intersection, écrit A & B, décrit une valeur qui est à la fois un A et un B. Pour les types objet, cela signifie que la valeur possède toutes les propriétés des deux. C'est ainsi qu'on combine des types existants sans réécrire leurs propriétés.

type Person = { name: string; email: string };
type Employee = { employeeId: number; team: string };

type Staff = Person & Employee; // has all four properties

const ada: Staff = { name: "Ada", email: "ada@example.com", employeeId: 7, team: "compilers" };

function badge(s: Staff): string {
  return `${s.name} (#${s.employeeId}, ${s.team})`;
}

console.log(badge(ada)); // Ada (#7, compilers)

// @ts-expect-error: Type '{ name: string; email: string; employeeId: number; }' is not assignable to type 'Staff'.
const partial: Staff = { name: "Alan", email: "alan@example.com", employeeId: 8 };

Le second objet omet team, il provoque donc l'erreur de compilation TS2322, et la ligne suivante du message indique Property 'team' is missing ... but required in type 'Employee'. Une valeur Staff peut être passée partout où un Person ou un Employee est attendu.

Combiner des types objet

& fonctionne avec n'importe quel mélange d'alias de type, d'interfaces et de types objet en ligne, ainsi qu'avec les paramètres de type génériques. C'est dans ce dernier cas qu'il est difficile à remplacer : une fonction qui ajoute des propriétés à l'objet qu'elle reçoit, quel qu'il soit, peut l'exprimer précisément.

function withMeta<T extends object>(obj: T, author: string): T & { author: string; savedAt: string } {
  return { ...obj, author, savedAt: "2024-03-15T10:30:00.000Z" };
}

const note = withMeta({ title: "Draft", words: 120 }, "ada");
// type: { title: string; words: number } & { author: string; savedAt: string }

console.log(note.title, note.words, note.author); // Draft 120 ada
console.log(note.savedAt);                         // 2024-03-15T10:30:00.000Z

L'appelant conserve le type exact de ce qu'il a passé (title, words), plus les deux propriétés ajoutées. Une interface ... extends ne peut pas exprimer « quel que soit T, plus ceci », car une interface ne peut pas étendre un paramètre de type.

Les propriétés contradictoires deviennent never

Quand les deux côtés déclarent la même propriété, le type de la propriété est l'intersection des deux. Si ces types n'ont aucune valeur en commun, la propriété devient never, et le compilateur ne dit rien tant que vous n'essayez pas de créer une valeur :

// This does not compile: id cannot be a string and a number at once
type WithStringId = { id: string; name: string };
type WithNumberId = { id: number };

type Account = WithStringId & WithNumberId; // no error on this line

const r: Account = { id: "u1", name: "Ada" };
console.log(r);

index.ts(7,22): error TS2322: Type 'string' is not assignable to type 'never'.

L'erreur désigne l'objet, pas le type qui l'a causée, ce qui rend ces bugs longs à retrouver. Survoler r.id dans l'éditeur montre son type : never. Quand la propriété contradictoire est une étiquette littérale, comme dans type Shape = { kind: "circle" } & { kind: "square" }, TypeScript va plus loin et réduit toute l'intersection à never. Lire une propriété d'une telle valeur explique alors pourquoi : Property 'kind' does not exist on type 'never'. The intersection 'Shape' was reduced to 'never' because property 'kind' has conflicting types in some constituents.

interface ... extends détecte le même conflit au niveau de la déclaration, avec l'erreur TS2430. C'est la principale différence pratique entre les deux ; la page interface ou type les compare côte à côte.

Les recouvrements compatibles affinent la propriété

Si les deux types de propriété se recouvrent, le résultat est ce recouvrement. C'est utile, pas une erreur :

type Editable = { id: string | number; tags: string[] };
type Stored = { id: string; createdAt: string };

type Doc = Editable & Stored; // id: (string | number) & string, which is string

const doc: Doc = { id: "d1", tags: ["draft"], createdAt: "2024-03-15" };
console.log(doc.id.toUpperCase()); // D1: id is a string, so string methods are allowed

type Letters = "a" | "b" | "c";
type Later = "b" | "c" | "d";
type Both = Letters & Later; // "b" | "c": what the two unions have in common

const shared: Both[] = ["b", "c"];
console.log(shared); // [ 'b', 'c' ]

La seconde moitié montre ce que & fait aux unions : il garde les membres communs aux deux côtés. Voir les types comme des ensembles de valeurs rend cela prévisible. A | B est la réunion des deux ensembles, A & B leur partie commune, et une partie commune vide vaut never.

Intersection ou union

Les noms viennent de la théorie des ensembles, et ils semblent inversés quand on les applique aux propriétés d'objets :

Une intersection de types objet a plus de propriétés précisément parce qu'elle autorise moins de valeurs : seulement les objets qui ont tout.

Intersection ou extends

Pour combiner quelques alias de types objet, & est idiomatique et convient très bien. Pour un type construit à partir de nombreuses parties, ou un type d'API publique, extends donne des erreurs plus tôt et des vérifications moins coûteuses.

Intersections avec des primitives : le branding

L'intersection d'une primitive et d'un type objet ne donne pas never : string & { readonly __brand: "UserId" } est une chaîne qui porte un marqueur supplémentaire, présent uniquement à la compilation. Aucune vraie chaîne n'a cette propriété, et c'est justement le but : seul du code qui affirme délibérément la marque peut en créer une, si bien qu'un simple string ou un OrderId ne peut plus être passé là où un UserId est attendu. Cette technique a sa propre page, types branded.