Typy przecięcia w TypeScript: łączenie typów przez &

Typ przecięcia, zapisywany jako A & B, opisuje wartość, która jest jednocześnie A i B. Dla typów obiektowych oznacza to, że wartość ma wszystkie właściwości obu. Tak łączy się istniejące typy bez ponownego wypisywania właściwości.

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

Drugiemu obiektowi brakuje team, więc to błąd kompilacji TS2322, a kolejna linia komunikatu mówi Property 'team' is missing ... but required in type 'Employee'. Wartość Staff można przekazać wszędzie tam, gdzie oczekiwany jest Person albo Employee.

Łączenie typów obiektowych

& działa z dowolną mieszanką aliasów typów, interfejsów i typów obiektowych zapisanych w miejscu, a także z generycznymi parametrami typu. W tym ostatnim przypadku trudno go czymś zastąpić: funkcja, która dodaje właściwości do dowolnego otrzymanego obiektu, może to dokładnie wyrazić.

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

Wywołujący zachowuje dokładny typ tego, co przekazał (title, words), plus dwie dodane właściwości. interface ... extends nie wyrazi „czymkolwiek jest T, plus to”, bo interfejs nie może rozszerzać parametru typu.

Sprzeczne właściwości stają się never

Gdy obie strony deklarują tę samą właściwość, jej typ jest przecięciem obu typów. Jeśli te typy nie mają żadnej wspólnej wartości, właściwość staje się never, a kompilator milczy, dopóki nie spróbujesz utworzyć wartości:

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

Błąd wskazuje na obiekt, a nie na typ, który go spowodował, więc takie bugi trudno namierzyć. Najechanie kursorem na r.id w edytorze pokazuje jego typ: never. Gdy sprzeczna właściwość jest literałowym tagiem, jak w type Shape = { kind: "circle" } & { kind: "square" }, TypeScript idzie dalej i redukuje całe przecięcie do never. Odczyt właściwości takiej wartości wyjaśnia wtedy dlaczego: 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 wyłapuje ten sam konflikt już przy deklaracji, błędem TS2430. To główna praktyczna różnica między nimi; strona o interface vs type porównuje je obok siebie.

Zgodne nakładanie się zawęża właściwość

Jeśli typy właściwości się nakładają, wynikiem jest ich część wspólna. To przydatne, a nie błąd:

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

Druga połowa pokazuje, co & robi z uniami: zostawia elementy wspólne dla obu stron. Myślenie o typach jak o zbiorach wartości sprawia, że jest to przewidywalne. A | B to suma obu zbiorów, A & B to ich część wspólna, a pusta część wspólna to never.

Przecięcie kontra unia

Nazwy pochodzą z teorii zbiorów i przy właściwościach obiektów wydają się odwrócone:

Przecięcie typów obiektowych ma więcej właściwości właśnie dlatego, że dopuszcza mniej wartości: tylko obiekty, które mają wszystko.

Przecięcie kontra extends

Do połączenia kilku aliasów typów obiektowych & jest idiomatyczne i w porządku. Dla typu złożonego z wielu części albo typu publicznego API extends daje wcześniejsze błędy i tańsze sprawdzanie typów.

Przecięcia z prymitywami: branding

Przecięcie prymitywu z typem obiektowym nie daje never: string & { readonly __brand: "UserId" } to string z dodatkowym znacznikiem istniejącym tylko w czasie kompilacji. Żaden prawdziwy string nie ma tej właściwości i właśnie o to chodzi: utworzyć taką wartość może tylko kod, który celowo potwierdza brand, więc zwykłego string ani OrderId nie da się już przekazać tam, gdzie oczekiwany jest UserId. Ta technika ma własną stronę, branded types.