Inférence de type en TypeScript : quand annoter, quand s'abstenir

L'inférence de type, c'est TypeScript qui déduit un type que vous n'avez pas écrit. Initialisez une variable, et elle prend le type de la valeur ; renvoyez une valeur depuis une fonction, et le type de retour suit. La plupart du code TypeScript contient bien moins d'annotations qu'on ne l'imagine.

let count = 0;            // number
let language = "TypeScript"; // string
let tags = ["ts", "js"];  // string[]
let user = { name: "Ada", age: 36 }; // { name: string; age: number }

function area(w: number, h: number) {
    return w * h;          // return type inferred as number
}

const size = area(3, 4);  // number
console.log(count, language, tags, user, size);

// The inferred types are enforced like written ones:
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
count = "one";

Les commentaires indiquent ce qu'affiche un éditeur au survol de chaque nom. La dernière ligne est une erreur de compilation (TS2322) alors que count n'a jamais été annoté ; // @ts-expect-error la marque comme attendue pour que le reste du bloc s'exécute.

let ou const : l'élargissement des littéraux

Une const ne peut jamais changer, TypeScript lui donne donc le type le plus étroit : la valeur littérale elle-même. Une let reçoit le type plus large, car elle peut être réassignée plus tard.

let a = "left";    // string
const b = "left";  // "left"
let c = 42;        // number
const d = 42;      // 42
const e = true;    // true

Cela compte quand une fonction n'accepte que certaines valeurs :

// This does not compile: `let` widened "left" to string.
function move(direction: "left" | "right") {
    console.log("moving", direction);
}

let dir = "left";
move(dir);

const fixed = "left";
move(fixed); // fine: fixed has type "left"

index.ts(7,6): error TS2345: Argument of type 'string' is not assignable to parameter of type '"left" | "right"'.

Corrigez avec const, ou en annotant la variable : let dir: "left" | "right" = "left". Les types littéraux ont leur propre page, types littéraux.

Les objets et les tableaux élargissent leurs membres

Les propriétés d'un littéral objet sont modifiables, elles s'élargissent donc comme une let, même quand l'objet lui-même est const. Les éléments de tableau font de même. as const rend tout readonly et conserve les types littéraux.

const config = { mode: "dark", retries: 3 };
// config: { mode: string; retries: number }
config.mode = "light"; // allowed: mode is string

const frozen = { mode: "dark", retries: 3 } as const;
// frozen: { readonly mode: "dark"; readonly retries: 3 }

const sizes = ["s", "m", "l"];            // string[]
const fixedSizes = ["s", "m", "l"] as const; // readonly ["s", "m", "l"]

console.log(config.mode, frozen.mode, sizes.length, fixedSizes[0]);

L'inférence du type de retour

Le type de retour d'une fonction est inféré à partir de ses instructions return. Quand il y en a plusieurs, le résultat est leur union.

function parsePort(text: string) {
    if (text === "") return null;
    return Number(text);
}
// parsePort returns number | null

const port = parsePort("8080");
if (port !== null) {
    console.log(port + 1); // 8081: port is number inside the check
}

function log(message: string) {
    console.log(message);
}
// log returns void: there is no return value

log("done");

Les types de retour inférés conviennent à la plupart des fonctions. Écrivez explicitement le type de retour des fonctions exportées ou publiques quand vous voulez que la signature soit un contrat : une modification dans le corps qui renvoie un autre type échoue alors au niveau de la fonction, et non chez un appelant lointain.

Le typage contextuel : les callbacks reçoivent leurs types

Les paramètres ne sont pas inférés à partir de la façon dont une fonction est appelée. Il y a deux exceptions. Un paramètre avec une valeur par défaut prend le type de cette valeur (function retry(times = 3) fait de times un number). Et une fonction écrite là où un type de fonction est déjà attendu reçoit ses types de paramètres de ce contexte, si bien que les paramètres des callbacks n'ont pas besoin d'annotation.

const names = ["ada", "grace", "alan"];

// s is string: map on a string[] passes strings
const upper = names.map((s) => s.toUpperCase());

// a and b are strings, the result must be a number
const sorted = [...names].sort((a, b) => a.length - b.length);

// The variable's type gives the arrow its parameter and return types
const greet: (name: string) => string = (n) => `Hello, ${n}`;

console.log(upper, sorted, greet("Ada"));

Il en va de même pour forEach, filter, reduce, les callbacks de Promise, les gestionnaires d'événements et toute fonction passée à un paramètre dont le type de fonction est déclaré.

Les paramètres ont besoin d'annotations

Sans valeur par défaut ni contexte de ce genre, TypeScript ne regarde pas comment une fonction est appelée pour deviner les types de ses paramètres. Avec strict activé, un paramètre non annoté provoque l'erreur TS7006 :

// This does not compile: a parameter with no type and no context.
function double(x) {
    return x * 2;
}
console.log(double(21));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

Écrivez function double(x: number) et le bloc affiche 42, avec le type de retour number inféré à partir de x * 2.

Le meilleur type commun

Pour un littéral de tableau contenant différents genres de valeurs, TypeScript infère un tableau de l'union de leurs types. Il ne cherche pas un type de base commun que vous n'auriez pas mentionné.

const mixed = [1, "two", null]; // (string | number | null)[]
const nums = [1, 2.5, -3];      // number[]

class Animal { name = "animal"; }
class Dog extends Animal { bark() { return "woof"; } }
class Cat extends Animal { meow() { return "meow"; } }

const pets = [new Dog(), new Cat()];            // (Cat | Dog)[]
const animals: Animal[] = [new Dog(), new Cat()]; // annotate to get Animal[]

console.log(mixed.length, nums, pets.length, animals[0].name);

Le tableau vide est le seul cas à surveiller. const list = [] commence comme un tableau « évolutif » dont le type grandit à chaque push ; une annotation, const list: string[] = [], énonce l'intention dès le départ et c'est plus clair.

Quand annoter

Le moyen le plus rapide de voir ce qui a été inféré est de survoler le nom dans votre éditeur. Sans éditeur, assignez la valeur à une variable d'un mauvais type, comme const probe: boolean = mixed;, et le message d'erreur du compilateur nomme le type inféré.