Discriminated unions, ou l'une de ces formes, exclusivement Discriminated unions, or one of these shapes, exclusively

Le sac de champs optionnels laisse construire des états qui ne devraient pas exister.The bag of optional fields lets you build states that shouldn't exist.

Un seul objet, un booléen et deux champs optionnels : et voilà l'état « en chargement, réussi, et en erreur » à la fois — parfaitement constructible, parfaitement absurde. On le « gère » alors à coups de if éparpillés, en priant pour avoir couvert toutes les combinaisons. La discriminated union pose la question à l'envers : et si cet état illégal ne se construisait même plus ?A single object, one boolean and two optional fields: and there it is, the 'loading, succeeded, and errored' state all at once — perfectly buildable, perfectly absurd. So you 'handle' it with scattered ifs, praying you covered every combination. The discriminated union flips the question: what if that illegal state could no longer be built at all?

type RequestState = {
  loading: boolean;
  data?: User;
  error?: string;
};

// rien n'interdit l'état absurde :
const s: RequestState = { loading: true, data: user, error: "boom" };
// en cours ? réussi ? échoué ? les trois à la fois — et ça compile.

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: string };

// l'état absurde ne se construit même plus :
const s: RequestState = { status: "loading", data: user };
// ✗ 'data' n'existe pas sur la branche "loading" — refusé à la compilation

On ne peut pas lire .data sur l'union. Il faut d'abord prouver la branche.You can't read .data on the union. You must first prove the branch.

Le réflexe venu du sac de champs : accéder à s.data directement. Le compilateur refuse — data n'est garanti que sur une seule branche, pas sur l'union. Et c'est exactement la protection qu'on voulait : impossible de toucher un champ avant d'avoir établi qu'on est dans la forme qui le possède. Le discriminant est la clé qui ouvre la branche.The reflex inherited from the bag of fields: reach for s.data directly. The compiler refuses — data is guaranteed only on a single branch, not on the union. And that's exactly the protection we wanted: you can't touch a field before establishing you're in the shape that owns it. The discriminant is the key that opens the branch.

function render(s: RequestState) {
  return s.data;
  //       ^ ✗ 'data' n'existe pas sur le type RequestState
  //         (absent de la branche "loading" et "error")
}

L'erreur n'est pas une gêne, c'est le théorème : sur RequestState, le compilateur ne sait qu'une chose sûre — qu'il y a un champ status. Tout le reste dépend de laquelle des trois formes on tient. Il refuse de te laisser supposer la réponse.The error isn't a nuisance, it's the theorem: on RequestState, the compiler knows only one sure thing — there's a status field. Everything else depends on which of the three shapes you hold. It refuses to let you assume the answer.

Un champ commun, littéral, distinct par membre — et le switch qui s'ouvre.One field, common, literal, distinct per member — and the switch that unfolds.

Une union devient « discriminée » dès qu'un champ commun la rend lisible : le discriminant (ou tag). TypeScript repère que chaque membre fixe ce champ à une valeur littérale différente, et s'en sert pour rétrécir. C'est tout le mécanisme — un switch sur le tag, et chaque case devient une branche typée à une seule forme.A union becomes 'discriminated' the moment a common field makes it readable: the discriminant (or tag). TypeScript notices each member pins that field to a different literal value, and uses it to narrow. That's the whole mechanism — a switch on the tag, and each case becomes a branch typed to a single shape.

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "rect"; w: number; h: number };
//   ^^^^ le discriminant : un champ COMMUN, de type LITTÉRAL, DISTINCT par membre

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;   // s : { kind: "circle"; r: number }
    case "rect":   return s.w * s.h;             // s : { kind: "rect"; w, h }
  }
}

Un discriminant typé string ne discrimine rien.A discriminant typed string discriminates nothing.

Le piège silencieux : tout a l'air d'une union discriminée — un champ status, un if dessus — mais le narrowing ne se produit pas, et data reste inaccessible. La cause : le discriminant est typé string, pas un littéral. Comparer un string à "ok" n'élimine aucune branche, parce que les deux membres acceptent n'importe quel string. Le tag ne sépare les formes que s'il est littéral.The silent trap: it all looks like a discriminated union — a status field, an if on it — but narrowing never happens, and data stays out of reach. The cause: the discriminant is typed string, not a literal. Comparing a string to "ok" eliminates no branch, because both members accept any string. The tag only separates the shapes if it's literal.

type Ok  = { status: string; data: User };     // ✗ status: string
type Err = { status: string; error: string };  // ✗ status: string
type State = Ok | Err;

function f(s: State) {
  if (s.status === "ok") {
    s.data;   // ✗ 'data' n'existe pas : 'ok' n'est qu'UN string parmi l'infini
  }           //   le test n'élimine NI Ok NI Err — aucun narrowing
}

Comme Ok et Err acceptent tous deux status: string, le test === "ok" n'en exclut aucun : après le if, s est encore Ok | Err. Même cause fréquente : un objet déclaré sans as const, dont TypeScript élargit le tag de "ok" à string avant même qu'il rejoigne l'union.Since Ok and Err both accept status: string, the === "ok" test excludes neither: after the if, s is still Ok | Err. A common cause: an object declared without as const, whose tag TypeScript widens from "ok" to string before it even joins the union.