safeAction, safeEventHandler

People are confused by the fact that a `WorkflowAction` can't assume that a sealed class / interface `StateT` is the same subtype that it was at render time when the action fires. And those that do understand it resent this boilerplate:

```kotlin
action {
  (state as? SpecificState)?.let { currentState ->
    // whatever
  }
}
```

So we introduce `StatefulWorkflow.safeAction` and `StatefulWorkflow.RenderContext.safeEventHandler` as conveniences to do that cast for you.

Author: rjrjr

samples/tictactoe/common/src/main/java/com/squareup/sample/gameworkflow/RunGameWorkflow.kt

@@ -18,7 +18,6 @@ import com.squareup.sample.gameworkflow.SyncState.SAVING
 import com.squareup.workflow1.Snapshot
 import com.squareup.workflow1.StatefulWorkflow
 import com.squareup.workflow1.Workflow
-import com.squareup.workflow1.action
 import com.squareup.workflow1.runningWorker
 import com.squareup.workflow1.rx2.asWorker
 import com.squareup.workflow1.ui.Screen
@@ -88,8 +87,12 @@ class RealRunGameWorkflow(
           namePrompt = NewGameScreen(
             renderState.defaultXName,
             renderState.defaultOName,
-            onCancel = context.eventHandler { setOutput(CanceledStart) },
-            onStartGame = context.eventHandler { x, o -> state = Playing(PlayerInfo(x, o)) }
+            onCancel = context.safeEventHandler<NewGame> {
+              setOutput(CanceledStart)
+            },
+            onStartGame = context.safeEventHandler<NewGame, String, String> { _, x, o ->
+              state = Playing(PlayerInfo(x, o))
+            }
           )
         )
       }
@@ -119,15 +122,11 @@ class RealRunGameWorkflow(
               message = "Do you really want to concede the game?",
               positive = "I Quit",
               negative = "No",
-              confirmQuit = context.eventHandler {
-                (state as? MaybeQuitting)?.let { oldState ->
-                  state = MaybeQuittingForSure(oldState.playerInfo, oldState.completedGame)
-                }
+              confirmQuit = context.safeEventHandler<MaybeQuitting> { oldState ->
+                state = MaybeQuittingForSure(oldState.playerInfo, oldState.completedGame)
               },
-              continuePlaying = context.eventHandler {
-                (state as? MaybeQuitting)?.let { oldState ->
-                  state = Playing(oldState.playerInfo, oldState.completedGame.lastTurn)
-                }
+              continuePlaying = context.safeEventHandler<MaybeQuitting> { oldState ->
+                state = Playing(oldState.playerInfo, oldState.completedGame.lastTurn)
               }
             )
           )
@@ -142,15 +141,11 @@ class RealRunGameWorkflow(
               message = "Really?",
               positive = "Yes!!",
               negative = "Sigh, no",
-              confirmQuit = context.eventHandler {
-                (state as? MaybeQuittingForSure)?.let { oldState ->
-                  state = GameOver(oldState.playerInfo, oldState.completedGame)
-                }
+              confirmQuit = context.safeEventHandler<MaybeQuittingForSure> { oldState ->
+                state = GameOver(oldState.playerInfo, oldState.completedGame)
               },
-              continuePlaying = context.eventHandler {
-                (state as? MaybeQuittingForSure)?.let { oldState ->
-                  state = Playing(oldState.playerInfo, oldState.completedGame.lastTurn)
-                }
+              continuePlaying = context.safeEventHandler<MaybeQuittingForSure> { oldState ->
+                state = Playing(oldState.playerInfo, oldState.completedGame.lastTurn)
               }
             )
           )
@@ -169,43 +164,37 @@ class RealRunGameWorkflow(
             renderState,
             onTrySaveAgain = context.trySaveAgain(),
             onPlayAgain = context.playAgain(),
-            onExit = context.eventHandler { setOutput(FinishedPlaying) }
+            onExit = context.safeEventHandler<GameOver> { setOutput(FinishedPlaying) }
           )
         )
       }
     }
 
