typescript-core

TypeScript のコアパターン

型安全性、ランタイム検証、最適な設定に関する最新の TypeScript 開発パターンです。

クイックスタート

新規プロジェクト： 2025 年版の tsconfig を使用 → strict と noUncheckedIndexedAccess を有効化 → 検証には Zod を選択

既存プロジェクト： 最初は strict: false を有効化 → any を unknown に置き換え → noUncheckedIndexedAccess を追加

API 開発： 境界部分で Zod スキーマを使用 → 型には z.infer<typeof Schema> を使用 → ルートには satisfies を使用

ライブラリ開発： declaration: true を有効化 → const 型パラメーターを使用 → advanced-patterns-2025.md を参照

クイックリファレンス

tsconfig.json の 2025 年版ベースライン

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

主なコンパイラーオプション

オプション	目的	有効にするタイミング
noUncheckedIndexedAccess	配列／オブジェクトへのアクセス時に null チェックを強制します	安全性のため常に
exactOptionalPropertyTypes	undefined とプロパティの欠落を区別します	オプショナルフィールドを持つ API
verbatimModuleSyntax	型のみのインポートを明示するよう強制します	ESM プロジェクト
erasableSyntaxOnly	Node.js 22 以降のネイティブ TS サポート	型消去を行う環境

ローカルのベースライン

リポジトリ固有の tsconfig パターン（CommonJS CLI、NodeNext strict、Next.js バンドラー）については、references/configuration.md を参照してください。

コア型パターン

Const 型パラメーター

ジェネリック関数を通じてリテラル型を保持します。

function createConfig<const T extends Record<string, unknown>>(config: T): T {
  return config;
}

const config = createConfig({ 
  apiUrl: "https://api.example.com", 
  timeout: 5000 
});
// Type: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000 }

Satisfies 演算子

リテラル推論を保持したまま、型との適合性を検証します。

type Route = { path: string; children?: Routes };
type Routes = Record<string, Route>;

const routes = {
  AUTH: { path: "/auth" },
  HOME: { path: "/" }
} satisfies Routes;

routes.AUTH.path;     // Type: "/auth" (literal preserved)
routes.NONEXISTENT;   // ❌ Type error

テンプレートリテラル型

型安全な文字列操作とルート抽出を実現します。

type ExtractParams<T extends string> = 
  T extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<Rest>
    : T extends `${string}:${infer Param}`
      ? Param
      : never;

type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"

網羅性チェックを伴う判別可能なユニオン

type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function handleResult<T>(result: Result<T>): T {
  if (result.success) return result.data;
  throw result.error;
}

// Exhaustiveness checking
type Action = 
  | { type: 'create'; payload: string }
  | { type: 'delete'; id: number };

function handle(action: Action) {
  switch (action.type) {
    case 'create': return action.payload;
    case 'delete': return action.id;
    default: {
      const _exhaustive: never = action;
      throw new Error(`Unhandled: ${_exhaustive}`);
    }
  }
}

ランタイム検証

TypeScript の型はランタイムでは消失します。外部データ（API、フォーム、設定ファイル）には検証ライブラリを使用してください。

クイック比較

ライブラリ	バンドルサイズ	速度	最適な用途
Zod	~13.5kB	基準	フルスタックアプリ、tRPC との統合
TypeBox	~8kB	約 10 倍高速	OpenAPI、パフォーマンスが重要な用途
Valibot	~1.4kB	約 2 倍高速	エッジ関数、最小限のバンドル

基本パターン（Zod）

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});

type User = z.infer<typeof UserSchema>;

// Validate external data
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

→ Zod、TypeBox、Valibot のパターンの全容については、runtime-validation.md を参照してください

選択のサポート

クイック選択ガイド

type と interface のどちらを選ぶべきですか？

• 公開 API／ライブラリの型 → interface
• ユニオン型／マップ型 → type
• シンプルなオブジェクトの形状 → interface（デフォルト）

ジェネリクスまたはユニオン型が必要ですか？

• 出力型が入力型に依存する → ジェネリクス
• 既知の型の固定セット → ユニオン型
• 再利用可能なデータ構造を構築する → ジェネリクス

未知のデータを扱っていますか？

• 外部データ（API、ユーザー入力） → unknown（型安全）
• 迅速なプロトタイピング／移行 → any（一時的に使用）

ランタイム検証が必要ですか？

• tRPC を使ったフルスタック TypeScript → Zod
• OpenAPI／高いパフォーマンス → TypeBox
• エッジ関数／最小限のバンドル → Valibot

→ 詳細な選択フレームワークについては、decision-trees.md を参照してください

トラブルシューティング

よくある問題のクイックリファレンス

プロパティが型に存在しない → 適切なインターフェースを定義するか、オプショナルプロパティを使用してください

