Type narrowing em TypeScript: como funciona o control flow

Type narrowing é o TypeScript descobrindo um tipo mais específico para um valor em um ponto do código, com base nas verificações que o código já fez. Um parâmetro string | number vira string dentro de if (typeof x === "string") e number no else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

Chamar value.toFixed(2) antes da verificação seria um erro de compilação, porque toFixed não existe em string. A verificação é JavaScript comum e roda em tempo de execução; o narrowing é o compilador lendo essa verificação e ajustando o tipo. Nada a mais é gerado.

Control flow analysis

O TypeScript segue todos os caminhos de uma função: if/else, return e throw antecipados, switch, loops e os operadores de curto-circuito &&, ||, ?? e ?:. Em cada ponto, o tipo de uma variável é o que ainda é possível ali.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

O estilo de retorno antecipado ("guard clauses") é o jeito mais legível de fazer narrowing: trate primeiro os casos estranhos, e o resto da função trabalha com o tipo limpo.

Todas as formas de narrowing

As três últimas são tratadas nas páginas sobre type guards e discriminated unions. As outras estão abaixo.

Narrowing por truthiness

if (x) remove null e undefined (e os literal types false, 0 e ""). É curto, e tem uma armadilha clássica: 0 e "" são falsy, então valores válidos acabam tratados como ausentes.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

Para números e strings, compare explicitamente com undefined ou null (ou use ??). Truthiness funciona bem para objetos, arrays e funções, que nunca são falsy.

Narrowing por igualdade

===, !==, == e != estreitam os dois lados. Comparar com um literal estreita para esse literal; == null (igualdade frouxa) corresponde a null e a undefined em uma só verificação, e é o único lugar em que a igualdade frouxa é idiomática.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

Comparar duas variáveis estreita as duas para o que elas podem ter em comum: se a: string | number e b: string | boolean passam em a === b, as duas são string dentro do if.

O operador in

"key" in obj estreita uma union de tipos de objeto para os membros que têm (ou podem ter) essa propriedade.

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

O in também funciona com unknown quando você já sabe que é um objeto: depois de typeof v === "object" && v !== null && "id" in v, o TypeScript sabe que v tem uma propriedade id do tipo unknown. Em unions que você mesmo projeta, uma propriedade-tag compartilhada (kind: "fish") é mais clara do que sondar métodos: esse padrão se chama discriminated union.

Narrowing por atribuição

Uma variável tem um tipo declarado e um tipo estreitado que acompanha as atribuições. Atribuir um valor estreita a variável para o tipo desse valor, dentro dos limites do tipo declarado.

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

Onde o narrowing se perde

O narrowing é local e conservador. Algumas situações o desfazem:

• Uma expressão diferente. Verificar obj.name estreita obj.name (e obj["name"]), mas não obj[key] quando key é uma variável string em vez de um literal, nem uma cópia feita antes da verificação.
• Callbacks e reatribuição. Dentro de um callback, um let estreitado só mantém o narrowing se não for atribuído de novo depois que o callback é criado. Um const ou um parâmetro que nunca é reatribuído continua estreitado.
• Verificações escondidas em helpers. Uma função isString(x: unknown): boolean não diz nada ao compilador. Dê a ela um tipo de retorno de type predicate, x is string, e as chamadas passam a estreitar como o typeof faz.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

O compilador mostra index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. O callback pode rodar depois, após x = undefined. Apague essa última atribuição (ou copie o valor para um const dentro do if) e o código compila e imprime 5 duas vezes.

Um helper que retorna boolean pode ser corrigido declarando o que ele prova. É isso que um type guard é:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Desde o TypeScript 5.5, o compilador infere esses predicates para arrow functions simples, e é por isso que list.filter((x) => x !== undefined) agora retorna um array sem undefined.