Improve the results of synchronously executed Mutations.

soil-query-core/src/commonMain/kotlin/soil/query/MutationClient.kt

@@ -22,3 +22,4 @@ interface MutationClient {
 }
 
 typealias MutationOptionsOverride = (MutationOptions) -> MutationOptions
+typealias MutationCallback<T> = (Result<T>) -> Unit

soil-query-core/src/commonMain/kotlin/soil/query/MutationCommand.kt

@@ -84,7 +84,8 @@ suspend fun <T, S> MutationCommand.Context<T>.mutate(
  */
 suspend inline fun <T, S> MutationCommand.Context<T>.dispatchMutateResult(
     key: MutationKey<T, S>,
-    variable: S
+    variable: S,
+    noinline callback: MutationCallback<T>?
 ) {
     mutate(key, variable)
         .onSuccess { data ->
@@ -98,6 +99,9 @@ suspend inline fun <T, S> MutationCommand.Context<T>.dispatchMutateResult(
         }
         .onFailure { dispatch(MutationAction.MutateFailure(it)) }
         .onFailure { options.onError?.invoke(it, state, key.id) }
+        .also {
+            callback?.invoke(it)
+        }
 }
 
 internal fun <T> MutationCommand.Context<T>.onRetryCallback(

soil-query-core/src/commonMain/kotlin/soil/query/MutationCommands.kt

@@ -4,6 +4,7 @@
 package soil.query
 
 import soil.query.internal.vvv
+import kotlin.coroutines.cancellation.CancellationException
 
 /**
  * Mutation commands are used to update the [mutation state][MutationState].
@@ -24,16 +25,18 @@ sealed class MutationCommands<T> : MutationCommand<T> {
     data class Mutate<T, S>(
         val key: MutationKey<T, S>,
         val variable: S,
-        val revision: String
+        val revision: String,
+        val callback: MutationCallback<T>? = null
     ) : MutationCommands<T>() {
 
         override suspend fun handle(ctx: MutationCommand.Context<T>) {
             if (!ctx.shouldMutate(revision)) {
                 ctx.options.vvv(key.id) { "skip mutation(shouldMutate=false)" }
+                callback?.invoke(Result.failure(CancellationException("skip mutation")))
                 return
             }
             ctx.dispatch(MutationAction.Mutating)
-            ctx.dispatchMutateResult(key, variable)
+            ctx.dispatchMutateResult(key, variable, callback)
         }
     }
 

soil-query-core/src/commonMain/kotlin/soil/query/MutationRef.kt

@@ -3,8 +3,8 @@
 
 package soil.query
 
-import kotlinx.coroutines.flow.dropWhile
-import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.CompletableDeferred
+import soil.query.internal.toResultCallback
 
 /**
  * A reference to a [Mutation] for [MutationKey].
@@ -28,16 +28,9 @@ class MutationRef<T, S>(
      * @return The result of the mutation.
      */
     suspend fun mutate(variable: S): T {
-        mutateAsync(variable)
-        val submittedAt = state.value.submittedAt
-        val result = state.dropWhile { it.submittedAt <= submittedAt }.first()
-        if (result.isSuccess) {
-            return result.data!!
-        } else if (result.isFailure) {
-            throw result.error!!
-        } else {
-            error("Unexpected ${result.status}")
-        }
+        val deferred = CompletableDeferred<T>()
+        command.send(MutationCommands.Mutate(key, variable, state.value.revision, deferred.toResultCallback()))
+        return deferred.await()
     }
 
     /**

soil-query-core/src/commonMain/kotlin/soil/query/internal/CompletableDeferredExt.kt

@@ -0,0 +1,14 @@
+// Copyright 2024 Soil Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+package soil.query.internal
+
+import kotlinx.coroutines.CompletableDeferred
+
+internal fun <T> CompletableDeferred<T>.toResultCallback(): (Result<T>) -> Unit {
+    return { result ->
+        result
+            .onSuccess { complete(it) }
+            .onFailure { completeExceptionally(it) }
+    }
+}