Template literal types w TypeScript: składnia i przykłady

Template literal type buduje typy literałów string tą samą składnią z backtickami co template string w JavaScripcie. `on${Capitalize<"click" | "focus">}` to typ "onClick" | "onFocus", obliczany przez kompilator:

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;

Template literal types istnieją tylko w czasie kompilacji. Sprawdzają literały string i otypowane wartości, gdy piszesz kod, i nic nie dodają do wyjściowego JavaScriptu. Powyższa tabela handlerów używa Record, żeby wymagać jednej funkcji dla każdej nazwy.

Składnia

W backtickach piszesz dosłowny tekst i placeholdery ${...}. Placeholder zawiera typ, nie wartość: typ literału string, number, bigint albo boolean, ich unię albo jeden z szerokich typów string, number, bigint, boolean, null i 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

Placeholder z szerokim typem, takim jak string albo number, tworzy wzorzec: typ zostaje jako `hello ${string}` i przyjmowany jest każdy pasujący string. Placeholder ze skończoną unią, taką jak boolean, jest rozwijany na jej elementy.

Unie się mnożą

Przy kilku uniach wynikiem jest każda kombinacja:

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

Trzy rozmiary razy dwa odcienie dają sześć elementów. Liczba szybko rośnie: pięć placeholderów, z których każdy zawiera unię dziesięciu liter, dałoby 100 000 elementów, a TypeScript odmawia z komunikatem error TS2590: Expression produces a union type that is too complex to represent. Użyj szerokiego placeholdera, takiego jak ${string}, gdy nie potrzebujesz każdej dokładnej wartości.

Uppercase, Lowercase, Capitalize, Uncapitalize

Cztery wbudowane typy zmieniają wielkość liter w typach literałów string. Są intrinsic: zaimplementowane w kompilatorze, a nie napisane w TypeScript.

Zmieniają tylko typy. Żeby zbudować odpowiadający im string w czasie wykonania, nadal wywołujesz toUpperCase() albo sam wycinasz i zamieniasz pierwszą literę, a potem mówisz TypeScriptowi, że wynik ma dokładny typ:

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 jest potrzebne, bo toUpperCase() ma w typach zwracać zwykły string. Wywołujący widzą sygnaturę funkcji, więc capitalize("report") ma typ literału "Report".

Wzorce stringów: ${number}px i podobne

Typ wzorca przyjmuje każdy string o danym kształcie. Przydaje się przy wartościach CSS, identyfikatorach i kluczach ze znanym prefiksem:

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} przyjmuje każdy string, który JavaScript odczytuje jako liczbę, a to więcej, niż się wydaje: "-3px", "1e3px" i "0x10px" przechodzą sprawdzanie typów. Traktuj te wzorce jako ochronę przed literówkami w literałach, a nie jako pełną walidację.

Template literals z mapped types

Template literal types są najbardziej przydatne w klauzuli as mapped type, gdzie generują nazwy właściwości z innych nazw właściwości:

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 zostawia tylko klucze typu string, bo Capitalize nie przyjmuje liczb ani symboli. Każdy callback dostaje typ parametru z właściwości, którą obserwuje.

Parsowanie stringów z infer

W typie warunkowym template literal może dopasować string i przechwycić jego części przez infer. Tak wyciąga się nazwy parametrów ze wzorca ścieżki:

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

Pomiń postId w wywołaniu, a kompilator zgłosi, że go brakuje.

Wyrażenia szablonowe poszerzają się do string

Wyrażenie template string w zwykłym kodzie ma typ string, nawet gdy każda jego część jest typem literału. Dodaj as const, żeby zachować template literal type:

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

Bez as const przypisanie loose do `log:${Level}` się nie udaje, bo string może być czymkolwiek.