O que é um type guard definido pelo usuário?

Question

IT Interview Practice · Accepted Answer

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.

```ts
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.

## Validando dados externos desconhecidos

```ts
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
```

## Ressalva

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ê.

## Por que isso importa

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ó.

Validando dados externos desconhecidos

Ressalva

Por que isso importa

Perguntas relacionadas