Un type guard definido por el usuario es una función cuyo tipo de retorno es un predicado de tipo (x is T). Cuando devuelve true, el compilador reduce (narrows) el argumento a T en el código que la llama, lo que te permite encapsular comprobaciones de tiempo de ejecución personalizadas.
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
}
}
Sin el predicado pet is Cat, si isCat devolviera boolean no reduciría pet: el compilador seguiría viendo Cat | Dog dentro del if. El predicado es lo que se lo enseña.
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
El compilador confía en tu predicado: si la lógica del cuerpo es incorrecta, obtienes un narrowing inseguro. Para formas complejas, un validador de esquemas (zod) genera los guards correctos por ti.
Los type guards te permiten convertir comprobaciones arbitrarias de tiempo de ejecución en funciones de narrowing reutilizables, algo esencial para validar datos de tipo unknown en los límites de la API y para distinguir miembros de una unión cuando una simple comprobación con typeof/in no es suficiente por sí sola.