【実務・中級編】Mapped TypesとInterfaceを組み合わせた「部分更新（Partial Update）」の型安全化 – TypeScript コア・型システムの基礎解析バイブル

TypeScriptの型システムを「武器」にする：PATCHリクエストにおける部分更新の完全掌握

フロントエンドからバックエンドまで、データの更新処理（PATCH）において「一部のプロパティだけを更新したい」という要件は日常茶飯事だ。しかし、多くの現場でこの実装は、単なる `Partial` の乱用によって型安全性という名の実質的な「型無効化」に陥っている。

「とりあえず動く」から「絶対にバグを埋め込まない」設計へ。今日はTypeScriptのコンパイラがどのように型を評価しているのか、その深層まで踏み込んで、堅牢な部分更新のパターンを伝授する。

—

なぜ単なる `Partial` では不十分なのか

まず、初心者が陥りがちなアンチパターンを見てほしい。

interface User {
id: string;
email: string;
username: string;
isActive: boolean;
}

// これをそのまま使うのは危険
type UpdateUserDto = Partial;

このコードの何が問題か？ `Partial` を使うと、`id` すらもオプション（`undefined` を許容）にしてしまう。`PATCH /users/:id` のようなエンドポイントでは、パスパラメータから `id` が確定していることが多いため、ボディに `id` が含まれる必要はない。むしろ「更新してはいけないプロパティ」までが更新可能になってしまうのだ。

型定義は「何を許可するか」だけでなく「何を禁止するか」を記述するドキュメントであるべきだ。

—

厳密な部分更新を実装する：PickとMapped Typesの調和

実務で最も美しく機能するのが、`Pick` と `Mapped Types` を組み合わせた設計だ。更新を許可する特定のプロパティのみを抽出し、その上で `Partial` を適用する。

特定のキーのみをPartial化し、型安全に更新を制限するユーティリティ

/
type PartialPick = Partial>;

// 使用例
interface User {
id: string;
email: string;
username: string;
isActive: boolean;
}

// emailとusernameだけを更新可能にする
type UpdateUserPayload = PartialPick;

// コンパイラが正しく制限を検知する
const patch: UpdateUserPayload = {
email: ‘new@example.com’,
// isActive: true, // Error: Type ‘boolean’ is not assignable to type ‘never’
};

このアプローチの利点は、「更新可能なプロパティのリスト」が型定義として明確に宣言されることだ。レビュー時に「なぜこのプロパティが更新できるのか？」という議論を、コードベース上の宣言で解決できる。

—

さらに一歩先へ：読み取り専用プロパティの保護

実戦では、`id` や `createdAt` のように「一度作成されたら絶対に更新してはいけない」プロパティが存在する。これらを `PartialPick` から意図的に除外する設計を徹底することで、APIの冪等性とセキュリティを担保する。

// ユーティリティ: 更新不可なプロパティを排除する
type Updateable = Omit;

// 組み合わせて最強のDTOを作る
type UserUpdateDto = Partial>;

この設計により、開発者が `id` を間違えて更新しようとしても、TypeScriptは即座に赤線を引いてくれる。これは実行時のエラーを未然に防ぐ、最強の防壁だ。

—

パフォーマンスとコンパイル時の注意点

大規模プロジェクトでこの手法をとる際、懸念されるのが「型評価のコスト」だ。`Mapped Types` や `Conditional Types` を複雑に重ねすぎると、IDEのレスポンスが鈍くなることがある。

1. 深いネストを避ける: `Partial, V>>` のように型を重ねすぎると、TSの型推論エンジンは評価に時間を要する。可能な限りフラットなユーティリティを定義せよ。
2. 型ユーティリティの再利用: 上記のような `PartialPick` や `Updateable` はプロジェクト共通の `types/utils.ts` に集約し、コンパイラのキャッシュ効率を意識せよ。
3. 明示的な型指定: 複雑なMapped Typesの結果に対しては、`type T = …` として名前を付けること。インラインで定義し続けると、コンパイラが型を推論し直す回数が増え、パフォーマンス低下の要因となる。

—

アーキテクトからの提言

コードは書いた瞬間から「負債」になる。しかし、型定義は「負債」ではなく「資産」だ。

Mapped Typesを活用した部分更新の制御は、APIの仕様変更に強い、拡張性の高いシステムを構築するための必須スキルである。「なんとなく動く」コードを卒業し、「コンパイラが論理を保証してくれる」コードを書こう。

型定義を疎かにするエンジニアは、実行時の例外という終わりのないデバッグ地獄に一生苦しむことになる。今日から、その甘えを捨て、TypeScriptの型システムという強力な味方を完全に掌握してほしい。

何か疑問があれば、いつでもコードレビューの場へ持ってくるがいい。我々の戦場は、常にその一行の先にある。