Type guard em TypeScript: verificar o tipo de um objeto

Um type guard é uma verificação em tempo de execução que o TypeScript entende, então ele estreita o tipo dentro do ramo verificado. typeof, instanceof e in são guards nativos; para todo o resto, você escreve uma função cujo tipo de retorno é um type predicate, 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 retorna um boolean comum em tempo de execução. O tipo de retorno value is User diz ao compilador o que um resultado true prova, e então todo if (isUser(x)) estreita x para User.

Type guards nativos

Estas verificações fazem narrowing sem nenhuma função auxiliar:

Todas rodam como JavaScript comum. O que o TypeScript acrescenta é o narrowing: ele lê a verificação e ajusta o tipo em cada ramo. A lista completa de formas está na página sobre type narrowing. Um guard próprio serve para verificações que não cabem em uma expressão, ou que você quer reutilizar.

Escrevendo um type predicate

Um type predicate tem a forma parameterName is Type e substitui boolean como tipo de retorno. O narrowing funciona nos dois sentidos: true estreita para Type, e false remove Type de uma union.

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[])

Passar um guard para o filter dá um array com o tipo certo. Desde o TypeScript 5.5, o compilador também infere um predicate a partir de arrow functions simples, então pets.filter((p) => p.kind === "cat") retorna Cat[] sem um guard com nome.

O tipo do predicate precisa caber no tipo do parâmetro: function f(x: string): x is number gera o erro TS2677, A type predicate's type must be assignable to its parameter's type.

O compilador confia no seu guard

O TypeScript verifica que um guard retorna um boolean. Ele não verifica se o boolean está certo. Um guard que retorna true para os valores errados faz os tipos mentirem, e o programa falha em tempo de execução sem nenhum erro de compilação.

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) lança TypeError: Cannot read properties of undefined (reading 'toFixed') em tempo de execução. O compilador aceitou data.price como number porque o guard disse isso. Verifique toda propriedade da qual o resto do código depende, e mantenha os guards pequenos, testados e perto do tipo que descrevem.

Verificando se um objeto é de um tipo

Essa é a pergunta por trás da maioria dos guards próprios: os dados chegam como unknown (de JSON.parse, fetch, localStorage, uma mensagem) e você precisa saber se eles correspondem à sua interface. A receita:

1. typeof value === "object" && value !== null (um objeto, e não null).
2. "prop" in value para cada propriedade obrigatória. Em um unknown, o in acrescenta a propriedade ao tipo como unknown.
3. typeof value.prop === "..." (ou um guard aninhado) para o tipo de cada propriedade.
4. Array.isArray(value.items) && value.items.every(isItem) para 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

Para formatos grandes ou muito aninhados, escrever isso à mão fica cansativo. Bibliotecas de schema como Zod ou Valibot permitem descrever o formato uma vez e dão a você a verificação em tempo de execução e o tipo TypeScript.

Assertion functions: asserts value is Type

Uma assertion function lança um erro se a verificação falha e retorna normalmente caso contrário. O tipo de retorno dela é asserts value is Type (ou asserts condition), e tudo o que vem depois da chamada fica estreitado, sem precisar 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
}

Uma regra pega muita gente: uma assertion function precisa ser chamada por meio de um nome com tipo explícito. Uma arrow function const sem anotação, const check = (v: unknown): asserts v is string => {...}, gera o erro TS2775 no local da chamada, Assertions require every name in the call target to be declared with an explicit type annotation. Use uma declaração function, ou anote a constante com um tipo de função.

Guards vs assertions vs casts

Uma type assertion (as) muda o tipo sem verificar nada. Em uma fronteira em que os dados vêm de fora, um guard ou uma assertion function é a versão segura da mesma ideia.

Guards baseados em this nas classes

Um método pode estreitar o objeto em que é chamado com this is Type. Isso é prático em hierarquias de classes:

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
}