TypeScript typeof: Type Guards und der Typoperator typeof

typeof bedeutet in TypeScript zwei Dinge. In einem Ausdruck ist es der JavaScript-Operator: Er läuft, gibt einen String wie "string" oder "number" zurück, und TypeScript engt die Variable ein, wenn du diesen String vergleichst. An einer Typposition ist es eine Type Query: typeof config liefert den statischen Typ der Variablen 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 }

Die letzte Zeile zeigt den Unterschied: typeof custom in einem console.log ist der Laufzeitoperator und gibt object aus, während typeof defaults nach type Options = die Abfrage beim Kompilieren ist und nie im JavaScript ankommt.

Die zwei Bedeutungen im Überblick

TypeScript unterscheidet sie anhand der Position, dasselbe Schlüsselwort bedeutet also nie beides zugleich.

Ergebnisse von typeof zur Laufzeit

Der Laufzeitoperator gibt einen von acht Strings zurück. Führe das aus, um zu sehen, was gängige Werte ergeben:

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

In reinem JavaScript gibt typeof auf eine nie deklarierte Variable "undefined" zurück, statt zu werfen. In TypeScript kompiliert dieser Code nicht: Cannot find name 'notDeclared'. (TS2304).

Narrowing mit typeof

Ein Vergleich mit typeof in einem if, einem switch, einem ternären Ausdruck oder nach && engt die Variable in jedem Zweig ein. Das ist der Standardweg, eine Union aus primitiven Typen zu behandeln, und die erste Prüfung, zu der du bei unknown greifst.

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" engt in die andere Richtung ein, auf alles außer string. Und der Compiler kennt die acht möglichen Strings, ein Tippfehler im Vergleich ist also ein Compilerfehler statt einer Prüfung, die stillschweigend immer false ist:

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

Der Compiler gibt 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. aus. In reinem JavaScript würde der Tippfehler still jeden String in den Pfad für number schicken. Korrigiere die Schreibweise, dann gibt es text aus.

Die Falle typeof null

Weil typeof null gleich "object" ist, engt TypeScript typeof x === "object" auf object | null ein, nicht auf object. Ergänze eine Prüfung auf null, sonst ist das Lesen einer Eigenschaft ein Fehler (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 kann Arrays, Datumswerte, Maps und einfache Objekte nicht unterscheiden: Alle sind "object". Nimm Array.isArray(x) für Arrays und x instanceof Date für Klasseninstanzen. Weder typeof noch sonst etwas kann zur Laufzeit prüfen, ob ein Wert zu einem Interface passt, weil Interfaces entfernt werden; dafür schreibst du eine Type-Guard-Funktion, die die Eigenschaften prüft.

typeof an Typpositionen

In einem Typ kopiert typeof someVariable den Typ, den TypeScript für diese Variable abgeleitet hat (oder den du deklariert hast). Das erspart es, einen Typ für einen bereits vorhandenen Wert von Hand zu schreiben, und hält beide synchron.

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)

Das Ergebnis hängt davon ab, wie die Variable deklariert wurde: Eine let oder eine Objekteigenschaft wird erweitert (string, number), ein primitiver Wert in einer const behält seinen Literaltyp. Ergänze as const an einem Objekt oder Array, dann liefert typeof readonly Literaltypen bis ganz nach unten. typeof akzeptiert auch Eigenschaftszugriffe, typeof theme.spacing ist number, aber keine beliebigen Ausdrücke: type T = typeof getTheme(); ist ein Syntaxfehler (';' expected., TS1005). Für den Typ, den ein Aufruf zurückgibt, nimm ReturnType<typeof getTheme>.

keyof typeof: die Schlüssel eines Objekts als Typ

keyof typeof obj ist die häufigste Kombination. typeof macht das Objekt zu einem Typ, keyof nimmt dessen Schlüssel, und du bekommst eine Union der Eigenschaftsnamen, die korrekt bleibt, wenn sich das Objekt ändert.

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

Derselbe Trick auf einem konstanten Array liefert eine Union seiner Werte: Mit const roles = ["admin", "editor"] as const ist der Typ (typeof roles)[number] gleich "admin" | "editor". Ohne as const wäre er nur string. Die Seite zu keyof behandelt keyof für sich.

ReturnType<typeof fn> und typeof bei Klassen

Utility Types wie ReturnType und Parameters nehmen einen Funktionstyp. Ein Funktionsname ist ein Wert, also führst du ihn zuerst durch 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> zu schreiben scheitert mit 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), und genau darum bittet der Compiler hier.

Klassen sind der eine Fall, in dem ein Name zugleich Wert und Typ ist. User als Typ bedeutet eine Instanz der Klasse; typeof User bedeutet die Klasse selbst, den Konstruktor, einschließlich seiner statischen Member:

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 ein Type Guard

Nimm das engste Werkzeug, das passt. Für Klasseninstanzen siehe instanceof; für Formen, die ein Interface beschreibt, ist eine Type-Guard-Funktion die einzige verfügbare Prüfung zur Laufzeit.