型を代入できない → プロパティの型を修正するか、ランタイム検証（Zod）を使用してください

オブジェクトが 'undefined' の可能性がある → オプショナルチェーン（?.）または型ガードを使用してください

モジュールが見つからない → ファイル拡張子（ESM では .js）とモジュール解決を確認してください

コンパイルが遅い → incremental を有効にし、skipLibCheck を使用して、esbuild／swc の使用を検討してください

→ 例を交えた詳しい解決策については、troubleshooting.md を参照してください

ナビゲーション

詳細リファレンス

• 📐 高度な型 - 条件型、マップ型、infer キーワード、再帰型。複雑な型ユーティリティやジェネリックライブラリを構築する場合に読み込んでください。

• ⚙️ 設定 - tsconfig.json の完全ガイド、プロジェクト参照、モノレポのパターン。新しいプロジェクトをセットアップする場合やビルドを最適化する場合に読み込んでください。

• 🔒 実行時検証 - Zod、TypeBox、Valibot の高度なパターン、エラー処理、統合戦略。API 検証やフォーム処理を実装する場合に読み込んでください。

• ✨ 高度なパターン 2025 - TypeScript 5.2+ の機能：using キーワード、安定版デコレーター、import type の動作、ジェネリクスでの satisfies。最新の言語機能を使う場合に読み込んでください。

• 🌳 判断ツリー - type と interface、ジェネリクスとユニオン、unknown と any、検証ライブラリの選択、型の絞り込み戦略、モジュール解決について、明確な判断基準を示します。TypeScript の設計上の判断を行う場合に読み込んでください。

• 🔧 トラブルシューティング - よくある TypeScript のエラーと修正方法、型推論の問題、モジュール解決の問題、tsconfig の設定ミス、ビルドパフォーマンスの最適化、型の互換性エラー。TypeScript の問題をデバッグする場合に読み込んでください。

JavaScript／実行時品質のアンチパターン

型システムは型エラーを検出しますが、JavaScript の欠陥には実行時／AST レベルのものもあり、出力された JS や通常の JS ファイルにも残ります。次の点に注意してください。

• 緩い等価比較（==／!=） — 型変換によるバグや認証の欠陥につながります。===／!== を使用してください（「null または undefined」とコメントで明示する場合に限り、== null を許容します）。
• 動的コード実行（eval、new Function(str)、文字列を渡す setTimeout） — インジェクションのリスクがあり、不要です。直接的な構文を使用してください。
• 組み込みオブジェクトの変更（Object／Array／Function.prototype） — for…in を汚染し、実行環境全体を破損させます。代わりに拡張するか、独立した関数を使用してください。
• 変数のシャドーイング、let／const の代わりに var を使用、宣言前に関数を使用 — 可読性を損ない、「誤った変数」を参照するバグにつながります。
• switch の case ラベルでの論理 OR（case 1 || 2: は 1 にしか一致しません） — case ラベルを複数行に分けてください。
• 深いメンバーへのアクセスの繰り返し — 解決済みのチェーンをローカル変数にキャッシュしてください（特に DOM）。
• ラップされていない IIFE、バックスラッシュを使った複数行文字列、new Array() — 可読性を損ない、よく知られた落とし穴です。ラップした IIFE、テンプレートリテラル、配列リテラルを使用してください。

各欠陥の適合例／非適合例、重大度、誤検知のフィルター、対応する ESLint／SonarSource ルールについては、**JS/TS 品質アンチパターン**を参照してください。CAST Highlight の JavaScript コード品質指標（https://doc.casthighlight.com/）をもとに、ESLint のコアルールおよび SonarSource RSPEC と照合しています。

危険信号

次の場合は、いったん立ち止まって再検討してください。

• 外部データに対して unknown ではなく any を使用している
• 実行時検証なしで as による型キャストを行っている
• 手軽さを理由に strict モードを無効にしている
• 明確な理由なく @ts-ignore を使用している
• noUncheckedIndexedAccess を使わずにインデックスアクセスを行っている

他のスキルとの統合

• nextjs-core：型安全な Server Actions とルートハンドラー
• nextjs-v16：非同期 API のパターンと Cache Components の型付け
• mcp-builder：MCP ツールの入力用 Zod スキーマ

関連スキル

Core の使用時に、次のスキルを利用するとワークフローを強化できます。

• react：React での TypeScript：コンポーネントの型付け、フック、ジェネリクス
• nextjs：Next.js での TypeScript：Server Components、Server Actions の型付け
• drizzle：Drizzle ORM を使った型安全なデータベースクエリ
• prisma：データベーススキーマ向けに Prisma が生成する TypeScript 型

[バンドルにデプロイされている場合は、これらのスキル内で完全なドキュメントを利用できます]