Intersection types em TypeScript: combinar tipos com &

Um intersection type, escrito A & B, descreve um valor que é um A e um B ao mesmo tempo. Para tipos de objeto, isso significa que o valor tem todas as propriedades dos dois. É assim que você combina tipos existentes sem reescrever as propriedades.

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

O segundo objeto deixa de fora team, então gera o erro de compilação TS2322, e a linha seguinte da mensagem diz Property 'team' is missing ... but required in type 'Employee'. Um valor Staff pode ser passado em qualquer lugar em que um Person ou um Employee é esperado.

Combinando tipos de objeto

O & funciona com qualquer mistura de type aliases, interfaces e tipos de objeto inline, e com type parameters genéricos. Esse último caso é onde ele é difícil de substituir: uma função que acrescenta propriedades a qualquer objeto que receba consegue dizer isso com precisão.

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

Quem chama mantém o tipo exato do que passou (title, words) mais as duas propriedades acrescentadas. Um interface ... extends não consegue expressar "seja o que for T, mais isto", porque uma interface não pode estender um type parameter.

Propriedades conflitantes viram never

Quando os dois lados declaram a mesma propriedade, o tipo dela é a intersection dos dois. Se esses tipos não têm nenhum valor em comum, a propriedade vira never, e o compilador não diz nada até você tentar criar um valor:

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

O erro aponta para o objeto, não para o tipo que o causou, e por isso esses bugs são lentos de rastrear. Passar o mouse sobre r.id no editor mostra o tipo dele: never. Quando a propriedade conflitante é uma tag literal, como em type Shape = { kind: "circle" } & { kind: "square" }, o TypeScript vai além e reduz a intersection inteira a never. Ler uma propriedade desse valor então explica o motivo: 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 pega o mesmo conflito já na declaração, com o erro TS2430. Essa é a principal diferença prática entre os dois; a página sobre interface vs type os compara lado a lado.

Sobreposições compatíveis estreitam a propriedade

Se os dois tipos da propriedade se sobrepõem, o resultado é a sobreposição. Isso é útil, não um erro:

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 segunda metade mostra o que o & faz com unions: mantém os membros que os dois lados têm em comum. Pensar nos tipos como conjuntos de valores torna isso previsível. A | B é a união dos dois conjuntos, A & B é a sobreposição deles, e uma sobreposição vazia é never.

Intersection vs union

Os nomes vêm da teoria dos conjuntos, e parecem invertidos quando aplicados a propriedades de objeto:

Uma intersection de tipos de objeto tem mais propriedades justamente porque permite menos valores: só objetos que têm tudo.

Intersection vs extends

Para combinar alguns type aliases de objeto, o & é idiomático e funciona bem. Para um tipo montado a partir de muitas partes, ou um tipo de API pública, o extends dá erros mais cedo e verificações de tipo mais baratas.

Intersections com primitivos: branding

Fazer a intersection de um primitivo com um tipo de objeto não produz never: string & { readonly __brand: "UserId" } é uma string que carrega uma marca extra, que só existe em tempo de compilação. Nenhuma string real tem essa propriedade, e é exatamente essa a ideia: só código que afirma a marca de propósito pode criar uma, então uma string simples ou um OrderId não podem mais ser passados onde um UserId é esperado. Essa técnica tem uma página própria, branded types.