Interface vs type en TypeScript : différences et quand les utiliser

Pour décrire la forme d'un objet, interface et type font le même travail, et les valeurs de l'un sont assignables à l'autre quand les formes correspondent. Les différences se situent aux marges : type peut nommer des choses qu'une interface ne peut pas (unions, tuples, types calculés), et une interface sait faire quelques choses qu'un alias de type ne sait pas faire (fusion, extends vérifié).

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 compare les types objet par leur structure : le nom de la déclaration ne compte donc pas pour l'assignabilité. Voici la liste des endroits où le choix, lui, compte.

Tableau comparatif

Ce que seul type sait faire

Tout ce qui n'est pas une forme d'objet unique demande un alias de type :

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

Aucun de ces types ne peut s'écrire avec interface (les deux derniers sont traités dans types mappés et types conditionnels). C'est la raison pratique pour laquelle toute base de code finit par utiliser type quelque part, quel que soit son choix pour les formes d'objets.

Ce que seule interface sait faire : la fusion de déclarations

Deux déclarations interface du même nom dans la même portée se combinent en une seule. Deux déclarations type du même nom provoquent l'erreur 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 fusion permet d'étendre de l'extérieur les types d'une bibliothèque : ajouter une propriété au Window global, au Request d'Express, ou au type de thème d'une bibliothèque. Si vous publiez des types que les utilisateurs peuvent avoir besoin d'augmenter, utilisez des interfaces. Dans votre propre code applicatif, une fusion accidentelle (deux fichiers de script déclarant le même nom d'interface globale) se produit en silence, sauf si les deux déclarent la même propriété avec des types différents : c'est l'un des arguments de certaines équipes pour préférer type.

extends ou intersection

Une interface s'étend avec extends, un alias de type avec &. Le résultat est en général le même, mais ils traitent différemment une propriété contradictoire. extends signale le conflit au niveau de la déclaration :

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

Une intersection accepte le même conflit en silence et transforme la propriété en never (un string qui serait aussi un number). L'erreur n'apparaît que plus tard, quand vous essayez de créer une valeur :

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'erreur désigne l'objet, loin de la déclaration qui l'a causée. Pour construire des types objet à partir d'autres types objet, extends donne le meilleur message.

Signatures d'index : une différence facile à manquer

Un alias de type pour un type objet reçoit une signature d'index implicite, il peut donc être passé là où un Record<string, unknown> est attendu. Une interface, non. C'est voulu : l'explication de l'équipe TypeScript (issue #15300 sur le dépôt TypeScript) est qu'une interface peut être augmentée par des déclarations ultérieures, qu'il est donc moins sûr de lui inférer une signature d'index, et que changer la règle aujourd'hui casserait trop de code.

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

L'appel marqué @ts-expect-error s'exécute quand même et affiche les champs d'Alan : la règle n'agit qu'à la compilation. C'est la cause habituelle d'une erreur déroutante quand une valeur typée par une interface est passée à un helper de journalisation, de sérialisation ou de requête typé avec Record<string, ...>. Passez cette déclaration à type, étalez la valeur, ou typez plutôt le paramètre du helper avec une interface ou un générique.

Performances et messages d'erreur

La page Performance du wiki TypeScript (section « Preferring Interfaces Over Intersections ») suggère interface Foo extends Bar, Baz { ... } plutôt que type Foo = Bar & Baz & { ... } pour composer des types objet. Ses raisons : une interface est un type objet plat unique qui détecte les conflits de propriétés, les relations de types entre interfaces sont mises en cache (les intersections dans leur ensemble ne le sont pas), et vérifier une valeur par rapport à une intersection vérifie chaque constituant avant le type aplati. La différence compte dans les grosses bases de code avec beaucoup de types composés ; pour quelques formes d'objets ordinaires, vous ne la mesurerez pas.

La même page note que les interfaces s'affichent mieux. Une interface apparaît sous son nom au survol et dans les messages d'erreur, alors qu'un alias d'intersection est souvent affiché développé en ses parties, ce qui rend les longs messages plus difficiles à lire.

Lequel utiliser

Une règle qui fonctionne :

1. Formes d'objets : interface. Vous obtenez un extends vérifié, des erreurs plus claires sur les grosses compositions, et les utilisateurs d'une bibliothèque peuvent l'augmenter. Cela correspond à l'heuristique du handbook TypeScript : « utilisez interface jusqu'à ce que vous ayez besoin de fonctionnalités de type ».
2. Tout le reste : type. Unions, tuples, types de fonctions, types littéraux, et tout ce qui se construit avec des types mappés, conditionnels ou template literal.
3. Exception : utilisez type pour une forme d'objet qui doit correspondre à des paramètres Record<string, ...>, ou quand vous voulez volontairement empêcher la fusion.

Utiliser type partout est aussi un choix cohérent, et beaucoup de bases de code le font. Mélanger les deux au hasard est la seule option à éviter : les lecteurs se demandent alors si une différence était voulue.