Type guard en TypeScript : vérifier le type d'un objet

Un type guard est une vérification à l'exécution que TypeScript comprend : il affine donc le type dans la branche vérifiée. typeof, instanceof et in sont des guards intégrés ; pour tout le reste, vous écrivez une fonction dont le type de retour est un prédicat de type, value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser renvoie un simple booléen à l'exécution. Le type de retour value is User indique au compilateur ce que prouve un résultat true, et chaque if (isUser(x)) affine alors x en User.

Les type guards intégrés

Ces vérifications affinent sans aucune fonction auxiliaire :

Tous s'exécutent comme du JavaScript ordinaire. Ce qu'ajoute TypeScript, c'est le narrowing : il lit la vérification et ajuste le type dans chaque branche. La liste complète des formes se trouve sur la page narrowing de types. Un guard personnalisé sert aux vérifications qui ne tiennent pas en une expression, ou que vous voulez réutiliser.

Écrire un prédicat de type

Un prédicat de type a la forme parameterName is Type et remplace boolean comme type de retour. Le narrowing fonctionne dans les deux sens : true affine vers Type, et false retire Type d'une union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Passer un guard à filter donne un tableau correctement typé. Depuis TypeScript 5.5, le compilateur infère aussi un prédicat à partir des fonctions fléchées simples : pets.filter((p) => p.kind === "cat") renvoie donc Cat[] sans guard nommé.

Le type du prédicat doit correspondre au type du paramètre : function f(x: string): x is number provoque l'erreur TS2677, A type predicate's type must be assignable to its parameter's type.

Le compilateur fait confiance à votre guard

TypeScript vérifie qu'un guard renvoie un booléen. Il ne vérifie pas que ce booléen est juste. Un guard qui renvoie true pour de mauvaises valeurs fait mentir les types, et le programme échoue à l'exécution sans aucune erreur de compilation.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) lève TypeError: Cannot read properties of undefined (reading 'toFixed') à l'exécution. Le compilateur a accepté data.price comme un number parce que le guard l'affirmait. Vérifiez chaque propriété dont dépend le reste du code, et gardez les guards petits, testés et proches du type qu'ils décrivent.

Vérifier qu'un objet est d'un certain type

C'est la question derrière la plupart des guards personnalisés : des données arrivent en unknown (depuis JSON.parse, fetch, localStorage, un message) et vous devez savoir si elles correspondent à votre interface. La recette :

1. typeof value === "object" && value !== null (un objet, pas null).
2. "prop" in value pour chaque propriété requise. Sur unknown, in ajoute la propriété au type en tant que unknown.
3. typeof value.prop === "..." (ou un guard imbriqué) pour le type de chaque propriété.
4. Array.isArray(value.items) && value.items.every(isItem) pour les tableaux.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Pour les formes grandes ou profondément imbriquées, écrire ces guards à la main devient fastidieux. Les bibliothèques de schémas comme Zod ou Valibot vous permettent de décrire la forme une seule fois et vous donnent à la fois la vérification à l'exécution et le type TypeScript.

Fonctions d'assertion : asserts value is Type

Une fonction d'assertion lève une exception si la vérification échoue et se termine normalement sinon. Son type de retour est asserts value is Type (ou asserts condition), et tout ce qui vient après l'appel est affiné, sans if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

Une règle fait trébucher : une fonction d'assertion doit être appelée via un nom au type explicite. Une fonction fléchée const sans annotation, const check = (v: unknown): asserts v is string => {...}, provoque l'erreur TS2775 à l'appel, Assertions require every name in the call target to be declared with an explicit type annotation. Utilisez une déclaration function, ou annotez la constante avec un type de fonction.

Guards, assertions ou casts

Une assertion de type (as) change le type sans rien vérifier. À une frontière où les données viennent de l'extérieur, un guard ou une fonction d'assertion est la version sûre de la même idée.

Guards basés sur this dans les classes

Une méthode peut affiner l'objet sur lequel elle est appelée avec this is Type. C'est pratique dans les hiérarchies de classes :

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}