-  private fun stopPlaying(game: CompletedGame) = action {
-    val oldState = state as Playing
+  private fun stopPlaying(game: CompletedGame) = safeAction<Playing>("stopPlaying") { oldState ->
     state = when (game.ending) {
       Quitted -> MaybeQuitting(oldState.playerInfo, game)
       else -> GameOver(oldState.playerInfo, game)
     }
   }
 
-  private fun handleLogGame(result: GameLog.LogResult) = action {
-    val oldState = state as GameOver
+  private fun handleLogGame(result: GameLog.LogResult) = safeAction<GameOver> { oldState ->
     state = when (result) {
       TRY_LATER -> oldState.copy(syncState = SAVE_FAILED)
       LOGGED -> oldState.copy(syncState = SAVED)
     }
   }
 
-  private fun RenderContext.playAgain() = eventHandler {
-    (state as? GameOver)?.let { oldState ->
-      val (x, o) = oldState.playerInfo
-      state = NewGame(x, o)
-    }
+  private fun RenderContext.playAgain() = safeEventHandler<GameOver> { oldState ->
+    val (x, o) = oldState.playerInfo
+    state = NewGame(x, o)
   }
 
-  private fun RenderContext.trySaveAgain() = eventHandler {
-    (state as? GameOver)?.let { oldState ->
-      check(oldState.syncState == SAVE_FAILED) {
-        "Should only fire trySaveAgain in syncState $SAVE_FAILED, " +
-          "was ${oldState.syncState}"
-      }
-      state = oldState.copy(syncState = SAVING)
+  private fun RenderContext.trySaveAgain() = safeEventHandler<GameOver> { oldState ->
+    check(oldState.syncState == SAVE_FAILED) {
+      "Should only fire trySaveAgain in syncState $SAVE_FAILED, " +
+        "was ${oldState.syncState}"
     }
+    state = oldState.copy(syncState = SAVING)
   }
 
   override fun snapshotState(state: RunGameState): Snapshot = state.toSnapshot()

workflow-core/api/workflow-core.api

@@ -155,6 +155,7 @@ public final class com/squareup/workflow1/Snapshots {
 public abstract class com/squareup/workflow1/StatefulWorkflow : com/squareup/workflow1/IdCacheable, com/squareup/workflow1/Workflow {
 	public fun <init> ()V
 	public final fun asStatefulWorkflow ()Lcom/squareup/workflow1/StatefulWorkflow;
+	public final fun defaultOnFailedCast (Ljava/lang/String;Lkotlin/reflect/KClass;Ljava/lang/Object;)V
 	public fun getCachedIdentifier ()Lcom/squareup/workflow1/WorkflowIdentifier;
 	public abstract fun initialState (Ljava/lang/Object;Lcom/squareup/workflow1/Snapshot;)Ljava/lang/Object;
 	public fun initialState (Ljava/lang/Object;Lcom/squareup/workflow1/Snapshot;Lkotlinx/coroutines/CoroutineScope;)Ljava/lang/Object;

workflow-core/src/commonMain/kotlin/com/squareup/workflow1/BaseRenderContext.kt

@@ -130,6 +130,45 @@ public interface BaseRenderContext<out PropsT, StateT, in OutputT> {
    * given [update] function, and immediately passes it to [actionSink]. Handy for
    * attaching event handlers to renderings.
    *
+   * It is important to understand that the [update] lambda you provide here
+   * may not run synchronously. This function and its overloads provide a short cut
+   * that lets you replace this snippet:
+   *
+   *    return SomeScreen(
+   *      onClick = {
+   *        context.actionSink.send(
+   *          action { state = SomeNewState }
+   *        }
+   *      }
+   *    )
+   *
+   *  with this:
+   *
+   *    return SomeScreen(
+   *      onClick = context.eventHandler { state = SomeNewState }
+   *    )
+   *
+   * Notice how your [update] function is passed to the [actionSink][BaseRenderContext.actionSink]
+   * to be eventually executed as the body of a [WorkflowAction]. If several actions get stacked
+   * up at once (think about accidental rapid taps on a button), that could take a while.
+   *
+   * If you require something to happen the instant a UI action happens, [eventHandler]
+   * is the wrong choice. You'll want to write your own call to `actionSink.send`:
+   *
+   *    return SomeScreen(
+   *      onClick = {
+   *        // This happens immediately.
+   *        MyAnalytics.log("SomeScreen was clicked")
+   *
+   *        context.actionSink.send(
+   *          action {
+   *            // This happens eventually.
+   *            state = SomeNewState
+   *          }
+   *        }
+   *      }
+   *    )
+   *
    * @param name A string describing the update, included in the action's [toString]
    * as a debugging aid
    * @param update Function that defines the workflow update.
@@ -264,7 +303,7 @@ public interface BaseRenderContext<out PropsT, StateT, in OutputT> {
   public fun <E1, E2, E3, E4, E5, E6, E7, E8, E9> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<@UnsafeVariance PropsT, StateT, @UnsafeVariance OutputT>
-      .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9) -> Unit
+    .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9) -> Unit
   ): (E1, E2, E3, E4, E5, E6, E7, E8, E9) -> Unit {
     return { e1, e2, e3, e4, e5, e6, e7, e8, e9 ->
       actionSink.send(action(name) { update(e1, e2, e3, e4, e5, e6, e7, e8, e9) })
@@ -274,7 +313,7 @@ public interface BaseRenderContext<out PropsT, StateT, in OutputT> {
   public fun <E1, E2, E3, E4, E5, E6, E7, E8, E9, E10> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<@UnsafeVariance PropsT, StateT, @UnsafeVariance OutputT>
-      .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9, E10) -> Unit
+    .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9, E10) -> Unit
   ): (E1, E2, E3, E4, E5, E6, E7, E8, E9, E10) -> Unit {
     return { e1, e2, e3, e4, e5, e6, e7, e8, e9, e10 ->
       actionSink.send(action(name) { update(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10) })
@@ -287,30 +326,30 @@ public interface BaseRenderContext<out PropsT, StateT, in OutputT> {
  */
 public fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
   BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
-    child: Workflow<Unit, ChildOutputT, ChildRenderingT>,
-    key: String = "",
-    handler: (ChildOutputT) -> WorkflowAction<PropsT, StateT, OutputT>
-  ): ChildRenderingT = renderChild(child, Unit, key, handler)
+  child: Workflow<Unit, ChildOutputT, ChildRenderingT>,
+  key: String = "",
+  handler: (ChildOutputT) -> WorkflowAction<PropsT, StateT, OutputT>
+): ChildRenderingT = renderChild(child, Unit, key, handler)
 
 /**
  * Convenience alias of [BaseRenderContext.renderChild] for workflows that don't emit output.
  */
 public fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
   BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
-    child: Workflow<ChildPropsT, Nothing, ChildRenderingT>,
-    props: ChildPropsT,
-    key: String = ""
-  ): ChildRenderingT = renderChild(child, props, key) { noAction() }
+  child: Workflow<ChildPropsT, Nothing, ChildRenderingT>,
+  props: ChildPropsT,
+  key: String = ""
+): ChildRenderingT = renderChild(child, props, key) { noAction() }
 
 /**
  * Convenience alias of [BaseRenderContext.renderChild] for children that don't take props or emit
  * output.
  */
 public fun <PropsT, StateT, OutputT, ChildRenderingT>
   BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
-    child: Workflow<Unit, Nothing, ChildRenderingT>,
-    key: String = ""
-  ): ChildRenderingT = renderChild(child, Unit, key) { noAction() }
+  child: Workflow<Unit, Nothing, ChildRenderingT>,
+  key: String = ""
+): ChildRenderingT = renderChild(child, Unit, key) { noAction() }
 
 /**
  * Ensures a [LifecycleWorker] is running. Since [worker] can't emit anything,
@@ -323,9 +362,9 @@ public fun <PropsT, StateT, OutputT, ChildRenderingT>
  */
 public inline fun <reified W : LifecycleWorker, PropsT, StateT, OutputT>
   BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
-    worker: W,
-    key: String = ""
-  ) {
+  worker: W,
+  key: String = ""
+) {
   runningWorker(worker, key) {
     // The compiler thinks this code is unreachable, and it is correct. But we have to pass a lambda
     // here so we might as well check at runtime as well.
@@ -348,9 +387,9 @@ public inline fun <reified W : LifecycleWorker, PropsT, StateT, OutputT>
 )
 public inline fun <reified W : Worker<Nothing>, PropsT, StateT, OutputT>
   BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
-    worker: W,
-    key: String = ""
-  ) {
+  worker: W,
+  key: String = ""
+) {
   runningWorker(worker, key) {
     // The compiler thinks this code is unreachable, and it is correct. But we have to pass a lambda
     // here so we might as well check at runtime as well.
@@ -378,10 +417,10 @@ public inline fun <reified W : Worker<Nothing>, PropsT, StateT, OutputT>
  */
 public inline fun <T, reified W : Worker<T>, PropsT, StateT, OutputT>
   BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
-    worker: W,
-    key: String = "",
-    noinline handler: (T) -> WorkflowAction<PropsT, StateT, OutputT>
-  ) {
+  worker: W,
+  key: String = "",
+  noinline handler: (T) -> WorkflowAction<PropsT, StateT, OutputT>
+) {
   runningWorker(worker, typeOf<W>(), key, handler)
 }
 
@@ -396,11 +435,11 @@ public inline fun <T, reified W : Worker<T>, PropsT, StateT, OutputT>
 @PublishedApi
 internal fun <T, PropsT, StateT, OutputT>
   BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
-    worker: Worker<T>,
-    workerType: KType,
-    key: String = "",
-    handler: (T) -> WorkflowAction<PropsT, StateT, OutputT>
-  ) {
+  worker: Worker<T>,
+  workerType: KType,
+  key: String = "",
+  handler: (T) -> WorkflowAction<PropsT, StateT, OutputT>
+) {
   val workerWorkflow = WorkerWorkflow<T>(workerType, key)
   renderChild(workerWorkflow, props = worker, key = key, handler = handler)
 }