Exclamação em TypeScript: o non-null assertion (!)

Um ponto de exclamação depois de uma expressão, value!, é o operador non-null assertion. Ele remove null e undefined do tipo, então um number | undefined pode ser usado como number. É uma promessa ao compilador, não uma verificação: nada acontece em tempo de execução.

const prices = new Map<string, number>([
  ["tea", 2.5],
  ["coffee", 3.2],
]);

const tea = prices.get("tea");         // number | undefined
const coffee = prices.get("coffee")!;  // number

console.log(coffee.toFixed(2)); // 3.20
console.log(tea!.toFixed(2));   // 2.50: ! works on any expression

Sem o !, tea.toFixed(2) gera o erro TS18048, 'tea' is possibly 'undefined'. Com ele, o código compila porque você disse ao compilador que a chave existe.

O que x! faz em tempo de execução: nada

O ! é apagado da saída. O JavaScript compilado de prices.get("coffee")! é só prices.get("coffee"). Se a afirmação estiver errada, o erro aparece depois, no primeiro lugar em que o valor ausente é usado:

const prices = new Map<string, number>([["tea", 2.5]]);

try {
  const juice = prices.get("juice")!; // compiles: the ! silences the check
  console.log(juice.toFixed(2));      // TypeError at runtime
} catch (e) {
  console.log((e as Error).message);
}

O programa imprime Cannot read properties of undefined (reading 'toFixed'). A quebra acontece na linha depois do !, e em código real pode ficar bem mais longe: o undefined pode ser guardado em um objeto e estourar em outro arquivo. Essa distância é o que torna o ! arriscado.

Definite assignment: let x!: T

O mesmo símbolo em uma declaração significa algo parecido. O TypeScript acompanha se uma variável é atribuída antes de ser lida, e não consegue seguir uma atribuição feita dentro de outra função:

// This does not compile: TypeScript cannot see the assignment inside init()
let config: { port: number };

function init() {
  config = { port: 8080 };
}

init();
console.log(config.port);

index.ts(9,13): error TS2454: Variable 'config' is used before being assigned.

let config!: { port: number }; é uma definite assignment assertion: "isto será atribuído antes de qualquer leitura". Ela resolve o erro, com o mesmo porém do x!: se init() for pulado algum dia, a leitura recebe undefined. Reestruturar costuma ser melhor, por exemplo const config = init(); com init retornando o objeto.

Propriedades de classe: prop!: T

Com strictPropertyInitialization (parte do strict), toda propriedade de classe precisa ser inicializada na declaração ou no construtor. Senão você recebe o TS2564: Property 'socket' has no initializer and is not definitely assigned in the constructor. Quando uma propriedade é definida depois por um método ou por um framework, prop!: T diz ao compilador para aceitá-la:

class Connection {
  url: string;
  socket!: { send(msg: string): string }; // set in open(), not in the constructor

  constructor(url: string) {
    this.url = url;
  }

  open() {
    this.socket = { send: (msg) => `sent "${msg}" to ${this.url}` };
  }
}

const c = new Connection("ws://example.com");
console.log(c.socket);            // undefined: declared but not set yet
c.open();
console.log(c.socket.send("hi")); // sent "hi" to ws://example.com

O primeiro console.log mostra a brecha: o tipo diz que socket sempre existe, mas antes de open() ele é undefined. Chamar c.socket.send nesse momento compila e lança um erro. Se a propriedade pode mesmo faltar, declare-a como socket?: ... e verifique, ou crie o objeto no construtor. O lugar principal em que prop! é prática padrão é um framework que preenche uma propriedade depois da construção: o @ViewChild(...) child!: ChildDirective do Angular (definido antes de ngAfterViewInit rodar), ou classes de entidade de ORM cujas colunas a biblioteca preenche ao carregar uma linha (a documentação do MikroORM escreve @Property() title!: string).

Alternativas mais seguras

A maioria dos ! pode ser trocada por algo que o compilador verifica, ou por uma verificação que falha de forma clara no lugar certo:

function must<T>(value: T | null | undefined, what: string): T {
  if (value == null) throw new Error(`missing ${what}`);
  return value;
}

function assertDefined<T>(value: T, what: string): asserts value is NonNullable<T> {
  if (value == null) throw new Error(`missing ${what}`);
}

const env = new Map([["PORT", "8080"]]);

const port = must(env.get("PORT"), "PORT"); // string
console.log(Number(port) + 1);              // 8081

const host = env.get("HOST");
try {
  assertDefined(host, "HOST");
  console.log(host.toUpperCase()); // host is string after the assertion
} catch (e) {
  console.log((e as Error).message); // missing HOST
}

Os dois helpers estreitam o tipo como o ! faz, mas uma suposição errada produz missing HOST na hora, em vez de um TypeError em outro lugar. assertDefined é uma assertion function (asserts value is ...): depois da chamada, o compilador trata host como string. Mais padrões em type guards.

Os outros pontos de exclamação

O ! significa coisas diferentes dependendo de onde está:

Só os dois primeiros são apagados na compilação. !value e !!value rodam em tempo de execução e retornam um boolean.