Type guards & assertion functions, ou la preuve qui traverse une fonction Type guards & assertion functions, or the proof that crosses a function

Le test marche. Mais sorti dans une fonction, la preuve reste à l'intérieur.The test works. But pulled into a function, the proof stays inside.

Le narrowing du numéro précédent vivait dans un if, sur place. Dès qu'on factorise ce test dans une fonction, le type rétréci s'évapore : un retour boolean dit seulement « vrai ou faux », jamais « et donc x est un string ». Le prédicat de type x is string est la seule façon de faire voyager cette preuve à travers la frontière de la fonction.The narrowing of the previous issue lived in an if, on the spot. The moment you factor that test into a function, the narrowed type evaporates: a boolean return only says 'true or false', never 'and therefore x is a string'. The type predicate x is string is the only way to carry that proof across the function boundary.

function isString(x: unknown): boolean {   // ': boolean' écrit à la main — sans lui,
  return typeof x === "string";                // TS 5.5+ inférerait x is string (voir ch. 3)
}

function f(x: unknown) {
  if (isString(x)) {
    x.toUpperCase();   // ✗ x est toujours 'unknown' — boolean ne dit pas QUOI
  }
}

function isString(x: unknown): x is string {
  return typeof x === "string";
}

function f(x: unknown) {
  if (isString(x)) {
    x.toUpperCase();   // ✓ x : string — la preuve a traversé la fonction
  }
}

Le compilateur vérifie que tu rends un boolean. Pas que tu dis vrai.The compiler checks you return a boolean. Not that you tell the truth.

Voici le marché caché du type guard. Quand tu écris : x is User, tu fais une promesse — « si je rends true, alors x est un User ». Le compilateur ne vérifie jamais que le corps tient cette promesse. Il te croit sur parole. La responsabilité de la correction bascule entièrement sur toi.Here's the hidden bargain of the type guard. When you write : x is User, you make a promise — 'if I return true, then x is a User'. The compiler never checks that the body keeps that promise. It takes your word. The responsibility for correctness shifts entirely onto you.

function isString(x: unknown): x is string {
  return typeof x === "string";
  // ✓ le compilateur vérifie UNE chose : que tu rends bien un boolean.
}

Le compilateur s'assure que la fonction renvoie bien un boolean — c'est tout son contrôle. Le lien entre ce boolean et la forme x is string, il ne le vérifie pas : il l'accepte comme une déclaration.The compiler makes sure the function returns a boolean — that's the whole of its check. The link between that boolean and the shape x is string, it does not verify: it accepts it as a declaration.

Deux formes de la même promesse : retourner, ou lever.Two forms of the same promise: return, or throw.

Le prédicat de type (v is Point) rend un boolean : on l'utilise dans un if, et le narrowing s'applique dans la branche. L'assertion function (asserts v is Point) ne rend rien : elle lève si la forme est mauvaise, et narrowe pour tout ce qui suit l'appel — sans if. Même promesse, deux régimes de flot de contrôle.The type predicate (v is Point) returns a boolean: you use it in an if, and narrowing applies inside the branch. The assertion function (asserts v is Point) returns nothing: it throws if the shape is wrong, and narrows everything after the call — with no if. Same promise, two control-flow regimes.

type Point = { x: number; y: number };

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null
    && "x" in v && typeof v.x === "number"   // "x" in v suffit à rétrécir (TS 4.9+)
    && "y" in v && typeof v.y === "number";
}

if (isPoint(data)) data.x;   // ✓ data : Point dans le bloc

function assertIsPoint(v: unknown): asserts v is Point {
  if (!isPoint(v)) throw new Error("pas un Point");
}

assertIsPoint(data);
data.x;   // ✓ data : Point — SANS if, pour tout le reste de la fonction

Le guard écrit à la main copie le type. Et les copies divergent.The hand-written guard copies the type. And copies drift apart.

Un type guard correct aujourd'hui ne le reste pas. Il duplique, en code impératif, la forme déjà décrite par le type — deux descriptions de la même chose, qu'aucun lien n'oblige à rester d'accord. Le jour où le type gagne un champ, le guard l'ignore, continue de dire « oui », et le mensonge du chapitre 2 revient par la petite porte.A type guard that's correct today won't stay so. It duplicates, in imperative code, the shape already described by the type — two descriptions of the same thing, with nothing forcing them to agree. The day the type gains a field, the guard ignores it, keeps saying 'yes', and chapter 2's lie sneaks back in.

type User = { name: string; age: number };   // ← age ajouté l'an dernier

function isUser(x: unknown): x is User {
  // écrit quand User n'avait que name — jamais remis à jour
  return typeof x === "object" && x !== null && "name" in x;
}

if (isUser(data)) {
  data.age.toFixed();   // 💥 age peut être absent : le guard a menti en silence
}

Le type dit « name et age » ; le guard ne vérifie que name. Rien ne signale l'écart — le guard compile, ment, et le compilateur propage sa fausse preuve. Un guard à la main est une dette : il faut le maintenir à chaque évolution du type.The type says "name and age"; the guard only checks name. Nothing flags the gap — the guard compiles, lies, and the compiler propagates its false proof. A hand-written guard is a debt: it must be maintained on every change to the type.