Narrowing
IntermédiaireComment TypeScript suit vos vérifications et vos retours anticipés dans une fonction, et réduit une union comme string | number | null jusqu’à un seul type.
Rien dans la portée pour l’instant
Aucune erreur
Spacelecture ou pause←→étape précédente ou suivanteRrevenir au début
Explication
Lecture : 3 min
Sur cette page
Qu'est-ce que le narrowing en TypeScript ?
Un type union comme string | number | null dit qu'une valeur peut être l'un de plusieurs types.
C'est honnête mais limitant : TypeScript ne laisse utiliser que ce que tous les membres ont en
commun, donc value.toUpperCase() est une erreur tant que vous n'avez pas prouvé que value est une
chaîne.
Le narrowing (réduction de type) est la façon de le prouver. Quand vous vérifiez une valeur, TypeScript calcule quels membres de l'union peuvent encore atteindre chaque ligne, et donne là à la valeur ce type plus petit, réduit.
Comment TypeScript réduit-il un type ?
Il lit votre code dans l'ordre où il s'exécute, ce qu'on appelle l', et reconnaît des vérifications appelées gardes de type :
- L'égalité :
value === null,value !== undefined,shape.kind === 'circle'. typeof:typeof value === 'string'pour les primitives (string,number,boolean,bigint,symbol,undefined,function,object).instanceof:error instanceof TypeErrorpour les classes.in:'radius' in shapeteste la présence d'une propriété.- La valeur de vérité :
if (value)retirenulletundefined(et les autres valeurs fausses). - Vos propres gardes : une fonction qui renvoie
value is Fishdit à TypeScript ce que signifie un résultattrue.
Les branches comptent aussi. Dans un if, le type est réduit ; dans le else, les membres vérifiés
sont retirés. Après une branche qui fait toujours return ou throw, ce qu'elle a traité ne peut
plus apparaître : les retours anticipés réduisent donc la suite de la fonction. Là où les branches se
rejoignent, les types se réunissent en une union.
Quelles erreurs fait-on souvent avec le narrowing ?
Mini-exemple
Une union discriminée donne à chaque membre une propriété littérale commune, ici kind. La
tester réduit à un seul membre, et TypeScript sait aussi que le switch couvre tous les cas :
type Shape = { kind: 'circle'; radius: number } | { kind: 'square'; side: number }; function area(shape: Shape): number { switch (shape.kind) { case 'circle': return Math.PI * shape.radius ** 2; // shape: the circle member case 'square': return shape.side ** 2; // shape: the square member }}Test rapide
Dans case "circle": du mini-exemple, quel est le type de shape ?
Pour aller plus loin
Toutes les étapes en texte
- Étape 1:
value est déclarée comme une union : string | number | null. Tant que vous ne vérifiez rien, seul ce que les trois ont en commun est utilisable.
Ligne 1
- Étape 2:
value === nullest une garde de type. Dans ce if, TypeScript sait que value vaut null.Ligne 2
- Étape 3:
Cette branche fait un return : null ne peut jamais passer. Après le if, value est string | number.
Lignes 3–4
- Étape 4:
typeof value === "string"réduit encore : dans cette branche, value est une chaîne, donc.lengthest permis.Lignes 6–7
- Étape 5:
Dans la branche else, string est exclu et il ne reste que number : la méthode des nombres
toFixedest permise.Lignes 8–9
- Étape 6:
Après le if/else, les deux branches se rejoignent : value redevient string | number.
Ligne 10
- Étape 7:
Cette vérification réduit value à number, et la branche fait un return.
Lignes 12–13
- Étape 8:
Après ce retour anticipé, number disparaît aussi. Sur cette dernière ligne, value ne peut être qu’une chaîne.
Ligne 16
- Étape 9:
Sans les vérifications, value serait encore string | number | null ici. TypeScript signalerait alors deux erreurs.
Ligne 16
- Étape 10:
Avec elles, value est une chaîne sur cette ligne :
toUpperCaseest permis et les deux erreurs disparaissent.Ligne 16
- Étape 11:
TypeScript suit votre code : chaque vérification et chaque retour anticipé réduisent l’union, et seuls les types restants décident de ce qui est permis.