readonly и as const: неизменяемость в типах

Слово readonly ставится перед именем поля — в interface, в type, в литеральном типе объекта. Оно означает ровно одно: снаружи это поле разрешено читать, но не присваивать. Значение задаётся один раз, при создании объекта.

interface User {
  readonly id: number;
  name: string;
}

const user: User = { id: 1, name: "Рико" };
user.name = "Женя"; // обычное поле — пишем и не думаем

user.id = 2;
console.log(user.id);

Компилятор сказал Не удается задать значение для "id", так как это свойство, доступное только для чтения — это TS2540. А потом в консоли появилась двойка: присваивание всё равно случилось. Та же история, что с readonly-массивом из главы про базовые типы — типы стираются при сборке, и до запуска доезжает обычный объект со всеми полями нараспашку.

Сравните с const, который выглядит похоже, но занимается совсем другим делом. const закрепляет связь имени со значением, а не содержимое объекта — и это правило самого JavaScript, а не выдумка TypeScript.

const config = { retries: 3 };
config.retries = 5;
console.log(config.retries);

config = { retries: 0 };

Отказов снова два, но они разной природы. TS2588 компилятор произносит до запуска, а следом браузер бросает настоящий TypeError — на этой строке пример обрывается. Точный текст у ошибки свой у каждого движка: выше напечатан тот, что даёт Chrome. const дожил до выполнения, readonly — нет.

readonly — про поле, const — про имя. Первое проверяет компилятор, второе — движок, и до запуска доживает только второе.

readonly закрывает само поле, а не значение, которое в нём лежит. Если внутри объект, его содержимое остаётся полностью открытым: ссылку менять нельзя, а вот всё, до чего по ней можно добраться, — пожалуйста.

interface Settings {
  readonly theme: string;
  readonly limits: { max: number };
}

const settings: Settings = { theme: "dark", limits: { max: 10 } };
settings.limits.max = 99;
console.log(settings.limits.max);

Ни одной диагностики: с точки зрения типов мы не трогали поле limits, мы им воспользовались. Чтобы закрыть и внутренность, readonly пришлось бы писать на каждом уровне вручную — или взять as const, который делает это сам.

Вторая дыра неприятнее и обнаруживается обычно на чужом коде. Помните структурную типизацию из этой главы: совместимость типов считается по набору полей и их типам. Модификатор readonly в этот подсчёт не входит вовсе.

interface Frozen {
  readonly count: number;
}
interface Counter {
  count: number;
}

const frozen: Frozen = { count: 1 };
const alias: Counter = frozen;
alias.count = 42;
console.log(frozen.count);

Объект один, имён у него два, и через второе имя поле спокойно переписывается. Это не баг и не недосмотр: если бы readonly учитывался в совместимости, ни один объект с неизменяемым полем нельзя было бы передать в тысячи существующих функций, объявленных без него. С массивами компилятор рассуждает иначе — readonly number[] в number[] он не пустит и скажет TS4104, — но для свойств объектов сделано именно такое послабление.

readonly — обещание, которое ваш код даёт компилятору, а не замок на объекте. Оно ловит опечатку и невнимательность, но не защищает от чужого кода.

Из главы про базовые типы вы помните: const kind = "circle" получает литеральный тип "circle", а let расширяет его до string. Внутри объекта работает правило от let: поле объекта можно переприсвоить, значит его тип расширяется — даже если сам объект объявлен через const.

type Theme = "light" | "dark";

function apply(theme: Theme): void {
  console.log("тема: " + theme);
}

const draft = { theme: "dark" };
apply(draft.theme);

const fixed = { theme: "dark" } as const;
apply(fixed.theme);

Значение подходит, а тип — нет: Аргумент типа "string" нельзя назначить параметру типа "Theme". Это одна из самых частых встреч новичка с as const: конфиг собран отдельной переменной, значение написано верно, а компилятор упирается. Обе строки, кстати, напечатали одно и то же — ошибка типов выполнение не отменяет.

Посмотреть, что именно поменялось, удобно приёмом из статьи про наведение типов: присвоить значение в null и прочитать отказ.

const draft = { theme: "dark", retries: 3 };
const fixed = { theme: "dark", retries: 3 } as const;

// заведомо невозможные присваивания: нам нужен текст отказа, а не результат
const probe1: null = draft;
const probe2: null = fixed;
console.log(probe1, probe2);

