TypeScript typeof: Type Guards and the typeof Type Operator

typeof means two things in TypeScript. In an expression it is the JavaScript operator: it runs, returns a string like "string" or "number", and TypeScript narrows the variable when you compare that string. In a type position it is a type query: typeof config gives the static type of the 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 }

The last line shows the difference: typeof custom in a console.log is the runtime operator and prints object, while typeof defaults after type Options = is the compile-time query and never reaches the JavaScript.

The Two Meanings at a Glance

TypeScript tells them apart by position, so the same keyword never means both at once.

typeof Results at Runtime

The runtime operator returns one of eight strings. Run this to see what common values give:

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 plain JavaScript, typeof on a variable that was never declared returns "undefined" instead of throwing. In TypeScript that code does not compile: Cannot find name 'notDeclared'. (TS2304).

Narrowing With typeof

A typeof comparison in an if, a switch, a ternary or after && narrows the variable in each branch. It is the standard way to handle a union of primitives, and the first check to reach for on 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" narrows the other way, to everything except string. And the compiler knows the eight possible strings, so a typo in the comparison is a compile error rather than a check that is silently always false:

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

The compiler prints 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. In plain JavaScript the typo would quietly send every string down the number path. Fix the spelling and it prints text.

The typeof null Trap

Because typeof null is "object", TypeScript narrows typeof x === "object" to object | null, not object. Add a null check, or reading a property is an 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 cannot tell arrays, dates, maps and plain objects apart: all of them are "object". Use Array.isArray(x) for arrays and x instanceof Date for class instances. Neither typeof nor anything else can check whether a value matches an interface at run time, because interfaces are erased; for that, write a type guard function that checks the properties.

typeof in Type Positions

In a type, typeof someVariable copies the type TypeScript inferred (or you declared) for that variable. It saves writing a type by hand for a value that already exists, and keeps the two in sync.

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)

The result depends on how the variable was declared: a let or an object property is widened (string, number), a const primitive keeps its literal type. Add as const to an object or array and typeof gives readonly literal types all the way down. typeof also accepts property access, typeof theme.spacing is number, but not arbitrary expressions: type T = typeof getTheme(); is a syntax error (';' expected., TS1005). For the type a call returns, use ReturnType<typeof getTheme>.

keyof typeof: Keys of an Object as a Type

keyof typeof obj is the most common combination. typeof turns the object into a type, keyof takes its keys, and you get a union of the property names that stays correct as the object changes.

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

The same trick on a constant array gives a union of its values: with const roles = ["admin", "editor"] as const, the type (typeof roles)[number] is "admin" | "editor". Without as const it would only be string. The keyof page covers keyof on its own.

ReturnType<typeof fn> and typeof on Classes

Utility types such as ReturnType and Parameters take a function type. A function name is a value, so pass it through typeof first:

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 }

Writing ReturnType<createUser> fails with 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), which is the compiler asking for exactly this.

Classes are the one case where a name is both a value and a type. User as a type means an instance of the class; typeof User means the class itself, the constructor, including its static members:

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

Pick the narrowest tool that fits. For class instances see instanceof; for shapes described by an interface, a type guard function is the only runtime check available.