【実務・中級編】引数に「Mapped Types」を適用して、特定のプロパティのみを必須化する関数設計 – TypeScript コア・型システムの基礎解析バイブル

【TypeScript】条件付き必須化を極める：Mapped Typesで実現する堅牢な設定オブジェクト設計

コードレビューをしていて、次のようなコードに出くわすことはないだろうか。

type Config = {
endpoint?: string;
timeout?: number;
retryCount?: number;
cacheStrategy?: ‘memory’ | ‘redis’;
};

// 特定のモードのときだけ、endpointが必須なのに…
function initializeClient(config: Config, isProduction: boolean) {
if (isProduction && !config.endpoint) {
throw new Error(‘Endpoint is required in production!’);
}
// …
}

この実装には、TypeScriptの型システムに対する敗北が刻まれている。引数の型が `Config` （すべてオプショナル）であるため、コンパイラは `isProduction` が `true` の世界線において `endpoint` が欠落している可能性を検知できない。結果として、実行時エラーの爆弾を抱えたままプロダクションへデプロイされることになる。

プロフェッショナルなフロントエンド／Node.jsエンジニアであれば、「関数の実行コンテキストや他の引数の状態に応じて、設定オブジェクトの一部のプロパティを型レベルで強制的に必須（Required）にする」べきだ。

今回は、Mapped Types（マッピング型）と条件付き型（Conditional Types）を極限まで応用し、バグの起きようがない堅牢な関数シグネチャを設計する手法を伝授する。

—

1. なぜ「単純なUnion型」では破綻するのか？

まず、多くのジュニア〜ミドルクラスのエンジニアが陥るアンチパターンを見ておこう。条件によって型を変えたい場合、関数のオーバーロードやUnion型を使おうとする。

type DevConfig = Config & { isProduction: false };
type ProdConfig = Config & { isProduction: true; endpoint: string };

function init(config: DevConfig | ProdConfig) { … }

これでも一見動くように見えるが、設定オブジェクトを外部から受取り、動的に構築する複雑なアプリケーション層においては、型推論のスコープが汚染され、IDEの補完が効かなくなるか、あるいは `Property ‘endpoint’ does not exist on type…` という残酷なコンパイルエラーの嵐に見舞われる。

我々が求めるのは、「ベースとなる設定型は1つに定義し、特定のキー群だけを動的に必須化（Required化）する汎用的なユーティリティ型」である。

—

2. 核心：Mapped Typesによる「選択的必須化」のメカニズム

TypeScriptのMapped Typesを使えば、既存のオブジェクト型を走査し、特定のキーだけをピックアップしてオプショナル修飾子（`?`）を剥ぎ取ることが可能だ。

以下のコードを見てほしい。これが、モダンTypeScriptの真骨頂とも言える「選択的必須化（Selective Required）」の型定義である。

T: ベースとなるオブジェクト型
K: 必須化したいプロパティのキー（Tのキーの部分集合）

/
type RequireKeys =
// 1. 必須化対象外のプロパティはそのまま維持
Omit &
// 2. 必須化対象のプロパティだけを抽出して -? でオプショナルを剥がす
{ [P in K]-?: T[P] };

この型の恐るべきメカニズム

1. `K extends keyof T` により、存在しないプロパティ名を指定した瞬間にコンパイルエラーを吐く（タイポの完全排除）。
2. `[P in K]-?` の `-?` 修飾子こそが肝である。TypeScriptの型演算子において `-` は「除去」を意味し、`?`（オプショナル）を取り去ることで、強制的に必須プロパティへと変貌させる。
3. これらを交差型（Intersection Type: `&`）で合成することで、IDEは「一部のキーだけが必須になった完璧なオブジェクト型」として認識する。

—

3. 実践プロダクションコード：APIクライアントの初期化設計

この設計を、実際のフロントエンド・バックエンド共通のAPIクライアント初期化関数に応用してみよう。

