Литеральные типы и as const в TypeScript: примеры

Литеральный тип это тип ровно с одним значением: "up" это тип, единственный элемент которого строка "up", а 404 это тип, единственный элемент которого число 404. Сами по себе они не очень полезны. Объединённые в union, они дают переменную, которая принимает фиксированный набор значений и ничего больше.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

Без комментария @ts-expect-error последний вызов был бы ошибкой компиляции (TS2345). С ним программа компилируется, а вызов всё равно выполняется и печатает moving north by 1: литеральные типы существуют только для компилятора, а во время выполнения значение это обычная строка.

Строковые, числовые и логические литералы

Любое строковое, числовое, bigint или логическое значение можно записать как тип. Тогда компилятор принимает только это конкретное значение.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

Сам boolean это просто объединение true | false, поэтому после сужения boolean через if (flag) в ветке else остаётся false.

Объединения литералов

Обычно используют объединение, которое перечисляет все допустимые значения. Внутри функции компилятор сужает объединение по мере проверок, поэтому каждая ветка точно знает, какое у неё значение.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

Объединение строковых литералов это обычная в TypeScript альтернатива enum. Оно ничего не стоит во время выполнения, значения это обычные строки, которые можно выводить в лог и передавать в JSON, а опечатка становится ошибкой компиляции. Подробнее о компромиссах в разделе enum.

Расширение типа: let и const

Когда TypeScript выводит тип из литерала, он смотрит, может ли значение измениться. Переменную const нельзя переприсвоить, поэтому она сохраняет литеральный тип. Переменную let можно, поэтому её тип расширяется до общего.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

Наведите курсор на каждое имя в редакторе, чтобы увидеть выведенный тип. Если нужна переменная let, которая хранит только определённые значения, аннотируйте её: let mode: "light" | "dark" = "light".

Почему свойства объекта расширяются

Свойства объектного литерала изменяемые, поэтому они тоже расширяются, даже если объект хранится в const. Чаще всего именно так на литеральные типы натыкаются случайно:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

Компилятор сообщает:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req выводится как { url: string; method: string }, потому что код ниже мог бы выполнить req.method = "DELETE". Есть три способа исправить:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

Четвёртый вариант это satisfies, который проверяет объект на соответствие типу, сохраняя литеральные типы его свойств.

as const

as const это утверждение const. Поставьте его после выражения, и компилятор выведет самый узкий возможный тип:

• строковые, числовые и логические значения сохраняют литеральные типы
• свойства объектов становятся readonly
• литералы массивов становятся кортежами readonly фиксированной длины

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

Утверждение действует только при компиляции. Сгенерированный JavaScript это тот же объектный литерал без as const, так что ничто не мешает другому коду изменить его во время выполнения. Если нужна гарантия во время выполнения, вызовите ещё и Object.freeze.

Тип объединения из массива с as const

Частый приём: хранить допустимые значения в одном массиве, по которому можно пройти циклом во время выполнения, и выводить из него тип объединения. (typeof arr)[number] означает «тип любого элемента arr».

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

Без as const ROLES имел бы тип string[], а Role был бы просто string. Приведение к readonly string[] в isRole нужно потому, что includes у кортежа литералов принимает только эти литералы, а смысл функции в том, чтобы проверить строку, которая может им не быть. Тот же приём с объектом работает для отображений ключ/значение: const Status = { Active: "active", Banned: "banned" } as const, затем type Status = (typeof Status)[keyof typeof Status].

Параметры типа const

Обобщённая функция обычно расширяет переданные ей литералы. Начиная с TypeScript 5.0 параметр типа можно пометить как const, и тогда компилятор выводит аргумент так, будто к нему применено as const, не требуя от вызывающего кода писать это.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

В основном это инструмент для авторов библиотек: определения маршрутов, билдеры и вспомогательные функции для схем используют его, чтобы вызывающий код получал точные типы из обычных литералов.

Значения const

Ключевое слово const встречается в коде на TypeScript в четырёх разных местах:

Ни один из них не замораживает объект во время выполнения. const obj = { a: 1 } по-прежнему допускает obj.a = 2; ошибкой будет только переприсваивание самого obj.