Type guard in TypeScript: controllare il tipo di un oggetto

Un type guard è un controllo a runtime che TypeScript capisce, quindi restringe il tipo dentro il ramo controllato. typeof, instanceof e in sono guard integrati; per tutto il resto scrivi una funzione il cui tipo di ritorno è un type predicate, value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

A runtime isUser restituisce un semplice booleano. Il tipo di ritorno value is User dice al compilatore cosa dimostra un risultato true, e ogni if (isUser(x)) restringe quindi x a User.

Type guard integrati

Questi controlli restringono il tipo senza alcuna funzione di supporto:

Vengono tutti eseguiti come normale JavaScript. Ciò che TypeScript aggiunge è il restringimento: legge il controllo e adegua il tipo in ogni ramo. L'elenco completo delle forme è nella pagina sul type narrowing. Un guard personalizzato serve per i controlli che non stanno in una sola espressione, o che vuoi riutilizzare.

Scrivere un type predicate

Un type predicate ha la forma parameterName is Type e sostituisce boolean come tipo di ritorno. Il restringimento funziona in entrambe le direzioni: true restringe a Type, e false toglie Type da una union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Passare un guard a filter produce un array tipizzato correttamente. Da TypeScript 5.5 il compilatore deduce un predicato anche dalle arrow function semplici, quindi pets.filter((p) => p.kind === "cat") restituisce Cat[] senza un guard con nome.

Il tipo del predicato deve essere compatibile con quello del parametro: function f(x: string): x is number è l'errore TS2677, A type predicate's type must be assignable to its parameter's type.

Il compilatore si fida del tuo guard

TypeScript controlla che un guard restituisca un booleano. Non controlla che il booleano sia giusto. Un guard che restituisce true per i valori sbagliati fa mentire i tipi, e il programma fallisce a runtime senza alcun errore di compilazione.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) lancia TypeError: Cannot read properties of undefined (reading 'toFixed') a runtime. Il compilatore ha accettato data.price come number perché lo diceva il guard. Controlla ogni proprietà su cui si basa il resto del codice, e mantieni i guard piccoli, testati e vicini al tipo che descrivono.

Verificare se un oggetto è di un certo tipo

È la domanda dietro la maggior parte dei guard personalizzati: i dati arrivano come unknown (da JSON.parse, fetch, localStorage, un messaggio) e devi sapere se corrispondono alla tua interface. La ricetta:

1. typeof value === "object" && value !== null (un oggetto, non null).
2. "prop" in value per ogni proprietà obbligatoria. Su unknown, in aggiunge la proprietà al tipo come unknown.
3. typeof value.prop === "..." (o un guard annidato) per il tipo di ogni proprietà.
4. Array.isArray(value.items) && value.items.every(isItem) per gli array.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Per forme grandi o molto annidate, scrivere questi controlli a mano diventa noioso. Librerie di schema come Zod o Valibot ti permettono di descrivere la forma una sola volta e ti danno sia il controllo a runtime sia il tipo TypeScript.

Assertion function: asserts value is Type

Una assertion function lancia un'eccezione se il controllo fallisce e altrimenti termina normalmente. Il suo tipo di ritorno è asserts value is Type (o asserts condition), e tutto ciò che viene dopo la chiamata è ristretto, senza bisogno di un if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

Una regola trae spesso in inganno: una assertion function va chiamata tramite un nome con un tipo esplicito. Una arrow function const senza annotazione, const check = (v: unknown): asserts v is string => {...}, dà l'errore TS2775 nel punto della chiamata, Assertions require every name in the call target to be declared with an explicit type annotation. Usa una dichiarazione function, oppure annota la costante con un tipo funzione.

Guard, asserzioni e cast a confronto

Una type assertion (as) cambia il tipo senza controllare nulla. Al confine in cui i dati arrivano da fuori, un guard o una assertion function è la versione sicura della stessa idea.

Guard basati su this nelle classi

Un metodo può restringere l'oggetto su cui viene chiamato con this is Type. È comodo nelle gerarchie di classi:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}