Provide final hook in HealthKitConstraint after batch of updates for anchored queries

[vinepb]

What Stanford Spezi module is your idea related to?

SpeziHealthKit

Use Case

Provide final hook to notify the Standard that processing of a batch of HealthKit updates (both additions and removals) has completed, to be used with anchored queries.

Problem

When using SpeziHealthKit with SwiftData, I found it unoptimized to leave auto save on, or to perform a save with each new sample when creating and storing custom data points, while using anchored queries.

actor StressAppStandard: Standard, HealthKitConstraint {
    let context: ModelContext
    
    init(container: ModelContainer) {
        self.context = ModelContext(container)
    }

    func add(sample: HKSample) async {

        let newDataPoint = CustomDataPoint(
            sample: sample
        )

        context.insert(newDataPoint)
        try? context.save()
    }

    func remove(sample: HKDeletedObject) {}
}

Solution

The idea to simply add a new method to the HealthKitConstraint protocol to be called at the end of batch updates. Example:

public protocol HealthKitConstraint: Standard {
    /// Notifies the `Standard` about the addition of a HealthKit `HKSample` sample instance.
    /// - Parameter sample: The `HKSample` that should be added.
    func add(sample: HKSample) async
    
    /// Notifies the `Standard` about the removal of a HealthKit sample as defined by the `HKDeletedObject`.
    /// - Parameter sample: The `HKDeletedObject` is a sample that should be removed.
    func remove(sample: HKDeletedObject) async
    
    /// Notifies the `Standard` that processing of a batch of HealthKit updates (both additions and removals) has completed.
    /// This method serves as a hook to finalize any operations after a group of HealthKit samples have been processed.
    func finalizeUpdates() async
}

Then in HKHealthStore+AnchoredObjectQuery.swift:

extension HKHealthStore {
    @MainActor
    func anchoredSingleObjectQuery(
        for sampleType: HKSampleType,
        using anchor: HKQueryAnchor?,
        withPredicate predicate: NSPredicate?,
        standard: any HealthKitConstraint
    ) async throws -> HKQueryAnchor {
        let anchorDescriptor = anchorDescriptor(sampleType: sampleType, predicate: predicate, anchor: anchor)
        let result = try await anchorDescriptor.result(for: self)
        for deletedObject in result.deletedObjects {
            await standard.remove(sample: deletedObject)
        }
        for addedSample in result.addedSamples {
            await standard.add(sample: addedSample)
        }
        await standard.finalizeUpdates()
        return result.newAnchor
    }
    [...]
}

Similarly, in HealthKitSampleCollector.swift:

final class HealthKitSampleCollector<Sample: _HKSampleWithSampleType>: HealthDataCollector {
    [...]
    @MainActor
    private func anchoredContinuousObjectQuery() async throws {
        let anchorDescriptor = healthStore.anchorDescriptor(
            sampleType: sampleType.hkSampleType,
            predicate: predicate,
            anchor: anchor
        )
        let updateQueue = anchorDescriptor.results(for: healthStore)
        let task = Task {
            for try await results in updateQueue {
                guard isActive else {
                    return
                }
                for deletedObject in results.deletedObjects {
                    await standard.remove(sample: deletedObject)
                }
                for addedSample in results.addedSamples {
                    await standard.add(sample: addedSample)
                }
                await standard.finalizeUpdates()
                self.anchor = results.newAnchor
            }
        }
        queryVariant = .anchorQuery(task)
    }
    [...]
}

Then an example usage scenario would be:

actor StressAppStandard: Standard, HealthKitConstraint {
    let context: ModelContext
    
    init(container: ModelContainer) {
        self.context = ModelContext(container)
    }

    func add(sample: HKSample) async {

        let newDataPoint = CustomDataPoint(
            sample: sample
        )

        context.insert(newDataPoint)
    }

    func finalizeUpdates() async {
        try? context.save()
    }

    func remove(sample: HKDeletedObject) {}
}

Alternatives considered

Haven't found a better alternative to integrate with SwiftData, but am open to suggestions.

Additional context

No response

Code of Conduct

• I agree to follow this projects's Code of Conduct and Contributing Guidelines

[lukaskollmer]

@vinepb we already have this: as part of the 1.0 release of SpeziHealthKit, the HealthKitConstraint was reworked to the following:

public protocol HealthKitConstraint: Standard {
    /// Notifies the `Standard` about the addition of a batch of HealthKit `HKSample` samples.
    /// - parameter addedSamples: The `HKSample`s that were added to the HealthKit database.
    /// - parameter sampleType: The ``SampleType`` of the new samples
    func handleNewSamples<Sample>(
        _ addedSamples: some Collection<Sample>,
        ofType sampleType: SampleType<Sample>
    ) async
    
    /// Notifies the `Standard` about the removal of a batch of HealthKit objects.
    /// - parameter deletedObjects: The `HKDeletedObject`s that were removed from the HealthKit database
    /// - parameter sampleType: The ``SampleType`` of the deleted objects
    func handleDeletedObjects<Sample>(
        _ deletedObjects: some Collection<HKDeletedObject>,
        ofType sampleType: SampleType<Sample>
    ) async
}

which will provide all new/deleted objects at once, on a per-sample-type basis

based on the interface you're describing (with every new/deleted sample being passed to the standard on its own), i think you're running an outdated pre-1.0 version.

also, regarding your question about integration with SwiftData: depending on your specific use case it might be more efficient to simply fetch the data from HealthKit on demand, instead of syncing it with SwiftData.
if your use case is accessing the Health data in SwiftUI Views: our 1.0 release added an @HealthKitQuery property wrapper (and some other related types) which allow you to directly query health samples within a view, in an efficient and auto-updating way. it's basically an @Query, but for HealthKit