TypeScript Academy · Leçon

Assertions et gardes de type

Privilégier les vérifications à l’exécution plutôt que les assertions lorsque cela est possible.

Assertions et gardes de type est une leçon TypeScript Academy gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage TypeScript Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours TypeScript Academy comprend 4 leçons au total.

Deux façons de convaincre le compilateur

Lorsque le compilateur ne connaît pas le type exact d’une valeur, deux possibilités s’offrent à vous : l’affirmer (déclarer son type) ou la protéger (prouver son type à l’exécution). Ces deux approches se ressemblent, mais offrent des niveaux de sécurité très différents.

function viaAssert(v: unknown): number {
  return (v as number) + 1; // claim
}
function viaGuard(v: unknown): number {
  return typeof v === 'number' ? v + 1 : 0; // prove
}
console.log(viaAssert(5), viaGuard(5), viaGuard('x'));

Les assertions ne vérifient rien

Une assertion est une promesse qui n’est soumise à aucun contrôle. Si vous vous trompez, le bogue passe à l’exécution. Les assertions sacrifient la sécurité au profit de la commodité.

const v: unknown = 'hello';
const n = v as number;
console.log(n.toFixed(2)); // runtime error: toFixed is not a function

Les gardes de type vérifient à l’exécution

Une garde de type vérifie réellement la valeur. Si la vérification réussit, vous et le compilateur savez que le type est correct : une véritable vérification à l’exécution justifie l’affinement du type.

function toFixed2(v: unknown): string {
  if (typeof v === 'number') return v.toFixed(2);
  return 'N/A';
}
console.log(toFixed2(3.14159), toFixed2('hi'));

Fonctions de garde de type personnalisées

Encapsulez les vérifications complexes dans une garde réutilisable qui renvoie value is T. L’ensemble de la base de code bénéficie ainsi d’une validation unique et soigneusement vérifiée.

type Email = { address: string };
function isEmail(v: unknown): v is Email {
  return typeof v === 'object' && v !== null &&
    'address' in v && typeof (v as any).address === 'string';
}
console.log(isEmail({ address: 'a@b.com' }), isEmail(null));

Les gardes se composent et se réutilisent

Comme les gardes sont des fonctions ordinaires, vous pouvez les combiner, les vérifier et les réutiliser. À l’inverse, les assertions sont des affirmations dispersées qui ne peuvent pas être validées de manière centralisée.

function isString(v: unknown): v is string { return typeof v === 'string'; }
function isNonEmpty(v: unknown): v is string {
  return isString(v) && v.length > 0;
}
console.log(isNonEmpty('hi'), isNonEmpty(''));

Fonctions d’assertion avec asserts

TypeScript propose également des fonctions d’assertion. Leur annotation de retour utilise le mot-clé asserts. Si la fonction se termine normalement, le compilateur affine le type de l’argument à partir de ce point ; si la condition échoue, elle lève une exception.

function assertNumber(v: unknown): asserts v is number {
  if (typeof v !== 'number') throw new Error('not a number');
}
function use(v: unknown): number {
  assertNumber(v); // after this line, v is number
  return v * 2;
}
console.log(use(21));

Affirmation par rapport au prédicat de type

Une garde value is T renvoie une valeur booléenne sur laquelle vous effectuez un branchement. Une fonction asserts value is T lève une exception en cas d’échec et affine le type pour le reste de la portée. Les deux sont fondées sur l’exécution, contrairement à un simple as.

function assertDefined<T>(v: T): asserts v is NonNullable<T> {
  if (v === null || v === undefined) throw new Error('missing');
}
const maybe: string | null = 'ok';
assertDefined(maybe);
console.log(maybe.length); // narrowed to string

Assistants d’assertion génériques

Les fonctions d’assertion sont idéales pour créer des conditions préalables réutilisables. Un seul assistant assert(condition) peut protéger les invariants dans tout votre code et signaler rapidement les violations.

function assert(cond: unknown, msg: string): asserts cond {
  if (!cond) throw new Error(msg);
}
function half(n: number): number {
  assert(n % 2 === 0, 'must be even');
  return n / 2;
}
console.log(half(8));

Comparer les niveaux de sécurité

Du plus sûr au plus risqué : les gardes de type et les fonctions d’assertion (vérifiées à l’exécution) se situent au-dessus des assertions simples as (non vérifiées), elles-mêmes au-dessus des doubles assertions (activement trompeuses). Choisissez l’outil le plus sûr qui convient.

// Safe: guard
function safe(v: unknown) {
  return typeof v === 'string' ? v.trim() : '';
}
console.log(safe('  hi  '));

Choisir le bon outil

Utilisez une garde de type lorsque vous effectuez un branchement selon le type. Utilisez une fonction d’assertion lorsqu’une condition préalable doit être respectée ou que l’exécution doit s’arrêter. Utilisez as uniquement lorsque l’affinement est impossible (par exemple, pour une spécialisation du DOM).

function getInput(v: unknown): asserts v is string {
  if (typeof v !== 'string') throw new Error('expected string');
}
const raw: unknown = 'name';
getInput(raw);
console.log(raw.toUpperCase());

Les vérifications à l’exécution l’emportent

Le thème récurrent de ce cours est le suivant : préférez les vérifications à l’exécution aux assertions. Les gardes et les fonctions d’assertion vous fournissent à la fois des types à la compilation et une sécurité à l’exécution. Les assertions ne fournissent qu’une affirmation.

function parsePort(v: unknown): number {
  if (typeof v === 'number' && Number.isInteger(v)) return v;
  throw new Error('invalid port');
}
console.log(parsePort(8080));

Vérification rapide

Vérifiez votre compréhension des assertions et des gardes de type.

Récapitulatif : assertions et gardes

Vous avez appris que :

Les gardes de type (value is T) prouvent un type à l’exécution et vous permettent d’effectuer un branchement.
Les fonctions d’assertion (asserts value is T) lèvent une exception en cas d’échec et affinent le type ensuite.
Les assertions simples as se contentent d’affirmer un type, sans sécurité à l’exécution.
Privilégiez les outils vérifiés à l’exécution ; réservez les assertions aux cas que l’affinement ne permet pas de gérer.

Cours suivant : chaînage optionnel et coalescence des valeurs nulles.

function isPositive(v: unknown): v is number {
  return typeof v === 'number' && v > 0;
}
console.log(isPositive(5), isPositive(-1));

Questions Fréquemment Posées

La leçon « Assertions et gardes de type » est-elle gratuite ?

Oui — le texte complet de « Assertions et gardes de type » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours TypeScript Academy, passe à CoddyKit PRO. Le cours TypeScript Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Assertions et gardes de type » ?

Privilégier les vérifications à l’exécution plutôt que les assertions lorsque cela est possible. Tu pratiques TypeScript Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer TypeScript Academy ?

Aucune expérience préalable n'est requise. TypeScript Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Assertions et gardes de type » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon TypeScript Academy ?

Oui. Chaque leçon TypeScript Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Le mot-clé as pour les assertions de type
Opérateur d’assertion de non-nullité
Assertions doubles et leurs risques
Assertions et gardes de type

← Retour à TypeScript Academy