Merge pull request #172 from yumemi-inc/codex/issue-166-pending-actions

Add pending action cancellation API

Author: hkusu

README.md

@@ -45,6 +45,8 @@ By combining Tart with Kotlin `sealed class`/`sealed interface`, you can model e
   - [Multiple states and transitions](#multiple-states-and-transitions)
   - [Error handling](#error-handling)
   - [Asynchronous Work](#asynchronous-work)
+  - [Cancel Pending Actions](#cancel-pending-actions)
+  - [Alternative DSL Forms](#alternative-dsl-forms)
   - [Specifying coroutineContext](#specifying-coroutinecontext)
     - [Specifying CoroutineDispatchers](#specifying-coroutinedispatchers)
   - [State Persistence](#state-persistence)
@@ -117,20 +119,6 @@ val store: Store<CounterState, CounterAction, Nothing> = Store(CounterState(coun
 }
 ```
 
-`anyState{}` lets you register handlers for all *States*, and `anyAction{}` can be used there as a fallback for all *Actions*.
-
-For conditional or complex updates, use `nextStateBy{}` to compute and return the new state.
-
-```kt
-nextStateBy {
-    // ...
-
-    val newCount = ...
-
-    state.copy(count = newCount)
-}
-```
-
 The *Store* setup is complete.
 Keep the store instance in a ViewModel (or similar).
 
@@ -360,8 +348,6 @@ val store: Store<CounterState, CounterAction, CounterEvent> = Store {
 }
 ```
 
-`error<Exception>{}` can also be written as `anyError{}`.
-
 Errors can be caught not only in the `enter{}` block but also in the `action{}` and `exit{}` blocks.
 In other words, your business logic errors can be handled in the `error{}` block.
 
@@ -418,12 +404,46 @@ state<MyState.Active> {
 }
 ```
 
-If you prefer shorter forms, use `enterAsync{}` / `actionAsync{}` (or `anyActionAsync{}` when using `anyAction{}`).
-
 This pattern lets your *Store* react to external data changes automatically, such as database updates, user preference changes, or network events.
 Coroutines started by `launch{}` are automatically cancelled when the *State* changes to a different *State*, making it easy to manage resources and subscriptions.
 In `action{}`, `launch{}` is tied to the *State* active at action start.
 
+### Cancel Pending Actions
+
+If you need to discard already queued `dispatch()` calls at a specific point, call `cancelPendingActions()` inside `enter{}`, `action{}`, `exit{}`, `error{}`, or inside `transaction{}` from a launched coroutine.
+
+```kt
+state<MyState.Active> {
+    action<MyAction.Finish> {
+        cancelPendingActions()
+        nextState(MyState.Done)
+    }
+}
+```
+
+### Alternative DSL Forms
+
+Some DSL APIs are just alternative forms of existing APIs:
+
+- `anyState{}` is the global form of `state<...>{}` and applies to all *States*.
+- `anyAction{}` is the global form of `action<...>{}` and applies to all *Actions*.
+- `anyError{}` is an alias of `error<Exception>{}`.
+- `enterAsync{}` is shorthand for `enter { launch { ... } }`.
+- `actionAsync{}` is shorthand for `action<...> { launch { ... } }`.
+- `anyActionAsync{}` is shorthand for `anyAction { launch { ... } }`.
+
+Instead of `nextState(...)`, use `nextStateBy{}` when you want to compute and return the next state inside a block.
+
+```kt
+nextStateBy {
+    // ...
+
+    val newCount = ...
+
+    state.copy(count = newCount)
+}
+```
+
 ### Specifying coroutineContext
 
 The Store operates using Coroutines, and the default CoroutineContext is `EmptyCoroutineContext + Dispatchers.Default`.

tart-core/src/commonMain/kotlin/io/yumemi/tart/core/StoreImpl.kt

@@ -86,15 +86,31 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
         )
     }
 
+    private val dispatchScope by lazy {
+        CoroutineScope(
+            coroutineScope.coroutineContext + SupervisorJob(coroutineScope.coroutineContext[Job]),
+        )
+    }
+
     private val mutex = Mutex()
 
     private val stateScopes = mutableMapOf<KClass<out S>, CoroutineScope>()
 
+    private var activeDispatchJob: Job? = null
+
     final override fun dispatch(action: A) {
-        coroutineScope.launch {
+        dispatchScope.launch {
             mutex.withLock {
-                initializeIfNeeded()
-                onActionDispatched(currentState, action)
+                val dispatchJob = coroutineContext[Job]
+                activeDispatchJob = dispatchJob
+                try {
+                    initializeIfNeeded()
+                    onActionDispatched(currentState, action)
+                } finally {
+                    if (activeDispatchJob == dispatchJob) {
+                        activeDispatchJob = null
+                    }
+                }
             }
         }
     }
@@ -243,6 +259,10 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
                     newState = block()
                 }
 
+                override fun cancelPendingActions() {
+                    clearPendingDispatchJobs()
+                }
+
                 override suspend fun event(event: E) {
                     emit(event)
                 }
@@ -280,6 +300,10 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
                     newState = block()
                 }
 
+                override fun cancelPendingActions() {
+                    clearPendingDispatchJobs()
+                }
+
                 override suspend fun event(event: E) {
                     emit(event)
                 }
@@ -348,6 +372,10 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
                                     newState = block()
                                 }
 
+                                override fun cancelPendingActions() {
+                                    clearPendingDispatchJobs()
+                                }
+
                                 override suspend fun event(event: E) {
                                     emit(event)
                                 }
@@ -399,6 +427,10 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
                                     newState = block()
                                 }
 
+                                override fun cancelPendingActions() {
+                                    clearPendingDispatchJobs()
+                                }
+
                                 override suspend fun event(event: E) {
                                     emit(event)
                                 }
@@ -430,6 +462,11 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
             onExit.invoke(
                 object : ExitScope<S, E, S> {
                     override val state = state
+
+                    override fun cancelPendingActions() {
+                        clearPendingDispatchJobs()
+                    }
+
                     override suspend fun event(event: E) {
                         emit(event)
                     }
@@ -469,6 +506,10 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
                     newState = block()
                 }
 
+                override fun cancelPendingActions() {
+                    clearPendingDispatchJobs()
+                }
+
                 override suspend fun event(event: E) {
                     emit(event)
                 }
@@ -485,6 +526,14 @@ internal abstract class StoreImpl<S : State, A : Action, E : Event> : Store<S, A
         processMiddleware { afterEventEmit(state, event) }
     }
 
+    private fun clearPendingDispatchJobs() {
+        val currentJob = activeDispatchJob
+        val dispatchScopeJob = dispatchScope.coroutineContext[Job] ?: return
+        dispatchScopeJob.children
+            .filter { it != currentJob && it.isActive }
+            .forEach { it.cancel() }
+    }
+
     private suspend fun processMiddleware(block: suspend Middleware<S, A, E>.() -> Unit) {
         try {
             coroutineScope {

tart-core/src/commonMain/kotlin/io/yumemi/tart/core/StoreScope.kt

@@ -36,6 +36,12 @@ interface EnterScope<S : State, A : Action, E : Event, S2 : S> : StoreScope {
      */
     fun nextStateBy(block: () -> S)
 
+    /**
+     * Cancels actions that are already queued behind the currently executing store work.
+     * The action/transaction currently in progress keeps running.
+     */
+    fun cancelPendingActions()
+
     /**
      * Emits an event from the enter handler.
      * Use this to communicate with the outside world about important occurrences.
@@ -111,6 +117,12 @@ interface EnterScope<S : State, A : Action, E : Event, S2 : S> : StoreScope {
              */
             fun nextStateBy(block: () -> S)
 
+            /**
+             * Cancels actions that are already queued behind the currently executing store work.
+             * The action/transaction currently in progress keeps running.
+             */
+            fun cancelPendingActions()
+
             /**
              * Emits an event from the transaction.
              * Use this to communicate with the outside world about important occurrences.
@@ -133,6 +145,12 @@ interface ExitScope<S : State, E : Event, S2 : S> : StoreScope {
      */
     val state: S2
 
+    /**
+     * Cancels actions that are already queued behind the currently executing store work.
+     * The action/transaction currently in progress keeps running.
+     */
+    fun cancelPendingActions()
+
     /**
      * Emits an event from the exit handler.
      * Use this to communicate with the outside world about important occurrences.
@@ -174,6 +192,12 @@ interface ActionScope<S : State, A : Action, E : Event, S2 : S> : StoreScope {
      */
     fun nextStateBy(block: () -> S)
 
+    /**
+     * Cancels actions that are already queued behind the currently executing store work.
+     * The action/transaction currently in progress keeps running.
+     */
+    fun cancelPendingActions()
+
     /**
      * Emits an event from the action handler.
      * Use this to communicate with the outside world about important occurrences.
@@ -259,6 +283,12 @@ interface ActionScope<S : State, A : Action, E : Event, S2 : S> : StoreScope {
              */
             fun nextStateBy(block: () -> S)
 
+            /**
+             * Cancels actions that are already queued behind the currently executing store work.
+             * The action/transaction currently in progress keeps running.
+             */
+            fun cancelPendingActions()
+
             /**
              * Emits an event from the transaction.
              * Use this to communicate with the outside world about important occurrences.
@@ -302,6 +332,12 @@ interface ErrorScope<S : State, E : Event, S2 : S, T : Throwable> : StoreScope {
      */
     fun nextStateBy(block: () -> S)
 
+    /**
+     * Cancels actions that are already queued behind the currently executing store work.
+     * The action/transaction currently in progress keeps running.
+     */
+    fun cancelPendingActions()
+
     /**
      * Emits an event from the error handler.
      * Use this to communicate with the outside world about important occurrences.

tart-core/src/commonTest/kotlin/io/yumemi/tart/core/StorePendingActionCancellationTest.kt

@@ -0,0 +1,112 @@
+package io.yumemi.tart.core
+
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.test.StandardTestDispatcher
+import kotlinx.coroutines.test.TestDispatcher
+import kotlinx.coroutines.test.advanceUntilIdle
+import kotlinx.coroutines.test.runCurrent
+import kotlinx.coroutines.test.runTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+@OptIn(ExperimentalCoroutinesApi::class)
+class StorePendingActionCancellationTest {
+
+    sealed interface AppState : State {
+        data class Active(val value: Int = 0) : AppState
+    }
+
+    sealed interface AppAction : Action {
+        data object HoldAndCancel : AppAction
+        data object LaunchTransactionAndCancel : AppAction
+        data object Increment : AppAction
+    }
+
+    private fun createTestStore(
+        testDispatcher: TestDispatcher,
+        onHoldAndCancelStarted: CompletableDeferred<Unit>? = null,
+        onHoldAndCancelCompleted: CompletableDeferred<Unit>? = null,
+        onTransactionStarted: CompletableDeferred<Unit>? = null,
+        onTransactionCompleted: CompletableDeferred<Unit>? = null,
+    ): Store<AppState, AppAction, Nothing> {
+        return Store(AppState.Active()) {
+            coroutineContext(testDispatcher)
+
+            state<AppState.Active> {
+                action<AppAction.HoldAndCancel>(testDispatcher) {
+                    onHoldAndCancelStarted?.complete(Unit)
+                    delay(100)
+                    cancelPendingActions()
+                    onHoldAndCancelCompleted?.complete(Unit)
+                    nextState(state.copy(value = state.value + 100))
+                }
+
+                action<AppAction.LaunchTransactionAndCancel>(testDispatcher) {
+                    launch(testDispatcher) {
+                        transaction(testDispatcher) {
+                            onTransactionStarted?.complete(Unit)
+                            delay(100)
+                            cancelPendingActions()
+                            onTransactionCompleted?.complete(Unit)
+                            nextState(state.copy(value = state.value + 100))
+                        }
+                    }
+                }
+
+                action<AppAction.Increment>(testDispatcher) {
+                    nextState(state.copy(value = state.value + 1))
+                }
+            }
+        }
+    }
+
+    @Test
+    fun cancelPendingActions_inAction_skipsQueuedDispatches() = runTest {
+        val testDispatcher = StandardTestDispatcher(testScheduler)
+        val actionStarted = CompletableDeferred<Unit>()
+        val actionCompleted = CompletableDeferred<Unit>()
+        val store = createTestStore(
+            testDispatcher = testDispatcher,
+            onHoldAndCancelStarted = actionStarted,
+            onHoldAndCancelCompleted = actionCompleted,
+        )
+
+        store.dispatch(AppAction.HoldAndCancel)
+        runCurrent()
+        actionStarted.await()
+
+        store.dispatch(AppAction.Increment)
+        store.dispatch(AppAction.Increment)
+
+        advanceUntilIdle()
+
+        assertEquals(true, actionCompleted.isCompleted, "The running action should not cancel itself")
+        assertEquals(AppState.Active(value = 100), store.currentState)
+    }
+
+    @Test
+    fun cancelPendingActions_inTransaction_skipsQueuedDispatches() = runTest {
+        val testDispatcher = StandardTestDispatcher(testScheduler)
+        val transactionStarted = CompletableDeferred<Unit>()
+        val transactionCompleted = CompletableDeferred<Unit>()
+        val store = createTestStore(
+            testDispatcher = testDispatcher,
+            onTransactionStarted = transactionStarted,
+            onTransactionCompleted = transactionCompleted,
+        )
+
+        store.dispatch(AppAction.LaunchTransactionAndCancel)
+        runCurrent()
+        transactionStarted.await()
+
+        store.dispatch(AppAction.Increment)
+        store.dispatch(AppAction.Increment)
+
+        advanceUntilIdle()
+
+        assertEquals(true, transactionCompleted.isCompleted, "The running transaction should complete")
+        assertEquals(AppState.Active(value = 100), store.currentState)
+    }
+}