typescript-standards

読み込むタイミング

次のタスクでは、このスキルを読み込んでください。

• 関数、メソッド、クラス、モジュールの作成またはリファクタリング
• 型付けに関する判断：インターフェース、型、列挙型、ジェネリクス、ユーティリティ型
• ドメインモデリング、境界、共有コントラクト
• API 設計、レイヤー間のモジュール境界
• 設計原則：SOLID、KISS、YAGNI、LIFT、SoC
• 実際の根拠に基づくデザインパターン（GoF）

構成

このスキルは、フレームワークのスキルを補完するものです。

• angular-standards と併せて読み込むと、Angular のリソースの .ts ファイルに TypeScript のルールを適用します
• フレームワーク固有の構成（Angular DI、シグナルなど）では、フレームワークのスキルが優先されます
• 一般的な言語および設計ルール（型、境界、モジュール）では、このスキルが優先されます
• angular-standards の構成セクションで指定された場合に読み込みます。angular-standards がすでに対象としているコンポーネントのタスクで、このスキルを単独で自動的に読み込まないでください

読み込まない場合

• HTML テンプレートまたは SCSS/CSS のみを扱うタスク
• ビルド、デプロイ、インフラ関連のタスク
• コミット（git-commit を使用してください）
• CI/CD の設定

---

TypeScript の標準

使用するタイミング

• プロジェクトで TypeScript ファイルを作成またはリファクタリングするとき。
• インターフェース、型、共有コントラクト、モジュール境界を定義するとき。
• ドメイン、結果、エラー、コレクション、公開 API をモデル化するとき。
• フレームワーク固有ではない設計やアーキテクチャに関する判断をするとき。

目標

• 強固で予測しやすく、読みやすい型付けを維持します。
• シンプルさ、凝集性、健全なコードの進化を保ちます。
• 重複を避け、優先順位を明確に保つため、詳細なルールはローカルのリファレンスに集約します。
• 過剰設計を避け、設計原則を実践的に適用します。

LIFT 原則

新しい型、ヘルパー、モジュール、クラス、アダプター、ファクトリー、ポート、または抽象化を作成する前に、LIFT 原則を適用してください。

• Locate（特定）：既存のコントラクト、型、ヘルパー、パターン、モジュール、リファレンスを探します。
• Identify（把握）：すでに問題の一部を解決しているものと、実際または潜在的に重複している箇所を把握します。
• Find（発見）：新しいものを導入する前に、再利用、拡張、または合成が可能な最小のまとまりを探します。
• Try to be DRY（DRY を心がける）：早すぎる抽象化、過度に汎用的なレイヤー、不透明な構造を作らずに、実際の重複を解消します。

他のスキルとの連携

• このスキルは、複数の領域に関わる言語レベルのスキルです。Angular や Vue などのフレームワークは、引き続きフレームワーク固有のアーキテクチャを規定します。
• typescript-standards は、TypeScript におけるモデリング、コントラクト、モジュール設計、境界の検証、実践的な設計を定めます。
• 競合する場合、フレームワーク固有の構成ではフレームワークのスキルが優先され、一般的な言語および設計ルールでは typescript-standards が優先されます。

主なルール

