O type guard instanceof funciona em uniões de classes: verifica se um valor é instância de uma classe, e o TypeScript estreita o tipo para essa classe. Ele faz uma verificação real da cadeia de protótipos em tempo de execução e é a ferramenta padrão para uniões envolvendo Date, Map, Error ou classes próprias.
Grupo
Restrição e Asserções de Tipos
Tipo
Operador
Modo strict
Não necessário
ℹ️ 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
function logValue(x: Date | string) {
if (x instanceof Date) {
console.log(x.toISOString()); // x: Date
} else {
console.log(x.toUpperCase()); // x: string
}
}
⚙️ Parâmetros
instanceof Klass
Em tempo de execução, percorre a cadeia de protótipos para ver se Klass.prototype aparece no objeto; o TS, simultaneamente, estreita o tipo para Klass (ou uma subclasse)
Retorno：A expressão instanceof retorna um boolean; o estreitamento ocorre em tempo de compilação, e o lado direito do instanceof precisa ser uma função construtora com prototype.
▶ Exemplo
Edite o código abaixo e clique em Testar para ver o resultado transpilado:
Saída：
Article: TS Basics
Video: 95s
(Saída de execução após a transpilação; item.title e item.duration passam na verificação de tipos porque o estreitamento por instanceof está em vigor — o estreitamento é garantido estaticamente pelo tsc, em tempo de execução existem apenas os valores)
ℹ️ Info instanceof é uma verificação real em tempo de execução (consulta a cadeia de protótipos), por isso não reconhece objetos "parecidos" produzidos por JSON.parse — o protótipo deles é Object.prototype, não a sua classe.
⚠️ Atenção instanceof não pode ser usado com interfaces — elas são apagadas em tempo de compilação e não há construtor para testar. Diferencie formatos de interfaces com in, type guards personalizados ou uniões discriminadas.
💡 Dica Objetos vindos de outro iframe ou de outro realm de vm têm um protótipo diferente da classe local, e instanceof pode retornar false erroneamente. Valide esses dados de fronteira estruturalmente com um type guard personalizado.
P O instanceof funciona para estreitar subclasses?
R Sim. O instanceof percorre a cadeia de protótipos, então uma instância da subclasse também passa em instanceof Parent, enquanto uma instância da classe pai falha em instanceof Child. O TS considera a herança ao estreitar.
P Por que instanceof sempre retorna false para resultados de JSON.parse?
R JSON.parse produz objetos simples cujo protótipo é Object.prototype — o protótipo da sua classe não está na cadeia. Valide a estrutura campo por campo com um type guard personalizado (x is T).
P Devo usar instanceof ou typeof?
R Use typeof para tipos primitivos (string/number/boolean etc.) e instanceof para instâncias de classes (Date, Map, classes próprias). Ambos são verificações reais em tempo de execução e podem ser combinados.
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.
