type или interface: чем они правда отличаются

Обе записи описывают форму объекта, и на значения это не влияет никак. Компилятор сравнивает типы по строению, а не по имени: если у значения есть нужные поля нужных типов, оно подходит — неважно, откуда взялось имя типа и было ли оно вообще.

interface Point {
  x: number;
  y: number;
}
type Coords = {
  x: number;
  y: number;
};
function distance(p: Point): number {
  return Math.round(Math.sqrt(p.x * p.x + p.y * p.y));
}
// значение объявлено псевдонимом, а функция требует интерфейс
const c: Coords = { x: 3, y: 4 };
console.log(distance(c));
const p: Point = c;
console.log(p.y);

Ни одной диагностики. distance ждёт Point, а получает значение, объявленное псевдонимом Coords; в обратную сторону тоже проходит. Ни interface, ни type не создают «новый тип», отличимый по имени, — разбору этого правила посвящена следующая статья главы.

Поэтому спор «что выбрать» и кажется вопросом вкуса. Но места, где выбор виден, есть. Первое ловит на ровном месте — на функции, которая принимает словарь.

interface UserI {
  name: string;
}
type UserT = {
  name: string;
};
// чужая функция ждёт словарь: ключи заранее неизвестны, значения — строки
function toQuery(data: Record<string, string>): string {
  return Object.entries(data).map(([key, value]) => key + "=" + value).join("&");
}
const fromAlias: UserT = { name: "Рико" };
const fromInterface: UserI = { name: "Рико" };
console.log(toQuery(fromAlias));
console.log(toQuery(fromInterface));

Диагностика ровно одна, на последней строке: TS2345, «Аргумент типа "UserI" нельзя назначить параметру типа "Record<string, string>". В типе "UserI" отсутствует сигнатура индекса для типа "string"». Формы у UserI и UserT совпадают до буквы, а проходит только псевдоним.

Причина — в слиянии объявлений, с которого начинается следующий раздел. Интерфейс можно дописать в любом месте программы, поэтому компилятор не вправе заранее решить, что все его поля будут строками. У псевдонима набор полей закрыт в момент объявления, и неявную сигнатуру индекса компилятор выводит без риска. Сам Record — словарь с заранее неизвестными ключами; ему отведена последняя статья главы.

Первый практический вывод: если тип уезжает в чужую функцию, которая ждёт Record, псевдоним избавит вас от спора.

Два объявления интерфейса с одним именем — не ошибка и не опечатка. Компилятор складывает их поля в один тип.

interface Point {
  x: number;
}
interface Point {
  y: number;
}
const full: Point = { x: 1, y: 2 };
console.log(full.x + full.y);
const half: Point = { x: 1 };
console.log(half);

Одна диагностика — на предпоследней строке: TS2741, «Свойство "y" отсутствует в типе "{ x: number; }" и является обязательным в типе "Point"». К моменту проверки Point — это { x: number; y: number }, и порядок объявлений не важен: первое ничего не знает о втором, но результат один.

Та же попытка с псевдонимом — просто ошибка.

type Point = { x: number };
type Point = { y: number };
const p: Point = { x: 1 };
console.log(p.x);
console.log(p.y);

Три диагностики: два TS2300 «Повторяющийся идентификатор "Point"» — по одной на каждое объявление — и TS2339 на последней строке, «Свойство "y" не существует в типе "Point"». Никакого сложения не произошло: победило первое объявление, второе просто отвергнуто. А выполнение всё равно случится и напечатает undefined — типы до браузера не доезжают.

Слияние — не курьёз, а приём, на котором держится расширение чужих типов. Библиотека объявила интерфейс, вы дописали в него своё поле, и оба объявления живут рядом.

interface Array<T> {
  last(): T | undefined;
}
Array.prototype.last = function () {
  return this[this.length - 1];
};
const items = ["раз", "два", "три"];
console.log(items.last());

Ни одной диагностики: наше объявление слилось с библиотечным, и last появился у всех массивов сразу. С псевдонимом такое невозможно в принципе — type Array<T> = ... даст всё тот же TS2300. Подробный разговор про расширение глобальных типов будет в статье «Расширение чужих типов: window, ImportMeta, слияние объявлений» из главы про границы программы.

Открытость — палка о двух концах: чужой пакет может дописать ваш интерфейс так же легко, как вы дописали Array.

Расширить готовый тип можно обеими записями, и в простом случае результат совпадает.

interface ApiUser {
  id: number;
  name: string;
}
interface Editor extends ApiUser {
  role: "editor";
}
// то же самое пересечением: слева готовый тип, справа добавка
type Guest = ApiUser & { role: "guest" };
const editor: Editor = { id: 1, name: "Рико", role: "editor" };
const guest: Guest = { id: 2, name: "Гость", role: "guest" };
console.log(editor.name, guest.role);

Записи не изолированы друг от друга: интерфейс может наследовать псевдоним объектного типа, а пересечение — включать интерфейс. Так что выбирать приходится не «во что расширять», а «чем записать расширение».

Расхождение появляется, когда новое поле конфликтует со старым. extends проверяет совместимость сразу, на месте объявления.