• 新しい型、モジュール、クラス、ヘルパー、アダプター、ファクトリー、パターンを導入する前に、LIFT を適用してください。
• any は使用しないでください。型が不確かな場合は、unknown を使用してください。
• インポートには必ずパスエイリアスを使用してください。深い相対インポート（../../ 以降）は厳禁です。
  • アプリ内部のモジュール間インポートには @<app-name>/<feature>/* を使用してください（例：@vendas/services/some.service）。
  • 共有ライブラリのインポートには @lib/<lib-name> を使用してください（例：@lib/data-access、@lib/ui、@lib/utils、@lib/pipes）。
  • 利用可能な場合は、サブパスエイリアスに @lib/<lib-name>/<sub-path> を使用してください（例：@lib/data-access/config、@lib/data-access/enums）。
  • 相対インポート（./ または ../）は、同じ機能フォルダー内でのみ使用できます（最大 1 階層）。
• インターフェース名は I で始めてください。
• インターフェース専用ではないファイルにインターフェースを作成しないでください。
• すべてのインターフェースに、faker.js を使用した対応する生成関数を用意してください。
• 生成関数は専用ファイルに配置し、プロジェクトで採用しているフォルダー階層に従ってください。
• 生成関数は実行ごとに単一のランダムシードを生成または受け取り、すべての契約データをそこから導出してください。
• enum 専用ではないファイルに enum を作成しないでください。
• 1 ファイルにつき enum は 1 つだけにしてください。
• すべての enum に対し、同じファイル内に値ラベルのマッピング構造を用意してください。
• クラスよりも関数とモジュールを優先してください。
• 継承よりも合成を優先してください。
• デフォルトで KISS、YAGNI、SoC を適用してください。
• SOLID は独断的なチェックリストではなく、実用的なヒューリスティックとして扱ってください。
• Object Calisthenics は任意の設計上の指針として扱い、絶対的な規則とはしないでください。
• GoF パターンは、変更、重複、疎結合に対する実際の必要性がある場合にのみ使用してください。
• オブジェクトキーで十分な場合は、Map より Record を優先してください。
• Map は、固有の API やシリアライズできないキーへの対応が本当に必要な場合にのみ使用してください。
• 型の関連性が強い場合を除き、1 ファイルにつき契約は 1 つにしてください。
• 新しい型を導入する前に、ドメイン内に同等の契約がすでに存在しないか確認してください。
• システム外部からデータが入力される際は、ランタイム境界を検証してください。
• シングルクォートとセミコロンを使用してください。

手順

1. 新しい型、モジュール、抽象化を作成する前に、LIFT を適用してください。
2. 変更に本当に必要な契約、型、境界を特定してください。
3. インターフェースがある場合は、適切なプロジェクト階層に対応する生成関数を配置する計画も立ててください。
4. 新しい型を作成する前に、既存の型を再利用してください。
5. 可能な限り制約が明確で、シンプルな選択肢を使ってモデル化してください。
6. 不確かな場合は unknown を使用し、明示的な型の絞り込みを行ってください。
7. 状態、同一性、ライフサイクル、ポリモーフィズムの実際の必要性に基づいて、関数、モジュール、オブジェクト、クラスを選択してください。
8. GoF パターンの使用を検討する場合は、まず単純な合成で解決できないか確認してください。
9. KISS、YAGNI、SoC、およびドメインの可読性に基づいて結果を見直してください。

品質チェックリスト

• 新しい構造を導入する前に LIFT を適用した。
• any を導入していない。
• 深い相対インポート（../../ 以降）がない。モジュール間インポートにはすべてパスエイリアスを使用している。
• インターフェース名が I プレフィックスに従っている。
• インターフェースが専用ファイルに配置されている。
• インターフェースに対応する生成関数がある。
• インターフェースの生成関数が faker.js を使用している。
• インターフェースの生成関数がプロジェクトのフォルダー階層に従っている。
• インターフェースの生成関数が実行ごとに単一のランダムシードを使用している。
• enum が専用ファイルに配置されている。
• 1 ファイルにつき enum が 1 つだけである。
• すべての enum に、同じファイル内にラベルのマッピング構造がある。
• 要件を満たす最もシンプルな解決策を優先した。
• 先を見越した抽象化がない。
• 十分な場合は Record を優先した。
• Map の使用に、実際の技術的な根拠がある。
• 必要に応じて、外部境界に適切な検証を適用した。
• ファイルでシングルクォートとセミコロンを使用している。
• 型、クラス、パターンを不必要に増やしていない。

注意事項

• このスキルでは、デフォルトでオブジェクト指向設計を求めません。TypeScript では、関数、モジュール、コンポジションを出発点とするのが通常は最適です。
• SOLID、GoF、Object Calisthenics は、設計と保守性を向上させるためのものであり、余計な複雑さを正当化するためのものではありません。
• フレームワークスキルで特定の構造が定義されている場合は、そのフレームワークに従い、このスキルを言語と設計のレイヤーで適用してください。

型付けの判断

インターフェース、型、列挙型、ジェネリクスを定義する場合や、ドメインの契約をモデル化する場合に参照してください。

• インターフェースと型の使い分け：references/types-interface-vs-type.md
• インターフェースジェネレーター：references/types-interface-generators.md
• 列挙型：references/types-enums.md
• ドメインモデリング：references/types-domain-modeling.md
• ジェネリクス：references/types-generics.md
• ユーティリティ型：references/types-utility-types.md
• ユニオンとクラス階層の使い分け：references/types-unions-vs-class-hierarchies.md
• 型の絞り込みと unknown：references/types-narrowing-and-unknown.md
• Readonly と不変性：references/types-readonly-and-immutability.md
• Record と Map の使い分け：references/types-record-vs-map.md
• エラーと結果の形式：references/types-errors-and-result-shapes.md
• 実行時検証：references/types-runtime-validation.md

アーキテクチャとモジュール設計

関数、クラス、モジュール、境界、API の設計について検討する場合に参照してください。

• 関数とクラスの使い分け：references/architecture-functions-vs-classes.md
• モジュールと境界：references/architecture-modules-and-boundaries.md
• DI とコンポジション：references/architecture-dependency-injection-and-composition.md
• 副作用とポート：references/architecture-side-effects-and-ports.md
• API 設計：references/architecture-api-design.md
• ファイル構成：references/architecture-file-organization.md

設計原則

保守性に影響する構造や設計上の判断を行う場合に参照してください。

• LIFT：references/principles-lift.md
• SOLID：references/principles-solid.md
• KISS と YAGNI：references/principles-kiss-yagni.md
• 関心の分離：references/principles-separation-of-concerns.md
• Object Calisthenics：references/principles-object-calisthenics.md

デザインパターン

変更、繰り返し、または疎結合の必要性が実際に生じた場合にのみ参照してください。

• パターンの概要：references/patterns-overview.md
• 生成：references/patterns-creational.md
• 構造：references/patterns-structural.md
• 振る舞い：references/patterns-behavioral.md
• パターンを使わない場合：references/patterns-when-not-to-use.md

実践的な設計

重複、抽象化のトレードオフ、リファクタリングのきっかけを評価する場合に参照してください。

• 重複と抽象化の使い分け：references/pragmatic-duplication-vs-abstraction.md
• リファクタリングのきっかけ：references/pragmatic-refactoring-triggers.md