Литеральные типы: когда «круг» — это тип

Аннотация : string разрешает любую строку — их бесконечно много. Литеральный тип сужает этот набор до одного элемента: до того самого значения, которое вы написали. Синтаксис прежний, необычно только место.

// в позиции типа стоит не string, а конкретная строка
let shape: "circle" = "circle";
shape = "square";
console.log(shape);

Компилятор возражает на присваивании: Тип ""square"" не может быть назначен для типа ""circle"". А в консоли всё равно square — знакомое по первой главе правило: диагностика не отменяет выполнение. До браузера доезжает обычный JavaScript, в котором никаких типов нет, и он честно делает то, что написано.

Кавычек в сообщении две пары не случайно: компилятор оборачивает имя типа в кавычки, а у строкового литерала кавычки уже свои. У числового литерала пара остаётся одна — «Тип "7"».

Переменная, которой можно присвоить ровно одно значение, сама по себе бесполезна. Но литеральные типы почти никогда не пишут руками поодиночке: чаще они появляются сами, при выводе типа — и вот тут начинается разница между let и const.

Само расширение вы уже видели в статье про вывод типов; здесь смотрим на него с другой стороны — что именно расширяется и во что. В следующем примере нет ни одной аннотации у переменных, типы компилятор выводит сам. Из одного и того же значения он выводит два разных типа.

const kind = "circle";
let shape = "circle";

function draw(figure: "circle") {
  console.log("рисую " + figure);
}

draw(kind);
draw(shape);

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

С let так нельзя. Объявляя let, вы как раз и говорите, что содержимое ячейки будет меняться; выведи компилятор тип "circle", любое присваивание в неё стало бы ошибкой. Поэтому при выводе типа для изменяемой ячейки он поднимается от литерала к его базовому типу — это и называется расширением: строка становится string, число — number, true — boolean.

const kind = "circle";
let shape = "circle";

// намеренно невозможные присваивания: нас интересует не результат,
// а левая часть сообщения об ошибке
const probe1: null = kind;
const probe2: null = shape;
console.log(probe1, probe2);

Расширение срабатывает в момент вывода, а не один раз при объявлении константы: стоит скопировать значение в let, и узкий тип потеряется. И наоборот — явная аннотация всегда сильнее вывода, в обе стороны.

const kind = "circle";
let copy = kind;
const mode: string = "circle";
let exact: "circle" = "circle";

function draw(figure: "circle") {
  console.log("рисую " + figure);
}

draw(exact);
draw(copy);
draw(mode);

Смысл появляется, когда значений несколько. Вертикальная черта перечисляет варианты, а type даёт получившемуся набору имя (про псевдонимы типов и их отличие от интерфейсов — в следующей главе).

type Level = "debug" | "info" | "error";

function log(level: Level, text: string) {
  console.log("[" + level + "] " + text);
}

let current: Level = "debug";
current = "error";
current = "fatal";

log("info", "страница загрузилась");
log("warning", "что-то пошло не так");

Две ошибки — на "fatal" и на "warning": Аргумент типа ""warning"" нельзя назначить параметру типа "Level". Сравните с level: string: там оба вызова прошли бы молча, а неизвестный уровень всплыл бы в проде пустым бейджем или сломанным фильтром логов.

Выигрыш не только в проверке. Редактор подсказывает все допустимые значения по Ctrl+Space — набор перечислен прямо в типе. А если завтра уровней станет четыре, достаточно дописать вариант в одну строку, и компилятор сам покажет места, где новый случай не разобран.

Только не примите тип за проверку. Компилятор рассуждает о коде, который видит; данные из формы, из сети или из localStorage он не видел никогда. Литеральный тип — обещание автора, а не контроль на входе.

type Shape = "circle" | "square";

// представьте, что строка пришла из формы
const fromForm = "трапеция";
const shape = fromForm as Shape;

const area = { circle: 3.14, square: 1 };
console.log(area[shape]);

Литеральный тип есть у любого примитива, а не только у строки. Числовые наборы читаются так же естественно.

type Dice = 1 | 2 | 3 | 4 | 5 | 6;

let roll: Dice = 3;
roll = 7;
console.log(roll);

Сообщение то же самое, только кавычек меньше: Тип "7" не может быть назначен для типа "Dice". И снова обратите внимание на консоль — семёрка спокойно доехала до выполнения.

А вот место, где интуиция подводит чаще всего: арифметика литеральные типы не сохраняет. Компилятор не считает значения — он складывает типы, и number + number даёт number.

type Dice = 1 | 2 | 3 | 4 | 5 | 6;

const roll: Dice = 6;
const next: Dice = roll + 1;
console.log(next);

Ошибка на четвёртой строке: Тип "number" не может быть назначен для типа "Dice". Формально компилятор прав дважды — не только потому, что не умеет вычислять, но и потому, что 6 + 1 действительно не входит в набор.

Булевых литеральных типов ровно два — true и false, а boolean и есть их объединение. Наборы можно смешивать: number | "auto" описывает величину, у которой кроме чисел есть одно особое слово.

function compare(a: number, b: number): -1 | 0 | 1 {
  return a < b ? -1 : a > b ? 1 : 0;
}

type Width = number | "auto";

function setWidth(width: Width) {
  console.log("ширина: " + width);
}

console.log(compare(2, 5));
setWidth(320);
setWidth("auto");
setWidth("100%");

Возвращаемый тип -1 | 0 | 1 у компаратора — не педантизм: он документирует договор сортировки лучше, чем number, и не даёт вернуть из функции разность.

Самая частая встреча с расширением выглядит так: значение объявлено через const, а компилятор всё равно говорит про string.

type Shape = "circle" | "square";

const config = { shape: "circle", size: 10 };
config.shape = "трапеция";

function draw(shape: Shape) {
  console.log("рисую " + shape);
}

draw(config.shape);

const держит саму переменную, а не то, что внутри объекта, — это правило из части I никуда не делось. Раз поле shape изменяемо, компилятор рассуждает о нём так же, как о let: выводит string. Отсюда и Аргумент типа "string" нельзя назначить параметру типа "Shape" на последней строке, и молча прошедшая «трапеция» на четвёртой.

Первое лекарство уже знакомо — аннотация. Она отменяет расширение и заодно ловит присваивание в поле.

type Shape = "circle" | "square";

const config: { shape: Shape; size: number } = { shape: "circle", size: 10 };

function draw(shape: Shape) {
  console.log("рисую " + shape);
}

draw(config.shape);

Второе — сказать компилятору, что объект целиком неизменяемый. Суффикс as const делает все поля доступными только для чтения, а значит, расширять их незачем: типы остаются литеральными (подробно про as const — в статье «readonly и as const: неизменяемость в типах» из главы про объекты).

type Shape = "circle" | "square";

const config = { shape: "circle", size: 10 } as const;
config.shape = "square";

function draw(shape: Shape) {
  console.log("рисую " + shape);
}

draw(config.shape);

Диагностика теперь совсем другая: Не удается задать значение для "shape", так как это свойство, доступное только для чтения. Вызов draw компилятор пропустил без замечаний — тип поля стал "circle".

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