x is T Type guards personalizados e funções de asserção

Última atualização: 2026-10-22

x is T Type guards personalizados e funções de asserção

Quando os guards nativos (typeof/instanceof/in) não bastam, escreva a sua própria função type guard: declare o tipo de retorno como x is T (um predicado de tipo) e o TypeScript estreitará x para T nos ramos em que a função retornar true. Seu irmão é a função de asserção (asserts x is T), que não retorna boolean, mas lança um erro em caso de falha.

ℹ️ Info O editor transpila TypeScript para JavaScript e o executa (sem verificação de tipos); veja a Saída de cada exemplo para o resultado da verificação.

📝 Sintaxe

// Predicado de tipo: x é estreitado para T onde a função retorna true
function isFoo(x: unknown): x is Foo {
  return typeof x === "object" && x !== null && "foo" in x;
}

// Função de asserção: lança erro quando inválido; depois x é tratado como T
function assertFoo(x: unknown): asserts x is Foo {
  if (!isFoo(x)) throw new Error("not a Foo");
}

⚙️ Parâmetros

Retorno：Uma função predicado é uma função boolean comum em tempo de execução; o estreitamento ocorre em tempo de compilação. Uma função asserts não retorna nada (void) em tempo de execução e sinaliza a falha lançando um erro.

▶ Exemplo

Edite o código abaixo e clique em Testar para ver o resultado transpilado:

Saída：

failed: 404
data: x,y

(Saída de execução após a transpilação; assim que isFailure retorna true, res é estreitado para ApiError e res.data passa na verificação de tipos — o estreitamento é garantido estaticamente pelo tsc, em tempo de execução existem apenas os valores)

💡 Observações

🏷️ Restrição e Asserções de Tipos Relacionadas

💡 Casos relacionados

📚 Tutoriais relacionados

❓ Perguntas frequentes

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós