Interface vs type in TypeScript: differenze e quando usarli

Per descrivere la forma di un oggetto, interface e type fanno lo stesso lavoro, e i valori dell'uno sono assegnabili all'altro quando le forme coincidono. Le differenze stanno ai margini: type può dare un nome a cose che un'interfaccia non può esprimere (unioni, tuple, tipi calcolati), e un'interfaccia può fare alcune cose che un alias di tipo non sa fare (merging, extends controllato).

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 confronta i tipi oggetto in base alla struttura, quindi per l'assegnabilità il nome della dichiarazione non conta. Di seguito trovi l'elenco dei casi in cui la scelta conta davvero.

Tabella di confronto

Cosa sa fare solo type

Tutto ciò che non è una singola forma di oggetto ha bisogno di un alias di 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

Nessuno di questi si può scrivere con interface (gli ultimi due sono spiegati in mapped types e conditional types). È il motivo pratico per cui ogni codebase finisce per usare type da qualche parte, qualunque cosa usi per le forme di oggetti.

Cosa sa fare solo interface: il declaration merging

Due dichiarazioni interface con lo stesso nome nello stesso scope si uniscono in una. Due dichiarazioni type con lo stesso nome danno l'errore 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'.

Il merging è il modo in cui i tipi delle librerie vengono estesi dall'esterno: aggiungere una proprietà al Window globale, alla Request di Express o al tipo del tema di una libreria. Se pubblichi tipi che gli utenti potrebbero dover estendere, usa le interfacce. Nel codice della tua applicazione, un merge accidentale (due file di script che dichiarano la stessa interfaccia globale) avviene senza avvisi, a meno che le due non dichiarino la stessa proprietà con tipi diversi: è uno degli argomenti con cui alcuni team preferiscono type.

extends o intersezione

Un'interfaccia si estende con extends, un alias di tipo con &. Il risultato è quasi sempre lo stesso, ma gestiscono in modo diverso una proprietà in conflitto. extends segnala il conflitto nella dichiarazione:

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

Un'intersezione accetta lo stesso conflitto senza avvisare e trasforma la proprietà in never (una string che è anche un number). L'errore compare solo più tardi, quando provi a creare un valore:

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");

L'errore punta all'oggetto, lontano dalla dichiarazione che l'ha causato. Per costruire tipi oggetto a partire da altri tipi oggetto, extends dà il messaggio migliore.

Index signature: una differenza che sfugge facilmente

Un alias di tipo per un tipo oggetto riceve una index signature implicita, quindi si può passare dove è atteso un Record<string, unknown>. Un'interfaccia no. È una scelta voluta: la spiegazione del team di TypeScript (issue #15300 nel repository di TypeScript) è che un'interfaccia può essere estesa da dichiarazioni successive, quindi dedurre per essa una index signature è meno sicuro, e cambiare ora la regola romperebbe troppo codice.

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 chiamata marcata @ts-expect-error viene comunque eseguita e stampa i campi di Alan: la regola vale solo in compilazione. È il motivo tipico di un errore poco chiaro quando un valore di un'interfaccia viene passato a un helper di logging, serializzazione o query tipizzato con Record<string, ...>. Trasforma quella dichiarazione in type, fai uno spread del valore, oppure tipizza il parametro dell'helper con un'interfaccia o un generic.

Prestazioni e messaggi di errore

La pagina Performance della wiki di TypeScript (sezione "Preferring Interfaces Over Intersections") suggerisce interface Foo extends Bar, Baz { ... } invece di type Foo = Bar & Baz & { ... } quando si compongono tipi oggetto. I suoi motivi: un'interfaccia è un unico tipo oggetto piatto che rileva i conflitti tra proprietà, le relazioni di tipo tra interfacce vengono messe in cache (le intersezioni nel loro insieme no), e controllare un valore rispetto a un'intersezione controlla ogni componente prima del tipo appiattito. La differenza conta nelle codebase grandi con molti tipi composti; per poche normali forme di oggetti non la misurerai.

La stessa pagina osserva che le interfacce vengono visualizzate meglio. Un'interfaccia viene mostrata con il suo nome nei tooltip e nei messaggi di errore, mentre un alias di intersezione viene spesso stampato espanso nelle sue parti, e questo rende più difficili da leggere i messaggi lunghi.

Quale usare

Una regola che funziona:

1. Forme di oggetti: interface. Ti dà un extends controllato, errori più chiari nelle composizioni grandi, e permette agli utenti di una libreria di estenderla. Corrisponde al criterio dell'handbook di TypeScript: "usa interface finché non ti servono funzionalità di type".
2. Tutto il resto: type. Unioni, tuple, tipi funzione, tipi letterali e tutto ciò che si costruisce con mapped, conditional o template literal types.
3. Eccezione: usa type per una forma di oggetto che deve adattarsi a parametri Record<string, ...>, o quando vuoi impedire di proposito il merging.

Usare type per tutto è anch'essa una scelta coerente, e molte codebase lo fanno. Mescolare i due a caso è l'unica opzione da evitare: fa chiedere a chi legge se una differenza fosse voluta.