Template literal types en TypeScript: sintaxis y ejemplos

Un template literal type construye tipos literales de string con la misma sintaxis de comillas invertidas que un template string de JavaScript. `on${Capitalize<"click" | "focus">}` es el tipo "onClick" | "onFocus", calculado por el 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;

Los template literal types solo existen en compilación. Comprueban literales de string y valores tipados mientras escribes código; no añaden nada al JavaScript de salida. La tabla de handlers de arriba usa Record para exigir una función por nombre.

Sintaxis

Dentro de las comillas invertidas escribes texto literal y marcadores ${...}. Un marcador contiene un tipo, no un valor: un tipo literal string, number, bigint o boolean, una unión de ellos, o uno de los tipos amplios string, number, bigint, boolean, null y 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

Un marcador con un tipo amplio como string o number crea un patrón: el tipo se queda como `hello ${string}` y acepta cualquier string que encaje. Un marcador con una unión finita, como boolean, se expande en sus miembros.

Las uniones se multiplican

Con varias uniones, el resultado son todas las combinaciones:

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

Tres tamaños por dos tonos dan seis miembros. La cuenta crece rápido: cinco marcadores con una unión de diez letras cada uno serían 100.000 miembros, y TypeScript se niega con error TS2590: Expression produces a union type that is too complex to represent. Usa un marcador amplio como ${string} cuando no necesites todos los valores exactos.

Uppercase, Lowercase, Capitalize, Uncapitalize

Cuatro tipos integrados cambian las mayúsculas y minúsculas de los tipos literales de string. Son intrínsecos: están implementados dentro del compilador, no escritos en TypeScript.

Solo cambian tipos. Para construir el string equivalente en ejecución, sigues llamando a toUpperCase() o cortando y poniendo la mayúscula tú mismo, y le dices a TypeScript que el resultado tiene el tipo preciso:

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

El as hace falta porque toUpperCase() está tipado para devolver un string normal. La firma de la función es lo que ve quien la llama, así que capitalize("report") tiene el tipo literal "Report".

Patrones de string: ${number}px y compañía

Un tipo patrón acepta cualquier string con una forma dada. Es práctico para valores CSS, ids y claves con un prefijo conocido:

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} acepta cualquier string que JavaScript lea como número, lo cual es más permisivo de lo que parece: "-3px", "1e3px" y "0x10px" pasan la comprobación. Usa estos patrones como protección frente a erratas en literales, no como validación completa.

Template literals con mapped types

Los template literal types son más útiles como cláusula as de un mapped type, donde generan nombres de propiedades a partir de otros nombres de propiedades:

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 conserva solo las claves string, porque Capitalize no acepta números ni símbolos. Cada callback recibe el tipo de su parámetro de la propiedad que vigila.

Analizar strings con infer

En un conditional type, un template literal puede encajar con un string y capturar partes de él con infer. Esto extrae los nombres de los parámetros de un patrón de ruta:

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

Si omites postId en la llamada, el compilador avisa de que falta.

Las expresiones de plantilla se amplían a string

Una expresión de template string en código normal tiene tipo string, aunque todas sus partes sean tipos literales. Añade as const para conservar el 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

Sin as const, asignar loose a `log:${Level}` falla, porque string podría ser cualquier cosa.