iii-state-reactions

状態リアクション

類似例：Firebase の onSnapshot、Convex のミューテーション

主な概念

タスクに適する場合は、以下の概念を使用してください。すべての状態リアクションに、すべての概念が必要なわけではありません。

• 状態トリガーは、監視対象のスコープ内で値が変更されるたびに発火します
• ハンドラーには、変更内容を示す { new_value, old_value, key, event_type } が渡されます
• condition_function_id は実行を制御します。条件が truthy を返した場合にのみリアクションが発火します
• 複数のリアクションで、同じスコープを個別に監視できます
• リアクションは、state::set、state::update、state::delete の各操作で発火します

アーキテクチャ

state::set / state::update / state::delete
  → StateModule が変更イベントを発行
    → registerTrigger type:'state'（スコープが一致）
      → condition_function_id を確認（設定されている場合）
        → registerFunction ハンドラー（{ new_value, old_value, key, event_type }）

iii で使用するプリミティブ

プリミティブ	用途
registerFunction	リアクションハンドラーを定義する
registerTrigger({ type: 'state' })	スコープ内の変更を監視する
config: { scope, key, condition_function_id }	スコープフィルターと任意の条件制御
イベントペイロード：{ new_value, old_value, key, event_type }	ハンドラーに渡される変更の詳細

実装例

完全な動作例については、../references/state-reactions.js を参照してください。状態スコープを監視し、値の変更時に副作用を発生させるリアクションの例で、任意の条件制御も含まれています。

Python 版もあります：../references/state-reactions.py

Rust 版もあります：../references/state-reactions.rs

よくあるパターン

このパターンを使うコードには、該当する場合、一般的に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーを初期化する
• registerFunction(id, handler) — リアクションハンドラーを定義する
• registerTrigger({ type: 'state', config: { scope, key, condition_function_id } }) — 変更を監視する
• payload.new_value / payload.old_value — 変更前と変更後を比較する
• payload.event_type — set、update、delete の各イベントを判別する
• trigger({ function_id: 'state::set', payload }) — リアクションから派生状態を書き込む
• const logger = new Logger() — リアクションごとの構造化ログを記録する

このパターンの応用

タスクに該当する場合は、以下の応用方法を使用してください。

• scope を設定して、特定のドメイン（例：orders、user-profiles）を監視します
• key を使用して、スコープ内の単一キーにリアクションを絞り込みます
• condition_function_id を追加してフィルターします。条件関数が truthy を返した場合にのみリアクションします
• あるハンドラーで状態を書き込み、別のスコープに対する別のリアクションを発火させて、リアクションを連鎖させます

エンジンの設定

状態トリガーを発火させるには、iii-config.yaml で StateModule を有効にする必要があります。注釈付きの設定リファレンス全体については、../references/iii-config.yaml を参照してください。

パターンの適用範囲

• リアクションを使わずに状態を直接読み書きするタスクでは、iii-state-management を優先してください。
• トリガーの種類をまたいで共有される条件付きトリガーロジックが必要なタスクでは、iii-trigger-conditions を優先してください。
• 主な要件が、状態変更時の自動的な副作用である場合は、iii-state-reactions を使用してください。

使用する場面

• iii エンジンで主に iii-state-reactions を扱うタスクでは、このスキルを使用してください。
• リクエストでこのパターン、または同等の実装が直接求められている場合に適用します。

適用範囲

• 無関係なタスクに対する汎用的なフォールバックとして、このスキルを使用しないでください。
• より適切な iii スキルがある場合、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全上の制約を確認してください。