Tipos intersección en TypeScript: combinar tipos con &

Un tipo intersección, escrito A & B, describe un valor que es un A y un B al mismo tiempo. Con tipos objeto, eso significa que el valor tiene todas las propiedades de los dos. Es la forma de combinar tipos existentes sin volver a escribir las propiedades.

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

Al segundo objeto le falta team, así que es el error de compilación TS2322, y la siguiente línea del mensaje dice Property 'team' is missing ... but required in type 'Employee'. Un valor Staff se puede pasar en cualquier sitio donde se espera un Person o un Employee.

Combinar tipos objeto

& funciona con cualquier mezcla de alias de tipo, interfaces y tipos objeto en línea, y con parámetros de tipo genéricos. Este último caso es donde es difícil de sustituir: una función que añade propiedades a cualquier objeto que recibe puede decirlo con precisión.

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

Quien llama conserva el tipo exacto de lo que pasó (title, words) más las dos propiedades añadidas. Un interface ... extends no puede expresar «sea lo que sea T, más esto», porque una interfaz no puede extender un parámetro de tipo.

Las propiedades en conflicto se vuelven never

Cuando los dos lados declaran la misma propiedad, el tipo de la propiedad es la intersección de los dos. Si esos tipos no tienen ningún valor en común, la propiedad pasa a ser never, y el compilador no dice nada hasta que intentas crear un 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'.

El error señala el objeto, no el tipo que lo causó, lo que hace que estos bugs sean lentos de rastrear. Pasar el cursor por r.id en el editor muestra su tipo: never. Cuando la propiedad en conflicto es una etiqueta literal, como en type Shape = { kind: "circle" } & { kind: "square" }, TypeScript va más allá y reduce toda la intersección a never. Leer una propiedad de un valor así explica entonces por qué: 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 detecta el mismo conflicto en la declaración, con el error TS2430. Es la principal diferencia práctica entre los dos; la página de interface frente a type los compara lado a lado.

Los solapamientos compatibles estrechan la propiedad

Si los dos tipos de la propiedad sí se solapan, el resultado es el solapamiento. Eso es útil, no un error:

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 segunda mitad muestra lo que hace & con las uniones: conserva los miembros que tienen en común los dos lados. Pensar en los tipos como conjuntos de valores lo hace predecible. A | B es la unión de los dos conjuntos, A & B es su solapamiento, y un solapamiento vacío es never.

Intersección frente a unión

Los nombres vienen de la teoría de conjuntos, y parecen al revés cuando se aplican a las propiedades de los objetos:

Una intersección de tipos objeto tiene más propiedades justamente porque admite menos valores: solo los objetos que lo tienen todo.

Intersección frente a extends

Para combinar unos pocos alias de tipos objeto, & es idiomático y está bien. Para un tipo construido a partir de muchas partes, o para el tipo de una API pública, extends da errores antes y comprobaciones de tipos más baratas.

Intersecciones con primitivos: branding

Intersecar un primitivo con un tipo objeto no produce never: string & { readonly __brand: "UserId" } es un string que lleva una marca extra que solo existe en tiempo de compilación. Ningún string real tiene esa propiedad, y esa es precisamente la idea: solo el código que afirma la marca a propósito puede crear uno, así que un string normal o un OrderId ya no se pueden pasar donde se espera un UserId. Esa técnica tiene su propia página, branded types.