TypeScript Academy · Aula

Entendendo unknown versus any

Por que unknown é a alternativa segura em relação a tipos de any.

Entendendo unknown versus any é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.

Os dois tipos de topo

O TypeScript tem dois tipos que podem conter qualquer valor: any e unknown. Eles parecem semelhantes, mas se comportam de maneiras muito diferentes. Escolher o tipo correto é uma habilidade fundamental para escrever código com segurança de tipos.

let a: any = 5;
let u: unknown = 5;
console.log(a, u);

any desativa a verificação de tipos

any é uma saída de emergência que desativa o verificador de tipos para esse valor. Você pode acessar qualquer propriedade ou chamá-lo como uma função — o compilador permanece em silêncio, mesmo quando isso causaria uma falha em tempo de execução.

const a: any = 'hello';
console.log(a.toUpperCase()); // OK
// a.doesNotExist(); // no compile error, but crashes at runtime

unknown obriga você a verificar

unknown também aceita qualquer valor, mas você não pode usá-lo até provar o que ele é. O compilador bloqueia o acesso a propriedades e as chamadas até que você restrinja o tipo.

const u: unknown = 'hello';
// console.log(u.toUpperCase()); // Error: u is unknown
console.log(typeof u);

Restringindo unknown com typeof

Uma verificação com typeof restringe unknown a um tipo concreto dentro do bloco. Depois da restrição, todos os métodos desse tipo ficam disponíveis com segurança.

function shout(value: unknown): string {
  if (typeof value === 'string') {
    return value.toUpperCase(); // safe here
  }
  return 'not a string';
}
console.log(shout('hi'), shout(42));

Por que unknown é mais seguro

unknown representa uma incerteza honesta: 'Ainda não sei o que é isto.' Ele incentiva você a validar antes de usar, detectando erros em tempo de compilação. any apenas esconde a incerteza e os erros.

function len(value: unknown): number {
  if (typeof value === 'string') return value.length;
  if (Array.isArray(value)) return value.length;
  return 0;
}
console.log(len('abc'), len([1, 2]), len(99));

Atribuindo a unknown e a partir de unknown

Qualquer valor pode ser atribuído a unknown. Porém, unknown só pode ser atribuído a unknown ou any — não a tipos específicos sem uma restrição. Essa assimetria é o que o mantém seguro.

let u: unknown = 10;
u = 'now a string';
u = true;
const anyVal: any = u; // allowed
console.log(anyVal);
// const s: string = u; // Error

any se espalha pelo código

Uma característica perigosa de any é que ele se espalha. Quando um valor é any, tudo o que deriva dele também se torna any, desgastando silenciosamente a segurança de tipos em todo o programa.

const a: any = { count: 5 };
const total = a.count + 10; // total is any
const flag = total.whatever; // still any, no error
console.log(total);

unknown contém o risco

Com unknown, a incerteza permanece no mesmo lugar. Você precisa restringir o tipo explicitamente em cada fronteira, para que operações inseguras não vazem para outras partes. O risco fica contido onde deve estar.

const u: unknown = { count: 5 };
if (typeof u === 'object' && u !== null && 'count' in u) {
  console.log('Has count property');
}

Tipando fronteiras de API e JSON

Dados externos — JSON, respostas da rede e entrada do usuário — não oferecem garantias. Tipá-los como unknown, em vez de any, obriga a validá-los antes de confiar neles, o que é a opção segura por padrão.

function parse(text: string): unknown {
  return JSON.parse(text);
}
const data = parse('{"id":1}');
if (typeof data === 'object' && data !== null) {
  console.log('Got an object');
}

Quando any é aceitável

any às vezes é uma escolha pragmática — em protótipos rápidos, na migração gradual de JavaScript ou na interoperabilidade com bibliotecas sem tipos. Mas trate-o como um marcador temporário, não como hábito. Prefira unknown sempre que puder.

// Migration placeholder, to be typed later
let legacy: any = getLegacyValue();
function getLegacyValue() { return { x: 1 }; }
console.log(legacy.x);

Uma comparação prática

Veja lado a lado: a versão com any compila, mas pode falhar; a versão com unknown se recusa a compilar o acesso inseguro. O compilador está cumprindo seu papel — protegendo você.

const a: any = 42;
console.log(a.toFixed(2)); // OK by luck

const u: unknown = 42;
if (typeof u === 'number') {
  console.log(u.toFixed(2)); // checked, safe
}

Verificação rápida

Teste sua compreensão sobre unknown e any.

Recapitulação: unknown e any

Pontos principais:

any desativa a verificação de tipos e se espalha pelos valores derivados.
unknown aceita qualquer valor, mas bloqueia seu uso até que você o restrinja.
Use unknown para dados externos (JSON, APIs e entrada do usuário), a fim de obrigar a validação.
Reserve any para migrações ou interoperabilidade sem tipos, como marcador temporário.

A seguir, exploraremos o tipo vazio: never.

function safeLen(v: unknown): number {
  return typeof v === 'string' ? v.length : 0;
}
console.log(safeLen('hello'), safeLen(123));

Perguntas Frequentes

A aula “Entendendo unknown versus any” é grátis?

Sim — o texto completo de “Entendendo unknown versus any” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.

O que vou aprender em “Entendendo unknown versus any”?

Por que unknown é a alternativa segura em relação a tipos de any. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar TypeScript Academy?

Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Entendendo unknown versus any”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de TypeScript Academy?

Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para TypeScript Academy