Null safety

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Null tem um lugar certo no sistema: os limites. Quando o ?. aparece espalhado pelo código inteiro, como defesa preventiva, isso indica que os contratos de entrada não estão fechados: o limite deixou passar um valor ausente, e cada função seguinte precisa checá-lo de novo.

Diante de cada ?., a pergunta a fazer é: "esse null deveria ter chegado até aqui?"

O sistema tem dois territórios, e as regras de um não valem no outro:

entrada externa → limite (checa + normaliza) → domínio (confia no contrato)

Null que aparece no interior indica um limite que deixou passar. Corrija na entrada.

Funções internas, serviços de domínio, cálculos: tudo que recebe dados já filtrados pelo limite. Essas funções não checam nada, porque confiam que quem chamou entregou o contrato cumprido.

function calculateDiscount(order) {
  if (!order) return 0;
  if (!order.discountRate) return 0;

  return order.total * order.discountRate;
}

function calculateDiscount(order) {
  const discount = order.total * order.discountRate;
  return discount;
}

A diferença está em quem responde pelo quê. Passar um Order válido é responsabilidade de quem chama calculateDiscount. Se chegar inválido, o bug é de quem chamou, e checar dentro da função apenas esconderia esse bug.

Três padrões dão conta da maioria dos casos:

1. Validação de schema na entrada

const orderRequest = CreateOrderSchema.parse(request.body); // lança se inválido

await createOrder(orderRequest); // domínio recebe dados garantidos

2. Guard clause logo após I/O

const order = await orderRepository.findById(id);
if (!order) throw new NotFoundError(`Order ${id} not found`);

// a partir daqui, order é garantido: sem ?. no restante da função
const total = calculateTotal(order);

3. Contratos não-nulos na construção

function buildOrder(id, items) {
  const order = { id, items: items ?? [] }; // items sempre [], nunca null
  return order;
}

Uma lista já tem um estado neutro pronto: []. Devolver null para dizer "não achei nada" não informa mais do que a lista vazia informaria, e obriga cada chamador a se defender antes de iterar.

Esses operadores existem para o campo que é opcional por design no domínio, aquele que legitimamente pode não estar lá. Não servem de escudo contra contrato mal fechado.

const discount = order?.discountRate ? order.total * order.discountRate : 0;
// order.discountRate nunca deveria ser null: contrato fraco exposto com `?.`

const display = user.nickname ?? user.name; // nickname é opcional no modelo
const city = user.address?.city ?? "N/A"; // endereço pode não existir

Se você precisa de ?. para acessar um campo que "sempre deveria existir", o contrato está aberto. Feche o contrato e remova o operador.

Uma regra de negócio muda, um campo novo entra no banco, e os registros antigos ficam com null porque não havia valor para eles. Esse null é histórico e o domínio não deve recebê-lo. O repositório resolve o valor antes de entregar o dado.

campo novo → registros antigos nulos → limite absorve → domínio nunca vê null

Três abordagens, em ordem de preferência:

1. Migration com DEFAULT: null nunca chega a existir no banco

A saída mais limpa. A migration preenche os registros antigos e garante valor para os novos, e o domínio nunca vê null nenhum.

ALTER TABLE orders ADD COLUMN priority VARCHAR(20) NOT NULL DEFAULT 'normal';
-- registros existentes recebem 'normal' automaticamente

2. Normalização no repositório: o null morre no limite

Use quando alterar o banco está fora de alcance: legado, multi-tenant, migration sob controle de outro time.

async function findById(id) {
  const row = await database.queryOne("SELECT id, priority, status FROM orders WHERE id = ?", [id]);
  if (!row) return null;

  const order = {
    ...row,
    priority: row.priority ?? "normal", // null histórico normalizado no limite
  };

  return order;
}

3. Campo opcional de verdade: quando a ausência significa alguma coisa

Às vezes o null carrega informação: "esse pedido foi criado antes dessa feature existir". Nesse caso o campo é opcional por design, e o domínio resolve a ausência em uma função central, sem espalhar ?. pelo código.

// priority é opcional: ausência significa "criado antes dessa feature existir"
function getEffectivePriority(order) {
  const priority = order.priority ?? "normal"; // uma função resolve, sem espalhar ?. pelo domínio
  return priority;
}

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.