【実務・中級編】関数の引数に渡すオブジェクトの「プロパティ存在確認」を型ガードで強制する設計 – TypeScript コア・型システムの基礎解析バイブル

TypeScriptの型システムは、我々の意図をコンパイラに正確に伝えることで、実行時エラーをビルド時にねじ伏せるための最強の武器だ。

しかし、コードレビューをしていると、未だに以下のようなコードを見かけることがある。

// ❌ 現場でよく見かける「思考停止」のコード
function processUser(user: { id: string; settings?: { theme?: string } }) {
if (user.settings && user.settings.theme) {
console.log(user.settings.theme.toUpperCase());
}
}

このコードの何が問題か。オプショナルチェーニング（`?.`）や安易なTruthyチェックに頼ることで、「本来存在していなければならないはずのデータ構造の揺らぎ」をコードベース全体に伝播させてしまっている点だ。結果として、アプリケーションのあちこちに「ひょっとしたら無いかもしれない」という不安を抱えた防衛的コードが乱立し、ドメインロジックの本体が見えなくなる。

今回は、関数の引数に渡される不確実なオブジェクトに対し、「プロパティの存在確認」を型ガード（Type Guard）によって強制し、認知負荷の低いクリーンかつ堅牢な関数を設計する極意を伝授する。

—

なぜオプショナルチェーニングだけでは不十分なのか

フロントエンドでのAPI連携や、複雑な設定オブジェクトを扱うコンポーネント設計において、オブジェクトの形状（Shape）が部分的であることは日常茶飯事だ。

しかし、単に `obj.prop?.subProp` で逃げ続けると、コンパイラは「そのプロパティが本当に存在するかどうか」のスコープを限定してくれない。そのため、関数の後半で再度プロパティにアクセスする際にも、毎回オプショナルな記述や冗長な条件分岐が必要になる。

私たちが目指すべきは、「あるスコープに入った瞬間、そのオブジェクトは必要なプロパティを確実に備えている」という状態を型システムに保証させることだ。

—

ユーザー定義型ガードによる「型の一撃確定」

TypeScriptの `in` 演算子やユーザー定義型ガード（User-Defined Type Guards）を使いこなせば、条件分岐の通過と同時に、コンパイラに型の絞り込み（Narrowing）を行わせることができる。

実際のプロダクションコードを想定した、洗練された設計パターンを見てみよう。

プロダクションコード例：APIレスポンスの安全な処理パイプライン

ユーザー設定のドメインモデル

/
interface StrictUserSettings {
theme: ‘light’ | ‘dark’;
notifications: boolean;
}

interface RawUserPayload {
id: string;
name: string;
// settingsは送られてくるかもしれないし、空かもしれない、あるいは一部だけかもしれない
settings?: Partial;
}

【型ガード関数】
渡されたオブジェクトが ‘settings’ プロパティを持ち、
かつそれがオブジェクトとして有効であるかをコンパイラに証明する。
戻り値の `payload is RawUserPayload & { settings: StrictUserSettings }` がキモ。

/
function hasCompleteSettings(
payload: RawUserPayload
): payload is RawUserPayload & { settings: StrictUserSettings } {
return (
payload.settings !== undefined &&
typeof payload.settings.theme === ‘string’ &&
typeof payload.settings.notifications === ‘boolean’
);
}

【ドメインロジック関数】
完全に型保証された安全な世界

/
function applyUserPreferences(user: RawUserPayload) {
// ここで型ガードを通す
if (!hasCompleteSettings(user)) {
// 存在しない、または不完全な場合はデフォルトフォールバックを適用して早期リターン
console.warn(`[Warning] User ${user.id} lacks complete settings. Using defaults.`);
return;
}

// 🔥 注目：このブロック内では、user.settings は StrictUserSettings として扱われる。
// オプショナルチェーニングは一切不要。コンパイラが完全に型を把握している。
const currentTheme = user.settings.theme; // ‘light’ | ‘dark’
const notifies = user.settings.notifications; // boolean

console.log(`Applying theme: ${currentTheme}, Notifications: ${notifies}`);
}

// — 実行テスト —
const validUser: RawUserPayload = {
id: ‘usr_001’,
name: ‘Alice’,
settings: { theme: ‘dark’, notifications: true }
};

const invalidUser: RawUserPayload = {
id: ‘usr_002’,
name: ‘Bob’,
settings: { theme: ‘light’ } // notifications が欠けている
}

applyUserPreferences(validUser); // => 成功: 設定が適用される
applyUserPreferences(invalidUser); // => 警告ログが出力され、安全に処理が中断される

—

この設計がもたらすアーキテクチャ上のメリット

1. ドメインロジックの純粋性の維持
ビジネスロジックを書く関数内部に、「プロパティが存在するかどうか分からない」というノイズを持ち込ませない。関数の入口（境界線）で型ガードによってデータを「浄化」し、内部では純粋なドメインモデルとして扱える。

2. 変更に対する強靭性（Refactor Resilience）
将来的に `StrictUserSettings` に新しい必須プロパティ（例: `language: string`）が追加された場合、型ガード関数 `hasCompleteSettings` の実装を修正し忘れると、TypeScriptコンパイラが即座にエラーを検知して教えてくれる。APIの仕様変更に対する最強の防壁となる。

3. 実行時パフォーマンスの最適化
JavaScriptのランタイムにおいて、無駄なプロパティアクセスのチェインや、あいまいな真偽値評価を何度も行う必要がなくなる。入口で一度構造を検証してしまえば、以降はダイレクトにメモリ上の値へアクセスできる。

—

チーフアーキテクトからの提言

「とりあえず `?` をつけておく」というコーディングは、一見すると親切で安全そうに見える。しかしそれは、型システムが持つ本来の表現力と安全性を放棄し、バグの温床を先送りしているにすぎない。

フロントエンドであれ、Node.jsのバックエンドであれ、外部から流入するデータ（APIレスポンス、localStorage、ユーザー入力）はすべて「汚染されている」という前提に立ち、境界線（Boundary）で確実に型ガードによって型を確定させること。

このデザインパターンをチームに浸透させれば、コードレビューで「このプロパティ、本当に存在しますか？」という不毛な議論をする時間は永遠に消え去るはずだ。さあ、今すぐプロジェクトの `?.` を見直し、厳格な型ガードによる設計へシフトしよう。