legend-state

Legend-State

コアのオブザーバブル、React または React Native との統合、永続化、リモート同期、移行など、Legend-State v3 の作業でこのスキルを使用します。

ワークフロー

1. コードを変更する前にプロジェクトを確認します。
   • ローカルのエージェント向けガイダンスと、周辺の状態管理の慣例を読みます。
   • @legendapp/state の正確なバージョンと、パッケージマネージャーのロックファイルを確認します。
   • 実行環境を特定します。バニラ TypeScript、React Web、React Native、Expo、SSR、または複合アプリのいずれかです。
   • オブザーバブルの所有者とライフタイムを把握します。モジュールシングルトン、リクエストスコープ、プロバイダースコープ、コンポーネントローカル、または同期対象リソースのいずれかです。
   • React での使用方法（useValue、observer、Memo、$React、制御フローコンポーネント）、永続化プラグイン、同期プラグイン、非推奨 API を洗い出します。
2. v3 API を使用する前にリリースチャネルを確認します。バージョン 3 はプレリリース（beta タグは 3.0.0-beta.48）で、npm の latest はまだ v2（2.1.15）です。@beta または正確なバージョンを指定してインストールします。references/source-map.md から始め、バージョンが重要な場合は最新のドキュメントとパッケージメタデータを確認します。
3. オブザーバブルの作成、読み取りと書き込み、計算状態またはリンク状態、リアクティビティ、配列、イベント、バッチ処理、ヘルパーについては、references/core-observables.md を参照します。
4. React、React Compiler との互換性、きめ細かなレンダリング、React Native、フック、制御フロー、コンテキスト、トレースについては、references/react-integration.md を参照します。
5. ローカル永続化、リモート同期、CRUD、再試行、変換、プラグイン、同期状態、ローカルファーストの信頼性については、references/persistence-sync.md を参照します。
6. v2 からの移行、ベータ版の差異、アーキテクチャ、セキュリティ、パフォーマンス、SSR、デバッグ、テストについては、references/production-migration-testing.md を参照します。
7. インストール済みの型宣言と既存のプロジェクトスタイルに合わせます。v2 の例を v3 のコードにそのままコピーしたり、v3 のベータ API が今後も変更されないと想定したりしないでください。

実装時の判断

• React での読み取りには useValue(observableOrSelector) を優先します。useSelector と use$ は移行用の別名として扱い、observer 内で直接 .get() を呼び出す方法には依存しないでください。このパターンは React Compiler のガイダンスに反します。
• observer は、useValue の呼び出しが多数ある、または条件付きで呼び出されるコンポーネントのフック数を最適化するための任意の手段として使用し、主要なサブスクリプション API としては使わないでください。
• set、assign、delete、配列メソッド、Map または Set のメソッドなどのオブザーバブル API を通じて変更します。get() または peek() が返す生データを変更しても通知されるとは考えないでください。
• peek() は、意図的にトラッキングしない読み取りにのみ使用します。浅いキーまたはコレクションのトラッキングが実際の依存関係である場合は、get(true) を使用します。
• 非同期または同期されたゲッターに関する、文書化済みのデータ読み込み動作を除き、計算、リンク、同期されたゲッターは純粋に保ちます。副作用はアクション、observe、onChange、または明示的なアプリケーションサービスに配置します。
• 範囲を絞ったオブザーバブルノードとセレクターを優先します。更新をより小さな React 境界へ移すことで明確な効果が得られる場合に限り、Memo、$React、For、Show、または Switch を使用します。
• 関連する書き込みはバッチ処理します。これはリスナーの頻繁な呼び出し、React の再レンダリング、永続化での書き込み増幅に影響します。
• 初回読み取り時の遅延アクティベーションが望ましい場合は synced(...) を選びます。既存のオブザーバブルをすぐに同期させる場合は syncObservable(...) を選びます。
• 永続化はキャッシュおよび再試行キューとして扱い、認可や機密情報の安全な保管には使用しないでください。サーバー認可、行レベルのアクセス制御、検証、競合ポリシーは明示します。
• 非同期の永続化では、データのハイドレーションが必要な読み取りを syncState(state$).isPersistLoaded で制御します。リモートの準備状態を推測で判断せず、isLoaded、error、保留中の変更状態を使用します。
• ログアウト、テナントの変更、認証ゲートは明示的にモデル化します。セレクターまたは同期設定で制御しない場合、ライブな useValue や他のオブザーバーによって、リセット後に遅延同期オブザーバブルが再アクティベートされる可能性があります。

検証

リポジトリに既存のチェックがあれば、それを使用してください。Legend-State に関する重要な作業では、関連する項目を適宜含めてください。

• インストール済みの v3 ベータ版の宣言と、正確なサブパスインポートに対する型チェック。
• オブザーバブルへの書き込み、計算値の依存関係、リンクされたセッター、バッチ処理、クリーンアップ、Map または Set の動作、raw データの変更ミスに関する単体テスト。
• レンダリング境界、useValue、observer、Memo、For、Show、Strict Mode のクリーンアップ、Suspense、React Compiler の影響を受けるパターンに関する React テスト。
• ハイドレーションの順序、変換、マイグレーション、再試行メタデータ、順序が入れ替わる保存、リセット、ストレージ障害に関する永続化テスト。
• 作成、更新、削除、ページング、リアルタイムサブスクリプション、再試行、競合または最終書き込みのルール、認証ゲート、再起動後の保留中の変更に関する同期テスト。
• オフライン編集、再読み込み、再接続、書き込みの失敗、ログアウト、テナントの切り替え、ストレージのアップグレードに関するブラウザーまたはデバイスのスモークテスト。
• v2 の永続化 API、古い計算値またはプロキシヘルパー、useSelector または use$、レンダリングパスでの直接的な .get()、レガシーのリアクティブコンポーネントのインポート、名前が変更された戻り値またはコールバックの動作に関するマイグレーションスキャン。