typeof in TypeScript: type guard e operatore di tipo typeof

In TypeScript typeof significa due cose. In un'espressione è l'operatore JavaScript: viene eseguito, restituisce una stringa come "string" o "number", e TypeScript restringe la variabile quando confronti quella stringa. In una posizione di tipo è una type query: typeof config dà il tipo statico della variabile config.

// 1. The runtime operator: a check that narrows
function double(value: string | number): string | number {
  if (typeof value === "string") {
    return value.repeat(2); // value: string
  }
  return value * 2;         // value: number
}
console.log(double("ab"), double(21)); // abab 42

// 2. The type query: reuse the type of an existing value
const defaults = { retries: 3, verbose: false };
type Options = typeof defaults; // { retries: number; verbose: boolean }

const custom: Options = { retries: 5, verbose: true };
console.log(typeof custom, custom); // object { retries: 5, verbose: true }

L'ultima riga mostra la differenza: typeof custom in un console.log è l'operatore a runtime e stampa object, mentre typeof defaults dopo type Options = è la query in fase di compilazione e non arriva mai al JavaScript.

I due significati a colpo d'occhio

TypeScript li distingue in base alla posizione, quindi la stessa parola chiave non significa mai entrambe le cose insieme.

I risultati di typeof a runtime

L'operatore a runtime restituisce una di otto stringhe. Esegui questo codice per vedere cosa danno i valori più comuni:

const samples: [string, unknown][] = [
  ['"hi"', "hi"],
  ["42", 42],
  ["NaN", NaN],
  ["10n", 10n],
  ["true", true],
  ["undefined", undefined],
  ["null", null],
  ["{}", {}],
  ["[]", []],
  ["new Date(0)", new Date(0)],
  ['new String("x")', new String("x")],
  ["() => 1", () => 1],
  ["class A {}", class A {}],
  ['Symbol("id")', Symbol("id")],
];

for (const [label, value] of samples) {
  console.log(label.padEnd(16), typeof value);
}

In JavaScript puro, typeof su una variabile mai dichiarata restituisce "undefined" invece di lanciare un errore. In TypeScript quel codice non compila: Cannot find name 'notDeclared'. (TS2304).

Narrowing con typeof

Un confronto con typeof in un if, uno switch, un operatore ternario o dopo && restringe la variabile in ogni ramo. È il modo standard per gestire una union di primitivi, e il primo controllo da usare su unknown.

function format(value: unknown): string {
  switch (typeof value) {
    case "string":
      return `"${value}"`;                 // value: string
    case "number":
    case "bigint":
      return value.toLocaleString("en-US"); // value: number | bigint
    case "boolean":
      return value ? "yes" : "no";         // value: boolean
    case "function":
      return `function ${value.name}()`;   // value: Function
    default:
      return String(value);
  }
}

console.log(format("hi"));          // "hi"
console.log(format(1234567.891));   // 1,234,567.891
console.log(format(2n ** 64n));     // 18,446,744,073,709,551,616
console.log(format(true));          // yes
console.log(format(Math.max));      // function max()
console.log(format(undefined));     // undefined

typeof x !== "string" restringe nell'altra direzione, a tutto tranne string. E il compilatore conosce le otto stringhe possibili, quindi un errore di battitura nel confronto è un errore di compilazione, non un controllo che risulta sempre falso in silenzio:

// This does not compile: "strnig" is not a possible typeof result.
function kind(value: string | number): string {
  if (typeof value === "strnig") {
    return "text";
  }
  return "number";
}

console.log(kind("hey"));

Il compilatore stampa index.ts(3,7): error TS2367: This comparison appears to be unintentional because the types '"bigint" | "boolean" | "function" | "number" | "object" | "string" | "symbol" | "undefined"' and '"strnig"' have no overlap. In JavaScript puro l'errore di battitura manderebbe in silenzio ogni stringa nel percorso number. Correggi l'ortografia e stampa text.

La trappola di typeof null

Poiché typeof null è "object", TypeScript restringe typeof x === "object" a object | null, non a object. Aggiungi un controllo su null, altrimenti leggere una proprietà è un errore (TS18047 'x' is possibly 'null'.).

function hasId(value: unknown): boolean {
  // typeof alone leaves value as object | null
  if (typeof value === "object" && value !== null) {
    // value: object
    return "id" in value;
  }
  return false;
}

