Typeof в TypeScript: защитники типов и оператор типа typeof

typeof в TypeScript означает две вещи. В выражении это оператор JavaScript: он выполняется, возвращает строку вроде "string" или "number", и TypeScript сужает переменную, когда вы сравниваете эту строку. В позиции типа это запрос типа: typeof config даёт статический тип переменной 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 }

Последняя строка показывает разницу: typeof custom в console.log это оператор времени выполнения, и он печатает object, а typeof defaults после type Options = это запрос времени компиляции, который никогда не попадает в JavaScript.

Два значения вкратце

TypeScript различает их по позиции, поэтому одно и то же ключевое слово никогда не означает обе вещи сразу.

Результаты typeof во время выполнения

Оператор времени выполнения возвращает одну из восьми строк. Запустите пример, чтобы увидеть, что дают распространённые значения:

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

В обычном JavaScript typeof для переменной, которая никогда не объявлялась, возвращает "undefined", а не бросает исключение. В TypeScript такой код не компилируется: Cannot find name 'notDeclared'. (TS2304).

Сужение через typeof

Сравнение typeof в if, switch, тернарном операторе или после && сужает переменную в каждой ветке. Это стандартный способ обработать объединение примитивов и первая проверка, к которой стоит обратиться для 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" сужает в обратную сторону, до всего, кроме string. А поскольку компилятор знает восемь возможных строк, опечатка в сравнении даёт ошибку компиляции, а не проверку, которая молча всегда ложна:

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

Компилятор выводит 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. В обычном JavaScript опечатка молча отправила бы каждую строку по пути number. Исправьте написание, и код напечатает text.

Ловушка typeof null

Поскольку typeof null равно "object", TypeScript сужает typeof x === "object" до object | null, а не до object. Добавьте проверку на null, иначе чтение свойства даст ошибку (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 не отличает массивы, даты, Map и обычные объекты: все они "object". Используйте Array.isArray(x) для массивов и x instanceof Date для экземпляров классов. Ни typeof, ни что-либо ещё не может проверить во время выполнения, соответствует ли значение интерфейсу, потому что интерфейсы стираются; для этого напишите функцию-защитник типа, которая проверяет свойства.

typeof в позициях типа

В типе typeof someVariable копирует тип, который TypeScript вывел (или вы объявили) для этой переменной. Это избавляет от ручного описания типа для уже существующего значения и держит их в согласии.

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)

Результат зависит от того, как объявлена переменная: let или свойство объекта расширяются (string, number), примитив в const сохраняет литеральный тип. Добавьте as const к объекту или массиву, и typeof даст readonly литеральные типы на всю глубину. typeof принимает и обращение к свойству, typeof theme.spacing это number, но не произвольные выражения: type T = typeof getTheme(); это синтаксическая ошибка (';' expected., TS1005). Для типа, который возвращает вызов, используйте ReturnType<typeof getTheme>.

keyof typeof: ключи объекта как тип

keyof typeof obj самая частая комбинация. typeof превращает объект в тип, keyof берёт его ключи, и вы получаете объединение имён свойств, которое остаётся верным при изменении объекта.

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

Тот же приём с константным массивом даёт объединение его значений: при const roles = ["admin", "editor"] as const тип (typeof roles)[number] равен "admin" | "editor". Без as const это был бы просто string. Сам keyof описан на странице keyof.

ReturnType<typeof fn> и typeof для классов

Служебные типы вроде ReturnType и Parameters принимают тип функции. Имя функции это значение, поэтому сначала пропустите его через 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 }

Запись ReturnType<createUser> падает с ошибкой 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), и компилятор просит именно этого.

Классы это единственный случай, когда имя одновременно значение и тип. User как тип означает экземпляр класса; typeof User означает сам класс, конструктор, включая его статические члены:

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 или защитник типа

Выбирайте самый узкий подходящий инструмент. Для экземпляров классов см. instanceof; для форм, описанных интерфейсом, функция-защитник типа единственная доступная проверка во время выполнения.