Template literal types em TypeScript: sintaxe e exemplos

Um template literal type monta string literal types com a mesma sintaxe de crases de uma template string do JavaScript. `on${Capitalize<"click" | "focus">}` é o tipo "onClick" | "onFocus", calculado pelo compilador:

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 existem só em tempo de compilação. Eles verificam string literals e valores tipados enquanto você escreve o código; não acrescentam nada ao JavaScript gerado. A tabela de handlers acima usa Record para exigir uma função por nome.

Sintaxe

Dentro das crases você escreve texto literal e placeholders ${...}. Um placeholder guarda um tipo, não um valor: um literal type de string, number, bigint ou boolean, uma union deles, ou um dos tipos amplos string, number, bigint, boolean, null e 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

Um placeholder com um tipo amplo como string ou number cria um padrão: o tipo continua sendo `hello ${string}` e qualquer string compatível é aceita. Um placeholder com uma union finita, como boolean, é expandido nos membros dela.

Unions se multiplicam

Com várias unions, o resultado é todas as combinações:

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

Três tamanhos vezes dois tons dá seis membros. A contagem cresce rápido: cinco placeholders, cada um com uma union de dez letras, dariam 100.000 membros, e o TypeScript recusa com error TS2590: Expression produces a union type that is too complex to represent. Use um placeholder amplo como ${string} quando você não precisar de cada valor exato.

Uppercase, Lowercase, Capitalize, Uncapitalize

Quatro tipos embutidos mudam a caixa de string literal types. Eles são intrínsecos: implementados dentro do compilador, não escritos em TypeScript.

Eles só mudam tipos. Para montar a string correspondente em tempo de execução, você ainda chama toUpperCase() ou corta e capitaliza por conta própria, e diz ao TypeScript que o resultado tem o tipo exato:

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

O as é necessário porque toUpperCase() é tipado para retornar string simples. A assinatura da função é o que quem chama enxerga, então capitalize("report") tem o literal type "Report".

Padrões de string: ${number}px e companhia

Um tipo padrão aceita toda string de um certo formato. Ele é útil para valores CSS, ids e chaves com um prefixo conhecido:

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} aceita qualquer string que o JavaScript leia como número, o que é mais permissivo do que parece: "-3px", "1e3px" e "0x10px" passam na verificação de tipos. Trate esses padrões como proteção contra erros de digitação em literais, não como validação completa.

Template literals com mapped types

Template literal types são mais úteis como a cláusula as de um mapped type, onde geram nomes de propriedades a partir de outros nomes de propriedades:

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 mantém só as chaves string, já que Capitalize não aceita números nem symbols. Cada callback recebe o tipo do parâmetro a partir da propriedade que observa.

Analisando strings com infer

Em um conditional type, um template literal pode casar com uma string e capturar partes dela com infer. Isto extrai os nomes dos parâmetros de um padrão de rota:

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

Deixe postId de fora na chamada e o compilador aponta que ele está faltando.

Expressões de template são ampliadas para string

Uma expressão de template string no código comum tem tipo string, mesmo quando todas as partes são literal types. Adicione as const para manter o 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

Sem as const, atribuir loose a `log:${Level}` falha, porque string pode ser qualquer coisa.