Template literal types in TypeScript: sintassi ed esempi

Un template literal type costruisce tipi letterali stringa con la stessa sintassi a backtick di una template string JavaScript. `on${Capitalize<"click" | "focus">}` è il tipo "onClick" | "onFocus", calcolato dal compilatore:

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;

I template literal types esistono solo in compilazione. Controllano i letterali stringa e i valori tipizzati mentre scrivi il codice; non aggiungono nulla all'output JavaScript. La tabella di handler qui sopra usa Record per richiedere una funzione per ogni nome.

Sintassi

Dentro i backtick scrivi testo letterale e segnaposto ${...}. Un segnaposto contiene un tipo, non un valore: un tipo letterale stringa, numero, bigint o boolean, una loro union, oppure uno dei tipi ampi 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

Un segnaposto con un tipo ampio come string o number crea un pattern: il tipo resta `hello ${string}` e qualsiasi stringa corrispondente viene accettata. Un segnaposto con una union finita, come boolean, viene espanso nei suoi membri.

Le union si moltiplicano

Con più union, il risultato è ogni combinazione:

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

Tre dimensioni per due toni danno sei membri. Il numero cresce in fretta: cinque segnaposto che contengono ciascuno una union di dieci lettere darebbero 100.000 membri, e TypeScript rifiuta con error TS2590: Expression produces a union type that is too complex to represent. Usa un segnaposto ampio come ${string} quando non ti serve ogni valore esatto.

Uppercase, Lowercase, Capitalize, Uncapitalize

Quattro tipi built-in cambiano maiuscole e minuscole dei tipi letterali stringa. Sono intrinseci: implementati dentro il compilatore, non scritti in TypeScript.

Cambiano solo i tipi. Per costruire la stringa corrispondente in esecuzione devi comunque chiamare toUpperCase() o tagliare e mettere la maiuscola da te, e dire a TypeScript che il risultato ha il 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

Serve as perché toUpperCase() è tipizzato per restituire un semplice string. La firma della funzione è ciò che vedono i chiamanti, quindi capitalize("report") ha il tipo letterale "Report".

Pattern di stringa: ${number}px e simili

Un tipo pattern accetta ogni stringa di una certa forma. È comodo per valori CSS, id e chiavi con un prefisso noto:

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} accetta qualsiasi stringa che JavaScript legge come numero, e questo è più permissivo di quanto sembri: "-3px", "1e3px" e "0x10px" superano tutti il controllo. Considera questi pattern una protezione contro i refusi nei letterali, non una validazione completa.

Template literal con i mapped type

I template literal types sono più utili come clausola as di un mapped type, dove generano nomi di proprietà a partire da altri nomi di proprietà:

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 tiene solo le chiavi stringa, perché Capitalize non accetta numeri né symbol. Ogni callback prende il tipo del parametro dalla proprietà che osserva.

Parsing di stringhe con infer

In un conditional type, un template literal può fare il match di una stringa e catturarne delle parti con infer. Questo estrae i nomi dei parametri da un pattern di route:

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

Ometti postId nella chiamata e il compilatore lo segnala come mancante.

Le espressioni template si allargano a string

Un'espressione template string nel codice normale ha tipo string, anche quando ogni parte è un tipo letterale. Aggiungi as const per mantenere il 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

Senza as const, assegnare loose a `log:${Level}` fallisce, perché string potrebbe essere qualsiasi cosa.