console.log(hasId({ id: 7 }));  // true
console.log(hasId(null));       // false
console.log(hasId([1, 2]));     // false (arrays pass the typeof check but have no id)
console.log(hasId("id"));       // false

typeof non sa distinguere array, date, map e oggetti semplici: sono tutti "object". Usa Array.isArray(x) per gli array e x instanceof Date per le istanze di classi. Né typeof né altro possono controllare a runtime se un valore corrisponde a un'interface, perché le interface vengono eliminate; per questo, scrivi una funzione type guard che controlla le proprietà.

typeof nelle posizioni di tipo

In un tipo, typeof someVariable copia il tipo che TypeScript ha dedotto (o che hai dichiarato) per quella variabile. Ti evita di scrivere a mano il tipo di un valore che esiste già, e mantiene i due allineati.

const theme = {
  primary: "#3178c6",
  spacing: 8,
  dark: false,
};

type Theme = typeof theme;
// { primary: string; spacing: number; dark: boolean }

function withSpacing(t: Theme, factor: number): Theme {
  return { ...t, spacing: t.spacing * factor };
}

console.log(withSpacing(theme, 2)); // { primary: '#3178c6', spacing: 16, dark: false }

let userName = "Ada";
const fixed = "Ada";
type A = typeof userName; // string
type B = typeof fixed;    // "Ada" (a const keeps its literal type)

Il risultato dipende da come è stata dichiarata la variabile: una let o una proprietà di un oggetto viene allargata (string, number), un primitivo const mantiene il suo tipo letterale. Aggiungi as const a un oggetto o a un array e typeof dà tipi letterali readonly a ogni livello. typeof accetta anche l'accesso alle proprietà, typeof theme.spacing è number, ma non espressioni arbitrarie: type T = typeof getTheme(); è un errore di sintassi (';' expected., TS1005). Per il tipo restituito da una chiamata, usa ReturnType<typeof getTheme>.

keyof typeof: le chiavi di un oggetto come tipo

keyof typeof obj è la combinazione più comune. typeof trasforma l'oggetto in un tipo, keyof ne prende le chiavi, e ottieni una union dei nomi delle proprietà che resta corretta quando l'oggetto cambia.

const prices = { apple: 1.2, pear: 0.8, kiwi: 0.5 };

type Fruit = keyof typeof prices; // "apple" | "pear" | "kiwi"

function priceOf(fruit: Fruit, quantity: number): string {
  return (prices[fruit] * quantity).toFixed(2);
}

console.log(priceOf("pear", 3)); // 2.40

// @ts-expect-error: Argument of type '"mango"' is not assignable to parameter of type '"apple" | "kiwi" | "pear"'.
priceOf("mango", 1);

Lo stesso trucco su un array costante dà una union dei suoi valori: con const roles = ["admin", "editor"] as const, il tipo (typeof roles)[number] è "admin" | "editor". Senza as const sarebbe solo string. La pagina keyof tratta keyof da solo.

ReturnType<typeof fn> e typeof sulle classi

Utility type come ReturnType e Parameters accettano un tipo funzione. Il nome di una funzione è un valore, quindi passalo prima attraverso typeof:

function createUser(name: string, admin = false) {
  return { id: name.toLowerCase(), name, admin };
}

type User = ReturnType<typeof createUser>;
// { id: string; name: string; admin: boolean }
type CreateArgs = Parameters<typeof createUser>;
// [name: string, admin?: boolean | undefined]

const args: CreateArgs = ["Grace", true];
const user: User = createUser(...args);
console.log(user); // { id: 'grace', name: 'Grace', admin: true }

Scrivere ReturnType<createUser> fallisce con 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), ed è il compilatore che chiede proprio questo.

Le classi sono l'unico caso in cui un nome è sia un valore sia un tipo. User come tipo indica un'istanza della classe; typeof User indica la classe stessa, il costruttore, compresi i suoi membri statici:

class Point {
  static origin = new Point(0, 0);
  constructor(public x: number, public y: number) {}
}

const p: Point = new Point(1, 2);        // an instance
const Ctor: typeof Point = Point;        // the class (constructor + statics)
const q = new Ctor(3, 4);                // q: Point
type Instance = InstanceType<typeof Point>; // Point

typeof, instanceof e type guard a confronto

Scegli lo strumento più specifico che funziona. Per le istanze di classi vedi instanceof; per le forme descritte da un'interface, una funzione type guard è l'unico controllo a runtime disponibile.