Messaggi di errore nelle DSL a livello di tipo
Mostri errori di compilazione utili agli utenti della DSL.
Messaggi di errore nelle DSL a livello di tipo è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 4 lezioni in totale.
Messaggi di errore utili nei DSL a livello di tipo
La parte più difficile di un DSL a livello di tipo consiste nel rendere gli errori leggibili. Gli errori grezzi con never o "non assegnabile" confondono gli utenti. Possiamo mostrare errori descrittivi usando tipi di errore branded e messaggi never costruiti ad hoc.
Il problema di never
Quando la validazione fallisce restituendo never, il compilatore segnala "l'argomento di tipo X non è assegnabile a never", senza spiegare all'utente perché. Possiamo fare di meglio.
Tipi di errore branded
Invece di un semplice never, restituisca un tipo di errore dalla forma univoca che contenga nel proprio tipo una stringa con un messaggio leggibile.
type TypeError<Msg extends string> = {
readonly __error: Msg;
};
type E = TypeError<"Column 'foo' does not exist">;Restituire errori dalla validazione
Un validatore restituisce il tipo del valore valido oppure un errore branded che descrive il problema. Il controllo "contiene un punto" è un pattern di template literal (nel codice reale si usano i backtick); qui lo indichiamo con 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">;Forzare la visualizzazione dell'errore
Vincoli il parametro in modo che il passaggio di un valore non assegnabile al brand dell'errore mostri il messaggio. Il tipo di errore compare direttamente nell'output del compilatore.
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..."Distinguere più errori
I diversi fallimenti restituiscono messaggi diversi, così gli utenti ricevono indicazioni specifiche invece di un unico rifiuto generico. Anche qui HasDot è il pattern di template literal con backtick per "contiene un punto".
type Check<S extends string> =
S extends "" ? TypeError<"Path cannot be empty">
: S extends HasDot ? S
: TypeError<"Missing dot separator">;never, con una variante
Un'altra tecnica associa una posizione di valore a un messaggio literal, in modo che questo venga mostrato al passaggio del mouse. Interseca il tipo che causa il problema con un oggetto etichettato.
type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the causeErrori nei DSL fluenti
In un DSL concatenato, fai in modo che il passaggio successivo non valido restituisca un tipo con errore branded invece di uno stage valido, così l'editor mostra il messaggio esattamente nel punto in cui si trova l'errore.
interface Stage {
// calling done() before where() yields a labeled error
done(): TypeError<"Call .where() before .done()">;
}Mantenere brevi i messaggi
I tipi con messaggi lunghi appesantiscono l'output del compilatore e rallentano gli strumenti di sviluppo. Preferisca frasi concise e operative. Includa il token che causa il problema quando è poco costoso farlo, ma eviti interpolazioni enormi.
Testare gli errori
Scriva test a livello di tipo che verifichino la presenza del brand dell'errore per input notoriamente errati, così i refactoring non peggioreranno silenziosamente l'esperienza degli sviluppatori.
type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;Perché è importante
Un DSL è valido quanto lo sono i suoi errori. I tipi di errore branded trasformano i fallimenti criptici con never in messaggi autoesplicativi, migliorando notevolmente l'esperienza di utilizzo della propria API a livello di tipo.
Verifica rapida
Confermi la sua comprensione dei messaggi di errore a livello di tipo.
Riepilogo
Per rendere utilizzabili i DSL a livello di tipo, sostituisca il semplice never con tipi di errore branded che contengano messaggi leggibili. I validatori restituiscono il tipo valido oppure uno specifico brand di errore; vincolare i parametri mostra il messaggio nell'output del compilatore. Mantenga brevi i messaggi e li sottoponga a test.
Domande Frequenti
La lezione «Messaggi di errore nelle DSL a livello di tipo» è gratuita?
Sì — il testo completo di «Messaggi di errore nelle DSL a livello di tipo» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 4 lezioni in totale.
Cosa imparerò in «Messaggi di errore nelle DSL a livello di tipo»?
Mostri errori di compilazione utili agli utenti della DSL. Eserciti TypeScript Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare TypeScript Academy?
Non è richiesta alcuna esperienza precedente. TypeScript Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.
Quanto tempo richiede la lezione «Messaggi di errore nelle DSL a livello di tipo»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione TypeScript Academy?
Sì. Ogni lezione TypeScript Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Che cos’è una DSL a livello di tipo
- Progettare una DSL fluente per le query
- Validazione degli input in fase di compilazione
- Messaggi di errore nelle DSL a livello di tipo