Add logic to emit state changes for a specific keyPath

Author: rickclephas

KMPObservableViewModelCore/ObservableKeyPath.swift

@@ -0,0 +1,38 @@
+//
+//  ObservableKeyPath.swift
+//  KMPObservableViewModelCore
+//
+//  Created by Rick Clephas on 11/06/2025.
+//
+
+import Observation
+import KMPObservableViewModelCoreObjC
+
+/// An observable `KeyPath` which uses an `ObservationRegistrar` to track changes.
+@available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, *)
+public final class ObservableKeyPath<Root, Value>: ViewModelKeyPath where Root: AnyObject, Root: Observable {
+    
+    private weak var subject: Root?
+    private let keyPath: KeyPath<Root, Value>
+    
+    /// Creates a new `ObservableKeyPath` for the provided `subject` and `keyPath`.
+    public init(_ subject: Root, _ keyPath: KeyPath<Root, Value>) {
+        self.subject = subject
+        self.keyPath = keyPath
+    }
+    
+    public func access(_ publisher: any Publisher) {
+        guard let subject else { return }
+        publisher.cast().observationRegistrar.access(subject, keyPath: keyPath)
+    }
+    
+    public func willSet(_ publisher: any Publisher) {
+        guard let subject else { return }
+        publisher.cast().observationRegistrar.willSet(subject, keyPath: keyPath)
+    }
+    
+    public func didSet(_ publisher: any Publisher) {
+        guard let subject else { return }
+        publisher.cast().observationRegistrar.didSet(subject, keyPath: keyPath)
+    }
+}

KMPObservableViewModelCore/ObservableViewModelPublisher.swift

@@ -6,13 +6,25 @@
 //
 
 import Combine
+import Observation
 import KMPObservableViewModelCoreObjC
 
 /// Publisher for `ObservableViewModel` that connects to the `ViewModelScope`.
 public final class ObservableViewModelPublisher: Combine.Publisher, KMPObservableViewModelCoreObjC.Publisher {
     public typealias Output = Void
     public typealias Failure = Never
 
+    private var _observationRegistrar: Any? = nil
+    @available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, *)
+    public var observationRegistrar: ObservationRegistrar {
+        if let observationRegistrar = _observationRegistrar {
+            return observationRegistrar as! ObservationRegistrar
+        }
+        let observationRegistrar = ObservationRegistrar()
+        _observationRegistrar = observationRegistrar
+        return observationRegistrar
+    }
+    
     internal let cancellable = ViewModelCancellable()
 
     private let publisher: ObservableObjectPublisher
@@ -33,6 +45,16 @@ public final class ObservableViewModelPublisher: Combine.Publisher, KMPObservabl
     }
 }
 
+internal extension KMPObservableViewModelCoreObjC.Publisher {
+    /// Casts this `Publisher` to an `ObservableViewModelPublisher`.
+    func cast() -> ObservableViewModelPublisher {
+        guard let publisher = self as? ObservableViewModelPublisher else {
+            fatalError("Publisher must be an ObservableViewModelPublisher")
+        }
+        return publisher
+    }
+}
+
 /// Subscriber for `ObservableViewModelPublisher` that creates `ObservableViewModelSubscription`s.
 private class ObservableViewModelSubscriber<S>: Subscriber where S : Subscriber, Never == S.Failure, Void == S.Input {
     typealias Input = Void

KMPObservableViewModelCore/PublishedKeyPath.swift

@@ -0,0 +1,28 @@
+//
+//  PublishedKeyPath.swift
+//  KMPObservableViewModelCore
+//
+//  Created by Rick Clephas on 09/06/2025.
+//
+
+import KMPObservableViewModelCoreObjC
+
+/// A published `KeyPath` which uses an `ObservableObject` to emit change events.
+public final class PublishedKeyPath: ViewModelKeyPath {
+    
+    public static let shared = PublishedKeyPath()
+    
+    private init() { }
+    
+    public func access(_ publisher: any Publisher) {
+        // Published keyPaths only emit on willSet
+    }
+    
+    public func willSet(_ publisher: any Publisher) {
+        publisher.cast().send()
+    }
+    
+    public func didSet(_ publisher: any Publisher) {
+        // Published keyPaths only emit on willSet
+    }
+}

KMPObservableViewModelCoreObjC/KMPOVMViewModelKeyPath.h

@@ -0,0 +1,25 @@
+//
+//  KMPOVMViewModelKeyPath.h
+//  KMPObservableViewModelCoreObjC
+//
+//  Created by Rick Clephas on 11/06/2025.
+//
+
+#ifndef KMPOVMViewModelKeyPath_h
+#define KMPOVMViewModelKeyPath_h
+
+#import <Foundation/Foundation.h>
+#import "KMPOVMPublisher.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+__attribute__((swift_name("ViewModelKeyPath")))
+@protocol KMPOVMViewModelKeyPath
+- (void)access:(id<KMPOVMPublisher>)publisher;
+- (void)willSet:(id<KMPOVMPublisher>)publisher;
+- (void)didSet:(id<KMPOVMPublisher>)publisher;
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* KMPOVMViewModelKeyPath_h */

KMPObservableViewModelCoreObjC/KMPObservableViewModelCoreObjC.h

@@ -7,4 +7,5 @@
 
 #import "KMPOVMPublisher.h"
 #import "KMPOVMSubscriptionCount.h"
+#import "KMPOVMViewModelKeyPath.h"
 #import "KMPOVMViewModelScope.h"

kmp-observableviewmodel-core/src/appleMain/kotlin/com/rickclephas/kmp/observableviewmodel/NativeViewModelScope.kt

@@ -1,6 +1,7 @@
 package com.rickclephas.kmp.observableviewmodel
 
 import com.rickclephas.kmp.observableviewmodel.objc.KMPOVMPublisherProtocol
+import com.rickclephas.kmp.observableviewmodel.objc.KMPOVMViewModelKeyPathProtocol
 import kotlinx.coroutines.CoroutineScope
 import platform.darwin.NSObject
 
@@ -21,9 +22,15 @@ internal class NativeViewModelScope internal constructor(
         if (_publisher != null) throw IllegalStateException("ViewModel can't be initialized more than once")
         _publisher = publisher
     }
+
+    /**
+     * Indicates if [ViewModelKeyPath][KMPOVMViewModelKeyPathProtocol]s musts be used with the [publisher].
+     */
+    var requireKeyPaths: Boolean = false
 }
 
 /**
  * Casts `this` [ViewModelScope] to a [NativeViewModelScope].
  */
