TypeScript Non-null Assertion

Ao acessar APIs externas ou índices de arrays, os valores podem se tornar undefined, tornando-os difíceis de manipular como estão em termos de tipo. Use asserções non-null para alcançar tanto verificações de execução quanto estreitamento de tipos.

Código

function assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
  if (value === undefined || value === null) {
    throw new Error(`Expected 'value' to be defined, but received ${value}`);
  }
}

function nonNull<T>(value: T): NonNullable<T> {
  assertIsDefined(value);
  return value;
}

Exemplos de uso

Acesso seguro a elementos de array

const arr = [1, 2, 3];
const value = arr[10]; // number | undefined

// Não é possível evitar erro de tipo
console.log(value.toFixed()); // Error: Object is possibly 'undefined'

// Usando nonNull
const safeValue = nonNull(arr[10]);
// Inferido como NonNullable<number>
console.log(safeValue.toFixed()); // OK

Validação de resposta de API

interface User {
  name: string;
}

async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const user = await response.json() as User | undefined;

  // Erro se a resposta estiver vazia
  assertIsDefined(user);

  // user pode ser tratado como tipo User neste ponto
  return user;
}

Diferença do operador !

TypeScript tem um operador de asserção non-null value!, mas este não realiza verificações em tempo de execução. O uso de funções de asserção permite validar valores em tempo de execução ao mesmo tempo em que estreita o tipo.

Cuidados

Use funções de asserção apenas quando tiver confiança de que um valor realmente existe. O uso descuidado resultará em erros de execução. Especialmente para acesso a índices de arrays, considere verificar o comprimento antecipadamente.