Types opaques et brands pour éviter les confusions d’unités
Évitez les confusions d’unités ou de balises en combinant les types de base avec des propriétés phantom brand ; construisez-les uniquement au moyen de fonctions fabriques.
Types opaques et brands pour éviter les confusions d’unités est une leçon TypeScript Academy gratuite sur CoddyKit. Ceci est la leçon 1 sur 3. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage TypeScript Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours TypeScript Academy comprend 3 leçons au total.
Introduction
Objectif : distinguer les valeurs qui se ressemblent au niveau des types. Un simple number ne permet pas de distinguer les mètres des secondes ; un marqueur de marque le permet.
- Aucun coût d’exécution
- Des APIs et des refactorisations plus sûres
- Créer uniquement au moyen de fabriques
Marquer les unités primitives
Les marqueurs de marque séparent les unités lors de la vérification des types ; un ordre d’arguments incorrect échoue lors de cette vérification.
type Meter = number & { readonly __brand: "meter" }
type Second = number & { readonly __brand: "second" }
function meter(n: number): Meter { return n as Meter }
function second(n: number): Second { return n as Second }
const d = meter(100)
const t = second(9)
function speed(dist: Meter, time: Second) { return (dist as number) / (time as number) }
// speed(t, d) // compile error: brands do not matchAssistant de marque générique
Utilisez un assistant générique Brand dans différents domaines : identifiants typés, jetons, curseurs, etc.
type Brand<Tag extends string, T> = T & { readonly __brand: Tag }
type UserId = Brand<"UserId", string>
type OrderId = Brand<"OrderId", string>
function userId(x: string): UserId { return x as UserId }
function orderId(x: string): OrderId { return x as OrderId }
function findUser(id: UserId) { /* ... */ }
const u = userId("u_123")
const o = orderId("o_456")
// findUser(o) // error: OrderId not assignable to UserIdMarque de symbole unique
La marque symbole unique évite les collisions de noms et les fuites dans les espaces de noms globaux.
declare const MeterSym: unique symbol
type Meter2 = number & { readonly [MeterSym]: "meter" }
function asMeter2(n: number): Meter2 { return n as Meter2 }
const m2 = asMeter2(5)
// const wrong: Meter2 = 5 // discourage raw assignment; prefer factoriesFonctions de fabrique et validation
Placez la marque dans une fonction de fabrique : validez d’abord, marquez ensuite, puis utilisez la valeur. Évitez les as ajoutés au cas par cas sur les sites d’appel.
type NonEmptyString = string & { readonly __brand: "NonEmpty" }
function nonEmpty(s: string): NonEmptyString | null {
return s.trim().length > 0 ? (s as NonEmptyString) : null
}
function makeSlug(s: NonEmptyString) {
return (s as string).toLowerCase().replace(/\s+/g, "-")
}
const ok = nonEmpty(" Hello ")
if (ok) { makeSlug(ok) } // safe: validated & branded firstConseils et pièges
Bonnes pratiques :
- Gardez des noms de marques courts et explicites.
- Exposez les fabriques comme seul moyen d’obtenir des valeurs marquées.
- Ne divulguez pas les marques dans les types d’API publiques, sauf si nécessaire.
- Les marques existent uniquement au niveau des types : aucun surcoût à l’exécution.
Vérification du marquage
Vérification rapide : quel modèle évite les confusions entre unités et étiquettes ?
Récapitulatif
Récapitulatif : les types marqués ou opaques séparent les valeurs qui se ressemblent (mètres et secondes, UserId et OrderId). Produisez-les au moyen de fabriques, utilisez-les dans les API et éliminez les confusions accidentelles.
Apprends TypeScript avec un tuteur IA — gratuit
Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.
- Cours
- 101
- Leçons
- 352
Questions Fréquemment Posées
La leçon « Types opaques et brands pour éviter les confusions d’unités » est-elle gratuite ?
Oui — le texte complet de « Types opaques et brands pour éviter les confusions d’unités » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours TypeScript Academy, passe à CoddyKit PRO. Le cours TypeScript Academy comprend 3 leçons au total.
Qu'est-ce que j'apprendrai dans « Types opaques et brands pour éviter les confusions d’unités » ?
Évitez les confusions d’unités ou de balises en combinant les types de base avec des propriétés phantom brand ; construisez-les uniquement au moyen de fonctions fabriques. Tu pratiques TypeScript Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.
Dois-je avoir de l'expérience pour commencer TypeScript Academy ?
Aucune expérience préalable n'est requise. TypeScript Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 3.
Combien de temps prend la leçon « Types opaques et brands pour éviter les confusions d’unités » ?
La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.
Peux-tu écrire et exécuter du code dans cette leçon TypeScript Academy ?
Oui. Chaque leçon TypeScript Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.
Toutes les leçons de ce cours
- Types opaques et brands pour éviter les confusions d’unités
- Identifiants marqués et motifs de modélisation métier
- Modélisation métier — agrégats, invariants et services