Um type guard definido pelo usuário é uma função cujo tipo de retorno é um predicado de tipo (x is T). Quando retorna true, o compilador estreita o argumento para T no código que a chama — permitindo que você encapsule verificações customizadas em tempo de execução.
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
}
}
Sem o predicado pet is Cat, o isCat retornando boolean não estreitaria pet — o compilador ainda veria Cat | Dog dentro do if. O predicado é o que ensina isso a ele.
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
O compilador confia no seu predicado — se a lógica no corpo estiver errada, você obtém um estreitamento inseguro. Para formas complexas, um validador de schema (zod) gera guards corretos para você.
Type guards permitem transformar verificações arbitrárias em tempo de execução em funções de estreitamento reutilizáveis — essencial para validar dados unknown em limites de API e para distinguir membros de uma union quando uma simples verificação typeof/in não é suficiente por si só.