Template literal types en TypeScript : syntaxe et exemples

Un template literal type construit des types littéraux de chaîne avec la même syntaxe à backticks qu'une template string JavaScript. `on${Capitalize<"click" | "focus">}` est le type "onClick" | "onFocus", calculé par le compilateur :

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;

Les template literal types n'existent qu'à la compilation. Ils vérifient les littéraux de chaîne et les valeurs typées pendant que vous écrivez le code ; ils n'ajoutent rien au JavaScript produit. La table de handlers ci-dessus utilise Record pour exiger une fonction par nom.

Syntaxe

Entre les backticks, on écrit du texte littéral et des emplacements ${...}. Un emplacement contient un type, pas une valeur : un type littéral string, number, bigint ou boolean, une union de ces types, ou l'un des types larges string, number, bigint, boolean, null et 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 emplacement avec un type large comme string ou number crée un motif : le type reste `hello ${string}` et toute chaîne qui correspond est acceptée. Un emplacement avec une union finie, comme boolean, est développé en ses membres.

Les unions se multiplient

Avec plusieurs unions, le résultat contient toutes les combinaisons :

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

Trois tailles fois deux tons donnent six membres. Le nombre grimpe vite : cinq emplacements contenant chacun une union de dix lettres donneraient 100 000 membres, et TypeScript refuse avec error TS2590: Expression produces a union type that is too complex to represent. Utilisez un emplacement large comme ${string} quand vous n'avez pas besoin de chaque valeur exacte.

Uppercase, Lowercase, Capitalize, Uncapitalize

Quatre types intégrés changent la casse des types littéraux de chaîne. Ils sont intrinsèques : implémentés dans le compilateur, et non écrits en TypeScript.

Ils ne changent que les types. Pour construire la chaîne correspondante à l'exécution, il faut toujours appeler toUpperCase() ou découper et mettre en majuscule vous-même, puis indiquer à TypeScript que le résultat a le type précis :

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

Le as est nécessaire parce que toUpperCase() est typé pour renvoyer un simple string. C'est la signature de la fonction que voient les appelants, donc capitalize("report") a le type littéral "Report".

Motifs de chaîne : ${number}px et compagnie

Un type motif accepte toute chaîne d'une forme donnée. C'est pratique pour les valeurs CSS, les identifiants et les clés avec un préfixe connu :

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} accepte toute chaîne que JavaScript lit comme un nombre, ce qui est plus permissif qu'il n'y paraît : "-3px", "1e3px" et "0x10px" passent tous la vérification. Voyez ces motifs comme une protection contre les fautes de frappe dans les littéraux, pas comme une validation complète.

Template literals et mapped types

Les template literal types sont surtout utiles dans la clause as d'un mapped type, où ils génèrent des noms de propriétés à partir d'autres noms de propriétés :

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 ne garde que les clés de type chaîne, car Capitalize n'accepte ni nombres ni symboles. Chaque callback reçoit le type de son paramètre depuis la propriété qu'il surveille.

Analyser des chaînes avec infer

Dans un type conditionnel, un template literal peut reconnaître une chaîne et en capturer des parties avec infer. Cet exemple extrait les noms de paramètres d'un motif de 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

Oubliez postId dans l'appel et le compilateur le signale comme manquant.

Les expressions template s'élargissent en string

Une expression template string dans du code ordinaire est typée string, même quand chaque partie est un type littéral. Ajoutez as const pour conserver le 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

Sans as const, affecter loose à `log:${Level}` échoue, car string pourrait être n'importe quoi.