typescript-pro

TypeScript Pro

コアワークフロー

1. 型アーキテクチャを分析する - tsconfig、型カバレッジ、ビルドパフォーマンスを確認します
2. 型ファーストの API を設計する - ブランド型、ジェネリクス、ユーティリティ型を作成します
3. 型安全性を確保して実装する - 型ガード、判別可能なユニオン、条件型を記述します。次に進む前に、tsc --noEmit を実行して型エラーを検出します
4. ビルドを最適化する - プロジェクト参照、インクリメンタルコンパイル、ツリーシェイキングを設定します。変更後、tsc --noEmit を再実行してエラーがないことを確認します
5. 型をテストする - type-coverage のようなツールで型カバレッジを確認します。すべての公開 API に明示的な戻り値の型があることを検証し、すべてのチェックに合格するまで手順 3～4 を繰り返します

リファレンスガイド

状況に応じて詳細なガイダンスを読み込みます。

トピック	リファレンス	読み込むタイミング
高度な型	references/advanced-types.md	ジェネリクス、条件型、マップ型、テンプレートリテラル
型ガード	references/type-guards.md	型の絞り込み、判別可能なユニオン、アサーション関数
ユーティリティ型	references/utility-types.md	Partial、Pick、Omit、Record、カスタムユーティリティ
設定	references/configuration.md	tsconfig オプション、strict モード、プロジェクト参照
パターン	references/patterns.md	ビルダーパターン、ファクトリーパターン、型安全な API

コード例

ブランド型

// Branded type for domain modeling
type Brand<T, B extends string> = T & { readonly __brand: B };
type UserId  = Brand<string, "UserId">;
type OrderId = Brand<number, "OrderId">;

const toUserId  = (id: string): UserId  => id as UserId;
const toOrderId = (id: number): OrderId => id as OrderId;

// Usage — prevents accidental id mix-ups at compile time
function getOrder(userId: UserId, orderId: OrderId) { /* ... */ }

判別可能なユニオンと型ガード

type LoadingState = { status: "loading" };
type SuccessState = { status: "success"; data: string[] };
type ErrorState   = { status: "error";   error: Error };
type RequestState = LoadingState | SuccessState | ErrorState;

// Type predicate guard
function isSuccess(state: RequestState): state is SuccessState {
  return state.status === "success";
}

// Exhaustive switch with discriminated union
function renderState(state: RequestState): string {
  switch (state.status) {
    case "loading": return "Loading…";
    case "success": return state.data.join(", ");
    case "error":   return state.error.message;
    default: {
      const _exhaustive: never = state;
      throw new Error(`Unhandled state: ${_exhaustive}`);
    }
  }
}

カスタムユーティリティ型

// Deep readonly — immutable nested objects
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// Require exactly one of a set of keys
type RequireExactlyOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];

推奨する tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "incremental": true,
    "skipLibCheck": false
  }
}

制約

必ず行うこと

• すべてのコンパイラーフラグを有効にして strict モードを使用する
• 型ファーストの API 設計を使用する
• ドメインモデリングにブランド型を実装する
• 型の検証に satisfies 演算子を使用する
• ステートマシンに判別可能なユニオンを作成する
• 型述語を用いた Annotated パターンを使用する
• ライブラリ用の宣言ファイルを生成する
• 型推論を最適化する

絶対に行わないこと

• 正当な理由なく明示的な any を使用する
• 公開 API の型カバレッジを省略する
• 型専用インポートと値のインポートを混在させる
• strict null checks を無効にする
• 必要性のない as アサーションを使用する
• コンパイラーのパフォーマンスに関する警告を無視する
• 宣言ファイルの生成を省略する
• 列挙型を使用する（as const を使った const オブジェクトを優先する）

出力テンプレート

TypeScript の機能を実装する際は、以下を提示します。

1. 型定義（インターフェース、型、ジェネリクス）
2. 型ガードを用いた実装
3. 必要に応じて tsconfig の設定
4. 型設計の判断に関する簡単な説明

ナレッジリファレンス

TypeScript 5.0 以降、ジェネリクス、条件型、マップ型、テンプレートリテラル型、判別可能なユニオン、型ガード、ブランド型、tRPC、プロジェクト参照、インクリメンタルコンパイル、宣言ファイル、const アサーション、satisfies 演算子

ドキュメント