TypeScript ベストプラクティス

CLAUDE.md の型優先、関数型、エラーハンドリングパターンに従います。このスキルは言語固有の慣例のみをカバーします。

React ベストプラクティスと組み合わせる

React コンポーネント (.tsx、.jsx ファイル、または @react インポート) を操作する場合は、常にこのスキルと一緒に react-best-practices をロードしてください。このスキルは TypeScript の基礎をカバーしており、React 固有のパターン (エフェクト、フック、ref、コンポーネント設計) は専用の React スキルに記載されています。

不正な状態を表現できないようにする

型システムを使用して、コンパイル時に無効な状態を防止します。

相互排他的な状態の判別ユニオン:

// Good: 有効な組み合わせのみが可能
type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

// Bad: { loading: true, error: Error } のような無効な組み合わせを許可
type RequestState<T> = {
  loading: boolean;
  data?: T;
  error?: Error;
};

ドメインプリミティブのブランド型:

type UserId = string & { readonly __brand: 'UserId' };
type OrderId = string & { readonly __brand: 'OrderId' };

// コンパイラが期待される UserId の場所に OrderId を渡すことを防止
function getUser(id: UserId): Promise<User> { /* ... */ }

リテラルユニオンの const アサーション:

const ROLES = ['admin', 'user', 'guest'] as const;
type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'

// 配列と型は自動的に同期を保つ
function isValidRole(role: string): role is Role {
  return ROLES.includes(role as Role);
}

never チェックによる網羅的な switch:

type Status = "active" | "inactive";

function processStatus(status: Status): string {
  switch (status) {
    case "active":
      return "processing";
    case "inactive":
      return "skipped";
    default: {
      const _exhaustive: never = status;
      throw new Error(`unhandled status: ${_exhaustive}`);
    }
  }
}

Zod によるランタイム検証

• スキーマを単一の情報源として定義し、z.infer<> で TypeScript 型を推論します。型とスキーマの重複を避けます。
• ユーザー入力に safeParse を使用します (失敗が予想される場合)。信頼境界で parse を使用します (無効なデータはバグ)。
• .extend()、.pick()、.omit()、.merge() でスキーマを組み合わせて DRY な定義を実現します。
• パース時のデータ正規化に .transform() を追加します (文字列をトリム、日付をパース)。

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1),
  createdAt: z.string().transform((s) => new Date(s)),
});

type User = z.infer<typeof UserSchema>;

// 信頼境界での厳格なパース — API コントラクト違反時に throw
export async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) {
    throw new Error(`fetch user ${id} failed: ${response.status}`);
  }
  return UserSchema.parse(await response.json());
}

// 呼び出し元がユーザー入力からの成功とエラーの両方を処理
const result = UserSchema.safeParse(formData);
if (!result.success) {
  setErrors(result.error.flatten().fieldErrors);
  return;
}

オプション: type-fest

TypeScript 組み込み機能を超える高度な型ユーティリティについては、type-fest を検討してください:

• Opaque<T, Token> - 手動の & { __brand } パターンよりもクリーンなブランド型
• PartialDeep<T> - ネストされたオブジェクトの再帰的 partial
• ReadonlyDeep<T> - 不変データの再帰的 readonly
• SetRequired<T, K> / SetOptional<T, K> - ターゲット指定フィールド修正
• Simplify<T> - IDE ツールチップの複雑なインターセクション型をフラット化

import type { Opaque, PartialDeep } from 'type-fest';

type UserId = Opaque<string, 'UserId'>;
type UserPatch = PartialDeep<User>;