Типы пересечения в TypeScript: объединение типов через &

Тип пересечения, записываемый как A & B, описывает значение, которое одновременно является A и B. Для объектных типов это значит, что у значения есть все свойства обоих. Так объединяют существующие типы, не выписывая свойства заново.

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

Во втором объекте нет team, поэтому это ошибка компиляции TS2322, а следующая строка сообщения говорит Property 'team' is missing ... but required in type 'Employee'. Значение Staff можно передать везде, где ожидается Person или Employee.

Объединение объектных типов

& работает с любым сочетанием псевдонимов типов, интерфейсов и встроенных объектных типов, а также с параметрами типа дженериков. В последнем случае его трудно заменить: функция, которая добавляет свойства к любому полученному объекту, может точно это выразить.

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

Вызывающий код сохраняет точный тип того, что передал (title, words), плюс два добавленных свойства. interface ... extends не может выразить «каким бы ни был T, плюс это», потому что интерфейс не может расширять параметр типа.

Конфликтующие свойства становятся never

Когда обе стороны объявляют одно и то же свойство, его тип это пересечение двух типов. Если у этих типов нет общих значений, свойство становится never, и компилятор молчит, пока вы не попробуете создать значение:

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

Ошибка указывает на объект, а не на тип, который её вызвал, поэтому такие ошибки долго ищут. Если навести курсор на r.id в редакторе, виден его тип: never. Когда конфликтующее свойство это литеральный тег, как в type Shape = { kind: "circle" } & { kind: "square" }, TypeScript идёт дальше и сводит всё пересечение к never. Тогда чтение свойства такого значения объясняет причину: 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 ловит тот же конфликт сразу в объявлении, с ошибкой TS2430. Это главное практическое различие между ними; на странице interface или type они сравниваются бок о бок.

Совместимое пересечение сужает свойство

Если типы двух свойств пересекаются, результатом будет их общая часть. Это полезно, а не ошибка:

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

Вторая половина показывает, что & делает с объединениями: он оставляет члены, общие для обеих сторон. Если думать о типах как о множествах значений, это становится предсказуемым. A | B это объединение двух множеств, A & B их пересечение, а пустое пересечение это never.

Пересечение и объединение

Названия взяты из теории множеств, и в применении к свойствам объектов они кажутся перевёрнутыми:

У пересечения объектных типов больше свойств именно потому, что оно допускает меньше значений: только объекты, у которых есть всё.

Пересечение и extends

Для объединения нескольких псевдонимов объектных типов & идиоматичен и вполне годится. Для типа из многих частей или типа публичного API extends даёт более ранние ошибки и более дешёвую проверку типов.

Пересечения с примитивами: брендирование

Пересечение примитива с объектным типом не даёт never: string & { readonly __brand: "UserId" } это строка с дополнительной меткой, существующей только при компиляции. Ни у одной настоящей строки нет такого свойства, и в этом весь смысл: создать такое значение может только код, который намеренно утверждает бренд, поэтому обычный string или OrderId больше нельзя передать туда, где ожидается UserId. Этому приёму посвящена отдельная страница, брендированные типы.