TypeScriptでオブジェクトのキーを取得する方法：型安全なキー操作の基本と実践

TypeScriptでアプリケーションを開発する際、オブジェクトのプロパティ名を抽出して処理を行う場面は非常に多く存在します。

しかし、標準的なJavaScriptの Object.keys() をそのまま使用すると、TypeScriptの型システム上では期待通りの挙動にならないことがあります。

特に、取得したキーを使用してオブジェクトの値にアクセスしようとした際に、型エラーが発生して困惑した経験を持つ開発者も少なくありません。

本記事では、TypeScriptにおいてオブジェクトのキーを型安全に取得する方法と、その背景にある型推論の仕組みを詳しく解説します。

型安全性を保ちながら効率的にコーディングを行うためのテクニックを学び、開発現場で即戦力となる知識を身に付けていきましょう。

TypeScriptにおけるObject.keys()の基本的な挙動

JavaScriptでオブジェクトのすべてのキーを取得する場合、 Object.keys() メソッドを使用するのが一般的です。

しかし、TypeScriptにおいてこのメソッドは、常に string[] 型を返すように定義されています。

まずは、具体的なコード例を見て、どのような問題が発生するのかを確認してみましょう。

const user = {
  id: 1,
  name: "田中太郎",
  email: "tanaka@example.com"
};

// keys の型は string[] と推論される
const keys = Object.keys(user);

keys.forEach(key => {
  // ここでエラーが発生する可能性がある
  // Element implicitly has an 'any' type because expression of type 'string' can't be used to index type
  console.log(user[key]); 
});

1
田中太郎
tanaka@example.com
(※ただしコンパイルエラーが発生する場合がある)

このエラーは、 keys に含まれる値が string 型であるのに対し、 user オブジェクトのインデックスには "id" | "name" | "email" という特定のリテラル型が求められているために発生します。

なぜTypeScriptは Object.keys() の戻り値を厳密なキーの型にしてくれないのでしょうか。

それは、TypeScriptの「構造的部分型 (Structural Subtyping)」という特性に理由があります。

TypeScriptでは、定義された型よりも多くのプロパティを持つオブジェクトが代入されることを許容しています。

そのため、実行時に Object.keys() が返す配列の中には、コンパイル時に認識できていない未知のキーが含まれている可能性があるのです。

この安全性を考慮して、TypeScriptの標準定義では戻り値が string[] に固定されています。

型アサーションを使用してキーを取得する

最も手軽に型エラーを回避する方法は、型アサーション (Type Assertion) を利用することです。

開発者が「このオブジェクトのキーはこれら以外に存在しない」と断言できる場合に有効な手段となります。

as キーワードを使用して、 string[] をより具体的な型へとキャストします。

const product = {
  code: "A001",
  price: 1500,
  stock: 10
};

// Object.keys の結果を (keyof typeof product)[] として扱う
const productKeys = Object.keys(product) as (keyof typeof product)[];

productKeys.forEach(key => {
  // key が "code" | "price" | "stock" と認識されるためエラーにならない
  console.log(`${key}: ${product[key]}`);
});

code: A001
price: 1500
stock: 10

ここで使用している keyof typeof product は、 product オブジェクトの型からプロパティ名の連合型を抽出する便利な記述です。

型アサーションは強力ですが、乱用には注意が必要です。

万が一、オブジェクトに実行時のみ存在するキーが含まれていた場合、型定義と実態に乖離が生じ、ランタイムエラーの原因となる可能性があります。

汎用的なユーティリティ関数の作成

プロジェクト全体で何度もオブジェクトのキー取得を行う場合、毎回型アサーションを記述するのは非効率です。

そのような場合は、型安全なキー取得を行うための汎用的なラッパー関数を作成するのが推奨されます。

ジェネリクスを活用することで、どのようなオブジェクトに対しても適切な型を適用できる関数を定義できます。

/**
 * オブジェクトのキーを厳密な型で取得する関数
 */
function getKeys<T extends object>(obj: T): (keyof T)[] {
  return Object.keys(obj) as (keyof T)[];
}

const config = {
  apiEndpoint: "https://api.example.com",
  timeout: 5000,
  retryLimit: 3
};

// getKeys を使用することで型推論が維持される
const configKeys = getKeys(config);

configKeys.forEach(key => {
  // key は "apiEndpoint" | "timeout" | "retryLimit" 型になる
  const value = config[key];
  console.log(key, value);
});

このように共通化することで、コードの可読性が向上し、型アサーションを一箇所に閉じ込めることができます。

また、関数の戻り値として型が保証されるため、呼び出し側で安全にプロパティへのアクセスが可能になります。

Object.entries() を活用したキーと値の同時取得

キーだけでなく、対応する値も同時に取得してループ処理を行いたい場合は、 Object.entries() を検討しましょう。

ただし、 Object.entries() も同様にデフォルトでは [string, any][] のような型になってしまいます。

こちらも型安全に扱うためには、適切な型定義が必要です。

const scores: Record<string, number> = {
  math: 90,
  english: 85,
  science: 95
};

// エントリを型安全にループする例
(Object.entries(scores) as [keyof typeof scores, number][]).forEach(([key, value]) => {
  console.log(`${key}のスコアは${value}点です。`);
});

mathのスコアは90点です。
englishのスコアは85点です。
scienceのスコアは95点です。

Object.entries() を使用すると、キーと値の両方に型を付与した状態で配列として受け取れるため、分割代入と組み合わせて簡潔に記述できます。

手法別の比較と使い分け

オブジェクトのキーを取得する方法はいくつかありますが、状況に応じて最適な手段を選択することが重要です。

以下の表に、主な手法の特徴をまとめました。

基本的には、「自作の getKeys 関数」を用意して一貫性を保つのが、中長期的なメンテナンス性の観点から最善の選択肢と言えるでしょう。

keyof 演算子と mapped types の応用

キーを取得するだけでなく、そのキーを基に新しい型を定義する技術も重要です。

TypeScriptの keyof 演算子を活用すると、既存のオブジェクトのキーに基づいた制約を設けることができます。

例えば、特定のオブジェクトのキーのみを受け取る引数を定義する場合などに非常に強力です。

interface Settings {
  theme: "light" | "dark";
  notifications: boolean;
  fontSize: number;
}

function updateSetting<K extends keyof Settings>(key: K, value: Settings[K]) {
  console.log(`Setting ${key} updated to ${value}`);
}

// 正しい呼び出し
updateSetting("theme", "dark");

// エラー：fontSize に文字列を渡そうとしている
// updateSetting("fontSize", "large");

このように keyof を利用して「キーと値の整合性」を保つ設計を心がけることで、 Object.keys() で取得した後の処理もより堅牢なものになります。

型安全なキー操作を極めることは、TypeScriptにおけるオブジェクト設計の質を大きく引き上げることに直結します。

まとめ

TypeScriptにおいてオブジェクトのキーを取得する際、 Object.keys() が string[] を返す挙動は、言語仕様上の安全策であることを理解することが第一歩です。

その上で、型アサーションやジェネリクスを用いたユーティリティ関数を活用することで、実務に必要な型安全性と柔軟性の両立が可能になります。

開発シーンに合わせて、 keyof 演算子や Object.entries() を適切に使い分けていきましょう。

まずは、今回紹介した getKeys 関数を自身のプロジェクトに導入し、型エラーのない快適な開発体験を構築してみてください。

型安全なキー操作をマスターすることで、バグの少ない、堅牢なTypeScriptコードを記述できるようになるはずです。