プラグイン¶

プラグインは、単一の処理コルーチン内でマシンのイベントを同期的に監視します。各イベントの後、登録順に呼び出されます。プラグインのロジックは高速に保ってください — 重い処理はコルーチンを起動して行います。

プラグインのインストール¶

store { } または stateMachine { } DSL ブロック内で install(plugin) を呼び出します:

val store = store<MyState, MyAction, MyEffect>(scope) {
    initialState(MyState.Idle)
    // …
    install(LoggingPlugin(tag = "MyStore"))
}

複数のプラグインをインストールできます。宣言順に呼び出されます。

組み込み: `LoggingPlugin`¶

アクション、ステート遷移、エフェクト、リジェクション、エラーのすべてをプラットフォームロガーに記録します。

install(LoggingPlugin(tag = "Auth"))

出力例:

[ACTION]     LoginAction.Submit
[TRANSITION] LoginState.Submitting
[EFFECT]     LoginEffect.NavigateToHome
[UNHANDLED]  LoginAction.Logout  (state: Authenticated)
[ERROR]      IllegalStateException: token expired  (handler: Hook.Enter)

カスタム Logger を渡して出力先を変更できます:

install(LoggingPlugin(tag = "Auth") { tag, message -> Log.d(tag, message) })

例外の安全性¶

プラグインのコールバックは独立して実行されます — 個々のプラグイン内でスローされた例外はキャッチされ破棄されるため、処理コルーチンをクラッシュさせたり他のプラグインの実行を妨げたりしません。これはつまり、問題のあるプラグインはサイレントに失敗するということです。CI やデバッグビルドなどでプラグインの失敗を検知したい場合は、プラグイン内で明示的なエラーハンドリングを追加してください:

class SafeAnalyticsPlugin : Plugin {
    override fun onTransition(fromState: State, toState: State) {
        runCatching {
            analytics.track(fromState, toState)
        }.onFailure { error ->
            logger.e("AnalyticsPlugin failed", error)
        }
    }
}

カスタムプラグインの作成¶

Plugin インターフェースを実装し、必要なコールバックのみをオーバーライドします:

class AnalyticsPlugin : Plugin {

    override fun onTransition(fromState: State, toState: State) {
        analytics.track(
            event = "state_transition",
            properties = mapOf("from" to fromState::class.simpleName, "to" to toState::class.simpleName),
        )
    }

    override fun onRejected(currentState: State, handlerType: HandlerType<Action>) {
        analytics.track("action_rejected")
    }

    override fun onError(error: Throwable, currentState: State, handlerType: HandlerType<Action>) {
        crashReporter.log(error)
    }
}

使用可能なコールバック¶

コールバック	呼び出しタイミング
`onAction(state, action)`	アクションがデキューされ処理される直前。
`onTransition(from, to)`	ステート遷移が記録・適用されたとき。
`onEffect(effect)`	サイドエフェクトが発行されたとき。
`onUnhandled(state, action)`	現在のステート+アクションのペアに `on<>` ハンドラーが登録されていないとき。
`onRejected(state, handlerType)`	ハンドラーが明示的に `reject()` を呼び出したとき。
`onError(error, state, handlerType)`	ハンドラーまたはフック内で未処理の例外がスローされたとき。ステートは変化しません。