【実務・中級編】引数に渡す「文字列リテラル型」の自動補完を効かせるための型定義 – TypeScript コア・型システムの基礎解析バイブル

TypeScriptにおける関数の型定義は、一見すると初歩的なトピックに思えるかもしれない。しかし、コンポーネント設計やAPIクライアントの抽象化レイヤーを構築する際、「特定の文字列リテラルを受け入れつつ、任意の文字列も許容したい。かつ、IDEの補完は絶対に殺したくない」という要件に直面したことはないだろうか？

コードレビューをしていて、次のような「よくあるアンチパターン」に遭遇する。

// ❌ ありがちだが、これでは補完が死ぬか、型安全が崩壊する
type Theme = ‘light’ | ‘dark’ | string;

この定義をした瞬間、TypeScriptの型システムは `string` の飲み込みによって `string` そのものになり、リテラル型の恩恵であるIDEの強力な自動補完は完全に消え去る。

今回は、TypeScriptの型システムの挙動（プリミティブ型とリテラル型の合流、およびWidening）を完全にハックし、「既定の補完候補を提示させながら、任意の文字列も完全型安全に受け入れる」ための極限のテクニックを伝授しよう。

—

なぜ通常のUnion型では補完が効かなくなるのか？

TypeScriptのコンパイラは、型推論の過程で「Widening（型の拡大）」を行う。単に `’light’ | ‘dark’ | string` と書いた場合、コンパイラは `string` が含まれていることで「これは任意の文字列を受け取るのだな」と判断し、ユニオン全体のプリミティブ性を優先してリテラル型の推論を放棄する。

私たちが目指すゴールは以下の2点だ。
1. 引数入力時に `’light’`, `’dark’` などの候補がIDEでサジェストされること。
2. デザイナが追加したカスタムテーマ名など、定義済み以外の任意の文字列もコンパイルエラーなく渡せること。

これを美しく解決する鍵が、「プリミティブ型のハック（`string & {}`）」である。

—

決定版：コンパイラを欺き、補完を維持する型ハック

実務の現場でそのまま使える、堅牢なプロダクションコードを見てほしい。ここでは、APIのエンドポイントやデザインシステムのバリアントを想定した汎用的なアプローチを示す。

T: 補完に出したい厳格な文字列リテラル型

/
type WithAutoComplete = T | (string & {});

// — 使用例 —

// デザイナが定義した標準テーマ
type BaseTheme = ‘light’ | ‘dark’ | ‘system’;

// 任意の文字列も許容しつつ、標準テーマの補完を効かせる型
type Theme = WithAutoComplete;

function applyTheme(theme: Theme): void {
console.log(`Applying theme: ${theme}`);
}

// 1. ちゃんと補完が効く (‘light’, ‘dark’, ‘system’ がサジェストされる)
applyTheme(‘light’);

// 2. 独自の文字列を渡しても型エラーにならない！
applyTheme(‘cyberpunk-neon’);

なぜ `string & {}` なのか？

ここにTypeScriptコアの型評価における美しいトリックがある。

単に `string` と書くと、前述の通りWideningが発生してリテラル型が飲み込まれる。しかし、`string & {}`（string型と空のオブジェクト型の交差型）と記述すると、TypeScriptの型チェッカーはこれを「即座に単純化できない複雑な型」として扱う。

その結果、コンパイラはリテラル型の推論（Unionの構築）を維持したまま、`string` が持つ「任意の文字列を受け入れる」という性質を同時に満たすようになる。これが、IDEのインテリセンス（自動補完）を生存させるためのコンパイラハックである。

—

実践：APIクライアントにおけるHTTPメソッドの拡張

このテクニックは、単なるUIのテーマだけに留まらない。例えば、独自のカスタムメソッドを追加できる高機能なHTTPクライアントを設計する場合を考えてみよう。

標準的なHTTPメソッドに加え、カスタムメソッドも柔軟に受け入れたいケース

/
type StandardHttpMethod = ‘GET’ | ‘POST’ | ‘PUT’ | ‘DELETE’ | ‘PATCH’;

// 補完を殺さずに拡張性を担保
type HttpMethod = WithAutoComplete;

interface ApiRequestOptions {
method: HttpMethod;
url: string;
body?: unknown;
}

async function request(options: ApiRequestOptions): Promise {
// 実装（Fetch APIのラッパーなど）
const response = await fetch(options.url, {
method: options.method,
body: JSON.stringify(options.body),
});
return response.json() as T;
}

// — 現場での利用 —

// 標準メソッドは当然バッチリ補完される
request({ method: ‘POST’, url: ‘/api/users’, body: { name: ‘Toreador’ } });

// 独自拡張された内部プロトコル（例: ‘PURGE’など）も型エラーなしで通る
request({ method: ‘PURGE’, url: ‘/api/cache’ });

もしここで `string` だけを許容してしまうと、開発者が `PST` と痛恨のタイポ（誤字）をしたときに、TypeScriptはそれを検知できなくなる。しかし、`WithAutoComplete` を使っていれば、`’POST’` や `’PUT’` の補完の恩恵を受けつつ、万が一のタイポはリテラルとして推論されるため、厳密な静的解析の網にかけることも可能になる（厳密には任意のstringが入るためタイポ自体は通るが、主要な候補を明示することでタイポの確率を劇的に減らせる）。

—

アーキテクトからの警鐘：パフォーマンスと認知負荷のバランス

型システムを過剰に複雑化させると、TypeScriptの言語サービス（tsserver）のメモリ消費量が増加し、エディタの動作が重くなるという「スケールの罠」に陥る。

だが、今回紹介した `string & {}` によるハックは、条件付き型（Conditional Types）や再帰型のような重い演算を伴わないため、コンパイルタイムのパフォーマンスに与える影響は実質的にゼロである。

コードレビューのチェックポイント

「とりあえず `string` にしておくか」という怠惰な型定義は、コードの意図（ドキュメント性）を殺す。
「厳格なUnion型」だけを定義すると、拡張性の壁にぶつかり、開発者が `as string` や `as any` という危険な型アサーションに逃げる原因になる。
補完の利便性（Developer Experience）と、型安全な拡張性の両立を求められたら、迷わず `WithAutoComplete` パターンを適用せよ。

型定義は単なるエラーチェックの道具ではない。「次にそのコードを書く開発者への最高の一手（IDEの補完）を導くためのデザインパターン」である。この知見をあなたのプロダクトに導入し、チームの開発体験を次の次元へと引き上げてほしい。