Branded / opaque types, ou un string qui a fait ses preuves Branded / opaque types, or a string that earned its name

Le structurel rend un Email validé et un string brut interchangeables.Structural typing makes a validated Email and a raw string interchangeable.

C'est le revers du Vol 1 : la compatibilité se décide sur la forme. Un email validé a la forme d'un string — donc il EST un string, et n'importe quel string passe là où on attend un email. Résultat : on revalide partout, ou pire, on oublie. La question du volume, poussée à son sommet : cet invariant que je revérifie sans cesse, puis-je le rendre impossible à ne pas avoir prouvé ?It's the flip side of Vol 1: compatibility is decided on shape. A validated email has the shape of a string — so it IS a string, and any string passes where an email is expected. The result: you re-validate everywhere, or worse, you forget. The volume's question, pushed to its summit: this invariant I keep rechecking, can I make it impossible to hold without having proven?

type Email = string;   // ✗ juste un alias : Email EST string, structurellement

function sendTo(to: Email) { /* ... */ }

sendTo("pas-un-email");      // compile — aucun email validé n'est exigé
sendTo(formInput.value);     // compile — string brut du dehors, jamais vérifié

type Email = string & { readonly __brand: "Email" };

function parseEmail(raw: string): Email | null {
  return /^[^@]+@[^@]+$/.test(raw) ? (raw as Email) : null;
}

function sendTo(to: Email) { /* ... */ }

sendTo("pas-un-email");      // ✗ string n'est PAS assignable à Email
const e = parseEmail(input);
if (e) sendTo(e);            // ✓ seul un Email prouvé franchit la porte

Le brand est un fantôme : il n'existe qu'à la compilation. À l'exécution, Email est un string nu.The brand is a phantom: it exists only at compile time. At runtime, Email is a bare string.

La propriété __brand n'est jamais posée sur la valeur. parseEmail ne fait que mentir au compilateur via un as — sans rien ajouter au string. C'est l'effacement du Vol 2 retourné en outil : le brand vit dans le système de types et s'évapore au runtime. On obtient donc le nominal à la compilation, le structurel à l'exécution. Et la seule chose qui protège l'invariant, c'est que ce as soit confiné à un seul endroit : le validateur.The __brand property is never set on the value. parseEmail merely lies to the compiler via an as — adding nothing to the string. It's Vol 2's erasure turned into a tool: the brand lives in the type system and evaporates at runtime. So you get nominal at compile time, structural at runtime. And the only thing protecting the invariant is that this as is confined to a single place: the validator.

type Email = string & { readonly __brand: "Email" };

const raw: string = "a@b.co";
const mail: Email = raw;   // ✗ Type 'string' is not assignable to type 'Email'
//    ^ le compilateur traite Email comme DISTINCT de string : nominal simulé

Le champ fantôme __brand rend Email plus précis que string : un string n'a pas ce champ, donc il n'est pas assignable. C'est du typage nominal simulé — exactement ce que le structurel (Vol 1) ne donne pas, réintroduit à la carte.The phantom field __brand makes Email more precise than string: a string lacks that field, so it isn't assignable. It's simulated nominal typing — exactly what structural typing (Vol 1) withholds, reintroduced à la carte.

Un type de base, une étiquette unique, et une seule porte d'entrée.A base type, a unique tag, and one way in.

Trois pièces. Le type de base (string, number) porte la donnée réelle. Le brand — une propriété fantôme avec une étiquette littérale unique — le rend distinct au compilateur. Le smart constructor est la seule fonction qui produit la valeur brandée : il valide, puis caste. Tant que le as ne vit que là, tenir la valeur prouve qu'elle est passée par le contrôle. Deux brands d'étiquettes différentes ne sont jamais interchangeables, même sur le même type de base.Three pieces. The base type (string, number) carries the real data. The brand — a phantom property with a unique literal tag — makes it distinct to the compiler. The smart constructor is the only function that produces the branded value: it validates, then casts. As long as the as lives only there, holding the value proves it went through the check. Two brands with different tags are never interchangeable, even on the same base type.

// Le helper générique : un type de base + une étiquette unique.
type Brand<T, B extends string> = T & { readonly __brand: B };

type Email       = Brand<string, "Email">;
type UserId      = Brand<string, "UserId">;
type PositiveInt = Brand<number, "PositiveInt">;

// Le smart constructor : la SEULE porte qui produit un brand.
function toPositiveInt(n: number): PositiveInt {
  if (!Number.isInteger(n) || n <= 0) throw new Error("entier positif requis");
  return n as PositiveInt;   // le seul 'as' autorisé : ici, on a VRAIMENT vérifié
}

const id: UserId = "u_42" as Email;   // ✗ Email n'est pas UserId : brands distincts

Brander tout : une cérémonie qui coûte plus cher que le bug qu'elle prévient.Branding everything: a ceremony costing more than the bug it prevents.

Le brand a un prix : chaque conversion passe par un constructeur ou un as, et chaque calcul reperd le brand qu'il faut reposer. Sur une valeur qui traverse une frontière dangereuse — un email, un identifiant, un montant — ce prix est dérisoire face au bug évité. Sur un index de boucle qui ne quitte jamais la fonction, c'est de la cérémonie pure : du bruit qui masque l'intention, pour une confusion qui n'arriverait jamais. Brander, c'est un choix par invariant, pas un réflexe global.The brand has a price: every conversion goes through a constructor or an as, and every computation loses the brand you must reapply. On a value crossing a dangerous boundary — an email, an id, an amount — that price is trivial against the bug avoided. On a loop index that never leaves the function, it's pure ceremony: noise that hides intent, for a mix-up that would never happen. Branding is a choice per invariant, not a blanket reflex.

type Index   = Brand<number, "Index">;
type Count   = Brand<number, "Count">;
type Celsius = Brand<number, "Celsius">;

function sum(xs: number[]): Count {
  let total = 0 as Count;                 // cérémonie…
  for (let i = 0 as Index; i < xs.length; i = (i + 1) as Index) {  // …à chaque ligne
    total = (total + xs[i]) as Count;     // …pour une valeur qui ne quitte jamais sum()
  }
  return total;
}

Chaque opération arithmétique « casse » le brand (un Count + number redevient number), qu'il faut reposer par un as. Le code se couvre de conversions sans qu'aucun bug réel soit en jeu : ces nombres ne quittent jamais sum(). C'est le contre-exemple obligatoire — brander a coûté plus que le bug qu'il prévient.Every arithmetic op "breaks" the brand (a Count + number becomes number again), to be reapplied with an as. The code drowns in conversions while no real bug is at stake: these numbers never leave sum(). This is the mandatory counter-example — branding cost more than the bug it prevents.