Erro TypeScript TS2533: como remover e o que está por baixo dos panos

Introdução: por que o TypeScript reclama do nada?

Você está escrevendo código em TypeScript, tudo parece lógico, mas de repente o compilador exibe: "error TS2533: Object is possibly 'null' or 'undefined'". Familiar? Esse erro é uma das "armadilhas" mais comuns para iniciantes. De acordo com dados do Stack Overflow, a pergunta sobre como suprimi-lo acumulou mais de 100.000 visualizações e se tornou um clássico.

Mas vamos olhar mais a fundo. TypeScript não é apenas um "JavaScript rigoroso". Seu sistema de tipos, especialmente o modo strictNullChecks, força você a lidar explicitamente com casos em que o valor pode ser null ou undefined. E isso não é um bug, é uma funcionalidade. O erro TS2533 é uma proteção contra bugs em tempo de execução que, em JavaScript, frequentemente levam a Cannot read property of null.

Neste artigo, abordaremos:

\n
• O que é strictNullChecks e como funciona "por baixo dos panos"
\n
• Por que o erro TS2533 ocorre
\n
• 5 maneiras de suprimi-lo (das simples às avançadas)
\n
• Quando cada método é adequado e quando não é
\n

Vamos resolver de uma vez por todas o erro null do TypeScript!

Como o strictNullChecks funciona por baixo dos panos

Por padrão, no TypeScript (a partir da versão 2.0), a opção strictNullChecks está ativada. O que isso significa? Antigamente, null e undefined eram considerados subtipos de qualquer tipo. Ou seja, você podia atribuir null a uma variável do tipo string — e o TypeScript não reclamava. Isso simplificava o código, mas gerava bugs.

No modo strictNullChecks, os tipos null e undefined são entidades separadas. Uma variável do tipo string só pode conter uma string. Se você quiser permitir null, precisa declarar explicitamente string | null.

Exemplo: como o erro se parece

// Exemplo 1: erro clássico TS2533\ninterface User {\n  name: string;\n  email?: string; // opcional — pode ser undefined\n}\n\nfunction getUserEmail(user: User): string {\n  // Erro TS2533: Object is possibly 'undefined'\n  return user.email.toUpperCase(); \n}\n\n// Exemplo 2: trabalhando com DOM\nconst button = document.querySelector('button');\n// Erro TS2533: Object is possibly 'null'\nbutton.addEventListener('click', () => console.log('clicado'));\n

No segundo exemplo, document.querySelector pode retornar null se o elemento não for encontrado. O TypeScript avisa: "Ei, você tem certeza de que o botão existe?"

5 maneiras de suprimir o erro TS2533

Agora vamos ao mais importante — como remover o erro. Abaixo estão 5 métodos testados, dos simples aos avançados. Escolha de acordo com a situação.

1. Operador de asserção non-null (!)

A maneira mais rápida é colocar um ponto de exclamação ! após a expressão. Isso diz ao TypeScript: "Eu sei que isso não é null, confie em mim".

// Usando ! para suprimir\nconst button = document.querySelector('button')!;\nbutton.addEventListener('click', () => console.log('clicado'));\n\n// Para propriedade opcional\nfunction getUserEmail(user: User): string {\n  return user.email!.toUpperCase();\n}\n

Quando usar: quando você tem absoluta certeza de que o valor não é null. Por exemplo, se você acabou de verificar a existência do elemento no DOM. Mas tenha cuidado: se errar, receberá um erro em tempo de execução.

2. Optional chaining (?.) e nullish coalescing (??)

Uma maneira moderna e segura. O operador ?. permite acessar uma propriedade apenas se o objeto não for null/undefined. E o ?? define um valor padrão.

function getUserEmail(user: User): string {\n  // Se email for undefined — retorna string vazia\n  return user.email?.toUpperCase() ?? '';\n}\n\n// Trabalhando com DOM\ndocument.querySelector('butt