Type guards en TypeScript: comprobar el tipo de un objeto

Un type guard es una comprobación en tiempo de ejecución que TypeScript entiende, así que estrecha el tipo dentro de la rama comprobada. typeof, instanceof e in son guards integrados; para cualquier otra cosa, escribes una función cuyo tipo de retorno es un predicado de tipo, value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser devuelve un booleano normal en tiempo de ejecución. El tipo de retorno value is User le dice al compilador qué demuestra un resultado true, y cada if (isUser(x)) estrecha entonces x a User.

Type guards integrados

Estas comprobaciones estrechan sin ninguna función auxiliar:

Todas se ejecutan como JavaScript normal. Lo que añade TypeScript es el estrechamiento: lee la comprobación y ajusta el tipo en cada rama. La lista completa de formas está en la página de estrechamiento de tipos. Un guard propio sirve para comprobaciones que no caben en una sola expresión o que quieres reutilizar.

Escribir un predicado de tipo

Un predicado de tipo tiene la forma parameterName is Type y sustituye a boolean como tipo de retorno. El estrechamiento funciona en los dos sentidos: true estrecha a Type, y false quita Type de una unión.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Pasar un guard a filter da un array con el tipo correcto. Desde TypeScript 5.5 el compilador también infiere un predicado a partir de funciones flecha sencillas, así que pets.filter((p) => p.kind === "cat") devuelve Cat[] sin un guard con nombre.

El tipo del predicado tiene que encajar con el tipo del parámetro: function f(x: string): x is number es el error TS2677, A type predicate's type must be assignable to its parameter's type.

El compilador se fía de tu guard

TypeScript comprueba que un guard devuelve un booleano. No comprueba que ese booleano sea correcto. Un guard que devuelve true para valores equivocados hace que los tipos mientan, y el programa falla en tiempo de ejecución sin ningún error de compilación.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) lanza TypeError: Cannot read properties of undefined (reading 'toFixed') en tiempo de ejecución. El compilador aceptó data.price como number porque el guard lo decía. Comprueba cada propiedad de la que depende el resto del código, y mantén los guards pequeños, probados y cerca del tipo que describen.

Comprobar si un objeto es de un tipo

Esta es la pregunta detrás de la mayoría de los guards propios: los datos llegan como unknown (de JSON.parse, fetch, localStorage, un mensaje) y necesitas saber si encajan con tu interfaz. La receta:

1. typeof value === "object" && value !== null (un objeto, no null).
2. "prop" in value para cada propiedad obligatoria. Sobre unknown, in añade la propiedad al tipo como unknown.
3. typeof value.prop === "..." (o un guard anidado) para el tipo de cada propiedad.
4. Array.isArray(value.items) && value.items.every(isItem) para los arrays.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Con formas grandes o muy anidadas, escribir esto a mano se vuelve pesado. Librerías de esquemas como Zod o Valibot te permiten describir la forma una vez y te dan tanto la comprobación en tiempo de ejecución como el tipo de TypeScript.

Funciones de aserción: asserts value is Type

Una función de aserción lanza un error si la comprobación falla y termina con normalidad en caso contrario. Su tipo de retorno es asserts value is Type (o asserts condition), y todo lo que va después de la llamada queda estrechado, sin necesidad de if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

Hay una regla que confunde a mucha gente: una función de aserción debe llamarse a través de un nombre con un tipo explícito. Una función flecha const sin anotación, const check = (v: unknown): asserts v is string => {...}, da el error TS2775 en la llamada, Assertions require every name in the call target to be declared with an explicit type annotation. Usa una declaración function, o anota la constante con un tipo de función.

Guards frente a aserciones y casts

Una aserción de tipo (as) cambia el tipo sin comprobar nada. En una frontera por la que entran datos de fuera, un guard o una función de aserción es la versión segura de la misma idea.

Guards basados en this en clases

Un método puede estrechar el objeto sobre el que se llama con this is Type. Es práctico en jerarquías de clases:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}