「`cacheStrategy` として `’redis’` を選択した場合のみ、接続文字列である `redisUrl` を必須にする」というビジネス要件を型で完全に縛り上げる。

// 1. すべてのプロパティがオプショナルのベース設定
type ApiClientOptions = {
endpoint?: string;
timeout?: number;
retryCount?: number;
cacheStrategy?: ‘memory’ | ‘redis’;
redisUrl?: string; // キャッシュ戦略がredisの時のみ必須にしたい
};

// 2. 条件に応じた型を動的に導出するヘルパー
// cacheStrategyが ‘redis’ の場合は redisUrl を必須化する
type ResolvedOptions =
T[‘cacheStrategy’] extends ‘redis’
? RequireKeys
: RequireKeys;

3. 堅牢なファクトリー関数
呼び出し元は、cacheStrategyに応じた適切なプロパティの入力を強制される。

/
function createApiClient(options: T): ResolvedOptions {
// 実行時バリデーション（型安全性の担保と二重の防御）
if (!options.endpoint) {
throw new Error(‘ValidationError: “endpoint” is strictly required.’);
}
if (options.cacheStrategy === ‘redis’ && !options.redisUrl) {
throw new Error(‘ValidationError: “redisUrl” is required when cacheStrategy is “redis”.’);
}

// ここでキャストが必要なケースがあるが、関数の境界で型を閉じ込める
return options as ResolvedOptions;
}

// — 【利用側のコードと型評価】 —

// ❌ ケースA: コンパイルエラー（endpointがない）
// const clientA = createApiClient({
// timeout: 1000,
// });

// ❌ ケースB: コンパイルエラー（redisを指定しているのに redisUrl がない）
// const clientB = createApiClient({
// endpoint: ‘https://api.example.com’,
// cacheStrategy: ‘redis’,
// });

// ✅ ケースC: 完璧なコンパイル成功
const clientC = createApiClient({
endpoint: ‘https://api.example.com’,
cacheStrategy: ‘redis’,
redisUrl: ‘redis://localhost:6379’,
});

// ✅ ケースD: memory戦略なら redisUrl は不要
const clientD = createApiClient({
endpoint: ‘https://api.example.com’,
cacheStrategy: ‘memory’,
});

—

4. チーフアーキテクトからの警鐘：パフォーマンスと認知負荷の罠

この手法は非常にエレガントだが、実務で採用する際には以下の2点に留意しなければならない。

① 型の複雑化によるIDEのパフォーマンス低下

巨大なスキーマに対して、深すぎる条件付き型（Conditional Types）やネストしたMapped Typesを適用すると、TypeScriptの言語サーバー（tsserver）の型推論キャッシュがヒットせず、VSCode等のエディタで「Type instantiation is excessively deep and possibly infinite.」というエラーや、インテリセンスの著しい遅延を招く。
型は「複雑にすればいい」というものではない。チームメンバーが読める限界の抽象度にとどめること。

② ランタイムバリデーションとの二重管理の回避

TypeScriptの型はコンパイル時に消え去る。したがって、上記コードのようにランタイム側でも `if (!options.redisUrl)` のようなチェックを書く必要がある。
もしZodなどのランタイムバリデーションライブラリを使っている場合は、型を自前で定義するのではなく、Zodのスキーマから型を逆引き（`z.infer`）するアプローチを取るべきだ。Mapped Typesは、純粋なTSの型定義だけで完結させたいレガシーなオブジェクト構造や、内部ユーティリティの構築において最大の効果を発揮する。

—

総括

TypeScriptにおける型システムの本質は、「実行時エラーが起きる未来を、開発者のタイピング中にすべてブチ壊すこと」にある。

今回紹介した Mapped Types による選択的必須化（`RequireKeys`）は、設定オブジェクトの散らかりがちなバリデーション要件を、型レベルで美しく、かつ厳格に統制するための強力な武器となる。

「なんとなくオプショナルにして、中でif文を書く」という悪癖から脱却し、コンパイラを味方につけた圧倒的に堅牢なコードベースを築き上げてほしい。