typescript-best-practices

TypeScript のベストプラクティス

まず type-system-discipline 原則のスキルを適用してください。このスキルでは、それを TypeScript の構文に落とし込みます。

ルール	概要
判別可能なユニオン	kind リテラルの判別子でバリアントをモデル化し、表現できない状態を作ります。オプションフィールドの寄せ集めは避けてください。
ブランド型	プリミティブ型に & { readonly __brand: "X" } を付け、取り違えを防ぎます。生成時に一度だけ検証します。
any より unknown	外部データは unknown にします。any は適用される場所すべてで型チェックを無効にします。
as キャストを使わない	すべての as は、いつでもランタイムクラッシュを引き起こしかねません。検証後にのみキャストしてください。
型の絞り込みの優先順位	判別子による switch > in 演算子 > typeof／instanceof > ユーザー定義の型ガード > as。
型ガード	主張する内容を検証する必要があります。嘘をつく型ガードは、問題が安全だと示す名前の裏に隠れるため、as よりも厄介です。isX または hasX という名前を付けてください。
網羅性	default 節に const _exhaustive: never = x; をインラインで記述し、新しいバリアントが追加されたときにコンパイラーがエラーを出すようにします。
as より satisfies	リテラル型を拡大せずに値を検証します。
境界での検証	データが入ってくる境界で検証し、内部では型を信頼します。boundary-discipline 原則のスキルを参照してください。
スキーマ由来の型	新しいインターフェースを宣言する前に、Pick／Omit／Parameters／ReturnType／Awaited／typeof を検討してください。
オブジェクト引数	位置引数ではなくオブジェクトを渡し、引数の順序がひと目で分かるようにします。ホットパス（フレームごとのレンダリング、トークナイザー、パーサー）では使わないでください。

例：references/patterns.md。