Il punto in cui il tipo che hai scritto smette di essere vero
Dentro il tuo programma i tipi sono una cosa seria: li scrivi, il compilatore li verifica, e se
sbagli te lo dice. Poi arriva una riga che legge una risposta HTTP, oppure una stringa
dall'archivio del browser, oppure il corpo di un messaggio in coda, e in quel punto il tipo non è
più una verifica: è una speranza. Nessuno ha controllato niente. Tu hai scritto che quella cosa è
un Profilo, e il compilatore ti ha creduto sulla parola.
Quel punto si chiama confine, e in un'applicazione ce ne sono pochi: le chiamate di rete, la
lettura da un archivio locale, i parametri nell'indirizzo, i messaggi di una coda, il contenuto di
un file. Sono pochi e sono tutti il posto in cui nascono gli errori più difficili da leggere,
perché il guasto si manifesta lontano dal punto in cui il dato è entrato sbagliato. Questo
articolo riguarda una sola decisione, da prendere su ognuno di quei confini: scriverci
any oppure unknown, e che cosa cambia davvero. Se ti serve prima il quadro
di quante vie di fuga restano in un progetto strict, è
l'articolo precedente.
I due tipi sembrano simili e fanno il contrario
Entrambi accettano qualunque valore in ingresso, e qui finisce la somiglianza. La differenza sta in
che cosa ti lasciano fare dopo. Con any puoi fare tutto: leggere una proprietà,
chiamarlo come funzione, usarlo in un'addizione. Nessuna di queste operazioni viene verificata, e
any è contagioso, perché il risultato di un'operazione su any è ancora
any, e il buco si allarga lungo il percorso del dato.
Con unknown non puoi fare niente, finché non dimostri che cosa è. Non è una
limitazione: è l'intera funzionalità. unknown sposta il momento del controllo dal
punto in cui non sai nulla al punto in cui hai appena verificato, e li collega. Il prezzo lo paghi
subito, in righe di codice, e una volta sola.
Il modo più rapido di vedere la differenza è una cosa che questo progetto ha già attiva senza
averla scelta esplicitamente. Fra i nove controlli che strict accende c'è
useUnknownInCatchVariables, e il suo effetto è esattamente questo: la variabile di un
blocco catch non è any ma unknown. È il motivo per cui in
questo repository la gestione di un errore è scritta così e non in modo più breve.
// useUnknownInCatchVariables (attivo con strict) tipizza 'err' come unknown.
export function messaggioDiErrore(err: unknown): string {
if (err instanceof Error) {
return err.message;
}
if (typeof err === 'string') {
return err;
}
return 'Errore sconosciuto';
}
Tre cose di questo blocco sono la sostanza dell'articolo, e vale la pena nominarle una per una.
err instanceof Error è un restringimento: una verifica che il compilatore riconosce e
di cui si fida, perché controlla la catena dei prototipi a tempo di esecuzione. Dentro quel
if, e solo là, err ha tipo Error, quindi
err.message è una lettura verificata e non un'affermazione. Da notare che non vale per
ogni valore lanciato: in JavaScript si può lanciare qualunque cosa, una stringa o un numero
compresi, e per questo il blocco ha un secondo ramo.
typeof err === 'string' è la seconda forma di restringimento, quella che funziona sui
tipi primitivi. Le due coprono casi diversi e non sono interscambiabili:
instanceof lavora sulle classi e non funziona sui primitivi, typeof
lavora sui primitivi e su una stringa restituisce 'string', ma su qualunque oggetto
restituisce 'object' e quindi non distingue nulla.
Il ritorno finale esiste perché, con strictNullChecks, una funzione che dichiara di
restituire string deve restituirlo su ogni percorso, e il percorso in cui il valore
lanciato non è né un Error né una stringa è un percorso reale. Provato: senza quella
riga il compilatore risponde error TS2366: Function lacks ending return statement and return
type does not include 'undefined'., con o senza noImplicitReturns, mentre con
--strict false l'errore sparisce, perché undefined rientra in ogni tipo. È
un motivo in più per non spegnere strict. Il caso, poi, capita davvero: un
Promise.reject() senza argomenti lancia undefined, e il blocco lo gestisce.
Che cosa dice il compilatore quando salti il passaggio
Tutti i blocchi di questo articolo sono stati compilati con quella versione e quei tre flag, e le
uscite riportate sono quelle vere. Con questa versione strict è acceso anche quando non lo scrivi:
un file passato a tsc senza nessuna opzione ha dato lo stesso TS2366.
Vale la pena vedere l'errore vero, perché è quello che incontrerai ed è più preciso di come lo
ricordano i tutorial. Questa è la versione sbagliata, cioè quella che legge il messaggio
direttamente:
export async function avvia(operazione: () => Promise<void>): Promise<string | null> {
try {
await operazione();
return null;
} catch (err) {
// 'err' e' unknown: leggere .message direttamente non compila.
return err.message;
}
}
Compilata con tsc 7.0.2, la versione corrente su npm il 13 novembre 2026, e con
strict, noImplicitReturns e noPropertyAccessFromIndexSignature
accesi, produce questo:
02-catch-sbagliato.ts(7,12): error TS18046: 'err' is of type 'unknown'.
Il codice TS18046 dice una cosa sola, e non parla di message: dice che la
variabile è di tipo unknown. Il compilatore non si lamenta del campo che hai chiesto,
si lamenta del fatto che non sai su che cosa lo stai chiedendo. È una distinzione che conviene
tenere a mente, perché la soluzione sbagliata a questo errore, cioè annotare la variabile come
any, lo fa sparire senza risolvere niente.
Un confine vero: leggere un oggetto da un archivio
Il caso del catch è utile perché il linguaggio lo impone. Il caso che devi scrivere tu
è l'altro: un valore che arriva da fuori come testo e che deve diventare un oggetto tipizzato. In
questo progetto lo scenario reale è l'archivio del browser, dove un servizio dedicato legge e
scrive valori sotto chiavi con un prefisso, e il valore letto è sempre una stringa che qualcuno ha
scritto in un'altra versione dell'applicazione.
export interface Preferenze {
tema: 'chiaro';
lingua: 'it' | 'en';
}
function sonoPreferenze(valore: unknown): valore is Preferenze {
if (typeof valore !== 'object' || valore === null) {
return false;
}
const o = valore as Record<string, unknown>;
return o['tema'] === 'chiaro' && (o['lingua'] === 'it' || o['lingua'] === 'en');
}
export function leggiPreferenze(grezzo: string | null, scorta: Preferenze): Preferenze {
if (grezzo === null) {
return scorta;
}
let analizzato: unknown;
try {
analizzato = JSON.parse(grezzo);
} catch {
return scorta;
}
return sonoPreferenze(analizzato) ? analizzato : scorta;
}
La proprietà di questo blocco su cui conviene fermarsi è la dichiarazione
analizzato: unknown, perché è l'unica riga indispensabile. JSON.parse
restituisce any, e questo è un dettaglio della libreria standard che vale la pena
conoscere: significa che senza quella dichiarazione il risultato si propagherebbe come
any in tutto il resto della funzione, e la guardia che ho scritto sotto diventerebbe
decorativa. Annotare la variabile come unknown è ciò che costringe a passare dalla
verifica. È una riga che non fa niente a tempo di esecuzione e che tiene in piedi tutto il resto.
La seconda cosa da spiegare è la firma valore is Preferenze. Non è un normale
boolean: è un predicato di tipo, e dice al compilatore che quando la funzione
restituisce vero il parametro può essere trattato come Preferenze. È il meccanismo
che fa funzionare l'ultima riga, dove l'operatore condizionale restituisce
analizzato senza nessun cast. Il prezzo di questo potere è alto e si paga una volta:
il compilatore non verifica che i controlli dentro il predicato corrispondano al tipo promesso.
Un predicato che restituisce sempre vero compila e mente a tutto il programma, ed è il
tranello di cui parla il prossimo articolo della serie.
Dentro la guardia il cast valore as Record<string, unknown> merita una nota,
perché sembra contraddire tutto l'articolo. Non lo è: è un cast verso un tipo meno
preciso, non più preciso. Afferma soltanto che è un oggetto con chiavi di testo e valori
ignoti, cosa che le due righe sopra hanno già verificato. Serve perché su unknown
puro non si può indicizzare nulla, e la lettura resta sicura perché ogni valore letto è a sua
volta unknown e va confrontato prima di essere usato. Le parentesi quadre invece
delle proprietà con il punto non sono una preferenza: con
noPropertyAccessFromIndexSignature attivo, come in questo progetto, leggere
o.tema su un tipo indicizzato non compila: error TS4111: Property 'tema' comes
from an index signature, so it must be accessed with ['tema']. Il flag non fa parte di
strict e va acceso a parte.
Compilare non dimostra che la funzione si comporti bene, e per questo ho eseguito i due blocchi con
Node 24, che toglie i tipi da solo e fa girare i file .ts. Salva il primo blocco come
messaggio.ts e quello con le preferenze come preferenze.ts, poi metti
accanto questo terzo file e lancia node prova.ts. L'uscita è identica in due
esecuzioni consecutive.
import { messaggioDiErrore } from './messaggio.ts';
import { leggiPreferenze } from './preferenze.ts';
import type { Preferenze } from './preferenze.ts';
const scorta: Preferenze = { tema: 'chiaro', lingua: 'it' };
console.log(messaggioDiErrore(new RangeError('fuori intervallo')));
console.log(messaggioDiErrore('testo lanciato'));
console.log(messaggioDiErrore(404));
console.log(messaggioDiErrore(undefined));
console.log(leggiPreferenze('{"tema":"chiaro","lingua":"en"}', scorta));
console.log(leggiPreferenze('{"tema":"scuro","lingua":"en"}', scorta));
console.log(leggiPreferenze('{"tema":"chiaro"}', scorta));
console.log(leggiPreferenze('non e json', scorta));
console.log(leggiPreferenze('null', scorta));
console.log(leggiPreferenze(null, scorta));
// Output:
// fuori intervallo
// testo lanciato
// Errore sconosciuto
// Errore sconosciuto
// { tema: 'chiaro', lingua: 'en' }
// { tema: 'chiaro', lingua: 'it' }
// { tema: 'chiaro', lingua: 'it' }
// { tema: 'chiaro', lingua: 'it' }
// { tema: 'chiaro', lingua: 'it' }
// { tema: 'chiaro', lingua: 'it' }
Le prime quattro righe provano i tre rami di messaggioDiErrore: un Error
restituisce il suo messaggio, una stringa lanciata passa com'è, e sia un numero sia
undefined finiscono nel ritorno finale. Le sei successive riguardano
leggiPreferenze, e solo la prima, con tema e lingua giusti, restituisce il dato letto.
Un tema diverso da quello ammesso, un campo mancante, un testo che non è JSON, il JSON
null (che JSON.parse accetta e che il controllo su null
scarta) e l'assenza del valore restituiscono tutti la scorta. È il comportamento che ti serve su un
confine: un dato sbagliato non entra, e il programma non si ferma.
Il costo vero, e quando non vale la pena
La critica onesta a unknown è che sposta il costo, non lo elimina. Su un confine
stretto e con poche forme, come le preferenze qui sopra, il costo è quindici righe scritte una
volta e poi mai più toccate, e in cambio ogni lettura a valle è verificata. Su una risposta con
quaranta campi annidati, scrivere la guardia a mano diventa un lavoro noioso che si fa male, e una
guardia scritta male è peggio di nessuna guardia, perché afferma una garanzia che non c'è.
In quel caso la risposta non è tornare ad any: è smettere di scrivere le guardie a
mano e usare uno strumento che le genera da uno schema, dove la descrizione del dato e la verifica
sono lo stesso oggetto e non possono divergere. La regola che uso per decidere è la dimensione del
confine, non la sua importanza: fino a tre o quattro campi la guardia a mano è la cosa più
semplice che funziona, oltre si prende la libreria.
C'è un caso in cui any resta la risposta giusta, e negarlo è disonesto: quando il
valore non viene mai letto ma solo trasportato. Un carico che prendi da una parte e consegni
dall'altra senza guardarlo dentro non ha bisogno di nessuna garanzia, e per quel caso esiste una
forma migliore di entrambi, cioè una variabile di tipo generico che conserva il tipo del
chiamante senza che tu debba conoscerlo.
Le quattro domande da farsi su ogni confine
Quando trovi un confine nel tuo codice, queste quattro domande si rispondono in pochi secondi e sono indipendenti fra loro.
- Da dove arriva il valore: rete, archivio locale, indirizzo, coda o file. Ogni origine ha una probabilità diversa di contenere dati di una versione precedente.
- Il valore viene letto dentro o solo trasportato. Se è solo trasportato, non serve nessuna verifica e il tipo giusto è generico.
- Quante forme diverse può avere. Una sola forma si verifica a mano, due o tre si descrivono con una unione discriminata, molte di più chiedono uno schema.
- Che cosa deve succedere quando la verifica fallisce: un valore di scorta, un errore all'utente, o una scrittura nel registro. Questa è la risposta che manca più spesso, e decide se la funzione può restituire un valore o deve sollevare.
Le quattro risposte non pesano allo stesso modo: la seconda decide se ti serve una verifica, e se la risposta è «solo trasportato» le altre tre non servono. Se il valore viene letto, la terza stabilisce lo strumento e la quarta il comportamento della funzione, quindi una guardia scritta senza aver deciso cosa fare in caso di fallimento è una guardia a metà. Quando le forme possibili sono due o tre, il modello è l'unione discriminata dell'articolo 04 della serie.
Chiusura
Adesso sai riconoscere un confine e sai che su quel confine unknown non è una versione
prudente di any, è il suo opposto: uno non verifica niente e si propaga, l'altro non
lascia fare niente finché non hai verificato. Sai che il compilatore in quel punto dice
TS18046 e che parla del tipo della variabile, non del campo che hai chiesto. Sai
perché JSON.parse va assegnato a una variabile dichiarata unknown, e che
senza quella riga il resto della verifica non serve a niente.
La prova che il passaggio è servito la puoi fare sul tuo codice adesso: cerca
JSON.parse e guarda dove va a finire il risultato. Se finisce in una variabile
tipizzata con l'interfaccia che ti aspetti, hai un'affermazione non verificata in un punto in cui
credevi di avere un controllo.
Resta aperta la questione più scomoda di tutte, quella che ho nominato senza affrontarla: il predicato di tipo che hai scritto per verificare il dato non viene a sua volta verificato dal compilatore. Il prossimo articolo parte da là.
Domande frequenti
Che differenza c'è fra any e unknown se accettano entrambi qualunque valore?
La differenza è su cosa ti lasciano fare dopo. Su any ogni operazione è permessa e non verificata, e il risultato resta any, quindi il buco si propaga. Su unknown nessuna operazione è permessa finché non restringi il tipo con un controllo che il compilatore riconosce.
Perché la variabile di catch è unknown e non any?
Perché il controllo useUnknownInCatchVariables, uno dei nove che strict attiva, la tipizza così. È corretto: in JavaScript si può lanciare qualunque valore, non solo un Error, quindi prima di leggere message serve un err instanceof Error.
Che errore dà il compilatore se leggo una proprietà su unknown?
error TS18046: 'err' is of type 'unknown'. Da notare che non nomina la proprietà che hai chiesto: si lamenta del fatto che il tipo della variabile è ignoto. Annotarla come any fa sparire il messaggio senza risolvere il problema.
JSON.parse restituisce un tipo sicuro?
No, restituisce any. Se assegni il risultato direttamente a una variabile tipizzata, hai un'affermazione non verificata. Va assegnato a una variabile dichiarata unknown, e da là si passa per una verifica esplicita.
Conviene sempre usare unknown invece di any?
Su un confine con poche forme si', perché il costo è una guardia scritta una volta. Su una risposta con decine di campi annidati una guardia scritta a mano diventa inaffidabile, e conviene uno strumento che la generi da uno schema. Quando il valore è solo trasportato e mai letto, il tipo giusto non è nessuno dei due ma un tipo generico.
Nella stessa serie trovi anche satisfies e le chiavi di un catalogo e Tipi template literal.
Fonti e approfondimenti
- TypeScript Handbook - il tipo unknown - la definizione (rappresenta qualunque valore, ma non è lecito farci nulla) e il confronto fra una funzione con parametro any e una con parametro unknown, che dà l'errore 18046, consultata il 2026-11-13
- TypeScript Handbook - restringimento dei tipi - typeof, instanceof e predicati di tipo come forme di restringimento, consultata il 2026-11-13
- TypeScript - strict e i controlli che accende, compreso useUnknownInCatchVariables - l'elenco dei nove controlli e l'assenza di noPropertyAccessFromIndexSignature fra loro, consultata il 2026-11-13
- TypeScript - noPropertyAccessFromIndexSignature - perché
o.temasu un tipo indicizzato non compila, consultata il 2026-11-13 - Prove eseguite per questo articolo:
npm view typescript version(7.0.2, 2026-11-13) etsc --noEmitsui blocchi mostrati
Commenti
Caricamento commenti...
Accedi per commentare