Type narrowing in TypeScript: come funziona la control flow analysis

Il type narrowing è TypeScript che ricava un tipo più specifico per un valore in un certo punto del codice, in base ai controlli che il codice ha già eseguito. Un parametro string | number diventa string dentro if (typeof x === "string") e number nell'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]

Chiamare value.toFixed(2) prima del controllo sarebbe un errore di compilazione, perché toFixed non esiste su string. Il controllo è normale JavaScript e viene eseguito a runtime; il narrowing è il compilatore che lo legge e adegua il tipo. Non viene generato nulla in più.

Control flow analysis

TypeScript segue ogni percorso all'interno di una funzione: if/else, return e throw anticipati, switch, cicli e gli operatori di cortocircuito &&, ||, ?? e ?:. In ogni punto, il tipo di una variabile è ciò che lì è ancora possibile.

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

Lo stile con return anticipati ("guard clause") è il modo più leggibile per restringere i tipi: gestisci prima i casi particolari e il resto della funzione lavora con il tipo pulito.

Tutti i modi per restringere un tipo

Le ultime tre sono trattate nelle pagine sui type guard e sulle discriminated union. Le altre sono qui sotto.

Truthiness narrowing

if (x) toglie null e undefined (e i tipi letterali false, 0, ""). È breve, e ha una trappola classica: 0 e "" sono falsy, quindi valori validi vengono trattati come mancanti.

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

Per numeri e stringhe, confronta in modo esplicito con undefined o null (oppure usa ??). La truthiness va bene per oggetti, array e funzioni, che non sono mai falsy.

Narrowing per uguaglianza

===, !==, == e != restringono entrambi i lati. Confrontare con un letterale restringe a quel letterale; == null (uguaglianza non stretta) corrisponde sia a null sia a undefined in un solo controllo, ed è l'unico caso in cui l'uguaglianza non stretta è idiomatica.

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

Confrontare due variabili restringe entrambe a ciò che potrebbero avere in comune: se a: string | number e b: string | boolean superano a === b, dentro l'if sono entrambe string.

L'operatore in

"key" in obj restringe una union di tipi oggetto ai membri che hanno (o potrebbero avere) quella proprietà.

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

in funziona anche su unknown quando sai che è un oggetto: dopo typeof v === "object" && v !== null && "id" in v, TypeScript sa che v ha una proprietà id di tipo unknown. Per le union che progetti tu, una proprietà etichetta condivisa (kind: "fish") è più chiara che andare a cercare i metodi: questo pattern si chiama discriminated union.

Narrowing per assegnazione

Una variabile ha un tipo dichiarato e un tipo ristretto che segue le sue assegnazioni. Assegnare un valore la restringe al tipo di quel valore, entro i limiti del tipo dichiarato.

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

Quando il narrowing si perde

Il narrowing è locale e prudente. Alcune situazioni lo azzerano:

• Un'espressione diversa. Controllare obj.name restringe obj.name (e obj["name"]), ma non obj[key] quando key è una variabile string invece di un letterale, e nemmeno una copia fatta prima del controllo.
• Callback e riassegnazione. Dentro una callback, una let ristretta mantiene il narrowing solo se non viene assegnata di nuovo dopo la creazione della callback. Una const o un parametro mai riassegnato resta ristretto.
• Controlli nascosti in funzioni di supporto. Una funzione isString(x: unknown): boolean non dice nulla al compilatore. Dalle un type predicate come tipo di ritorno, x is string, e le sue chiamate restringono il tipo come fa typeof.

// 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);

Il compilatore segnala index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. La callback potrebbe essere eseguita più tardi, dopo x = undefined. Elimina quell'ultima assegnazione (o copia il valore in una const dentro l'if) e il codice compila e stampa 5 due volte.

Una funzione di supporto che restituisce boolean si sistema dichiarando ciò che dimostra. È proprio questo un type guard:

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

Da TypeScript 5.5 il compilatore deduce questi predicati per le arrow function semplici, ed è per questo che list.filter((x) => x !== undefined) ora restituisce un array senza undefined.