開発チームの皆さん、お疲れ様です。テクニカルリードの私だ。
今日のコードレビューで、また「あれ、このコード通るはずなのに、なんでここで型エラーになるんだ？」という初歩的だが本質的な混乱に遭遇した。
エラーメッセージをよく読めば、お馴染みのこいつだ。
> “Object literal may only specify known properties, and ‘xxx’ does not exist in type ‘YYY’.”
> （オブジェクトリテラルは既知のプロパティのみを指定できます。’xxx’ は ‘YYY’ 型に存在しません。）
構造的部分型（Structural Subtyping）を採用しているはずのTypeScriptが、なぜかオブジェクトリテラルを渡した時だけ、異様に厳しい検閲（余剰プロパティチェック：Excess Property Checking）を行ってくる。変数経由で渡せばスルーされるのに、だ。
この挙動の裏側でコンパイラが何をやっているのか、そして我々フロントエンド・フルスタックエンジニアがAPI連携やコンポーネント設計において、いかにしてこの仕様を味方につけ、バグの踏み抜きを防ぐべきか。
今日はその核心をロジカルに解説しよう。
—
1. なぜ「オブジェクトリテラル」だけが厳しく取り締まられるのか？
まずTypeScriptの基本思想を確認する。TypeScriptは「ダックタイピング（歩き、鳴くならそれはアヒルだ）」をベースにした構造的部分型だ。「要求されているプロパティさえ満たしていれば、余計なプロパティが含まれていても代入可能」というのが大原則である。
しかし、以下のコードを見てほしい。
type UserConfig = {
name: string;
age: number;
};
// 変数経由：これは当然通る（構造的部分型の恩恵）
const rawInput = { name: “Alice”, age: 30, role: “admin” };
const configA: UserConfig = rawInput; // OK! ‘role’ は無視される
// オブジェクトリテラル直接：ここでコンパイルエラー！
const configB: UserConfig = {
name: “Bob”,
age: 25,
role: “admin”, // Error: Object literal may only specify known properties…
};
なぜ変数 `rawInput` を経由した場合は通るのに、直書き（オブジェクトリテラル）だとエラーになるのか？
コンパイラの意図：タイポやAPIの設計ミスを早期に潰すための「セーフティネット」
これはバグではない。TypeScriptチームが意図的に導入した強力な検知機構だ。
もしオブジェクトリテラルに対するチェックがなかったとしよう。あなたがAPIクライアントやコンポーネントのpropsに、うっかりタイポしたプロパティ（例: `usreName`）を渡したとする。
構造的部分型ルールのみに従うと、これは「余分なプロパティを持つ有効なオブジェクト」とみなされ、静かにスルーされてしまう。そして、実行時になって「あれ、データが反映されないぞ？」という難解なバグを生む。
TypeScriptコンパイラは、「開発者がその場で直接書いたオブジェクト（リテラル）には、タイポや不要なパラメータの混入が多い」と見なし、型に定義されていないプロパティが含まれていないかを特別に厳しくチェックしているのだ。これを余剰プロパティチェック（Excess Property Checking）と呼ぶ。
—
2. 実務で踏みがちな「罠」とアンチパターン
この仕様の厄介なところは、「変数に代入するだけでチェックがすり抜ける」という点にある。実務のコードベースで、これを悪用（あるいは無知による誤用）した危険なパターンを見かけることが多い。
アンチパターン：エラーを消すために `as any` や `as UserConfig` を乱用する
type ApiPayload = {
endpoint: string;
timeout: number;
};
function sendRequest(payload: ApiPayload) {
/ … /
}
// ❌ 悪手：エラーが出たからといって安易に型アサーションでねじ伏せる
sendRequest({
endpoint: “/api/v1/users”,
timeout: 5000,
retries: 3, // 本来エラーになるべき余剰プロパティ
} as ApiPayload); // 型の安全性をここで完全にブチ壊している
型アサーション（`as`）は、コンパイラに対して「俺の方が賢いから黙ってろ」と命令する危険なハックだ。これを多用すると、API仕様変更時の影響範囲検知や、リファクタリングの耐性が一気に失われる。
—
3. 堅牢な設計パターン：どう向き合い、どう回避すべきか？
では、意図的に「追加のプロパティ（メタデータや拡張フィールドなど）」を受け入れたい場合はどう設計すべきか。実務で即座に使える3つのアプローチを伝授する。
パターンA：型定義側に「インデックスシグネチャ」を持たせる
もしそのオブジェクトが「既知のプロパティに加え、任意の追加プロパティを許容する」という性質を持つなら、型定義の段階でそれを明示すべきだ。
type ExtensibleConfig = {
name: string;
age: number;
[key: string]: unknown; // 任意のキーと値（unknown推奨）を許容
};
// これならオブジェクトリテラルでもエラーにならない！
const config: ExtensibleConfig = {
name: “Charlie”,
age: 28,
role: “admin”, // OK
customField: “foo”, // OK
};
※ `[key: string]: any;` は型安全性を殺すため、特別な理由がない限り `unknown` を使い、利用時に型ガードを通すのがモダンTSの作法だ。
パターンB：Omit / Pick による関心の分離と型合成
フロントエンド開発、特にReactのコンポーネント設計や、APIのラッパー関数などでは、ベースの型を拡張・制限したい場面が多々ある。
type BaseUser = {
id: string;
name: string;
email: string;
};
// 更新用リクエストの型：idは不要だが、clientMetaという独自フィールドを追加したい場合
type UpdateUserPayload = Omit
clientMeta?: string;
};
// 綺麗に意図を表現できる
const payload: UpdateUserPayload = {
name: “Dave”,
email: “dave@example.com”,
clientMeta: “from-web-form”, // OK!
};
パターンC：厳格なユニオン型（Discriminated Unions）による排他的設計
APIのリクエストボディなどで、「このプロパティが存在する場合は、あのプロパティも必須」といった複雑な排他制御が必要な場合は、オブジェクトリテラルの余剰プロパティチェックの厳格さを逆手に取った、判別可能なユニオン型で設計する。
type EmailAuth = {
method: “email”;
email: string;
token: string;
};
type PasskeyAuth = {
method: “passkey”;
credentialId: string;
};
type AuthRequest = EmailAuth | PasskeyAuth;
// コンパイラがオブジェクトリテラルの形状を完璧に精査し、
// 余計なプロパティやタイポを即座に弾いてくれる
const request: AuthRequest = {
method: “email”,
email: “test@example.com”,
token: “abc123xyz”,
};
この設計にしておけば、開発者がうっかり `passkey` の方に `email` プロパティを混ぜ込もうとしたり、タイポしたりした瞬間に対処できる。
—
4. チーフアーキテクトからの提言
TypeScriptの余剰プロパティチェックは、慣れるまでは「おせっかいなエラー」に感じるかもしれない。
だが、思い出してほしい。TypeScriptの本懐は、「実行時エラーをコンパイルタイムに駆逐すること」だ。
オブジェクトリテラルに対する厳格なチェックは、あなたのコードのバグを未然に防ぐためにコンパイラが用意してくれた最強の防壁である。これを `as any` で安易にバイパスするのではなく、型定義側（インデックスシグネチャやユニオン型など）を正しく設計してコンパイラと協調させよう。
コードレビューで `as` や不要なアサーションを見かけたら、今日の話を思い出してほしい。「本当にその型アサーションは必要か？ 型設計で美しく解決できないか？」と。
明日のプルリクエストから、より堅牢で無駄のない型設計が実践されることを期待している。