typeof en TypeScript : type guards et opérateur de type typeof

typeof a deux sens en TypeScript. Dans une expression, c'est l'opérateur JavaScript : il s'exécute, renvoie une chaîne comme "string" ou "number", et TypeScript affine la variable quand vous comparez cette chaîne. En position de type, c'est une requête de type : typeof config donne le type statique 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 dernière ligne montre la différence : typeof custom dans un console.log est l'opérateur d'exécution et affiche object, tandis que typeof defaults après type Options = est la requête de compilation et n'atteint jamais le JavaScript.

Les deux sens en un coup d'œil

TypeScript les distingue par leur position : le même mot-clé n'a jamais les deux sens à la fois.

Résultats de typeof à l'exécution

L'opérateur d'exécution renvoie l'une de huit chaînes. Exécutez ce code pour voir ce que donnent les valeurs courantes :

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 pur, typeof sur une variable jamais déclarée renvoie "undefined" au lieu de lever une exception. En TypeScript, ce code ne compile pas : Cannot find name 'notDeclared'. (TS2304).

Affiner avec typeof

Une comparaison typeof dans un if, un switch, un ternaire ou après && affine la variable dans chaque branche. C'est la façon standard de traiter une union de primitives, et la première vérification à utiliser sur 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" affine dans l'autre sens, vers tout sauf string. Et le compilateur connaît les huit chaînes possibles : une faute de frappe dans la comparaison est donc une erreur de compilation plutôt qu'une vérification toujours fausse en silence :

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

Le compilateur affiche 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 pur, la faute de frappe enverrait discrètement chaque chaîne vers le chemin number. Corrigez l'orthographe et le code affiche text.

Le piège de typeof null

Comme typeof null vaut "object", TypeScript affine typeof x === "object" en object | null, et non en object. Ajoutez une vérification de null, sinon lire une propriété est une erreur (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 ne sait pas distinguer tableaux, dates, maps et objets simples : tous valent "object". Utilisez Array.isArray(x) pour les tableaux et x instanceof Date pour les instances de classes. Ni typeof ni quoi que ce soit d'autre ne peut vérifier à l'exécution qu'une valeur correspond à une interface, car les interfaces sont effacées ; pour cela, écrivez une fonction type guard qui vérifie les propriétés.

typeof en position de type

Dans un type, typeof someVariable copie le type que TypeScript a inféré (ou que vous avez déclaré) pour cette variable. Cela évite d'écrire à la main le type d'une valeur qui existe déjà, et garde les deux synchronisés.

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)

Le résultat dépend de la façon dont la variable a été déclarée : une let ou une propriété d'objet est élargie (string, number), une primitive const garde son type littéral. Ajoutez as const à un objet ou à un tableau et typeof donne des types littéraux readonly à tous les niveaux. typeof accepte aussi l'accès aux propriétés, typeof theme.spacing vaut number, mais pas les expressions arbitraires : type T = typeof getTheme(); est une erreur de syntaxe (';' expected., TS1005). Pour le type que renvoie un appel, utilisez ReturnType<typeof getTheme>.

keyof typeof : les clés d'un objet en tant que type

keyof typeof obj est la combinaison la plus courante. typeof transforme l'objet en type, keyof prend ses clés, et vous obtenez une union des noms de propriétés qui reste juste quand l'objet change.

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

La même astuce sur un tableau constant donne une union de ses valeurs : avec const roles = ["admin", "editor"] as const, le type (typeof roles)[number] vaut "admin" | "editor". Sans as const, ce ne serait qu'un string. La page keyof traite de keyof seul.

ReturnType<typeof fn> et typeof sur les classes

Les types utilitaires comme ReturnType et Parameters prennent un type de fonction. Un nom de fonction est une valeur : passez-le donc d'abord par 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 }

Écrire ReturnType<createUser> échoue avec 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749) : le compilateur demande exactement cela.

Les classes sont le seul cas où un nom est à la fois une valeur et un type. User comme type désigne une instance de la classe ; typeof User désigne la classe elle-même, le constructeur, avec ses membres statiques :

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

Choisissez l'outil le plus étroit qui convient. Pour les instances de classes, voir instanceof ; pour les formes décrites par une interface, une fonction type guard est la seule vérification possible à l'exécution.