Le type branding en TypeScript : usages, code et limites

Résumé : Le type branding en TypeScript distingue des valeurs qui partagent la même forme, mais représentent des concepts différents. Cette technique ajoute une marque au niveau du système de types, sans modifier la valeur à l’exécution. Elle limite certaines erreurs de programmation, à condition de contrôler la création des valeurs et de ne pas confondre sécurité de typage et validation réelle des données.

Deux nombres peuvent-ils désigner des réalités si différentes qu’une fonction ne devrait jamais les confondre ? C’est le cas d’un identifiant utilisateur et d’un identifiant de commande. TypeScript face à JavaScript aide à situer l’intérêt du typage, mais les alias simples ne suffisent pas toujours à distinguer ces valeurs.

Le type branding en TypeScript simule une distinction nominale dans un langage principalement structurel. Il permet au compilateur de refuser certains échanges accidentels entre valeurs compatibles en apparence. Pour des équipes qui développent des applications métier en France, ce repère peut clarifier les contrats entre fonctions et les frontières entre domaines.

Pourquoi distinguer des valeurs de même type ?

Imaginez deux paramètres représentés par le type number : userId et orderId. Avec de simples alias, comme type UserId = number et type OrderId = number, TypeScript considère les deux types comme équivalents. Une fonction peut donc recevoir le mauvais identifiant sans signaler cette confusion.

Ce comportement découle du typage structurel : la compatibilité dépend de la forme des valeurs, et non simplement du nom attribué à leur type. La documentation TypeScript présente ce principe comme une caractéristique du langage. Le branding ajoute une marque distinctive à cette forme pour séparer des concepts qui partagent pourtant le même type de base.

Comment définir un type brandé ?

Une approche courante consiste à créer un type générique fondé sur une intersection. Par exemple, type Brand<T, B extends string> = T & { readonly __brand: B } associe à la valeur de base T une marque B. Vous pouvez ensuite définir UserId comme Brand<number, « UserId »> et OrderId comme Brand<number, « OrderId »>.

La propriété __brand n’est pas ajoutée à chaque nombre lorsque le code s’exécute. Elle sert au compilateur pour différencier les types. Une valeur number ordinaire ne devient donc pas automatiquement un UserId : il faut une assertion ou une fonction qui la transforme en valeur brandée du point de vue du typage.

Dans une application métier, cette distinction peut aider à prévenir l’échange accidentel d’identifiants dans les signatures de fonctions et les modèles de données. Elle ne remplace toutefois pas une vérification de la provenance ni de la validité des valeurs.

Comment créer et valider les valeurs ?

Une assertion telle que value as UserId est concise, mais elle ne vérifie pas que value représente réellement un identifiant valide. Elle demande simplement au compilateur de traiter cette valeur comme le type brandé indiqué. Utilisez-la près d’une frontière contrôlée et évitez de la disperser dans le code.

Une fonction de construction rend cette opération plus explicite. Elle peut vérifier une règle métier avant d’affirmer le type : par exemple, confirmer qu’un numéro est strictement positif avant de le considérer comme un PositiveNumber. Le dépôt de ts-brand illustre un utilitaire générique et la possibilité d’y associer une fonction de validation.

Pour des données provenant d’une API, d’un formulaire ou d’une base externe, validez d’abord leur contenu à l’exécution. Un prédicat de type peut ensuite indiquer à TypeScript qu’une valeur vérifiée satisfait le type attendu. Le compilateur ne contrôle pas si la logique de ce prédicat correspond correctement à la règle métier : cette responsabilité reste dans votre code.

Branding, flavoring ou union : que choisir ?

Le branding strict convient lorsque vous voulez exiger une conversion explicite avant d’accepter une valeur. Le flavoring repose sur un marqueur optionnel : il peut permettre à une valeur non brandée d’être acceptée, tout en gardant une distinction entre certaines marques incompatibles. Cette souplesse réduit les conversions explicites, mais elle rend l’entrée dans le type moins stricte.

Si un état ne peut prendre qu’un petit nombre de valeurs prédéfinies, une union de chaînes littérales est souvent plus directe. Par exemple, un statut limité à « en attente », « accepté » ou « refusé » se décrit naturellement avec ces choix explicites. Le guide de style TypeScript de Google rappelle lui aussi que le langage privilégie les types structurels, ce qui aide à comprendre pourquoi le branding reste un motif de conception plutôt qu’un typage nominal natif.

Le choix des outils et du cadre technique dépend aussi de l’architecture globale. Pour élargir cette réflexion, consultez les technologies et frameworks les plus utilisés. Dans une interface React, le branding concerne surtout les données et paramètres métier, et non le rendu des composants. Les questions propres à la bibliothèque sont abordées dans les avantages de React.

Quelles sont ses limites et quand l’utiliser ?

Le branding protège contre certaines erreurs de programmation, pas contre toutes les erreurs possibles. Une assertion erronée peut contourner la distinction, et le type brandé ne valide pas les données reçues à l’exécution. Il ne bloque pas non plus les opérations arithmétiques incohérentes par lui-même. Traitez-le comme un garde-fou de conception, et non comme une frontière de sécurité.

La documentation d’Effect sur les types brandés distingue notamment les marques nominales des constructeurs raffinés qui intègrent une validation. Cette différence est essentielle : déclarer un nombre comme positif ne le rend pas positif. Seule une vérification réelle de la valeur peut établir cette propriété au moment de l’exécution.

Avant d’ajouter une marque, posez-vous trois questions : les concepts sont-ils réellement différents, une confusion serait-elle coûteuse, et l’équipe saura-t-elle construire les valeurs de façon cohérente ? Si le modèle devient difficile à lire ou si les assertions se multiplient, une fonction de validation, une union ou un objet avec ses propres invariants sera peut-être plus clair.