Messages d’erreur dans les DSL au niveau des types
Afficher des erreurs de compilation utiles aux utilisateurs de DSL.
Messages d’erreur dans les DSL au niveau des types est une leçon TypeScript Academy gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. 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 4 leçons au total.
Des erreurs utiles dans les DSL de niveau type
La partie la plus difficile d’une DSL de niveau type consiste à rendre les échecs lisibles. Les erreurs brutes never ou "not assignable" déconcertent les utilisateurs. Nous affichons des erreurs descriptives au moyen de types d’erreur marqués et de messages never soigneusement conçus.
Le problème avec never
Lorsque la validation échoue en se résolvant en never, le compilateur indique "Argument of type X is not assignable to never", ce qui n’explique pas à l’utilisateur pourquoi. Nous pouvons faire mieux.
Types d’erreur marqués
Au lieu de renvoyer simplement never, renvoyez un type d’erreur à la forme unique qui contient, dans son type, une chaîne de caractères avec un message compréhensible.
type TypeError<Msg extends string> = {
readonly __error: Msg;
};
type E = TypeError<"Column 'foo' does not exist">;Renvoyer des erreurs depuis la validation
Un validateur renvoie soit le type de la valeur valide, soit une erreur marquée qui décrit le problème. La vérification « contient un point » est un motif de littéral de gabarit (avec des accents graves dans le code réel) ; nous le désignons par HasDot.
// HasDot<S> is the backtick pattern: any text, ".", any text.
type Validate<S extends string> =
S extends HasDot
? S
: TypeError<"Path must contain a dot, e.g. user.name">;Forcer l’affichage de l’erreur
Contraignez le paramètre afin que le passage d’une valeur qui n’est pas assignable à la marque d’erreur affiche le message. Le type d’erreur apparaît directement dans la sortie du compilateur.
declare function path<S extends string>(
p: Validate<S> extends TypeError<infer M> ? TypeError<M> : S
): void;
path("oops");
// Error message includes: __error: "Path must contain a dot..."Distinguer plusieurs erreurs
Les différents échecs renvoient des messages différents, ce qui fournit aux utilisateurs des indications précises plutôt qu’un rejet générique. HasDot désigne à nouveau le motif de littéral de gabarit entre accents graves pour « contient un point ».
type Check<S extends string> =
S extends "" ? TypeError<"Path cannot be empty">
: S extends HasDot ? S
: TypeError<"Missing dot separator">;never avec une astuce
Une autre technique associe une position de valeur à un message littéral afin qu’il apparaisse au survol. Vous intersectez le type problématique avec un objet étiqueté.
type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the causeLes erreurs dans les DSL fluides
Dans une DSL enchaînée, faites en sorte que l’étape suivante non valide renvoie un type marqué comme erreur plutôt qu’une étape valide, afin que l’éditeur affiche le message exactement là où l’erreur est commise.
interface Stage {
// calling done() before where() yields a labeled error
done(): TypeError<"Call .where() before .done()">;
}Garder des messages courts
Les types de messages longs alourdissent la sortie du compilateur et ralentissent les outils. Privilégiez des formulations concises et directement exploitables. Incluez le jeton problématique lorsque cela ne coûte presque rien, mais évitez les interpolations volumineuses.
Tester vos erreurs
Écrivez des tests de niveau type qui vérifient que la marque d’erreur apparaît pour des entrées connues comme incorrectes, afin que les remaniements ne dégradent pas silencieusement l’expérience de développement.
type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;Pourquoi est-ce important
Une DSL ne vaut que par la qualité de ses erreurs. Les types d’erreur marqués transforment les échecs cryptiques de never en messages explicites, ce qui améliore considérablement l’utilisation de votre API de niveau type.
Vérification rapide
Vérifiez votre compréhension des messages d’erreur de niveau type.
Récapitulatif
Pour rendre les DSL de niveau type utilisables, remplacez never seul par des types d’erreur marqués qui intègrent des messages lisibles. Les validateurs renvoient soit le type valide, soit une marque d’erreur spécifique ; les contraintes appliquées aux paramètres font apparaître le message dans la sortie du compilateur. Gardez les messages courts et testez-les.
Questions Fréquemment Posées
La leçon « Messages d’erreur dans les DSL au niveau des types » est-elle gratuite ?
Oui — le texte complet de « Messages d’erreur dans les DSL au niveau des types » 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 4 leçons au total.
Qu'est-ce que j'apprendrai dans « Messages d’erreur dans les DSL au niveau des types » ?
Afficher des erreurs de compilation utiles aux utilisateurs de DSL. 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 4 sur 4.
Combien de temps prend la leçon « Messages d’erreur dans les DSL au niveau des types » ?
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
- Qu’est-ce qu’un DSL au niveau des types
- Concevoir un DSL de requêtes fluide
- Validation des entrées à la compilation
- Messages d’erreur dans les DSL au niveau des types