Types littéraux et as const en TypeScript, avec exemples

Un type littéral est un type qui n'a qu'une seule valeur : "up" est un type dont le seul membre est la chaîne "up", et 404 un type dont le seul membre est le nombre 404. Seuls, ils ne servent pas à grand-chose. Réunis en une union, ils donnent une variable qui accepte un ensemble fixe de valeurs et rien d'autre.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

Sans le commentaire @ts-expect-error, le dernier appel est une erreur de compilation (TS2345). Avec lui, le programme compile et l'appel s'exécute quand même en affichant moving north by 1 : les types littéraux n'existent que pour le compilateur, et à l'exécution la valeur est une chaîne ordinaire.

Littéraux string, number et boolean

N'importe quelle valeur string, number, bigint ou boolean peut s'écrire comme un type. Le compilateur n'accepte alors que cette valeur exacte.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean n'est lui-même que l'union true | false, c'est pourquoi affiner un boolean avec if (flag) laisse false dans la branche else.

Unions de littéraux

L'usage courant est une union qui liste chaque valeur autorisée. Dans la fonction, le compilateur affine l'union au fil de vos vérifications, et chaque branche sait exactement quelle valeur elle a.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

Une union de littéraux de chaîne est l'alternative habituelle à un enum en TypeScript. Elle ne coûte rien à l'exécution, les valeurs sont de simples chaînes que vous pouvez journaliser et envoyer en JSON, et une faute de frappe est une erreur de compilation. Les compromis sont détaillés dans enums.

Élargissement : let ou const

Quand TypeScript infère un type à partir d'un littéral, il regarde si la valeur peut changer. Une variable const ne peut jamais être réassignée, elle garde donc le type littéral. Une variable let le peut, son type est donc élargi au type général.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

Survolez chaque nom dans l'éditeur pour voir le type inféré. Si vous voulez une let qui ne contienne que certaines valeurs, annotez-la : let mode: "light" | "dark" = "light".

Pourquoi les propriétés d'objet s'élargissent

Les propriétés d'un littéral objet sont modifiables, elles s'élargissent donc aussi, même quand l'objet est stocké dans une const. C'est la façon la plus courante de tomber sur les types littéraux par accident :

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

Le compilateur signale :

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req est inféré comme { url: string; method: string }, car du code pourrait plus tard exécuter req.method = "DELETE". Il y a trois corrections :

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

Une quatrième option est satisfies, qui vérifie l'objet par rapport à un type tout en gardant les types littéraux de ses propriétés.

as const

as const est une const assertion. Placez-la après une expression et le compilateur infère le type le plus étroit possible :

• les valeurs string, number et boolean gardent leurs types littéraux
• les propriétés d'objet deviennent readonly
• les littéraux de tableau deviennent des tuples readonly de longueur fixe

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

L'assertion n'agit qu'à la compilation. Le JavaScript émis est le même littéral objet sans as const : rien n'empêche donc un autre code de le modifier à l'exécution. Si vous avez besoin d'une garantie à l'exécution, appelez aussi Object.freeze.

Un type union à partir d'un tableau as const

Un motif fréquent consiste à garder les valeurs autorisées dans un seul tableau, que vous pouvez parcourir à l'exécution, et à en dériver le type union. (typeof arr)[number] signifie « le type de n'importe quel élément de arr ».

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

Sans as const, ROLES serait un string[] et Role un simple string. La conversion en readonly string[] dans isRole est nécessaire parce que includes sur un tuple de littéraux n'accepte que ces littéraux, alors que le but de la fonction est de tester une chaîne qui n'en est peut-être pas un. Le même motif fonctionne pour les tables clé/valeur : const Status = { Active: "active", Banned: "banned" } as const, puis type Status = (typeof Status)[keyof typeof Status].

Paramètres de type const

Une fonction générique élargit normalement les littéraux que vous lui passez. Depuis TypeScript 5.0, vous pouvez marquer un paramètre de type const, ce qui fait inférer l'argument par le compilateur comme s'il portait as const, sans demander à l'appelant de l'écrire.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

C'est surtout un outil pour les auteurs de bibliothèques : les définitions de routes, les builders et les helpers de schéma l'utilisent pour que les appelants obtiennent des types précis à partir de simples littéraux.

Les sens de const

Le mot-clé const apparaît à quatre endroits différents dans du code TypeScript :

Aucun d'eux ne gèle un objet à l'exécution. const obj = { a: 1 } autorise toujours obj.a = 2 ; seule la réassignation de obj lui-même est une erreur.