TypeScriptのtypeof: 型ガードと型としての typeof

TypeScriptの typeof には2つの意味があります。式の中ではJavaScriptの演算子で、実行されて "string" や "number" のような文字列を返し、その文字列を比較するとTypeScriptが変数を絞り込みます。型の位置では型クエリで、typeof config は変数 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 }

最後の行が違いを示しています。console.log の中の typeof custom は実行時の演算子なので object を出力しますが、type Options = のあとの typeof defaults はコンパイル時のクエリで、JavaScriptには残りません。

2つの意味の比較

TypeScriptは書かれた位置で2つを区別するので、同じキーワードが同時に両方の意味になることはありません。

実行時の typeof の結果

実行時の演算子は8種類の文字列のどれかを返します。よく使う値で何が返るか、実行して確かめてください:

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

素のJavaScriptでは、宣言されていない変数に typeof を使うと、例外を投げずに "undefined" を返します。TypeScriptではそのコードはコンパイルできません: Cannot find name 'notDeclared'.（TS2304）。

typeof による絞り込み

if、switch、三項演算子、&& のあとで typeof を比較すると、各ブランチで変数が絞り込まれます。プリミティブのユニオン型を扱う標準的な方法で、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" は逆方向に、string 以外のすべてに絞り込みます。また、コンパイラーは8種類の文字列を知っているので、比較の文字列を打ち間違えると、黙って常に 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"));

コンパイラーは 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. を出力します。素のJavaScriptなら、この打ち間違いで文字列はすべて黙って number の経路に進んでしまいます。つづりを直すと text が出力されます。

typeof null の落とし穴

typeof null は "object" なので、TypeScriptは typeof x === "object" を object ではなく object | null に絞り込みます。null のチェックを追加しないと、プロパティを読むのはエラーです（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 では配列、日付、Map、普通のオブジェクトを区別できません。どれも "object" です。配列には Array.isArray(x)、クラスのインスタンスには x instanceof Date を使います。インターフェースは消去されるので、値がインターフェースに一致するかを実行時にチェックする方法は typeof にもほかの何にもありません。その場合はプロパティをチェックする型ガード関数を書きます。

型の位置の typeof

型の中の typeof someVariable は、その変数についてTypeScriptが推論した（または宣言された）型をコピーします。すでにある値の型を手で書く手間が省け、値と型がずれることもありません。

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)

結果は変数の宣言のしかたによって変わります。let やオブジェクトのプロパティは広げられ（string、number）、const のプリミティブはリテラル型のままです。オブジェクトや配列に as const を付けると、typeof は奥まですべて readonly のリテラル型になります。typeof はプロパティアクセスも受け付けます（typeof theme.spacing は number）が、任意の式は受け付けません。type T = typeof getTheme(); は構文エラー（';' expected.、TS1005）です。呼び出しが返す型には ReturnType<typeof getTheme> を使います。

keyof typeof: オブジェクトのキーを型にする

keyof typeof obj はいちばんよく使う組み合わせです。typeof がオブジェクトを型に変え、keyof がそのキーを取り出すので、オブジェクトが変わっても正しいままのプロパティ名のユニオン型が得られます。

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

定数の配列に同じ方法を使うと、値のユニオン型が得られます。const roles = ["admin", "editor"] as const なら、型 (typeof roles)[number] は "admin" | "editor" です。as const がなければただの string になります。keyof 単体については keyof のページで説明しています。

ReturnType<typeof fn> とクラスの typeof

ReturnType や Parameters のようなユーティリティ型は関数の型を受け取ります。関数名は値なので、先に 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> と書くと 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'?（TS2749）で失敗します。コンパイラーがまさにこの書き方を求めているわけです。

名前が値でもあり型でもある唯一のケースがクラスです。型としての User はクラスのインスタンスを意味し、typeof User はクラスそのもの、つまり static メンバーを含むコンストラクターを意味します:

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、型ガードの比較

条件に合う、いちばん限定的な方法を選びましょう。クラスのインスタンスについては instanceof を参照してください。インターフェースで表した形については、使える実行時のチェックは型ガード関数だけです。