effectorjs

EffectorJS スキル

このスキルは、新機能の開発、リファクタリング、コードレビューにおいて、決定論的でスコープセーフな Effector ソリューションを作成するために使用します。

ワークフロー

1. リクエストを分類します：

• modeling：ストア／イベント／エフェクトを作成または拡張します。
• refactor：アンチパターンを宣言的なフローに置き換えます。
• ssr：スコープセーフな SSR を実装またはデバッグします。
• review：リスク、リグレッション、不足しているテストを評価します。
• legacy-migration：古いパターンを安全にモダンな v23+ へ移行します。

2. 必要なリファレンスのみを読み込みます：

• 必ず最初に references/core-patterns.md を読み込みます。
• プラグインに裏付けられたベストプラクティスを適用するため、コアパターンの後に必ず references/lint-derived-best-practices.md を読み込みます。
• アプリのブートストラップ、起動ロジック、初期化順序、テスト、スコープ、SSR に関わるタスクでは、references/explicit-start.md を追加します。
• 順序、watch、シーケンス、競合のような動作、副作用の配置に関わるタスクでは、references/computation-priority.md を追加します。
• React／SSR／スコープが関わる場合は、references/react-ssr-scope.md を追加します。
• Solid との統合が関わる場合は、references/solid-scope.md を追加します。
• Vue との統合が関わる場合は、references/vue-scope.md を追加します。
• 既存ロジックの修正またはレビューでは、references/anti-patterns-and-fixes.md を追加します。
• 非推奨 API／インポートがある場合は、references/legacy-migration-map.md を追加します。
• 受け入れ基準の確認には、最後に references/checklists.md を読み込みます。

3. 次の順序でソリューションを構築します：

• アトミックなストアと明示的なイベントをモデル化します。
• 明示的なアプリ起動（appStarted）を定義し、起動時の配線は宣言的に保ちます。
• 副作用をエフェクトに移します。
• まず sample でユニットを接続し、エフェクトを合成する場合は attach を使用します。
• テスト、SPA のブートストラップ境界、SSR ではスコープ優先のルール（fork、allSettled）を適用します。
• UI フレームワークでは useUnit と適切なプロバイダー配線を使用します。

4. 出力要件：

• 提案するモデルのトポロジー（ストア／イベント／エフェクトとそれぞれの責務）。
• 配線のスニペット（必要に応じて sample、attach、split）。
• 該当する場合はスコープ／SSR に関する注意事項。
• 命名／データフロー／スコープ／React の制約に関する、Lint 由来の準拠事項。
• テストシナリオと受け入れチェックリスト。

デフォルト

• Effector のモダンな v23+ を対象とします。
• 非推奨／レガシーのパターンはデフォルトではなく、移行対象として扱います。
• 気の利いた抽象化より、最小限で明示的なユニットグラフを優先します。
• eslint-plugin-effector 由来のプラクティスを基本制約として扱います。
• 説明やレビューでは用語集に沿った用語を使用します。

用語集との整合（Effector）

• Unit：Store、Event、Effect、Domain、Scope を含みます。
• Common unit：Store、Event、Effect のみを指します（多くの API におけるリアクティブな更新ソース）。
• Derived store：ほかのストアから構築される読み取り専用ストアです（map、combine、.pending のようなエフェクト由来のストア）。
• Derived store の制約：直接変更してはならず、sample の target としても使用してはなりません。
• Reducer：store.on(...) のハンドラーは次の状態を返す必要があります。undefined または同じ参照（===）が返された場合、ストアは更新されません。
• Watcher：副作用／デバッグ用の可観測性にのみ使用します。Watcher の戻り値は無視されます。
• Subscription：購読解除ハンドラーはインフラストラクチャ上の関心事として扱い、ビジネスロジックでの手動の購読管理は避けます。
• Purity：純粋関数（map、.on、変換コールバック）は、イベント／エフェクトを命令的に呼び出してはなりません。
• Domain：ユニットの名前空間です。onCreate* フックは、ビジネスオーケストレーションではなく、インフラストラクチャレベルの横断的関心事（ロギング／計測）には使用できます。

ガードレール

• watch にビジネスロジックを配置しないでください。
• オーケストレーションには forward／guard より sample を優先してください。
• 計算の優先順位を守り、map／.on は純粋な処理として保ち、純粋な計算段階で副作用を避けてください。
• 宣言的な配線でフローを表現できる場合は、エフェクト本体からイベント／エフェクトを命令的に呼び出さないでください。
• ビジネスデータフローで $store.getState() を使用せず、sample の source を通じて状態を渡してください。
• sample の target として派生ストアを使用せず、書き込み可能なユニット／イベント／エフェクトのみを指定してください。
• sample／guard のオプションは意味的な順序で記述してください：clock -> source -> filter -> fn -> target。
• あいまいな target の使い方を避けてください（結果の代入と明示的な target を同時に指定しないでください）。
• clock／source の配列に重複するユニットを含めず、1 つのストアとイベントの組み合わせに対して重複する .on ハンドラーを設定しないでください。
• 実行時の効果がない sample／guard を使用しないでください（target またはキャプチャされた結果が必要です）。
• 実行時にユニットを動的に作成しないでください。
• 明示的な名前を使用してください（$store、eventHappened、someFx）。
• React では、呼び出し可能なユニットを useUnit にバインドし、JSX ハンドラー内でイベント／エフェクトを直接使用しないでください。

レガシーコードの扱い

レガシーコードがある場合：

1. まず動作を変更せずに維持してください。
2. レガシーなセクションであることを明示してください。
3. 移行時の安全性を考慮した差分戦略とともに、最新の置き換え案を提示してください。
4. クリーンアップの前に、同等性を証明するテストを追加してください。