TypeScript Intersection Types: Typen mit & kombinieren

Ein Intersection-Typ, geschrieben A & B, beschreibt einen Wert, der zugleich ein A und ein B ist. Bei Objekttypen heißt das, dass der Wert jede Eigenschaft beider hat. So kombinierst du vorhandene Typen, ohne die Eigenschaften erneut auszuschreiben.

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 };

Beim zweiten Objekt fehlt team, also ist es der Compilerfehler TS2322, und die nächste Zeile der Meldung sagt Property 'team' is missing ... but required in type 'Employee'. Ein Staff-Wert lässt sich überall übergeben, wo ein Person oder ein Employee erwartet wird.

Objekttypen kombinieren

& funktioniert mit jeder Mischung aus Typaliassen, Interfaces und Inline-Objekttypen sowie mit generischen Typparametern. Im letzten Fall ist es schwer zu ersetzen: Eine Funktion, die jedem erhaltenen Objekt Eigenschaften hinzufügt, kann das genau ausdrücken.

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

Der Aufrufer behält den genauen Typ dessen, was er übergeben hat (title, words), plus die zwei hinzugefügten Eigenschaften. Ein interface ... extends kann „was auch immer T ist, plus diese“ nicht ausdrücken, weil ein Interface keinen Typparameter erweitern kann.

Widersprüchliche Eigenschaften werden zu never

Deklarieren beide Seiten dieselbe Eigenschaft, ist ihr Typ die Intersection der beiden. Haben diese Typen keinen gemeinsamen Wert, wird die Eigenschaft zu never, und der Compiler sagt nichts, bis du versuchst, einen Wert zu erzeugen:

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

Der Fehler zeigt auf das Objekt, nicht auf den Typ, der ihn verursacht hat, und deshalb sind diese Bugs mühsam zu verfolgen. Fährst du im Editor mit der Maus über r.id, siehst du seinen Typ: never. Ist die widersprüchliche Eigenschaft ein Literal-Tag, wie in type Shape = { kind: "circle" } & { kind: "square" }, geht TypeScript weiter und reduziert die ganze Intersection auf never. Das Lesen einer Eigenschaft eines solchen Werts erklärt dann den Grund: 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 findet denselben Konflikt stattdessen an der Deklaration, mit dem Fehler TS2430. Das ist der wichtigste praktische Unterschied zwischen beiden; die Seite interface vs type stellt sie nebeneinander.

Kompatible Überschneidungen engen die Eigenschaft ein

Überschneiden sich die beiden Eigenschaftstypen, ist das Ergebnis die Überschneidung. Das ist nützlich, kein Fehler:

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

Die zweite Hälfte zeigt, was & mit Unions macht: Es behält die Member, die beide Seiten gemeinsam haben. Wenn man Typen als Mengen von Werten betrachtet, wird das vorhersagbar. A | B ist die Vereinigung der beiden Mengen, A & B ihre Schnittmenge, und eine leere Schnittmenge ist never.

Intersection vs Union

Die Namen stammen aus der Mengenlehre und wirken auf Objekteigenschaften angewendet verkehrt herum:

Eine Intersection von Objekttypen hat genau deshalb mehr Eigenschaften, weil sie weniger Werte erlaubt: nur Objekte, die alles haben.

Intersection vs extends

Zum Kombinieren einiger Typaliasse für Objekte ist & idiomatisch und in Ordnung. Für einen Typ aus vielen Teilen oder einen öffentlichen API-Typ liefert extends frühere Fehler und günstigere Typprüfungen.

Intersections mit primitiven Typen: Branding

Einen primitiven Typ mit einem Objekttyp zu schneiden ergibt kein never: string & { readonly __brand: "UserId" } ist ein String, der eine zusätzliche Markierung trägt, die nur beim Kompilieren existiert. Kein echter String hat diese Eigenschaft, und genau darum geht es: Nur Code, der die Marke absichtlich behauptet, kann einen solchen Wert erzeugen, also lässt sich ein einfacher string oder eine OrderId nicht mehr übergeben, wo eine UserId erwartet wird. Diese Technik hat eine eigene Seite, Branded Types.