TypeScriptのkeyof: オブジェクトのキーを型として取得する

keyof はオブジェクト型を受け取り、そのプロパティ名のユニオン型を作ります。下の keyof User は型 "id" | "name" | "email" なので、その型の変数はこの3つの文字列のどれかしか持てません。

interface User {
  id: number;
  name: string;
  email: string;
}

type UserKey = keyof User; // "id" | "name" | "email"

const key: UserKey = "name"; // OK
// @ts-expect-error: "age" is not one of the keys of User
const wrong: UserKey = "age";

function printField(user: User, field: keyof User) {
  console.log(`${field}: ${user[field]}`);
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };
printField(ada, "email"); // email: ada@example.com
printField(ada, key);     // name: Ada

keyof は型システムの中にしか存在しません。コードのコンパイル時に消去されるので、実行時に何かをチェックすることはありません。与えてくれるのは、キーが本当に存在するプロパティを指しているというコンパイル時の保証です。インターフェースで email の名前を変えると、keyof User と型付けされたすべての "email" がエラーになります。

keyof typeof: 普通のオブジェクトのキー

keyof は値ではなく型に働きます。値として書いたオブジェクトなら、先に typeof で型を得てから、キーを取り出します:

const colors = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};

type Color = keyof typeof colors; // "red" | "green" | "blue"

function hex(color: Color): string {
  return colors[color];
}

console.log(hex("green")); // #00ff00
// hex("purple") would be error TS2345:
// Argument of type '"purple"' is not assignable to parameter of type '"blue" | "green" | "red"'.

内側から読みましょう。typeof colors は { red: string; green: string; blue: string } で、その keyof がキーのユニオン型です。typeof なしで keyof colors と書くと、error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'? で失敗します。

これがルックアップテーブルからユニオン型を作る定番の方法です。オブジェクトに色を追加すれば、Color 型もそれに合わせて増えます。typeof には実行時の意味もあり、typeof のページで両方を扱っています。

ジェネリクスを使った型付きのプロパティアクセス

keyof のいちばんよくある使い方はジェネリクスの制約です。K extends keyof T は「K は T のキーのどれか」という意味で、T[K] はそのキーのプロパティの型です:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const book = { title: "Dune", pages: 412, inStock: true };

const pages = getProperty(book, "pages"); // number
const title = getProperty(book, "title"); // string

console.log(pages + 1);           // 413
console.log(title.toUpperCase()); // DUNE
// getProperty(book, "author") would be error TS2345

2つ目の型パラメーターには意味があります。K を使わずに key: keyof T とすると、戻り値の型は T[keyof T]、つまりすべてのプロパティの型のユニオン（ここでは string | number | boolean）になるので、title.toUpperCase() は error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean' で失敗します。正確なキーを K で捉えると、正確なプロパティの型が保たれます。T[K] はインデックスアクセス型で、インデックスアクセス型のページで説明しています。

普通の string でインデックスアクセスする

どこかから来た string でオブジェクトにインデックスアクセスすると、とてもよく見るエラーが出ます:

// This does not compile: a plain string is not a key of Settings
interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

function read(name: string) {
  return settings[name];
}

console.log(read("theme"));

コンパイラーの出力は次のとおりです:

index.ts(10,10): error TS7053: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Settings'.
  No index signature with a parameter of type 'string' was found on type 'Settings'.

read には "colour" を含むどんな文字列でも届く可能性があり、Settings はそのキーについて何も言っていません。直し方は2つあります。本当のキーだけを受け付けるか、知らない文字列を使う前にチェックするかです。

interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

// Fix 1: only accept real keys
function read(name: keyof Settings) {
  return settings[name];
}
console.log(read("fontSize")); // 14

// Fix 2: narrow a string you do not control
function isSettingsKey(name: string): name is keyof Settings {
  return Object.hasOwn(settings, name);
}

for (const input of ["theme", "colour"]) {
  if (isSettingsKey(input)) {
    console.log(input, "=", settings[input]);
  } else {
    console.log(input, "is not a setting");
  }
}
// theme = dark
// colour is not a setting

name is keyof Settings は型述語です。関数が true を返すと、if の中でTypeScriptは input をキーとして扱います。型述語については 型ガードのページ で詳しく説明しています。

インデックスシグネチャと keyof: string | number

インデックスシグネチャを持つ型に対して、keyof はインデックスの型を返し、文字列のインデックスシグネチャなら string だけではなく string | number を返します:

type Scores = { [player: string]: number };

type ScoreKey = keyof Scores; // string | number

const scores: Scores = { ada: 3 };
scores[42] = 7; // allowed: a number key is a valid key

console.log(Object.keys(scores)); // [ '42', 'ada' ]

type OnlyStrings = Extract<keyof Scores, string>; // string
const k: OnlyStrings = "ada";
console.log(k);

JavaScriptは数値のプロパティキーをすべて文字列に変換するので、scores[42] と scores["42"] は同じプロパティです。TypeScriptはそれを number を含めることで表しています。出力はJavaScriptのルールも示しています。整数のようなキーは、ほかの文字列のキーより前に昇順で並びます。ジェネリック関数で文字列のキーだけが必要なら、Extract<keyof T, string> か string & keyof T と書きます。Exclude と Extract には専用のページがあります。

keyof の結果の一覧

ユニオン型と交差型の行は、最初は逆に見えます。ユニオン型の値はどちらのメンバーでもありうるので、安全なのは両方にあるキーだけです。交差型の値は両方のすべてを持っているので、すべてのキーを持ちます。

Object.keys が string[] を返す理由

Object.keys(obj) の型は string[] で、(keyof T)[] になることはありません。理由は構造的型付けです。値は、宣言された型より多くのプロパティを持てます。

interface Point {
  x: number;
  y: number;
}

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // allowed: extra properties are fine here

console.log(Object.keys(p)); // [ 'x', 'y', 'z' ]

// When you know the object has exactly its declared keys, cast:
const origin = { x: 0, y: 0 };
for (const key of Object.keys(origin) as (keyof typeof origin)[]) {
  console.log(key, origin[key]);
}
// x 0
// y 0

p の型は Point ですが、実行時には z というキーを持っています。Object.keys が ("x" | "y")[] を約束したら、それに頼るコードは p に対して間違ってしまいます。自分で作ったオブジェクトリテラルならキャストしても安全です。外から届くオブジェクトなら、キーは string のままにしてチェックしましょう。

マップ型の中の keyof

keyof は、型のキーをループして新しい型を作る方法でもあります。組み込みのユーティリティ型 Partial と Readonly はこの方法で書かれています:

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

interface User {
  id: number;
  name: string;
}

type UserDraft = MyPartial<User>; // { id?: number; name?: string }

[K in keyof T] は各キーを順に訪れ、T[K] はそのキーのプロパティの型を読みます。マップ型には、修飾子やキーの再マッピングを扱う専用のページがあります。