Interface vs type en TypeScript: diferencias y cuándo usar cada uno

Para describir la forma de un objeto, interface y type hacen el mismo trabajo, y los valores de uno se pueden asignar al otro cuando las formas coinciden. Las diferencias están en los bordes: type puede nombrar cosas que una interfaz no puede (uniones, tuplas, tipos calculados), y una interfaz puede hacer algunas cosas que un alias de tipo no puede (fusionarse, un extends comprobado).

interface PointI {
  x: number;
  y: number;
}

type PointT = {
  x: number;
  y: number;
};

const a: PointI = { x: 1, y: 2 };
const b: PointT = a; // same shape, so they are interchangeable
const c: PointI = b;

function show(p: PointI): string {
  return `(${p.x}, ${p.y})`;
}

console.log(show(b), show(c)); // (1, 2) (1, 2)

TypeScript compara los tipos objeto por estructura, así que el nombre de la declaración no importa para la asignabilidad. Lo que sigue es la lista de sitios donde la elección sí importa.

Tabla comparativa

Lo que solo puede hacer type

Todo lo que no sea una única forma de objeto necesita un alias de tipo:

type Status = "idle" | "loading" | "done";                   // union of literals
type Coordinates = [lat: number, lng: number];               // tuple
type Handler = (event: string) => void;                      // function type
type ID = string | number;                                   // union of primitives
type Flags<T> = { [K in keyof T]: boolean };                 // mapped type
type ElementOf<T> = T extends readonly (infer U)[] ? U : T;  // conditional type

const current: Status = "loading";
const here: Coordinates = [51.5, -0.12];
const onSave: Handler = (e) => console.log("saved:", e);
const flags: Flags<{ dark: string; beta: number }> = { dark: true, beta: false };
const first: ElementOf<string[]> = "a";

onSave(current);
console.log(here, flags, first);
// saved: loading
// [ 51.5, -0.12 ] { dark: true, beta: false } a

Nada de esto se puede escribir con interface (los dos últimos se explican en mapped types y conditional types). Esa es la razón práctica de que todos los proyectos acaben usando type en algún sitio, usen lo que usen para las formas de objeto.

Lo que solo puede hacer interface: la fusión de declaraciones

Dos declaraciones interface con el mismo nombre en el mismo ámbito se combinan en una. Dos declaraciones type con el mismo nombre son el error TS2300, Duplicate identifier.

interface Settings {
  theme: string;
}
interface Settings {
  fontSize: number;
}
const s: Settings = { theme: "dark", fontSize: 14 }; // needs both

type Options = { a: number };
type Options = { b: number }; // error TS2300: Duplicate identifier 'Options'.

La fusión es cómo se amplían desde fuera los tipos de las librerías: añadir una propiedad al Window global, al Request de Express o al tipo del tema de una librería. Si publicas tipos que los usuarios podrían necesitar ampliar, usa interfaces. En tu propio código de aplicación, una fusión accidental (dos archivos de script que declaran el mismo nombre de interfaz global) ocurre sin avisar salvo que las dos declaren la misma propiedad con tipos distintos, y ese es uno de los argumentos que dan algunos equipos para preferir type.

extends frente a intersección

Una interfaz se extiende con extends, un alias de tipo con &. Casi siempre dan el mismo resultado, pero tratan de forma distinta una propiedad en conflicto. extends informa del conflicto en la declaración:

// This does not compile: id cannot change from string to number
interface Base {
  id: string;
  name: string;
}

interface Broken extends Base {
  id: number;
}

const x: Broken = { id: 1, name: "a" };
console.log(x);

index.ts(7,11): error TS2430: Interface 'Broken' incorrectly extends interface 'Base'.
  Types of property 'id' are incompatible.
    Type 'number' is not assignable to type 'string'.

Una intersección acepta el mismo conflicto sin avisar y convierte la propiedad en never (un string que también es un number). El error solo aparece después, cuando intentas crear un valor:

type Base = { id: string; name: string };
type Broken = Base & { id: number }; // no error here

// id is string & number, which is never: no object can satisfy Broken
// @ts-expect-error: Type 'number' is not assignable to type 'never'.
const x: Broken = { id: 1, name: "a" };

console.log("the alias compiled; only using it failed");

El error señala el objeto, lejos de la declaración que lo causó. Para construir tipos objeto a partir de otros tipos objeto, extends da el mejor mensaje.

Firmas de índice: una diferencia fácil de pasar por alto

Un alias de un tipo objeto recibe una firma de índice implícita, así que se puede pasar donde se espera un Record<string, unknown>. Una interfaz no. Es deliberado: la explicación del equipo de TypeScript (issue #15300 del repositorio de TypeScript) es que una interfaz se puede ampliar con declaraciones posteriores, así que inferirle una firma de índice es menos seguro, y cambiar la regla ahora rompería demasiado código.

interface UserI { name: string; age: number }
type UserT = { name: string; age: number };

function logFields(fields: Record<string, unknown>) {
  for (const [key, value] of Object.entries(fields)) {
    console.log(`${key}=${String(value)}`);
  }
}

const t: UserT = { name: "Ada", age: 36 };
const i: UserI = { name: "Alan", age: 41 };

logFields(t); // fine

// @ts-expect-error: Index signature for type 'string' is missing in type 'UserI'.
logFields(i);

logFields({ ...i }); // a spread copy is a fresh object type, so it is accepted

La llamada marcada con @ts-expect-error se ejecuta igualmente e imprime los campos de Alan: la regla es de tiempo de compilación. Esta es la razón habitual de un error confuso cuando se pasa un valor de una interfaz a una función auxiliar de logging, serialización o consultas tipada con Record<string, ...>. Cambia esa declaración a type, expande el valor, o tipa el parámetro de la función auxiliar con una interfaz o un genérico.

Rendimiento y mensajes de error

La página Performance de la wiki de TypeScript (sección "Preferring Interfaces Over Intersections") sugiere interface Foo extends Bar, Baz { ... } en lugar de type Foo = Bar & Baz & { ... } al componer tipos objeto. Sus razones: una interfaz es un único tipo objeto plano que detecta conflictos de propiedades, las relaciones entre interfaces se guardan en caché (las intersecciones en su conjunto no), y comprobar un valor contra una intersección comprueba cada componente antes del tipo aplanado. La diferencia importa en proyectos grandes con muchos tipos compuestos; con unas pocas formas de objeto normales no la vas a notar.

La misma página señala que las interfaces se muestran mejor. Una interfaz aparece por su nombre al pasar el cursor y en los mensajes de error, mientras que un alias de intersección a menudo se imprime desplegado en sus partes, lo que hace más difíciles de leer los mensajes largos.

Cuál usar

Una regla que funciona:

1. Formas de objeto: interface. Da un extends comprobado, errores más claros en composiciones grandes y permite que los usuarios de una librería la amplíen. Coincide con la heurística del handbook de TypeScript: «usa interface hasta que necesites características de type».
2. Todo lo demás: type. Uniones, tuplas, tipos de función, tipos literales y todo lo que se construya con mapped types, conditional types o template literal types.
3. Excepción: usa type para una forma de objeto que tenga que encajar en parámetros Record<string, ...>, o cuando quieras impedir la fusión a propósito.

Usar type para todo también es una opción coherente, y muchos proyectos lo hacen. Mezclar los dos al azar es la única opción que conviene evitar: hace que quien lee se pregunte si la diferencia era intencionada.