Шаблонные литеральные типы в TypeScript: синтаксис и примеры

Шаблонный литеральный тип строит строковые литеральные типы с тем же синтаксисом обратных кавычек, что и шаблонная строка JavaScript. `on${Capitalize<"click" | "focus">}` это тип "onClick" | "onFocus", вычисленный компилятором:

type DomEvent = "click" | "focus" | "blur";

type HandlerName = `on${Capitalize<DomEvent>}`;
// "onClick" | "onFocus" | "onBlur"

const handlers: Record<HandlerName, () => string> = {
  onClick: () => "clicked",
  onFocus: () => "focused",
  onBlur: () => "blurred",
};

console.log(handlers.onFocus()); // focused
// @ts-expect-error: "onHover" is not one of the handler names
handlers.onHover;

Шаблонные литеральные типы существуют только при компиляции. Они проверяют строковые литералы и типизированные значения, пока вы пишете код, и ничего не добавляют в вывод JavaScript. Таблица обработчиков выше использует Record, чтобы требовать по функции на каждое имя.

Синтаксис

Внутри обратных кавычек пишется литеральный текст и заполнители ${...}. Заполнитель содержит тип, а не значение: строковый, числовой, bigint или логический литеральный тип, их объединение или один из широких типов string, number, bigint, boolean, null и undefined.

type Greeting = `hello ${string}`;   // any string that starts with "hello "
type Version = `v${number}`;         // "v1", "v2.5", ...
type Toggle = `is-${boolean}`;       // "is-true" | "is-false"

const g: Greeting = "hello Ada";
const v: Version = "v3";
const t: Toggle = "is-false";

// @ts-expect-error: Type '"hi Ada"' is not assignable to type '`hello ${string}`'
const wrong: Greeting = "hi Ada";

console.log(g, v, t); // hello Ada v3 is-false

Заполнитель с широким типом вроде string или number создаёт шаблон: тип остаётся `hello ${string}`, и принимается любая подходящая строка. Заполнитель с конечным объединением, например boolean, раскрывается в его члены.

Объединения перемножаются

С несколькими объединениями результатом будут все комбинации:

type Size = "sm" | "md" | "lg";
type Tone = "primary" | "danger";

type ButtonClass = `btn-${Size}-${Tone}`;
// "btn-sm-primary" | "btn-sm-danger" | "btn-md-primary" | ... (6 members)

function button(cls: ButtonClass): string {
  return `<button class="${cls}">`;
}

console.log(button("btn-lg-danger")); // <button class="btn-lg-danger">
// button("btn-xl-danger") would be error TS2345

Три размера на два тона дают шесть членов. Число растёт быстро: пять заполнителей, каждый с объединением из десяти букв, дали бы 100 000 членов, и TypeScript отказывается с ошибкой error TS2590: Expression produces a union type that is too complex to represent. Используйте широкий заполнитель вроде ${string}, когда не нужны все точные значения.

Uppercase, Lowercase, Capitalize, Uncapitalize

Четыре встроенных типа меняют регистр строковых литеральных типов. Они встроенные (intrinsic): реализованы внутри компилятора, а не написаны на TypeScript.

Они меняют только типы. Чтобы построить соответствующую строку во время выполнения, по-прежнему вызывайте toUpperCase() или сами делите строку и меняйте регистр, а затем сообщите TypeScript, что у результата точный тип:

function capitalize<S extends string>(s: S): Capitalize<S> {
  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
}

const title = capitalize("report"); // type "Report"
const loud: Uppercase<"ok"> = "OK";

console.log(title, loud); // Report OK

as нужен потому, что toUpperCase() типизирован как возвращающий обычный string. Вызывающий код видит сигнатуру функции, поэтому capitalize("report") имеет литеральный тип "Report".

Шаблоны строк: ${number}px и другие

Тип-шаблон принимает любую строку заданной формы. Это удобно для значений CSS, идентификаторов и ключей с известным префиксом:

type Pixels = `${number}px`;
type UserId = `user_${string}`;
type Semver = `${number}.${number}.${number}`;

function setWidth(w: Pixels) {
  return `width: ${w}`;
}

const id: UserId = "user_42";
const version: Semver = "7.0.2";

console.log(setWidth("120px"), id, version); // width: 120px user_42 7.0.2
// setWidth("120") and setWidth("wide px") would both be error TS2345

${number} принимает любую строку, которую JavaScript читает как число, а это мягче, чем кажется: "-3px", "1e3px" и "0x10px" проходят проверку типов. Считайте такие шаблоны защитой от опечаток в литералах, а не полноценной валидацией.

Шаблонные литералы в сопоставленных типах

Больше всего пользы от шаблонных литеральных типов в конструкции as сопоставленного типа, где они порождают имена свойств из других имён свойств:

type Watchers<T> = {
  [K in keyof T as `on${Capitalize<string & K>}Change`]: (value: T[K]) => void;
};

type Form = { email: string; age: number };

// { onEmailChange: (value: string) => void; onAgeChange: (value: number) => void }
const watch: Watchers<Form> = {
  onEmailChange: (v) => console.log("email is now", v),
  onAgeChange: (v) => console.log("age is now", v.toFixed(0)), // v is number
};

watch.onEmailChange("ada@example.com"); // email is now ada@example.com
watch.onAgeChange(37);                  // age is now 37

string & K оставляет только строковые ключи, поскольку Capitalize не принимает числа и символы. Каждый колбэк получает тип параметра из свойства, за которым он следит.

Разбор строк через infer

В условном типе шаблонный литерал может сопоставить строку и захватить её части через infer. Так извлекаются имена параметров из шаблона маршрута:

type RouteParams<S extends string> =
  S extends `${string}:${infer Param}/${infer Rest}`
    ? Param | RouteParams<`/${Rest}`>
    : S extends `${string}:${infer Param}`
      ? Param
      : never;

type P = RouteParams<"/users/:userId/posts/:postId">; // "userId" | "postId"

function link<S extends string>(pattern: S, params: Record<RouteParams<S>, string>): string {
  return pattern.replace(/:(\w+)/g, (_, key: string) => params[key as RouteParams<S>]);
}

console.log(link("/users/:userId/posts/:postId", { userId: "7", postId: "42" }));
// /users/7/posts/42

Если пропустить postId в вызове, компилятор сообщит, что его не хватает.

Шаблонные выражения расширяются до string

Выражение с шаблонной строкой в обычном коде имеет тип string, даже если все его части это литеральные типы. Добавьте as const, чтобы сохранить шаблонный литеральный тип:

type Level = "info" | "warn";

function tag(level: Level) {
  const loose = `log:${level}`;          // string
  const exact = `log:${level}` as const; // "log:info" | "log:warn"
  return { loose, exact };
}

const { exact } = tag("warn");
const again: `log:${Level}` = exact; // OK: the exact type fits
console.log(exact, again);           // log:warn log:warn

Без as const присваивание loose в `log:${Level}` не проходит, потому что string может быть чем угодно.