+@Suppress("NOTHING_TO_INLINE")
 internal inline fun ViewModelScope.asNative(): NativeViewModelScope = this as NativeViewModelScope

kmp-observableviewmodel-core/src/appleMain/kotlin/com/rickclephas/kmp/observableviewmodel/ObservableStateFlow.kt

@@ -1,5 +1,6 @@
 package com.rickclephas.kmp.observableviewmodel
 
+import com.rickclephas.kmp.observableviewmodel.objc.KMPOVMViewModelKeyPathProtocol
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.ExperimentalForInheritanceCoroutinesApi
 import kotlinx.coroutines.Job
@@ -17,17 +18,28 @@ internal class ObservableMutableStateFlow<T>(
     private val stateFlow: MutableStateFlow<T>
 ): MutableStateFlow<T> {
 
+    /**
+     * The [KeyPath][KMPOVMViewModelKeyPathProtocol] associated with the [StateFlow] property.
+     */
+    var keyPath: KMPOVMViewModelKeyPathProtocol? = null
+        set(value) {
+            if (value != null) viewModelScope.requireKeyPaths = true
+            field = value
+        }
+
     override var value: T
-        get() = stateFlow.value
+        get() = viewModelScope.access(keyPath) { stateFlow.value }
         set(value) {
-            if (stateFlow.value != value) {
-                viewModelScope.publisher?.send()
+            val changed = stateFlow.value != value
+            viewModelScope.set(keyPath, changed) {
+                stateFlow.value = value
             }
-            stateFlow.value = value
         }
 
+    // Same implementation as in StateFlowImpl, but we need to go through our own value property.
+    // https://github.com/Kotlin/kotlinx.coroutines/blob/6dfabf763fe9fc91fbb73eb0f2d5b488f53043f1/kotlinx-coroutines-core/common/src/flow/StateFlow.kt#L367
     override val replayCache: List<T>
-        get() = stateFlow.replayCache
+        get() = listOf(value)
 
     /**
      * The combined subscription count from the [NativeViewModelScope] and the actual [StateFlow].
@@ -38,10 +50,10 @@ internal class ObservableMutableStateFlow<T>(
         stateFlow.collect(collector)
 
     override fun compareAndSet(expect: T, update: T): Boolean {
-        if (stateFlow.value == expect && expect != update) {
-            viewModelScope.publisher?.send()
+        val changed = stateFlow.value == expect && expect != update
+        return viewModelScope.set(keyPath, changed) {
+            stateFlow.compareAndSet(expect, update)
         }
-        return stateFlow.compareAndSet(expect, update)
     }
 
     @ExperimentalCoroutinesApi
@@ -70,3 +82,24 @@ internal class ObservableStateFlow<T>(
     @Suppress("unused")
     private val job: Job? = null
 ): StateFlow<T> by flow
+
+/**
+ * Returns the `ObservableStateFlow` for the provided [stateFlow].
+ * @throws IllegalArgumentException if the [stateFlow] isn't an `ObservableStateFlow`.
+ */
+internal fun <T> requireObservableStateFlow(
+    stateFlow: StateFlow<T>,
+): ObservableMutableStateFlow<T> = when (stateFlow) {
+    is ObservableMutableStateFlow -> stateFlow
+    is ObservableStateFlow -> stateFlow.flow
+    else -> throw IllegalArgumentException("$stateFlow is not an ObservableStateFlow")
+}
+
+/**
+ * Asserts that the provided [stateFlow] is an `ObservableStateFlow`.
+ * @throws IllegalArgumentException if the [stateFlow] isn't an `ObservableStateFlow`.
+ */
+@InternalKMPObservableViewModelApi
+public fun <T> assertObservableStateFlow(stateFlow: StateFlow<T>) {
+    requireObservableStateFlow(stateFlow)
+}

kmp-observableviewmodel-core/src/appleMain/kotlin/com/rickclephas/kmp/observableviewmodel/StateFlow.kt

@@ -62,3 +62,9 @@ private fun <T> CoroutineScope.launchSharing(
         }
     }
 }