interface Base {
  id: number;
}
interface Extended extends Base {
  id: string;
}
const row: Extended = { id: "p-1" };
console.log(row.id);

TS2430 на строке с extends: «Интерфейс "Extended" неправильно расширяет интерфейс "Base". Типы свойства "id" несовместимы. Тип "string" не может быть назначен для типа "number"». Сообщение в три уровня ведёт ровно туда, где вы ошиблись, — читать такие сообщения вы научились в статье про диагностику.

Пересечение на то же самое не жалуется. Оно вообще не проверяет совместимость: number & string — законный тип, просто в нём нет ни одного значения.

type Base = { id: number };
type Crossed = Base & { id: string };
const asNumber: Crossed = { id: 1 };
const asString: Crossed = { id: "abc" };
console.log(asNumber.id, asString.id);

Обе попытки получили TS2322: «Тип "number" не может быть назначен для типа "never"» и «Тип "string" не может быть назначен для типа "never"». Поле id в Crossed имеет тип never — это и есть пересечение числа со строкой. Компилятор промолчал там, где ошибка написана, и заговорил там, где типом воспользовались; поэтому такую опечатку ищут дольше.

Пересечение полей — это пересечение множеств значений, а не «второе побеждает». Общих значений у number и string нет ни одного.

type Shape = { kind: "circle" } | { kind: "square" };
interface Sized extends Shape {
  size: number;
}
console.log("объявление не состоялось");

Интерфейс описывает объект. Всё остальное — территория псевдонима: у interface просто нет формы записи ни для объединения, ни для кортежа, ни для имени примитива. Попытка написать interface Status = "новый" | "готов" обрывается на разборе синтаксиса, ещё до проверки типов.

type Status = "новый" | "в работе" | "готов";
type Point = [number, number];
type Handler = (status: Status) => void;
const report: Handler = (status) => console.log("статус: " + status);
const start: Point = [0, 0];
report("готов");
console.log(start[0]);

Ни одной диагностики, и заметьте: параметру status внутри report аннотация не понадобилась. Тип функции задан слева, поэтому компилятор вывел тип параметра сам — тот же контекстный вывод, что был в статье про наведение типов.

Псевдоним умеет ссылаться и сам на себя. Так описывают деревья и вообще любые данные неизвестной глубины.

type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
const config: Json = { name: "учебник", parts: [1, 2, 3], draft: false };
console.log(config);

Дальше по учебнику список того, что доступно только псевдониму, будет расти: keyof, индексный доступ, сопоставленные и условные типы записываются через type и никак иначе. Практическое следствие простое: как только тип становится хоть немного вычисляемым, интерфейс отпадает сам собой.

interface Formatter {
  (value: number): string;
}
const money: Formatter = (value) => value.toFixed(2) + " руб.";
console.log(money(1500));

Расхожее утверждение: интерфейс компилятор показывает по имени, а псевдоним «разворачивает» в структуру, и потому сообщения про псевдонимы длиннее. Сегодня это неправда. Проверим на паре типов-близнецов.

interface UserI {
  name: string;
  age: number;
}
type UserT = {
  name: string;
  age: number;
};
const fromInterface: UserI = { name: "Рико" };
const fromAlias: UserT = { name: "Рико" };
console.log(fromInterface, fromAlias);

Две диагностики TS2741, отличающиеся ровно одной буквой в имени: «...и является обязательным в типе "UserI"» и «...в типе "UserT"». Никакого разворачивания.

Настоящая разница видна на цепочке расширений. extends собирает один плоский тип с именем, пересечение остаётся списком слагаемых — и в сообщении всплывает слагаемое, а не имя, которое вы написали.

interface Base { id: number }
interface WithName extends Base { name: string }
interface Full extends WithName { tags: string[] }
type BaseT = { id: number };
type WithNameT = BaseT & { name: string };
type FullT = WithNameT & { tags: string[] };
const viaExtends: Full = { id: 1, name: "Рико" };
const viaIntersection: FullT = { id: 1, name: "Рико" };
console.log(viaExtends, viaIntersection);

Первая диагностика короткая — TS2741, «Свойство "tags" отсутствует в типе "{ id: number; name: string; }" и является обязательным в типе "Full"». Вторая — TS2322 с вложенной причиной, и виноватым названо безымянное слагаемое { tags: string[]; }, а не FullT. Ошибка одна и та же, но искать по второму сообщению дольше: имени, по которому можно грепнуть, в нём нет.

Чем длиннее цепочка пересечений, тем дальше сообщение уходит от имени типа. На двух слагаемых это мелочь, на семи — уже нет.

Всё, что мы проверили, помещается в одну таблицу. Ни одна строка в ней не про «стиль» — каждая проверяется запуском.

Правило, которое переживает споры в команде: форму объекта, которую кто-то будет расширять или которую вы отдаёте наружу как часть публичного интерфейса модуля, пишите через interface; всё остальное — через type. И главное: не переписывайте чужой файл ради единообразия. Разница проявляется в шести строках таблицы, а не «вообще везде».