typescript-advanced-patterns

TypeScript の高度なパターンに関するベストプラクティス

TypeScript 5.x を表面的に使う範囲を超えた、型レベルプログラミング、ライブラリ作成者向けのイディオム、機能実装パターンです。コンシューマーのコードベースへの影響度に基づいて優先順位を付けた、5 カテゴリー・40 のルールを収録しています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 公開ライブラリや DSL のインターフェースを設計するとき（流れるように呼び出せるビルダー、イベントエミッター、ルートパーサー、クエリビルダー、スキーマから導出されるクライアントなど）
• 型レベルのアルゴリズムを記述するとき（再帰的な条件型、アキュムレーターパターン、キーの再マッピング、可変長タプル、型レベルの文字列・数値演算、型レベルのテストなど）
• TS 5.x の機能を複雑な形で使用するとき（Stage 3 デコレーター、using の合成、オーバーロードの曖昧さを解消する const T、アンカー用パラメーターと制約付きパラメーターを分ける NoInfer、分散アノテーション、双変性の抜け穴など）
• 型レベルでワークフローの状態、遷移、機能を表現し、不正な状態やチェック漏れをコンパイルエラーにするとき
• 宣言・モジュールシステムと統合するとき（モジュール拡張、宣言のマージ、アンビエントなアセットモジュール、exports／typesVersions によるライブラリ型の公開など）

隣接するスキルとの境界

スキル	次のことが必要な場合は、このスキルを使用しないでください…
typescript（厳選）	コンパイラーのパフォーマンス／tsconfig の調整
typescript-refactor	一般的なリファクタリングパターンや最新の TS の基本
ts-google	Google スタイルのコードスタイルに関する判断
clean-code-ts-react	クリーンコードの原則（命名、関数の形、抽象化）
effect-ts / opencode-ts	Effect ライブラリ固有のパターン

このスキルのルールが typescript-refactor または .curated/typescript のルールと重複する場合、「Scope delta」セクションで、このスキルがより基本的なバージョンに加える内容を説明しています。

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	接頭辞	ルール数
1	ライブラリ作成者向け／DSL パターン	CRITICAL	dsl-	8
2	型レベルプログラミング	HIGH	tlp-	10
3	最新機能の深掘り	HIGH	mod-	8
4	機能実装パターン	MEDIUM-HIGH	impl-	8
5	宣言・モジュールシステム	MEDIUM	decl-	6

クイックリファレンス

1. ライブラリ作成者向け／DSL パターン（CRITICAL）

• dsl-fluent-builder-phantom-state — ファントム状態型でビルダーの呼び出し順序を強制する
• dsl-typed-event-emitter — マップ型のイベントマップで型付きイベントエミッターを構築する
• dsl-type-safe-object-paths — ドット記法による推論でオブジェクトパスへのアクセスに型を付ける
• dsl-route-param-inference — パスパターンからルートパラメーターを推論する
• dsl-schema-first-inference — 実行時スキーマから静的型を導出する
• dsl-type-safe-query-builder — ビルダーの戻り値の型にクエリの形状を符号化する
• dsl-narrow-api-surface — 内部ヘルパーではなく API のみを公開する
• dsl-overloads-vs-conditional-returns — 条件付き戻り値型よりオーバーロードを選ぶ

2. 型レベルプログラミング（高）

• tlp-recursive-conditional-types — 再帰的な条件型を使って構造を変換します
• tlp-tail-recursion-accumulator — 末尾再帰アキュムレーターパターンを使い、50 ステップの制限を回避します
• tlp-infer-extends-constraints — infer を extends で制約し、検証済みの抽出を行います
• tlp-key-remapping-as — マップ型の as 句でキーを再マッピングします
• tlp-variadic-tuple-types — 可変長タプルを使い、位置を考慮した型アルゴリズムを実装します
• tlp-type-level-string-algorithms — 再帰的なテンプレートリテラルで型レベルの文字列アルゴリズムを構築します
• tlp-distributive-conditional-control — [T] extends [U] のタプルトリックで分配を制御します
• tlp-type-level-tests — Equal、Expect、@ts-expect-error で型をテストします
• tlp-template-literal-pattern-matching — テンプレートリテラル内の infer で構造化文字列を照合します
• tlp-hkt-emulation — インターフェースディクショナリーで高カインド型をエミュレートします

3. 最新機能を深く掘り下げる（高）

• mod-stage-3-decorators — メタプログラミングにデコレーターコンテキストを使って Stage 3 デコレーターを使用します
• mod-using-disposal-ordering — using リソースを明示的な破棄順序で組み合わせます
• mod-const-type-params-overloads — const T を使い、オーバーロードされた API でリテラルを保持します
• mod-noinfer-overload-disambiguation — NoInfer<T> を使い、オーバーロードされた関数シグネチャを区別します
• mod-variance-debugging — in／out アノテーションで変性エラーをデバッグします
• mod-method-vs-property-bivariance — 双変性の穴を避けるため、メソッド構文よりプロパティ構文を優先します
• mod-phantom-capability-tracking — ファントムブランドで型レベルの機能を追跡します
• mod-satisfies-branded-config — satisfies とブランド型を組み合わせ、設定を検証します

4. 機能実装パターン（中〜高）

• impl-tagged-result-type — 操作の結果を Ok<T> | Err<E> のタグ付きユニオンとしてモデル化します
• impl-state-discriminated-union — ワークフローの状態を、状態レコードの判別ユニオンとしてモデル化します
• impl-finite-state-machine — 関数シグネチャで FSM の遷移を表現します
• impl-schema-derived-api-client — エンドポイントスキーマからクライアントの引数型と戻り値型を導出します
• impl-type-safe-form-builder — 単一のスキーマ定義を基にフォームフィールドの型推論を行います
• impl-phantom-feature-flags — ファントム機能型で機能に依存するコードを制御します
• impl-assert-never-exhaustive — assertNever を使い、ユニオンの各バリアントを漏れなく処理するよう強制します
• impl-env-config-loader — スキーマ推論を使い、境界で環境設定を検証します

5. 宣言とモジュールシステム（中）

• decl-module-augmentation — ソースを変更せずにサードパーティモジュールの型を拡張します
• decl-declaration-merging — インターフェース、名前空間、クラスの宣言を統合して API を拡張します
• decl-ambient-asset-modules — TypeScript 以外のアセットをインポートするためのアンビエントモジュールを宣言します
• decl-global-augmentation-discipline — グローバル型の拡張範囲を制限し、競合を防ぎます
• decl-exports-and-types-versions — exports および typesVersions マップを使ってライブラリの型を配布します
• decl-authoring-d-ts-for-js — プレーンな JavaScript ライブラリ向けの .d.ts ファイルを作成します

使用方法

詳しい説明、コード例、「適用すべきでない場合」のガイダンスについては、個々のリファレンスファイルをお読みください。

• セクションの定義 — カテゴリの構成と影響度
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

ルール間は [[other-rule-slug]] で相互リンクされています。関連するパターンが参照されている場合は、そのリンクをたどってください。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報