Intersection types in TypeScript: combinare tipi con &

Un intersection type, scritto A & B, descrive un valore che è un A e un B allo stesso tempo. Per i tipi oggetto significa che il valore ha ogni proprietà di entrambi. È il modo per combinare tipi esistenti senza riscrivere le proprietà.

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

Il secondo oggetto omette team, quindi è l'errore di compilazione TS2322, e la riga successiva del messaggio dice Property 'team' is missing ... but required in type 'Employee'. Un valore Staff può essere passato ovunque sia atteso un Person o un Employee.

Combinare tipi oggetto

& funziona con qualsiasi combinazione di alias di tipo, interfacce e tipi oggetto inline, e con i parametri di tipo generici. È in quest'ultimo caso che è difficile da sostituire: una funzione che aggiunge proprietà a qualunque oggetto riceva può dirlo con precisione.

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

Chi chiama mantiene il tipo esatto di ciò che ha passato (title, words) più le due proprietà aggiunte. Un interface ... extends non può esprimere "qualunque cosa sia T, più queste", perché un'interfaccia non può estendere un parametro di tipo.

Le proprietà in conflitto diventano never

Quando entrambi i lati dichiarano la stessa proprietà, il tipo della proprietà è l'intersezione dei due. Se quei tipi non hanno alcun valore in comune, la proprietà diventa never, e il compilatore non dice nulla finché non provi a creare un valore:

// 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'errore punta all'oggetto, non al tipo che l'ha causato, e questo rende lenti da rintracciare questi bug. Passando il mouse su r.id nell'editor vedi il suo tipo: never. Quando la proprietà in conflitto è un tag letterale, come in type Shape = { kind: "circle" } & { kind: "square" }, TypeScript va oltre e riduce l'intera intersezione a never. Leggere una proprietà di un valore del genere spiega poi il perché: 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 intercetta lo stesso conflitto già nella dichiarazione, con l'errore TS2430. È questa la principale differenza pratica tra i due; la pagina interface vs type li mette a confronto.

Le sovrapposizioni compatibili restringono la proprietà

Se i due tipi della proprietà si sovrappongono, il risultato è la sovrapposizione. È utile, non un errore:

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 seconda metà mostra cosa fa & alle unioni: tiene i membri che entrambi i lati hanno in comune. Pensare ai tipi come insiemi di valori lo rende prevedibile. A | B è l'unione dei due insiemi, A & B è la loro sovrapposizione, e una sovrapposizione vuota è never.

Intersezione vs unione

I nomi vengono dalla teoria degli insiemi, e sembrano al contrario quando li applichi alle proprietà degli oggetti:

Un'intersezione di tipi oggetto ha più proprietà proprio perché ammette meno valori: solo gli oggetti che hanno tutto.

Intersezione vs extends

Per combinare pochi alias di tipi oggetto, & è idiomatico e va benissimo. Per un tipo costruito da molte parti, o un tipo di un'API pubblica, extends dà errori prima e controlli dei tipi più leggeri.

Intersezioni con i primitivi: branding

Intersecare un primitivo con un tipo oggetto non produce never: string & { readonly __brand: "UserId" } è una stringa che porta un marcatore in più, valido solo in fase di compilazione. Nessuna stringa reale ha quella proprietà, ed è proprio questo il punto: solo il codice che afferma deliberatamente il brand può crearne una, quindi una semplice string o un OrderId non si possono più passare dove è atteso un UserId. Questa tecnica ha una pagina tutta sua, branded types.