typeof w TypeScript: type guardy i operator typu typeof

typeof oznacza w TypeScript dwie rzeczy. W wyrażeniu to operator JavaScriptu: wykonuje się, zwraca string taki jak "string" albo "number", a TypeScript zawęża zmienną, gdy porównujesz ten string. W pozycji typu to zapytanie o typ: typeof config daje statyczny typ zmiennej 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 }

Ostatnia linia pokazuje różnicę: typeof custom w console.log to operator czasu wykonania i wypisuje object, a typeof defaults po type Options = to zapytanie w czasie kompilacji, które nigdy nie trafia do JavaScriptu.

Dwa znaczenia w skrócie

TypeScript rozróżnia je po pozycji, więc to samo słowo kluczowe nigdy nie oznacza obu rzeczy naraz.

Wyniki typeof w czasie wykonania

Operator czasu wykonania zwraca jeden z ośmiu stringów. Uruchom to, żeby zobaczyć, co dają typowe wartości:

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

W zwykłym JavaScripcie typeof na zmiennej, której nigdy nie zadeklarowano, zwraca "undefined" zamiast rzucać wyjątek. W TypeScript taki kod się nie kompiluje: Cannot find name 'notDeclared'. (TS2304).

Zawężanie przez typeof

Porównanie typeof w if, switch, operatorze trójargumentowym albo po && zawęża zmienną w każdej gałęzi. To standardowy sposób obsługi unii typów prostych i pierwsze sprawdzenie, po które warto sięgnąć przy 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" zawęża w drugą stronę, do wszystkiego poza string. Kompilator zna osiem możliwych stringów, więc literówka w porównaniu to błąd kompilacji, a nie sprawdzenie, które po cichu zawsze daje false:

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

Kompilator wypisuje 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. W zwykłym JavaScripcie ta literówka po cichu wysłałaby każdy string ścieżką dla number. Popraw pisownię, a kod wypisze text.

Pułapka typeof null

Ponieważ typeof null to "object", TypeScript zawęża typeof x === "object" do object | null, a nie do object. Dodaj sprawdzenie null, bo inaczej odczyt właściwości jest błędem (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 nie odróżni tablic, dat, map i zwykłych obiektów: wszystkie to "object". Dla tablic używaj Array.isArray(x), a dla instancji klas x instanceof Date. Ani typeof, ani nic innego nie sprawdzi w czasie wykonania, czy wartość pasuje do interfejsu, bo interfejsy są usuwane przy kompilacji. Do tego napisz funkcję type guard, która sprawdza właściwości.

typeof w pozycjach typu

W typie typeof someVariable kopiuje typ, który TypeScript wywnioskował (albo który zadeklarowano) dla tej zmiennej. Oszczędza ręcznego pisania typu dla wartości, która już istnieje, i utrzymuje oba w zgodzie.

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)

Wynik zależy od tego, jak zadeklarowano zmienną: let albo właściwość obiektu są poszerzane (string, number), a typ prosty w const zachowuje typ literału. Dodaj as const do obiektu albo tablicy, a typeof da typy literałów readonly na każdym poziomie. typeof przyjmuje też dostęp do właściwości, typeof theme.spacing to number, ale nie dowolne wyrażenia: type T = typeof getTheme(); to błąd składni (';' expected., TS1005). Dla typu zwracanego przez wywołanie użyj ReturnType<typeof getTheme>.

keyof typeof: klucze obiektu jako typ

keyof typeof obj to najczęstsze połączenie. typeof zamienia obiekt w typ, keyof bierze jego klucze, a ty dostajesz unię nazw właściwości, która pozostaje poprawna, gdy obiekt się zmienia.

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

Ta sama sztuczka na stałej tablicy daje unię jej wartości: przy const roles = ["admin", "editor"] as const typ (typeof roles)[number] to "admin" | "editor". Bez as const byłby to tylko string. Sam keyof omawia strona o keyof.

ReturnType<typeof fn> i typeof na klasach

Typy narzędziowe, takie jak ReturnType i Parameters, przyjmują typ funkcji. Nazwa funkcji to wartość, więc najpierw przepuść ją przez 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 }

Zapis ReturnType<createUser> kończy się błędem 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), czyli kompilator prosi dokładnie o to.

Klasy to jedyny przypadek, gdy nazwa jest jednocześnie wartością i typem. User jako typ oznacza instancję klasy, a typeof User oznacza samą klasę, czyli konstruktor razem z jego statycznymi składowymi:

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 i type guard

Wybierz najwęższe narzędzie, które pasuje. Dla instancji klas zobacz instanceof. Dla kształtów opisanych interfejsem jedynym dostępnym sprawdzeniem w czasie wykonania jest funkcja type guard.