typescript-advanced-patterns

スキル：typescript

対象範囲

• 対象：TypeScript v5 以降の高度な型システム機能、型安全な API、複雑なドメインモデル、高度な型推論、コンパイル時の保証
• 対象外：基本的な TypeScript の構文、フレームワーク固有のパターン、実行時検証ライブラリ（別途 Zod を使用してください）

前提条件

• TypeScript v5 以降
• Strict モードが有効（tsconfig.json の "strict": true）
• ターゲット：ES2020 以降

原則

• 条件に基づいて型を選択するには、条件型を使用します
• オブジェクト型を体系的に変換するには、マップ型を使用します
• 実行時チェックと型の絞り込みには、型ガード（value is Type）を使用します
• 網羅性チェックが可能な型安全なステートマシンには、判別可能なユニオンを使用します
• プリミティブ型の混同を防ぐには、ブランド型を使用します
• 型安全性のため、any より unknown を優先します
• 型アサーション（as Type）より型ガードを使用します
• 型は合成しやすく、浅い構造に保ちます（深いネストは避けます）
• 不変のデータ構造には readonly を指定します

制約

必須

• Strict モードを有効にします（tsconfig.json の "strict": true）
• 型が不明な値には any の代わりに unknown を使用します
• 可能な場合は、型アサーションではなく型ガード（value is Type）を使用します

推奨

• ユニオンやユーティリティには type を、オブジェクトの形状には interface を使用します
• 型は合成しやすく、浅い構造に保ちます
• 不変のデータ構造には readonly を指定します
• プリミティブ型の混同を防ぐには、ブランド型を使用します

避けること

• any の使用（型ガードとともに unknown を使用します）
• 検証を伴わない型アサーション
• ジェネリクスの過剰な使用（型が実際に変化する場合に限って使用します）
• 深い型のネスト（コンパイルが遅くなり、デバッグが難しくなります）

相互連携

• 実行時検証と型推論には、zod と連携します
• 型安全な API ルートには、nextjs を補完します
• 型安全なルートスキーマには、fastify を補完します

パターン

マップ型

オブジェクト型を体系的に変換します：

type Partial<T> = { [P in keyof T]?: T[P] }
type Readonly<T> = { readonly [P in keyof T]: T[P] }
type Pick<T, K extends keyof T> = { [P in K]: T[P] }

型ガード

型の絞り込みを伴う実行時の型チェック：

function isString(value: unknown): value is string {
  return typeof value === 'string'
}

function isSuccess(result: Result): result is Success {
  return result.status === 'success'
}

ブランド型

型安全性のために名目的な型を作成します：

type UserId = string & { readonly __brand: 'UserId' }
type PostId = string & { readonly __brand: 'PostId' }

function createUserId(id: string): UserId {
  return id as UserId
}

判別可能なユニオン

網羅性チェックが可能な型安全なステートマシン：

type LoadingState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string[] }
  | { status: 'error'; error: Error }

参考資料

• 条件型 - 条件に基づく型の選択
• 高度なジェネリクス - ジェネリック制約と型推論のパターン
• 判別可能なユニオン - 型安全なステートマシン

リソース

• TypeScript ハンドブック
• Type Challenges
• ts-toolbelt - 高度な型ユーティリティライブラリ