typeof en TypeScript: type guards y el operador de tipo typeof

typeof significa dos cosas en TypeScript. En una expresión es el operador de JavaScript: se ejecuta, devuelve un string como "string" o "number", y TypeScript estrecha la variable cuando comparas ese string. En una posición de tipo es una consulta de tipo: typeof config da el tipo estático de la variable 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 }

La última línea muestra la diferencia: typeof custom dentro de un console.log es el operador de ejecución e imprime object, mientras que typeof defaults después de type Options = es la consulta en tiempo de compilación y nunca llega al JavaScript.

Los dos significados de un vistazo

TypeScript los distingue por la posición, así que la misma palabra clave nunca significa las dos cosas a la vez.

Resultados de typeof en tiempo de ejecución

El operador devuelve uno de ocho strings. Ejecuta esto para ver qué dan los valores habituales:

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

En JavaScript normal, typeof sobre una variable que nunca se declaró devuelve "undefined" en lugar de lanzar un error. En TypeScript ese código no compila: Cannot find name 'notDeclared'. (TS2304).

Estrechar con typeof

Una comparación con typeof en un if, un switch, un ternario o después de && estrecha la variable en cada rama. Es la forma estándar de manejar una unión de primitivos, y la primera comprobación a la que recurrir con 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" estrecha en el otro sentido, a todo excepto string. Y el compilador conoce los ocho strings posibles, así que una errata en la comparación es un error de compilación y no una comprobación que siempre da false sin avisar:

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

El compilador muestra 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. En JavaScript normal la errata mandaría sin avisar todos los strings por el camino de number. Corrige la ortografía y se imprime text.

La trampa de typeof null

Como typeof null es "object", TypeScript estrecha typeof x === "object" a object | null, no a object. Añade una comprobación de null, o leer una propiedad será un error (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 no distingue arrays, fechas, maps y objetos normales: todos son "object". Usa Array.isArray(x) para arrays y x instanceof Date para instancias de clases. Ni typeof ni ninguna otra cosa puede comprobar en tiempo de ejecución si un valor cumple una interfaz, porque las interfaces se borran; para eso, escribe una función type guard que compruebe las propiedades.

typeof en posiciones de tipo

En un tipo, typeof someVariable copia el tipo que TypeScript infirió (o que declaraste) para esa variable. Te ahorra escribir a mano un tipo para un valor que ya existe y mantiene los dos 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)

El resultado depende de cómo se declaró la variable: un let o una propiedad de objeto se ensanchan (string, number), un primitivo const conserva su tipo literal. Añade as const a un objeto o array y typeof da tipos literales readonly en todos los niveles. typeof también acepta acceso a propiedades, typeof theme.spacing es number, pero no expresiones arbitrarias: type T = typeof getTheme(); es un error de sintaxis (';' expected., TS1005). Para el tipo que devuelve una llamada, usa ReturnType<typeof getTheme>.

keyof typeof: las claves de un objeto como tipo

keyof typeof obj es la combinación más habitual. typeof convierte el objeto en un tipo, keyof toma sus claves, y obtienes una unión de los nombres de propiedad que sigue siendo correcta cuando el objeto 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);

El mismo truco sobre un array constante da una unión de sus valores: con const roles = ["admin", "editor"] as const, el tipo (typeof roles)[number] es "admin" | "editor". Sin as const sería solo string. La página de keyof trata keyof por separado.

ReturnType<typeof fn> y typeof sobre clases

Utility types como ReturnType y Parameters reciben un tipo de función. El nombre de una función es un valor, así que pásalo antes por 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 }

Escribir ReturnType<createUser> falla con 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), que es el compilador pidiendo exactamente esto.

Las clases son el único caso en el que un nombre es a la vez un valor y un tipo. User como tipo significa una instancia de la clase; typeof User significa la clase en sí, el constructor, incluidos sus miembros 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 frente a instanceof y a un type guard

Elige la herramienta más específica que encaje. Para instancias de clases consulta instanceof; para formas descritas por una interfaz, una función type guard es la única comprobación posible en tiempo de ejecución.