TypeScript Academy · Aula

Tratamento Seguro de Tipos unknown

Restrinja os valores unknown antes de utilizá-los com segurança.

Tratamento Seguro de Tipos unknown é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 4 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.

Trabalhando com unknown com segurança

Tipar dados externos como unknown é apenas metade do trabalho. A outra metade é fazer o refinamento para um tipo concreto antes do uso. Esta lição aborda as principais técnicas de refinamento.

function describe(v: unknown): string {
  if (typeof v === 'string') return 'string: ' + v;
  if (typeof v === 'number') return 'number: ' + v;
  return 'other';
}
console.log(describe('hi'), describe(7), describe(true));

Refinamento com typeof

A verificação typeof é a ferramenta mais simples. Ela refina unknown para tipos primitivos: string, number, boolean, function, object e outros.

function double(v: unknown): number {
  if (typeof v === 'number') {
    return v * 2; // v is number here
  }
  return 0;
}
console.log(double(21), double('no'));

Refinamento com instanceof

Para instâncias de classes, use instanceof. Ele refina unknown para a classe específica, liberando o acesso seguro a seus métodos e propriedades.

function handle(v: unknown): string {
  if (v instanceof Date) {
    return v.toISOString(); // v is Date
  }
  return 'not a date';
}
console.log(handle(new Date(0)));

Refinamento com o operador in

O operador in verifica se uma propriedade existe em um objeto, refinando valores tipados como objetos. Primeiro confirme que o valor é um objeto não nulo e, depois, consulte suas chaves.

function getName(v: unknown): string {
  if (typeof v === 'object' && v !== null && 'name' in v) {
    return String((v as { name: unknown }).name);
  }
  return 'anonymous';
}
console.log(getName({ name: 'Ada' }), getName(5));

Guardas de tipo personalizadas

Uma guarda de tipo personalizada é uma função cujo tipo de retorno é value is T. Quando ela retorna true, o TypeScript refina o argumento para T no local da chamada.

function isString(v: unknown): v is string {
  return typeof v === 'string';
}

function shout(v: unknown): string {
  return isString(v) ? v.toUpperCase() : '?';
}
console.log(shout('hey'), shout(9));

Guardas para estruturas de objetos

As guardas personalizadas são especialmente úteis para validar estruturas de objetos. Escreva uma função que verifique todos os campos obrigatórios, e o restante do código poderá confiar no tipo refinado.

type User = { id: number; name: string };

function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null &&
    'id' in v && 'name' in v;
}
console.log(isUser({ id: 1, name: 'Sam' }), isUser({}));

JSON.parse retorna dados semelhantes a unknown

JSON.parse é tipado para retornar any, o que contorna silenciosamente a segurança. A prática recomendada é capturá-lo como unknown e validar os dados antes de confiar em sua estrutura.

function parseConfig(text: string): unknown {
  return JSON.parse(text);
}
const raw = parseConfig('{"port":8080}');
console.log(typeof raw);

Validando JSON analisado

Combine JSON.parse com uma guarda de tipo para transformar com segurança um texto não confiável em um valor tipado. Se a validação falhar, trate o erro em vez de confiar em dados inválidos.

type Config = { port: number };

function isConfig(v: unknown): v is Config {
  return typeof v === 'object' && v !== null &&
    'port' in v && typeof (v as any).port === 'number';
}

const data: unknown = JSON.parse('{"port":8080}');
if (isConfig(data)) console.log('Port:', data.port);

Encadeando várias guardas

Para entradas complexas, aplique as guardas em camadas: verifique primeiro a estrutura geral e, depois, refine-a. Cada guarda refina um pouco mais, produzindo tipos precisos e seguros passo a passo.

function process(v: unknown): string {
  if (Array.isArray(v)) {
    if (v.every((x) => typeof x === 'string')) {
      return v.join('-');
    }
  }
  return 'invalid';
}
console.log(process(['a', 'b']), process([1, 2]));

Lançando exceções para dados inválidos

Quando a validação falhar para dados obrigatórios, lance uma exceção. Combinado com uma função auxiliar de falha que retorna never, isso mantém o caminho principal limpo e bem tipado.

function asNumber(v: unknown): number {
  if (typeof v === 'number') return v;
  throw new Error('Expected a number');
}
console.log(asNumber(42));
try { asNumber('x'); } catch (e) { console.log('rejected'); }

Reunindo tudo

O padrão completo é: receber os dados como unknown, refiná-los com guardas e, depois, operar sobre o tipo preciso. Essa é a fronteira segura entre o mundo externo sem tipos e o seu código tipado.

type Point = { x: number; y: number };
function isPoint(v: unknown): v is Point {
  return typeof v === 'object' && v !== null &&
    'x' in v && 'y' in v;
}
const input: unknown = { x: 1, y: 2 };
if (isPoint(input)) console.log(input.x + input.y);

Verificação rápida

Verifique sua compreensão de como lidar com unknown com segurança.

Recapitulação: lidando com unknown

Você aprendeu a refinar unknown com:

typeof para tipos primitivos e instanceof para instâncias de classes.
O operador in para propriedades de objetos.
Guardas de tipo personalizadas que retornam value is T.
A validação dos resultados de JSON.parse antes de confiar neles.

Próximo curso: asserções e conversão de tipos.

function isNonEmpty(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}
console.log(isNonEmpty('hi'), isNonEmpty(''));

Perguntas Frequentes

A aula “Tratamento Seguro de Tipos unknown” é grátis?

Sim — o texto completo de “Tratamento Seguro de Tipos unknown” é 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 “Tratamento Seguro de Tipos unknown”?

Restrinja os valores unknown antes de utilizá-los com segurança. 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 4 de 4.

Quanto tempo leva a aula “Tratamento Seguro de Tipos unknown”?

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