Компилятор назвал оба типа: { theme: string; retries: number; } и { readonly theme: "dark"; readonly retries: 3; }. То есть as const делает две вещи разом — каждому полю добавляет readonly и каждому значению оставляет литеральный тип вместо расширенного.

И, в отличие от ручного readonly, утверждение идёт вглубь: вложенные объекты и массивы тоже становятся неизменяемыми.

const point = { x: 0, y: 0 } as const;
point.x = 5;

const box = { size: { w: 10 } } as const;
box.size.w = 20;

console.log(point.x, box.size.w);

Два TS2540 — и обе записи всё равно прошли. К этому пора привыкнуть: as const строже, но по-прежнему исчезает при сборке.

function readTheme(): string {
  return "dark";
}

const value = readTheme() as const;
console.log(value);

type Theme = "light" | "dark";

const draft = { theme: "dark" as const, count: 0 };
const theme: Theme = draft.theme;
draft.count = 1;
console.log(theme, draft.count);

Набор допустимых значений обычно нужен дважды: как тип для сигнатур и как массив или объект для запуска — отрисовать список, проверить пришедшее с сервера. Написанные порознь, они рано или поздно расходятся, и компилятор об этом не узнает. Поэтому пишут один раз — значение, — а тип выводят из него.

const STATUSES = ["новая", "в работе", "готова"] as const;

type Status = (typeof STATUSES)[number];

function move(status: Status): void {
  console.log("статус: " + status);
}

move(STATUSES[2]);
move("отменена");

Читается это справа налево. typeof STATUSES — тип значения STATUSES, то есть readonly ["новая", "в работе", "готова"]. Индекс [number] спрашивает «а что лежит по любому числовому индексу» — и получается объединение всех трёх литералов. В отказе компилятор перечисляет его целиком: нельзя назначить параметру типа "новая" | "в работе" | "готова".

Без as const фокус не работает: тип массива был бы string[], а string[][number] — это просто string. Литеральные типы здесь не украшение, а всё содержание приёма.

С объектом делают то же самое, только ключи и значения дают два разных набора. Ключи достаёт keyof.

const LABELS = {
  new: "новая",
  done: "готова",
} as const;

type StatusKey = keyof typeof LABELS;

function label(key: StatusKey): string {
  return LABELS[key];
}

console.log(label("done"));
console.log(label("cancelled"));

Добавили в LABELS новый ключ — тип StatusKey расширился сам, и все места, где перечислялись варианты, компилятор проверит заново. Убрали ключ — сломаются ровно те строки, где он использовался. Ради этого приём и живёт.

Подробный разбор keyof и typeof ждёт в статье «keyof и typeof: тип из значения и его ключи» из главы про типы, вычисляемые из значений. Пока достаточно относиться к этим трём строчкам как к готовым рецептам: они закрывают большую часть повседневных случаев.

const STATUSES = ["новая", "готова"] as const;

const input: string = "готова";
console.log(STATUSES.includes(input));

const wide: readonly string[] = STATUSES;
console.log(wide.includes(input));

as const строже обычного readonly, но природа у него та же — это по-прежнему обещание в типах. Дыра из второго раздела никуда не делась.

const preset = { width: 100, height: 50 } as const;

const copy: { width: number; height: number } = preset;
copy.width = 1;

console.log(preset.width);

Ни одной диагностики, а «константа» поменялась. Если объект действительно должен быть неизменяемым во время выполнения — например, уезжает в чужой код или живёт в общем состоянии, — нужен Object.freeze. Он и типы уточняет, и запись запрещает по-настоящему.

const config = Object.freeze({ retries: 3, nested: { deep: 1 } });

config.nested.deep = 42;
console.log(config.nested.deep);

config.retries = 10;
console.log("до этой строки дело не дойдёт");

Знакомый TS2540 — и следом то, чего за всю статью не добились ни readonly, ни as const: TypeError: Cannot assign to read only property, и пример обрывается. Так выглядит настоящий запрет. Заодно видно, что Object.freeze поверхностный в обе стороны: и в типах, и при запуске вложенный объект остался изменяемым.

TypeError бросается в строгом режиме — а он включён везде, где вы пишете современный код: в модулях и в собранном tsc выводе. В нестрогом коде запись просто молча не сработает.

На практике выбор простой. as const — для наборов-констант, откуда выводятся типы: это девять случаев из десяти. readonly — в сигнатурах функций и полях моделей, чтобы намерение «я это не порчу» проверялось, а не жило в комментарии. Object.freeze — там, где цена случайной мутации выше цены лишней проверки в рантайме.