+
+/**
+ * @see kotlinx.coroutines.flow.asStateFlow
+ */
+public actual fun <T> MutableStateFlow<T>.asObservableStateFlow(): StateFlow<T> =
+    ObservableStateFlow(requireObservableStateFlow(this), null)

kmp-observableviewmodel-core/src/appleMain/kotlin/com/rickclephas/kmp/observableviewmodel/ViewModelKeyPath.kt

@@ -0,0 +1,53 @@
+package com.rickclephas.kmp.observableviewmodel
+
+import com.rickclephas.kmp.observableviewmodel.objc.KMPOVMViewModelKeyPathProtocol
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * Sets the [KeyPath][KMPOVMViewModelKeyPathProtocol] of an `ObservableStateFlow`.
+ * @throws IllegalArgumentException if `this` [StateFlow] isn't an `ObservableStateFlow`.
+ */
+@InternalKMPObservableViewModelApi
+public fun <T> StateFlow<T>.setKeyPath(keyPath: KMPOVMViewModelKeyPathProtocol?) {
+    requireObservableStateFlow(this).keyPath = keyPath
+}
+
+/**
+ * Helper to emit [keyPath] access events through the [NativeViewModelScope].
+ * @param keyPath The keyPath being accessed.
+ * @param action The action accessing the keyPath value.
+ */
+internal inline fun <R> NativeViewModelScope.access(
+    keyPath: KMPOVMViewModelKeyPathProtocol?,
+    action: () -> R
+): R {
+    val publisher = publisher
+    if (keyPath != null && publisher != null) {
+        keyPath.access(publisher)
+    }
+    return action()
+}
+
+/**
+ * Helper to emit [keyPath] willSet and didSet events through the [NativeViewModelScope].
+ * @param keyPath The keyPath being set.
+ * @param changed Indicates if it's likely the property will be changed.
+ * False-positives are allowed, false-negatives aren't.
+ * @param action The action setting the new keyPath value.
+ */
+internal inline fun <R> NativeViewModelScope.set(
+    keyPath: KMPOVMViewModelKeyPathProtocol?,
+    changed: Boolean,
+    action: () -> R
+): R {
+    val publisher = publisher
+    if (!changed || publisher == null) return action()
+    if (keyPath != null) {
+        keyPath.willSet(publisher)
+    } else if (!requireKeyPaths) {
+        publisher.send()
+    }
+    val result = action()
+    keyPath?.didSet(publisher)
+    return result
+}

kmp-observableviewmodel-core/src/commonMain/kotlin/com/rickclephas/kmp/observableviewmodel/StateFlow.kt

@@ -21,3 +21,8 @@ public expect fun <T> Flow<T>.stateIn(
     started: SharingStarted,
     initialValue: T
 ): StateFlow<T>
+
+/**
+ * @see kotlinx.coroutines.flow.asStateFlow
+ */
+public expect fun <T> MutableStateFlow<T>.asObservableStateFlow(): StateFlow<T>

kmp-observableviewmodel-core/src/nativeInterop/cinterop/KMPObservableViewModelCoreObjC.def

@@ -1,3 +1,3 @@
 language = Objective-C
 package = com.rickclephas.kmp.observableviewmodel.objc
-headers = KMPOVMPublisher.h KMPOVMSubscriptionCount.h KMPOVMViewModelScope.h
+headers = KMPOVMPublisher.h KMPOVMSubscriptionCount.h KMPOVMViewModelKeyPath.h KMPOVMViewModelScope.h

kmp-observableviewmodel-core/src/nonAppleMain/kotlin/com/rickclephas/kmp/observableviewmodel/StateFlow.kt

@@ -18,3 +18,8 @@ public actual inline fun <T> Flow<T>.stateIn(
     started: SharingStarted,
     initialValue: T
 ): StateFlow<T> = stateIn(viewModelScope.coroutineScope, started, initialValue)
+
+/**
+ * @see kotlinx.coroutines.flow.asStateFlow
+ */
+public actual fun <T> MutableStateFlow<T>.asObservableStateFlow(): StateFlow<T> = asStateFlow()