Type guards (value is T)

Des fonctions de vérification personnalisées qui restreignent le type à l’endroit de l’appel.

Sur cette page

Exemple

#
TypeScript
interface Course {
  title: string
  modules: number
}

function isCourse(value: unknown): value is Course {
  return (
    typeof value === 'object' &&
    value !== null &&
    typeof (value as Course).title === 'string' &&
    typeof (value as Course).modules === 'number'
  )
}

const data: unknown = JSON.parse('{"title":"Python","modules":12}')

if (isCourse(data)) {
  console.log(`${data.title}: ${data.modules} modules`)
}
Résultat
Python: 12 modules

Définition et utilisation

#

Un type guard est une fonction qui renvoie un boolean et dont le type de retour est écrit sous forme de prédicat : value is Course. Si la fonction renvoie true, le compilateur considère que la valeur a ce type.

Cela permet d’enfermer une vérification complexe en un seul endroit et de l’utiliser exactement comme les typeof ou instanceof intégrés. C’est particulièrement utile avec les données d’une API, la vérification de la forme d’objets et le filtrage de tableaux.

Depuis TypeScript 5.5, le compilateur peut déduire seul le prédicat pour les fonctions simples, par exemple x => x !== null passé à filter().

Syntaxe

#
Syntaxe
function isType(value: unknown): value is Type {
  return …
}

Plus d’exemples

#
Filtrage avec restriction de type
TypeScript
const values = ['HTML', null, 'CSS', undefined]
const names = values.filter((v): v is string => typeof v === 'string')

console.log(names)
Résultat
['HTML', 'CSS']

Bonnes pratiques

#
  • Un type guard doit réellement vérifier ce qu’il promet. Le compilateur fait confiance au prédicat et ne contrôle pas sa logique.
  • Pour une validation poussée des données d’une API, il vaut la peine d’utiliser une bibliothèque comme Zod, qui génère à la fois les types et les vérifications à partir d’un seul schéma.

Entrées associées

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.