TypeScript Academy · Aula

Asserções versus Guardas de Tipo

Prefira verificações em tempo de execução às asserções sempre que possível.

Asserções versus Guardas de Tipo é 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.

Duas maneiras de convencer o compilador

Quando o compilador não conhece o tipo exato de um valor, você tem duas opções: fazer uma asserção sobre ele (alegar o tipo) ou usar uma guarda (comprovar o tipo em tempo de execução). Elas parecem semelhantes, mas oferecem níveis de segurança muito diferentes.

function viaAssert(v: unknown): number {
  return (v as number) + 1; // claim
}
function viaGuard(v: unknown): number {
  return typeof v === 'number' ? v + 1 : 0; // prove
}
console.log(viaAssert(5), viaGuard(5), viaGuard('x'));

Asserções não verificam

Uma asserção é uma promessa sem nenhuma garantia. Se você estiver errado, a falha chegará ao tempo de execução. Asserções trocam segurança por conveniência.

const v: unknown = 'hello';
const n = v as number;
console.log(n.toFixed(2)); // runtime error: toFixed is not a function

Guardas de tipo verificam em tempo de execução

Uma guarda de tipo realmente verifica o valor. Se a verificação for aprovada, tanto você quanto o compilador saberão que o tipo está correto — há um teste real em tempo de execução sustentando o refinamento.

function toFixed2(v: unknown): string {
  if (typeof v === 'number') return v.toFixed(2);
  return 'N/A';
}
console.log(toFixed2(3.14159), toFixed2('hi'));

Funções personalizadas de guarda de tipo

Encapsule verificações complexas em uma guarda reutilizável que retorne value is T. Toda a base de código se beneficia de uma única validação bem testada.

type Email = { address: string };
function isEmail(v: unknown): v is Email {
  return typeof v === 'object' && v !== null &&
    'address' in v && typeof (v as any).address === 'string';
}
console.log(isEmail({ address: 'a@b.com' }), isEmail(null));

As guardas podem ser compostas e reutilizadas

Como as guardas são funções comuns, você pode combiná-las, testá-las e reutilizá-las. Asserções, por outro lado, são alegações dispersas que não podem ser validadas centralmente.

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

Funções de asserção com a anotação de asserção

O TypeScript também oferece funções de asserção. A anotação de retorno delas usa a palavra-chave asserts. Se a função retornar normalmente, o compilador refina o argumento a partir desse ponto; se a condição falhar, ela lança uma exceção.

function assertNumber(v: unknown): asserts v is number {
  if (typeof v !== 'number') throw new Error('not a number');
}
function use(v: unknown): number {
  assertNumber(v); // after this line, v is number
  return v * 2;
}
console.log(use(21));

Anotação de asserção versus predicado de tipo

Uma guarda value is T retorna um booleano sobre o qual você faz uma ramificação. Uma função asserts value is T lança uma exceção em caso de falha e faz o refinamento pelo restante do escopo. Ambas têm suporte em tempo de execução, ao contrário de um as simples.

function assertDefined<T>(v: T): asserts v is NonNullable<T> {
  if (v === null || v === undefined) throw new Error('missing');
}
const maybe: string | null = 'ok';
assertDefined(maybe);
console.log(maybe.length); // narrowed to string

Auxiliares genéricos de asserção

Funções de asserção são excelentes pré-condições reutilizáveis. Um único auxiliar assert(condition) pode proteger invariantes em todo o código, lançando uma exceção imediatamente quando elas forem violadas.

function assert(cond: unknown, msg: string): asserts cond {
  if (!cond) throw new Error(msg);
}
function half(n: number): number {
  assert(n % 2 === 0, 'must be even');
  return n / 2;
}
console.log(half(8));

Comparando a segurança

Da opção mais segura à mais arriscada: guardas de tipo e funções de asserção (verificadas em tempo de execução) ficam acima das asserções simples com as (sem verificação), que ficam acima das asserções duplas (ativamente enganosas). Escolha a ferramenta mais segura que atenda à necessidade.

// Safe: guard
function safe(v: unknown) {
  return typeof v === 'string' ? v.trim() : '';
}
console.log(safe('  hi  '));

Escolhendo a ferramenta certa

Use uma guarda de tipo quando fizer uma ramificação com base no tipo. Use uma função de asserção quando uma pré-condição precisar ser satisfeita ou a execução deva ser interrompida. Use as somente quando o refinamento for impossível (por exemplo, na especialização de DOM).

function getInput(v: unknown): asserts v is string {
  if (typeof v !== 'string') throw new Error('expected string');
}
const raw: unknown = 'name';
getInput(raw);
console.log(raw.toUpperCase());

As verificações em tempo de execução vencem

O tema recorrente deste curso é: prefira verificações em tempo de execução a asserções. Guardas e funções de asserção oferecem tanto tipos em tempo de compilação quanto segurança em tempo de execução. Asserções oferecem apenas uma alegação.

function parsePort(v: unknown): number {
  if (typeof v === 'number' && Number.isInteger(v)) return v;
  throw new Error('invalid port');
}
console.log(parsePort(8080));

Verificação rápida

Teste sua compreensão sobre asserções e guardas de tipo.

Recapitulação: asserções versus guardas

Você aprendeu que:

Guardas de tipo (value is T) comprovam um tipo em tempo de execução e permitem fazer uma ramificação.
Funções de asserção (asserts value is T) lançam uma exceção em caso de falha e fazem o refinamento depois.
Asserções simples com as apenas alegam um tipo — não oferecem segurança em tempo de execução.
Prefira ferramentas verificadas em tempo de execução; reserve asserções para casos que o refinamento não consegue tratar.

Próximo curso: encadeamento opcional e coalescência de nulos.

function isPositive(v: unknown): v is number {
  return typeof v === 'number' && v > 0;
}
console.log(isPositive(5), isPositive(-1));

Perguntas Frequentes

A aula “Asserções versus Guardas de Tipo” é grátis?

Sim — o texto completo de “Asserções versus Guardas de Tipo” é 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 “Asserções versus Guardas de Tipo”?

Prefira verificações em tempo de execução às asserções sempre que possível. 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 “Asserções versus Guardas de Tipo”?

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

A Palavra-chave as para Asserções de Tipo
Operador de Asserção de Não Nulidade
Asserções Duplas e Seus Riscos
Asserções versus Guardas de Tipo

← Voltar para TypeScript Academy