Qu'est-ce qu'un type guard défini par l'utilisateur ?

Question

Accepted Answer

Un **user-defined type guard** est une fonction dont le type de retour est un **type predicate** (`x is T`). Quand il retourne `true`, le compilateur rétrécit l'argument à `T` dans le code appelant — vous permettant d'encapsuler des vérifications d'exécution personnalisées.

```ts
interface Cat { meow(): void; }
interface Dog { bark(): void; }

// the magic is the return type `pet is Cat`, not just `boolean`
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

function speak(pet: Cat | Dog) {
  if (isCat(pet)) {
    pet.meow(); // ✅ narrowed to Cat
  } else {
    pet.bark(); // ✅ narrowed to Dog
  }
}
```

Sans le prédicat `pet is Cat`, `isCat` retournant `boolean` ne rétrécirais *pas* `pet` — le compilateur verrait toujours `Cat | Dog` à l'intérieur du `if`. Le prédicat est ce qui le lui enseigne.

## Valider les données externes inconnues

```ts
interface User { id: number; name: string; }

function isUser(x: unknown): x is User {
  return (
    typeof x === "object" && x !== null &&
    typeof (x as any).id === "number" &&
    typeof (x as any).name === "string"
  );
}

const data: unknown = await res.json();
if (isUser(data)) data.name; // ✅ safely typed as User
```

## Mise en garde

Le compilateur **fait confiance** à votre prédicat — si la logique du corps est incorrecte, vous obtenez un rétrécissement non sécurisé. Pour les formes complexes, un validateur de schéma (zod) génère des guards corrects pour vous.

## Pourquoi c'est important

Les type guards vous permettent de transformer des vérifications d'exécution arbitraires en fonctions de rétrécissement réutilisables — essentielles pour valider les données `unknown` aux frontières d'API et pour distinguer les membres d'une union quand une simple vérification `typeof`/`in` ne suffit pas à elle seule.