TypeScript Academy · Aula

Operador de Asserção de Não Nulidade

Utilize o operador ! para afirmar que um valor não é null nem undefined.

Operador de Asserção de Não Nulidade é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 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.

O operador de asserção de não nulidade

O operador pós-fixo ! diz ao TypeScript: “este valor não é null nem undefined aqui”. Ele remove esses valores do tipo sem fazer nenhuma verificação em tempo de execução.

function firstChar(s: string | null): string {
  return s!.charAt(0); // assert s is not null
}
console.log(firstChar('hello'));

Onde colocar o !

O ! vem imediatamente depois da expressão que você está afirmando, antes de qualquer acesso adicional. Ele remove null | undefined do tipo dessa expressão.

type Box = { value?: number };
const box: Box = { value: 7 };
const n: number = box.value!; // value is number | undefined -> number
console.log(n);

Afirmando não nulidade após uma verificação

Às vezes, você garantiu logicamente que um valor está presente, mas o compilador não consegue acompanhar esse raciocínio. O ! permite prosseguir. Ainda assim, uma verificação real em tempo de execução geralmente é mais clara.

const list: Array<string | null> = ['a', null, 'c'];
const present = list.filter((x) => x !== null);
// TS may still see string | null; assert if certain:
console.log(present[0]!.toUpperCase());

Apenas em tempo de compilação, novamente

Assim como as, o operador ! é removido em tempo de execução. Ele não faz nenhuma verificação. Se o valor for realmente nulo, ocorrerá um erro em tempo de execução, apesar de o compilador estar satisfeito.

function risky(s: string | null): number {
  return s!.length; // no runtime guard
}
console.log(risky('hi'));
// risky(null) would throw at runtime

O perigo de !

Se você afirmar que um valor não é nulo quando ele pode realmente ser nulo, terá criado um erro oculto. O compilador deixará de avisar, e o erro só aparecerá quando esse valor nulo surgir em produção.

type User = { name?: string };
const u: User = {};
// const len = u.name!.length; // compiles, crashes at runtime
console.log('name is undefined here -> ! would crash');

Prefira uma verificação real

Sempre que for viável, substitua ! por uma verificação real de nulo ou por encadeamento opcional. A versão segura custa uma linha e elimina toda uma classe de falhas em tempo de execução.

type User = { name?: string };
function nameLen(u: User): number {
  if (u.name) return u.name.length; // checked
  return 0;
}
console.log(nameLen({ name: 'Ada' }), nameLen({}));

Asserção de atribuição definida

Um recurso relacionado é a asserção de atribuição definida: let x!: T. Ela promete ao compilador que x receberá um valor antes de ser usado, mesmo que não seja inicializado na declaração.

let token!: string; // promise: assigned before use
function init() { token = 'abc123'; }
init();
console.log(token.length);

Atribuição definida em classes

Isso é comum em classes nas quais uma propriedade é definida por uma estrutura ou por um método de inicialização, em vez do construtor. O ! depois do nome da propriedade suprime o erro “não atribuído definitivamente”.

class Service {
  config!: { url: string }; // set later by setup()
  setup() { this.config = { url: '/api' }; }
}
const s = new Service();
s.setup();
console.log(s.config.url);

Use a atribuição definida com cuidado

A asserção de atribuição definida é outra promessa que o compilador não pode verificar. Se você acessar a propriedade antes de atribuir um valor a ela, lerá undefined em tempo de execução sem receber nenhum aviso.

class Late {
  data!: number[];
  read() { return this.data.length; } // crashes if called before init
}
const l = new Late();
l.data = [1, 2];
console.log(l.read());

! vs encadeamento opcional

Não use ! quando ?. resolveria o problema. O encadeamento opcional trata valores nulos com segurança em tempo de execução, enquanto ! apenas silencia o compilador. Eles resolvem problemas diferentes.

type Cfg = { db?: { host?: string } };
const c: Cfg = {};
console.log(c.db?.host ?? 'localhost'); // safe
// c.db!.host! would crash here

Quando ! é justificável

O operador ! é razoável quando você tem uma garantia genuína que o compilador não consegue expressar — por exemplo, um valor que acabou de inserir e ler imediatamente. Mesmo assim, documente por que ele é seguro.

const cache = new Map<string, number>();
cache.set('hits', 0);
// We just set it, so get is non-null:
const hits = cache.get('hits')!;
console.log(hits);

Verificação rápida

Verifique sua compreensão do operador de asserção de não nulidade.

Recapitulação: asserção de não nulidade

Você aprendeu que:

O ! pós-fixado remove null | undefined de um tipo apenas em tempo de compilação.
Ele não realiza nenhuma verificação em tempo de execução, portanto uma asserção incorreta ainda faz o programa falhar.
let x!: T é a asserção de atribuição definitiva para valores inicializados posteriormente.
Prefira verificações reais ou encadeamento opcional; reserve ! para garantias genuínas.

A seguir, as asserções duplas e seus riscos.

const map = new Map<string, number>();
map.set('a', 1);
const v = map.get('a')!;
console.log(v);

Perguntas Frequentes

A aula “Operador de Asserção de Não Nulidade” é grátis?

Sim — o texto completo de “Operador de Asserção de Não Nulidade” é 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 “Operador de Asserção de Não Nulidade”?

Utilize o operador ! para afirmar que um valor não é null nem undefined. 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 2 de 4.

Quanto tempo leva a aula “Operador de Asserção de Não Nulidade”?

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