Le narrowing, ou la preuve qui se construit branche par branche Narrowing, or the proof built branch by branch

L'union ne se caste pas. Elle rétrécit, garde après garde.The union isn't cast. It narrows, gate after gate.

Le 2.1 a montré qu'à l'exécution il ne reste que des valeurs. Voici comment le compilateur, lui, garde le fil : il lit nos tests ordinaires — un if, un typeof, un return anticipé — et rétrécit le type en conséquence. Le même x n'a pas le même type d'une ligne à l'autre. C'est le narrowing, et c'est la signature de la série.2.1 showed that only values remain at runtime. Here's how the compiler keeps the thread: it reads our ordinary tests — an if, a typeof, an early return — and narrows the type accordingly. The same x doesn't have the same type from one line to the next. That's narrowing, and it's the series' signature.

function len(x: string | string[] | null): number {
  if (x === null) return 0;            // ici x : string | string[]
  if (typeof x === "string")           // ici x : string
    return x.length;
  return x.length;                     // ici x : string[]
}

Pas de syntaxe magique. TypeScript lit le if que tu écris déjà.No magic syntax. TypeScript reads the if you already write.

Venant du JavaScript, on croit qu'il faudra « convaincre » le compilateur à coups de as. C'est l'inverse : le narrowing n'a aucune syntaxe propre. Il s'appuie sur le flot de contrôle ordinaire — tes if, tes return, tes &&. Écris le test qu'un humain écrirait pour se protéger, et le type suit tout seul.Coming from JavaScript, you assume you'll have to 'convince' the compiler with as. It's the opposite: narrowing has no syntax of its own. It rides on ordinary control flow — your ifs, your returns, your &&. Write the test a human would write to stay safe, and the type follows on its own.

function shout(x: string | null) {
  // le réflexe « je sais mieux » : caster partout
  return (x as string).toUpperCase();
  // ✓ compile — mais si x est null, 💥 à l'exécution.
  // Le as a fait taire le compilateur, pas vérifié null.
}

as string ne retire pas le null : il ordonne au compilateur de l'ignorer. Le test qui aurait protégé n'a pas été écrit, juste contourné. On a rétabli exactement le crash que le type signalait.as string doesn't remove the null: it orders the compiler to ignore it. The test that would have protected you was never written, only bypassed. You've restored exactly the crash the type was flagging.

Six gardes, et un compilateur qui se souvient.Six gates, and a compiler that remembers.

Le narrowing n'a pas de syntaxe à lui, mais il a un vocabulaire : une poignée de tests que le compilateur sait interpréter. Chacun retire un ensemble de possibilités. Et l'analyse de flot tient les comptes d'un bout à l'autre du bloc — ce qui est éliminé dans une branche reste éliminé dans la suite.Narrowing has no syntax of its own, but it has a vocabulary: a handful of tests the compiler knows how to read. Each removes a set of possibilities. And control flow analysis keeps the books across the whole block — what's eliminated in one branch stays eliminated afterward.

typeof x === "string"      // primitives : string, number, boolean, …
x instanceof Date          // classes (une vraie valeur JS)
"role" in obj              // présence d'une propriété
Array.isArray(x)           // tableau vs reste
if (x) { … }               // truthiness : retire null, undefined, 0, "", false
x.kind === "circle"        // égalité sur un discriminant littéral

function f(x: string | number) {
  if (typeof x === "number") {
    x;            // number
    return x + 1;
  }
  x;              // string — le compilateur SE SOUVIENT que le number est parti
  return x.trim();
}

Après un if qui return, le membre testé ne peut plus être présent dans la suite : l'analyse de flot le retire pour le reste du bloc. C'est pour ça que x est string après le bloc number, sans nouveau test — le compilateur a tenu le compte.After an if that returns, the tested member can't appear afterward: control flow analysis removes it for the rest of the block. That's why x is string after the number block, with no new test — the compiler kept the count.

Tout ce qui précède se lit en hochant la tête et ne s'applique jamais : une règle n'a de poids que le jour où on la voit se déclencher. Alors écrivez. Le compilateur ci-dessous n'est pas une imitation — c'est tsc lui-même, chargé dans la page, avec les mêmes drapeaux strict que le site. Les codes qu'il rend sont ceux que vous reverrez dans votre terminal.Everything above reads with a nod and never gets applied: a rule only carries weight the day you watch it fire. So write. The compiler below isn't an imitation — it's tsc itself, loaded into the page, with the same strict flags as this site. The codes it returns are the ones you'll see again in your terminal.

La colonne de droite ne compte pas les erreurs : elle compte les portes de sortie. C'est la seule chose qu'un « ✓ ça compile » ne saurait pas dire.The right-hand column doesn't count errors: it counts escape hatches. It's the one thing a “✓ it compiles” could never tell you.

La truthiness mange le 0. Et le narrowing s'oublie.Truthiness eats the 0. And narrowing forgets itself.

Deux façons de se faire piéger par un outil pourtant juste. La première : tester la « truthiness » pour dire « a une valeur » — mais 0, la chaîne vide et false sont falsy, et passent à la trappe. La seconde : croire qu'un type rétréci le reste pour toujours — alors qu'il se perd dès qu'une fonction pourrait avoir changé la donnée entre-temps.Two ways to get trapped by an otherwise-correct tool. First: testing 'truthiness' to mean 'has a value' — but 0, the empty string and false are falsy, and fall through. Second: assuming a narrowed type stays narrowed forever — when it's lost the moment a function could have changed the data in between.

function label(count: number | undefined) {
  if (!count) return "rien";   // ⚠ piège : 0 est falsy
  return `${count} éléments`;
}
label(0);   // "rien" — alors que 0 est une valeur parfaitement valide
// truthiness retire undefined… mais aussi 0, "", NaN, false

!count est vrai pour undefined et pour 0. Pour ne retirer que l'absence, on teste explicitement : count === undefined, ou count == null (qui couvre null et undefined). À noter aussi : typeof null === "object" — la garde typeof x === "object" laisse passer null.!count is true for undefined and for 0. To remove only absence, test explicitly: count === undefined, or count == null (covering null and undefined). Note too: typeof null === "object" — the typeof x === "object" gate lets null through.

function f(o: { v: string | null }) {
  if (o.v !== null) {
    // ici o.v : string
    setTimeout(() => {
      o.v.toUpperCase();   // ✗ 'o.v' is possibly 'null'.
      // entre le test et l'appel, o.v a pu changer : le narrowing est perdu
    });
  }
}

Le narrowing d'une propriété mutable ne tient pas à travers une closure : le callback s'exécutera plus tard, et le compilateur doit supposer que o.v a pu redevenir null entre-temps. (Un simple appel de fonction, lui, ne l'efface pas — TypeScript fait là un pari optimiste.) Il refuse, à raison.Narrowing of a mutable property doesn't hold across a closure: the callback runs later, and the compiler must assume o.v could have gone back to null in between. (A plain function call doesn't erase it — TypeScript makes an optimistic bet there.) It refuses, rightly.