Lo stato che non dovrebbe esistere e invece si può scrivere
Prendi il modo in cui quasi tutti descrivono il caricamento di dati da una rete: un oggetto con un booleano che dice se sta caricando, un campo per i dati e uno per il messaggio d'errore, entrambi facoltativi. Sembra ragionevole, e permette di scrivere combinazioni che non significano niente: dati ed errore insieme, oppure un caricamento che ha già un errore e dei dati.
Le combinazioni possibili sono otto: due valori del booleano, per due possibilità (presente o assente) del campo dei dati, per due dell'errore. Quattro hanno un nome che chiunque capisce: inattivo, in corso, riuscito, fallito. Le altre quattro sono dati più errore, con o senza caricamento, e il caricamento insieme a dati o a errore. Possono avere un senso se lo decidi tu, per esempio un aggiornamento che riparte con i dati vecchi o un nuovo tentativo dopo un errore, ma il tipo non dice quale. Così ogni punto del programma che le incontra se ne inventa uno, e l'incoerenza si vede nella vista, dove un ramo controlla il booleano, un altro la presenza dei dati, e i due possono essere veri insieme.
La soluzione non è gestire meglio quei quattro stati. È rendere impossibile scriverli, in modo che
il compilatore rifiuti il codice che li costruisce. Lo strumento si chiama unione discriminata, e la
parte che vale la pena imparare non è la sintassi: è il controllo che ti avvisa quando aggiungi un
caso e dimentichi di gestirlo. Ti serve sapere come si restringe un tipo con una guardia, che è
l'argomento dell'articolo 03 sulle
type guard, e perché i dati in arrivo da fuori vanno trattati come unknown, come
nell'articolo 02: l'unione
discriminata vale per i valori che il programma costruisce da sé, e il confine con l'esterno resta
un altro problema.
Tutti gli errori del compilatore riportati qui sono quelli di TypeScript 7.0.2, la versione
latest sul registro npm il 2026-11-13, installata in un progetto di prova con
strict attivo; la serie 7 è il compilatore riscritto in Go, annunciato l'8 luglio 2026.
Gli stessi file provati con la 5.9.3 danno gli stessi codici e le stesse posizioni. Ogni blocco è il
file che ho compilato, con in coda l'uscita vera.
La forma piatta: il compilatore approva gli stati senza senso
Prima di costruire la soluzione vale la pena guardare il problema compilato, perché il punto non è che la forma piatta sia brutta: è che il compilatore la approva senza una parola.
// Un booleano e due campi facoltativi: 2 x 2 x 2 = otto combinazioni.
export interface StatoPiatto<T> {
caricamento: boolean;
dati?: T;
errore?: string;
}
// Questa è legittima: nessuna richiesta in corso, niente dati, niente errore.
export const inattivo: StatoPiatto<number> = { caricamento: false };
// Queste due compilano e non descrivono nessuno stato dell'interfaccia:
// dati ed errore insieme, e per di più mentre sta caricando.
export const datiEErrore: StatoPiatto<number> = { caricamento: false, dati: 42, errore: 'fallito' };
export const tuttoInsieme: StatoPiatto<number> = { caricamento: true, dati: 42, errore: 'fallito' };
// Uscita di tsc 7.0.2: nessun errore.
Il compilatore non ha niente da dire sulle tre costanti. La prima, inattivo, è
legittima: nessuna richiesta in corso, niente dati, niente errore. Le altre due sono quelle che il
tipo non dovrebbe lasciar passare. datiEErrore dichiara allo stesso tempo un successo e
un fallimento, e tuttoInsieme aggiunge un caricamento in corso. Non c'è nessun modo di
sapere quale dei tre campi dica la verità, e il tipo sta descrivendo otto combinazioni di cui
quattro sono difetti in attesa di arrivare nella vista.
Un tipo per ogni stato, con un campo che li distingue
// Quattro stati, e nessun campo che esista dove non ha senso.
export type StatoRichiesta<T> =
| { fase: 'inattivo' }
| { fase: 'caricamento'; iniziatoA: number }
| { fase: 'successo'; dati: T }
| { fase: 'errore'; messaggio: string };
export function etichetta<T>(stato: StatoRichiesta<T>): string {
switch (stato.fase) {
case 'inattivo':
return 'Nessuna richiesta';
case 'caricamento':
return 'Caricamento in corso';
case 'successo':
return 'Dati pronti';
case 'errore':
return `Errore: ${stato.messaggio}`;
default:
return controlloEsaustivo(stato);
}
}
// Nel default il tipo è never solo se i casi sopra li coprono tutti.
function controlloEsaustivo(valore: never): never {
throw new Error(`Caso non gestito: ${JSON.stringify(valore)}`);
}
const stati: StatoRichiesta<number>[] = [
{ fase: 'inattivo' },
{ fase: 'caricamento', iniziatoA: 1000 },
{ fase: 'successo', dati: 42 },
{ fase: 'errore', messaggio: 'timeout' },
];
for (const s of stati) console.log(etichetta(s));
// Un valore che arriva da fuori (JSON, per esempio) può non rispettare il tipo.
try {
etichetta(JSON.parse('{"fase":"annullato"}') as StatoRichiesta<number>);
} catch (e) {
console.log((e as Error).message);
}
// Uscita di tsc 7.0.2: nessun errore.
// Uscita di node 24.11.0:
// Nessuna richiesta
// Caricamento in corso
// Dati pronti
// Errore: timeout
// Caso non gestito: {"fase":"annullato"}
Nel blocco, StatoRichiesta elenca quattro forme alternative, e etichetta
le attraversa con uno switch sul campo fase. Dentro ogni
case il compilatore ha già ristretto il tipo: nel ramo 'errore' esiste
stato.messaggio, e scriverlo altrove non compilerebbe. L'uscita di Node mostra i quattro
stati e, nell'ultima riga, il caso di un valore che arriva da fuori con una fase che il tipo non
conosce: la funzione solleva e dice quale valore ha ricevuto, invece di restituire una stringa
sbagliata. Node 24 toglie i tipi senza compilare, quindi quel JSON.parse con un cast è
proprio la situazione in cui il compilatore non aveva giurisdizione.
Il campo fase è il discriminante, ed è la proprietà su cui si decide tutto. Deve avere
tre caratteristiche, e ognuna ha una conseguenza pratica se manca. Le tre prove stanno in un solo
file, con le tre rotture una dopo l'altra.
// 1. Discriminante dichiarato string: la dichiarazione compila, il restringimento no.
type StatoLargo =
| { fase: string }
| { fase: string; dati: number };
export function leggiLargo(s: StatoLargo): number {
if (s.fase === 'successo') {
return s.dati;
}
return 0;
}
// 2. Due rami con lo stesso valore: il compilatore non sa quale dei due sia.
type StessoValore =
| { fase: 'errore'; messaggio: string }
| { fase: 'errore'; codice: number };
export function leggiStesso(s: StessoValore): string {
if (s.fase === 'errore') {
return s.messaggio;
}
return '';
}
// 3. Un ramo senza il discriminante: non si può nemmeno leggere.
type SenzaCampo =
| { fase: 'successo'; dati: number }
| { dati: string };
export function leggiSenza(s: SenzaCampo): number {
if (s.fase === 'successo') {
return s.dati;
}
return 0;
}
// Uscita di tsc 7.0.2:
// 04-discriminante.ts(8,14): error TS2339: Property 'dati' does not exist on type 'StatoLargo'.
// Property 'dati' does not exist on type '{ fase: string; }'.
// 04-discriminante.ts(20,14): error TS2339: Property 'messaggio' does not exist on type 'StessoValore'.
// Property 'messaggio' does not exist on type '{ fase: "errore"; codice: number; }'.
// 04-discriminante.ts(31,9): error TS2339: Property 'fase' does not exist on type 'SenzaCampo'.
// Property 'fase' does not exist on type '{ dati: string; }'.
// 04-discriminante.ts(32,5): error TS2322: Type 'string | number' is not assignable to type 'number'.
// Type 'string' is not assignable to type 'number'.
Il primo caso è un discriminante dichiarato string. La dichiarazione dell'unione
compila senza un avviso, ed è questo il silenzio pericoloso; l'errore arriva più tardi, quando provi
a leggere s.dati dopo il confronto con 'successo', perché un confronto
con una stringa qualunque non permette al compilatore di scegliere il ramo. Il campo deve quindi
avere un tipo letterale, cioè 'successo' e non string.
Il secondo caso sono due rami con lo stesso valore: il confronto con 'errore' non
distingue fra loro, e s.messaggio non è leggibile perché potrebbe essere il ramo con
codice. I valori devono essere diversi fra i rami. Il terzo è un ramo
senza il campo: già leggere s.fase è un errore, perché la proprietà non esiste su tutti
i membri, e il campo deve essere presente in tutti. Nota anche l'ultimo errore,
che è una conseguenza: senza il restringimento s.dati vale string | number,
e non entra in un number.
Il nome del campo è libero: fase, tipo, kind o
stato funzionano identicamente, e la convenzione conta solo per la leggibilità. Quello
che non è libero è la posizione dei dati: dati esiste solo nel ramo
del successo e messaggio solo in quello dell'errore. È questo, e non il discriminante,
che rende impossibile lo stato che aveva dati e un errore insieme: non c'è nessun membro
dell'unione che dichiari entrambi i campi.
Il parametro generico T trasporta il tipo dei dati senza che l'unione debba
conoscerlo: il valore attraversa questa struttura e non viene mai letto dentro, quindi il tipo va
conservato e non verificato. Il campo iniziatoA sul ramo del caricamento mostra la
vera forza dello schema: ogni stato può portare i dati che servono a quello stato,
e una marca temporale di inizio ha senso solo mentre si carica. In un oggetto a campi facoltativi
quel campo sarebbe stato un altro campo vuoto per tre stati su quattro.
Messi uno accanto all'altro, i due tipi si differenziano su quattro punti, indipendenti fra loro, e ognuno risolve un guaio diverso.
- Il numero di stati rappresentabili scende da otto a quattro, e i quattro che restano sono esattamente quelli che hanno un significato.
- I dati non sono più facoltativi: nel ramo del successo
datiè obbligatorio, quindi non esiste un successo senza carico. - Ogni stato può portare campi propri, come
iniziatoAsul caricamento, che nella forma piatta sarebbe stato un quarto campo vuoto per tre stati su quattro. - L'aggiunta di uno stato nuovo diventa un errore di compilazione in ogni punto che consuma il tipo, invece di un ramo mancante che nessuno nota.
Il quarto punto è quello che giustifica il costo degli altri tre, e le prossime sezioni lo dimostrano. I primi tre sono vantaggi di precisione che puoi ottenere anche con disciplina e revisione del codice; il quarto è un controllo meccanico che continua a funzionare quando il programma cresce e chi lo modifica non è più chi lo ha scritto.
Il controllo che ti avvisa quando l'unione cresce
La parte del blocco che sembra strana è la funzione finale, quella che accetta un parametro di tipo
never. Non è una curiosità accademica: è il motivo per cui questo schema si mantiene
nel tempo, e si capisce meglio vedendola fallire.
never è il tipo senza nessun valore possibile. Quando il compilatore ha esaminato
tutti i rami di un'unione dentro uno switch, nel ramo default il tipo
della variabile si è ridotto a never, perché non resta nessuna possibilità. Passarlo
a una funzione che accetta never è quindi lecito. Se invece un caso non è gestito,
nel default resta quel caso, e un tipo con valori non è assegnabile a
never: lo dice l'Handbook, secondo cui never è assegnabile a ogni tipo
ma nessun tipo è assegnabile a never, tranne never stesso. Il controllo
scatta a tempo di compilazione. Ecco lo stesso file senza il caso 'errore':
export type StatoRichiesta<T> =
| { fase: 'inattivo' }
| { fase: 'caricamento'; iniziatoA: number }
| { fase: 'successo'; dati: T }
| { fase: 'errore'; messaggio: string };
export function etichetta<T>(stato: StatoRichiesta<T>): string {
switch (stato.fase) {
case 'inattivo':
return 'Nessuna richiesta';
case 'caricamento':
return 'Caricamento in corso';
case 'successo':
return 'Dati pronti';
default:
return controlloEsaustivo(stato);
}
}
function controlloEsaustivo(valore: never): never {
throw new Error(`Caso non gestito: ${JSON.stringify(valore)}`);
}
// Uscita di tsc 7.0.2:
// 03-caso-mancante.ts(16,33): error TS2345: Argument of type '{ fase: "errore"; messaggio: string; }' is not assignable to parameter of type 'never'.
Il messaggio è migliore di qualunque commento: non dice «hai dimenticato un caso», dice
quale, con tutti i suoi campi, e punta alla riga 16, colonna 33, cioè
all'argomento passato al controllo. Il giorno in cui qualcuno aggiunge uno stato
'annullato' all'unione, ogni switch del progetto che la consuma si rompe in
compilazione, e il messaggio nomina lo stato nuovo. È la differenza fra un refactoring che si fa
seguendo gli errori e uno che si fa cercando con il grep e sperando di aver trovato tutto.
Una precisazione sul perché la funzione dichiara never come tipo di ritorno. Dal
TypeScript 3.7 il compilatore tratta la chiamata a una funzione che dichiara never
come un punto da cui non si esce: lo spiegano le note di rilascio di quella versione, dove il
return davanti a process.exit(1) non serve più. Ho provato che cosa cambia
nel nostro caso, togliendo il return davanti alla chiamata.
type Stato = { fase: 'a' } | { fase: 'b' };
function esaurito(valore: never): never {
throw new Error(`Caso non gestito: ${JSON.stringify(valore)}`);
}
// Senza "return" davanti alla chiamata, con noImplicitReturns attivo.
export function etichetta(s: Stato): string {
switch (s.fase) {
case 'a':
return 'A';
case 'b':
return 'B';
default:
esaurito(s);
}
}
// Stessa cosa, ma la funzione NON ha il tipo di ritorno dichiarato.
const esauritoSenzaAnnotazione = (valore: never) => {
throw new Error(`Caso non gestito: ${JSON.stringify(valore)}`);
};
export function etichetta2(s: Stato): string {
switch (s.fase) {
case 'a':
return 'A';
case 'b':
return 'B';
default:
esauritoSenzaAnnotazione(s);
}
}
// Uscita di tsc 7.0.2:
// 05-niente-return.ts(24,39): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.
Il primo etichetta compila: la chiamata a esaurito, dichiarata con
never esplicito, chiude il percorso. Il secondo no, e l'errore TS2366 è alla riga 24: la
funzione ausiliaria è un'espressione a freccia senza il tipo scritto, e per il compilatore la
chiamata non è più un punto di non ritorno, quindi la funzione può finire senza valore. Due note per
non fraintendere. L'errore compare identico anche senza l'opzione noImplicitReturns
(l'ho provato), quindi non è quella a decidere. E la parte che solleva, nel corpo di
controlloEsaustivo, serve a un'altra cosa: protegge a tempo di esecuzione dal valore
che arriva da fuori, dove il compilatore non aveva giurisdizione, e in quel caso fallire subito e
dire quale valore è arrivato è meglio che restituire una stringa vuota.
Resta da capire quando la funzione con il default serve davvero, e quando senza si
starebbe comunque protetti. L'ultimo file dimostra la differenza.
type Stato = { fase: 'a' } | { fase: 'b' } | { fase: 'c' };
// Restituisce un valore: con un caso mancante il compilatore se ne accorge da solo.
export function etichetta(s: Stato): string {
switch (s.fase) {
case 'a':
return 'A';
case 'b':
return 'B';
}
}
// Non restituisce niente: con un caso mancante il compilatore tace.
export function registra(s: Stato): void {
switch (s.fase) {
case 'a':
console.log('A');
break;
case 'b':
console.log('B');
break;
}
}
// Uscita di tsc 7.0.2:
// 06-senza-default.ts(4,38): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.
Per una funzione che restituisce un valore, il compilatore si accorge da solo di un caso mancante:
TS2366, alla riga 4. Il messaggio però non dice quale caso manca. Per una funzione
che non restituisce niente, come registra, non dice proprio niente: lo
switch incompleto passa in silenzio, e il caso 'c' viene ignorato. È lì
che il default con il controllo su never guadagna il proprio posto, e
altrove ti dà almeno il nome del caso.
Che cosa si perde, perché qualcosa si perde
Lo schema ha un prezzo e va detto, perché i confronti onesti sono più utili dei consigli. Scrivere
e leggere questi stati è più verboso: non puoi più toccare stato.dati direttamente,
devi prima passare dal controllo sulla fase. In un template questo significa un ramo per stato
invece di un paio di condizioni, e su stati molto semplici è lavoro in più senza guadagno.
La soglia che uso per decidere è il numero di combinazioni illegali. Con un booleano e un solo campo facoltativo le combinazioni sono quattro e hanno quasi tutte un senso, quindi il costo di gestirle a mano è basso. Da tre campi in su il conto cresce come una potenza di due, e l'unione discriminata diventa la scelta meno costosa, non la più rigorosa. L'altro segnale, più affidabile del conteggio, è di natura diversa: se ti accorgi di scrivere un commento che spiega quali combinazioni di campi sono valide, quel commento è un tipo che non hai scritto.
Resta un secondo prezzo, meno ovvio: il controllo con never protegge dove lo scrivi, e
in nessun altro posto. Una catena di if funziona esattamente come uno
switch se il ramo finale pretende never; se il ramo finale è un
else generico, il caso nuovo ci finisce dentro senza un errore.
type Stato =
| { fase: 'inattivo' }
| { fase: 'successo'; dati: number }
| { fase: 'errore'; messaggio: string };
function esaurito(valore: never): never {
throw new Error(`Caso non gestito: ${JSON.stringify(valore)}`);
}
// Catena di if con il ramo finale che pretende never: copre tutto.
export function conControllo(s: Stato): string {
if (s.fase === 'inattivo') {
return 'fermo';
} else if (s.fase === 'successo') {
return `dati: ${s.dati}`;
} else {
return esaurito(s);
}
}
// Stessa catena, ma il ramo finale è un else generico: il caso 'errore' finisce lì dentro.
export function senzaControllo(s: Stato): string {
if (s.fase === 'inattivo') {
return 'fermo';
} else if (s.fase === 'successo') {
return `dati: ${s.dati}`;
}
return 'altro';
}
// Uscita di tsc 7.0.2:
// 07-catena-if.ts(17,21): error TS2345: Argument of type '{ fase: "errore"; messaggio: string; }' is not assignable to parameter of type 'never'.
La prima funzione, conControllo, non compila perché in questo esperimento ho lasciato
fuori il ramo dell'errore: il compilatore lo nomina, alla riga 17. La seconda, che chiude con
return 'altro', non produce nessun errore, e quel valore di scorta nasconde il caso
dimenticato. Un template o un'espressione che non contengono il controllo sono nella stessa
situazione, ragionamento che non ho provato su un template di framework. Per questo conviene far
passare la decisione da una sola funzione che restituisce quello che serve alla vista, come
etichetta, invece di distribuire la logica degli stati nella vista stessa.
Quattro segnali dicono che è il momento di passare all'unione discriminata. Si riconoscono indipendentemente l'uno dall'altro, e basta che se ne presenti uno.
- Stai scrivendo un commento che spiega quali combinazioni di campi sono valide: quel commento è un tipo che non hai scritto.
- In un punto del codice leggi un campo facoltativo con un punto esclamativo o un cast, perché «là dentro c'è sicuramente».
- Un test deve costruire un oggetto con campi che non gli servono, solo per soddisfare il tipo.
- Nella vista due condizioni possono essere vere insieme e l'ordine dei rami decide che cosa si vede: è il sintomo che gli stati si sovrappongono.
I quattro segnali hanno in comune un fatto: il codice sa qualcosa sullo stato che il tipo non sa. Il punto esclamativo e il cast sono la forma più visibile, perché dicono «fidati» al compilatore; la correzione è spostare quella conoscenza dentro il tipo, in modo che non debba più essere ripetuta in ogni punto di lettura.
Che cosa sai fare adesso
Adesso sai riconoscere il sintomo, cioè un oggetto con più campi facoltativi che insieme descrivono uno stato, e sai che il numero di stati illegali che quel tipo autorizza cresce come una potenza di due. Sai costruire l'unione discriminata che li rende inesprimibili, e sai le tre condizioni sul discriminante, ognuna con l'errore che il compilatore produce se la rompi: tipo letterale, valore diverso in ogni ramo, campo presente in tutti.
Sai anche aggiungere il controllo di esaustività con never, e che cosa risponde il
compilatore quando un caso manca: nomina il caso dimenticato con tutti i suoi campi. Sai che serve
soprattutto dove una funzione non restituisce un valore, e che vale dove lo scrivi. La prova che
funziona la puoi fare adesso, aggiungendo un quinto stato alla tua unione e contando quanti punti
del programma si rifiutano di compilare. Quelli sono i punti che avresti dovuto trovare a mano.
Nel prossimo articolo, 05 su
satisfies, la stessa precisione si applica a un oggetto letterale, come un catalogo
di voci: perché annotarlo con un'interfaccia distrugge l'informazione sulle sue chiavi, e che cosa
usare al suo posto. L'inizio della serie, sulle vie di fuga che strict lascia aperte,
è nell'articolo 01.
Domande frequenti
Che cos'è un'unione discriminata?
Un tipo composto da più forme alternative, ognuna con un campo in comune il cui valore letterale è diverso in ciascuna. Il compilatore usa quel campo per capire in quale forma si trova e restringe il tipo di conseguenza, quindi i campi di una forma non sono leggibili nelle altre.
Perché il discriminante non può essere di tipo string?
Perché il restringimento funziona solo su tipi letterali. Dichiarare il campo come string compila senza errori, ma poi leggere un campo specifico di un ramo, dopo il confronto, produce l'errore TS2339: il compilatore non può più scegliere il ramo.
A che serve una funzione che accetta un parametro never?
A verificare l'esaustività. Nel ramo default di uno switch che copre tutti i casi, il tipo si è ridotto a never e l'assegnazione è lecita. Se un caso manca, quel caso resta nel default, non è assegnabile a never, e il compilatore lo segnala nominandolo.
Il controllo di esaustività funziona anche sugli if?
Sì, se il ramo finale della catena pretende never, proprio come il default di uno switch. Se il ramo finale è un else generico o un valore di scorta, un caso nuovo ci finisce dentro senza nessun errore. Il controllo vale dove lo scrivi.
Quando non vale la pena usare un'unione discriminata?
Quando le combinazioni illegali sono poche, cioè con un booleano e un solo campo facoltativo: il costo di gestirle a mano è inferiore alla verbosità del tipo. Il segnale che la soglia è passata è di solito un commento che spiega quali combinazioni di campi sono valide, perché quel commento è un tipo non scritto.
Nella stessa serie trovi anche Tipi template literal.
Fonti
- TypeScript Handbook - Narrowing: il passo sulle unioni discriminate, sul tipo
nevere sul controllo di esaustività, letto; consultata il 2026-11-13. - TypeScript 3.7 - note di rilascio: il passo sulle funzioni che ritornano
nevere sul controllo di flusso, letto; consultata il 2026-11-13. - Announcing TypeScript 7.0: la data (8 luglio 2026) e la natura del compilatore usato per le prove, solo l'apertura letta; consultata il 2026-11-13.
- Gli errori e le uscite di Node sono prodotti dai comandi
tsc --noEmit --strict --noImplicitReturns --target ES2022 --module ESNext --moduleResolution bundler file.ts(typescript 7.0.2,npm view typescript versionil 2026-11-13) enode file.ts(Node 24.11).
Commenti
Caricamento commenti...
Accedi per commentare