Un type guard definito dall'utente è una funzione il cui tipo di ritorno è un predicato di tipo (x is T). Quando restituisce true, il compilatore restringe l'argomento a T nel codice chiamante — permettendoti di incapsulare controlli di runtime personalizzati.
interface Cat { meow(): void; }
interface Dog { bark(): void; }
// the magic is the return type `pet is Cat`, not just `boolean`
function isCat(pet: Cat | Dog): pet is Cat {
return "meow" in pet;
}
function speak(pet: Cat | Dog) {
if (isCat(pet)) {
pet.meow(); // ✅ narrowed to Cat
} else {
pet.bark(); // ✅ narrowed to Dog
}
}
Senza il predicato pet is Cat, isCat che restituisce boolean non restringerebbe pet — il compilatore vedrebbe comunque Cat | Dog all'interno dell'if. Il predicato è ciò che glielo insegna.
interface User { id: number; name: string; }
function isUser(x: unknown): x is User {
return (
typeof x === "object" && x !== null &&
typeof (x as any).id === "number" &&
typeof (x as any).name === "string"
);
}
const data: unknown = await res.json();
if (isUser(data)) data.name; // ✅ safely typed as User
Il compilatore si fida del tuo predicato — se la logica del corpo è sbagliata, otterrai un restringimento non sicuro. Per forme complesse, un validatore di schema (zod) genera guardie corrette per te.
I type guard ti permettono di trasformare controlli di runtime arbitrari in funzioni di restringimento riutilizzabili — essenziali per validare dati unknown ai confini API e per distinguere i membri di un'unione quando un semplice controllo typeof/in non è sufficiente di per sé.