typeof em TypeScript: type guards e o operador de tipo typeof

O typeof significa duas coisas no TypeScript. Em uma expressão, é o operador do JavaScript: roda, retorna uma string como "string" ou "number", e o TypeScript faz o narrowing da variável quando você compara essa string. Em uma posição de tipo, é uma type query: typeof config dá o tipo estático da variável 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 }

A última linha mostra a diferença: typeof custom dentro de um console.log é o operador de tempo de execução e imprime object, enquanto typeof defaults depois de type Options = é a query de tempo de compilação e nunca chega ao JavaScript.

Os dois significados em resumo

O TypeScript os distingue pela posição, então a mesma palavra-chave nunca significa as duas coisas ao mesmo tempo.

Resultados do typeof em tempo de execução

O operador de tempo de execução retorna uma de oito strings. Rode isto para ver o que valores comuns dão:

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

Em JavaScript puro, typeof em uma variável que nunca foi declarada retorna "undefined" em vez de lançar erro. No TypeScript esse código não compila: Cannot find name 'notDeclared'. (TS2304).

Narrowing com typeof

Uma comparação com typeof em um if, um switch, um operador ternário ou depois de && estreita a variável em cada ramo. É o jeito padrão de lidar com uma union de primitivos, e a primeira verificação a usar em um 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" estreita no sentido contrário, para tudo exceto string. E o compilador conhece as oito strings possíveis, então um erro de digitação na comparação é erro de compilação, e não uma verificação que é sempre falsa em silêncio:

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

O compilador mostra 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. Em JavaScript puro, o erro de digitação mandaria em silêncio toda string pelo caminho do number. Corrija a grafia e ele imprime text.

A armadilha do typeof null

Como typeof null é "object", o TypeScript estreita typeof x === "object" para object | null, e não para object. Adicione uma verificação de null, senão ler uma propriedade é erro (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

O typeof não distingue arrays, datas, maps e objetos simples: todos são "object". Use Array.isArray(x) para arrays e x instanceof Date para instâncias de classes. Nem o typeof nem nada mais consegue verificar em tempo de execução se um valor corresponde a uma interface, porque as interfaces são apagadas; para isso, escreva uma função type guard que verifica as propriedades.

typeof em posições de tipo

Em um tipo, typeof someVariable copia o tipo que o TypeScript inferiu (ou que você declarou) para aquela variável. Isso poupa escrever à mão um tipo para um valor que já existe e mantém os dois sincronizados.

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)

O resultado depende de como a variável foi declarada: um let ou uma propriedade de objeto é alargado (string, number), um primitivo const mantém o literal type. Adicione as const a um objeto ou array e o typeof dá literal types readonly em todos os níveis. O typeof também aceita acesso a propriedades, typeof theme.spacing é number, mas não expressões arbitrárias: type T = typeof getTheme(); é um erro de sintaxe (';' expected., TS1005). Para o tipo que uma chamada retorna, use ReturnType<typeof getTheme>.

keyof typeof: as chaves de um objeto como tipo

keyof typeof obj é a combinação mais comum. O typeof transforma o objeto em um tipo, o keyof pega as chaves dele, e você obtém uma union dos nomes das propriedades que continua correta quando o objeto muda.

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

O mesmo truque em um array constante dá uma union dos valores dele: com const roles = ["admin", "editor"] as const, o tipo (typeof roles)[number] é "admin" | "editor". Sem as const seria só string. A página sobre keyof trata do keyof sozinho.

ReturnType<typeof fn> e typeof em classes

Utility types como ReturnType e Parameters recebem um tipo de função. O nome de uma função é um valor, então passe-o antes pelo 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 }

Escrever ReturnType<createUser> falha com 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), que é o compilador pedindo exatamente isso.

Classes são o único caso em que um nome é ao mesmo tempo valor e tipo. User como tipo significa uma instância da classe; typeof User significa a própria classe, o construtor, incluindo os membros estáticos:

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 vs instanceof vs type guard

Escolha a ferramenta mais específica que servir. Para instâncias de classes, veja instanceof; para formatos descritos por uma interface, uma função type guard é a única verificação de tempo de execução disponível.