@kingstinct/react-native-healthkit 14.0.2 → 15.1.0

package/README.md

@@ -121,13 +121,13 @@ Some imperative examples:
       'HKQuantityTypeIdentifierInsulinDelivery',
       'IU',
       5.5,
+      new Date(),
+      new Date(),
       {
-        metadata: {
           // Metadata keys could be arbirtary string to store app-specific data.
           // To use built-in types from https://developer.apple.com/documentation/healthkit/samples/metadata_keys
           // you need to specify string values instead of variable names (by dropping MetadataKey from the name).
           HKInsulinDeliveryReason: HKInsulinDeliveryReason.basal,
-        },
       }
     );
 ```
@@ -154,6 +154,36 @@ Example:
   // etc..
 ```
 
+### Memory considerations for workouts and other native objects
+
+Workouts (and a few other results, like sources) are returned as *proxies*: native objects that keep the underlying `HKWorkout` alive so you can call follow-up functions such as `getWorkoutRoutes()`, `getStatistic()` or `getAllStatistics()` on them. The JavaScript garbage collector frees a proxy, and the HealthKit objects behind it, once it is no longer referenced. The library reports an estimate of each proxy's native size to the JS engine so it can schedule collections sensibly. Note that react-native-nitro-modules currently keeps a small fixed amount of bookkeeping (on the order of a hundred bytes) per native object it has handed to JS for the lifetime of the JS runtime, so memory will not return exactly to baseline even after collection. If you process large numbers of workouts in a loop you can release the HealthKit side eagerly by calling `dispose()` once you are done with a workout:
+
+```TypeScript
+const workouts = await queryWorkoutSamples({ limit: 0 })
+
+for (const workout of workouts) {
+  const routes = await workout.getWorkoutRoutes()
+  // ... do something with the routes
+  workout.dispose()
+}
+```
+
+After `dispose()` the proxy can no longer be used - calling any function or reading any property on it will throw. If you need to keep the data around, call `toJSON()` first to get a plain object and store that instead of the proxy:
+
+```TypeScript
+const plainWorkouts = workouts.map((workout) => {
+  const json = workout.toJSON()
+  workout.dispose()
+  return json
+})
+```
+
+Other tips for keeping memory in check when working with large datasets:
+- Query in chunks (for example per month, or with `limit` and anchors) instead of fetching everything at once.
+- Prefer statistics queries (`queryStatisticsForQuantity`, `queryStatisticsCollectionForQuantity`) over fetching every sample when you only need aggregates.
+- Keep plain data (from `toJSON()` or the sample queries) in React state rather than proxies.
+- `sourceRevision.source` on samples and `sources` on statistics are plain objects, not proxies. To filter queries by a source, get a `SourceProxy` from `querySources()` and match it by `bundleIdentifier`.
+
 ## Migration to 9.0.0
 
 There are a lot of under-the-hood changes in version 9.0.0, some of them are breaking (although I've tried to reduce it as much as possible).

package/app.plugin.js

@@ -1,94 +1,49 @@
-const {
-  withPlugins,
-  createRunOncePlugin,
-  withEntitlementsPlist,
-  withInfoPlist,
-} = require('@expo/config-plugins')
-
-/**
- * @typedef ConfigPlugin
- * @type {import('@expo/config-plugins').ConfigPlugin<T>}
- * @template T = void
- */
-
-/**
- * @typedef InfoPlistConfig
- * @type {{
- *  NSHealthShareUsageDescription?: string | boolean,
- *  NSHealthUpdateUsageDescription?: string | boolean
- * }}
- */
-
-/**
- * @typedef AppPluginConfig
- * @type {InfoPlistConfig & { background?: boolean }}
- */
-
-/**
- * @type {ConfigPlugin<{background: boolean}>}
- */
-const withEntitlementsPlugin = (
-  config,
-  /**
-   * @type {{background: boolean} | undefined}
-   * */
-  props,
-) =>
-  withEntitlementsPlist(config, (config) => {
-    config.modResults['com.apple.developer.healthkit'] = true
-
-    // background is enabled by default, but possible to opt-out from
-    // (haven't seen any drawbacks from having it enabled)
-    if (props?.background !== false) {
-      config.modResults['com.apple.developer.healthkit.background-delivery'] =
-        true
-    }
-
-    return config
-  })
-
-/**
- * @type {ConfigPlugin<InfoPlistConfig>}
- */
-const withInfoPlistPlugin = (
-  config,
-  /**
-   * @type {{NSHealthShareUsageDescription?: string | true, NSHealthUpdateUsageDescription?: string | false} | undefined}
-   * */
-  props,
-) =>
-  withInfoPlist(config, (config) => {
-    config.modResults.NSHealthShareUsageDescription =
-      typeof props?.NSHealthShareUsageDescription === 'string'
-        ? props.NSHealthShareUsageDescription
-        : typeof config.modResults.NSHealthShareUsageDescription === 'string'
-          ? config.modResults.NSHealthShareUsageDescription
-          : `${config.name} wants to read your health data`
-
-    if (props?.NSHealthUpdateUsageDescription !== false) {
-      config.modResults.NSHealthUpdateUsageDescription =
-        typeof props?.NSHealthUpdateUsageDescription === 'string'
-          ? props.NSHealthUpdateUsageDescription
-          : typeof config.modResults.NSHealthUpdateUsageDescription === 'string'
-            ? config.modResults.NSHealthUpdateUsageDescription
-            : `${config.name} wants to update your health data`
-    }
-
-    return config
-  })
-
-const pkg = require('./package.json')
-
-/**
- * @type {ConfigPlugin<AppPluginConfig>}
- */
-const healthkitAppPlugin = (config, props) =>
-  withPlugins(config, [
-    [withEntitlementsPlugin, props],
-    [withInfoPlistPlugin, props],
-  ])
-
-/**
- * @type {ConfigPlugin<AppPluginConfig>}
- */
-module.exports = createRunOncePlugin(healthkitAppPlugin, pkg.name, pkg.version)
+// GENERATED FILE - do not edit by hand (gitignored).
+// Compiled from app.plugin.ts by `bun run build:plugin`.
+// Expo loads this file, not the .ts source, so edit app.plugin.ts and rebuild.
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("@expo/config-plugins");
+const package_json_1 = __importDefault(require("./package.json"));
+const withEntitlementsPlugin = (config, props) => {
+    return (0, config_plugins_1.withEntitlementsPlist)(config, (configPlist) => {
+        configPlist.modResults['com.apple.developer.healthkit'] = true;
+        // background is enabled by default, but possible to opt-out from
+        // (haven't seen any drawbacks from having it enabled)
+        if (props?.background !== false) {
+            configPlist.modResults['com.apple.developer.healthkit.background-delivery'] = true;
+        }
+        return configPlist;
+    });
+};
+const withInfoPlistPlugin = (config, props) => {
+    return (0, config_plugins_1.withInfoPlist)(config, (configPlist) => {
+        const existingShareDescription = configPlist.modResults.NSHealthShareUsageDescription;
+        configPlist.modResults.NSHealthShareUsageDescription =
+            typeof props?.NSHealthShareUsageDescription === 'string'
+                ? props.NSHealthShareUsageDescription
+                : typeof existingShareDescription === 'string'
+                    ? existingShareDescription
+                    : `${config.name ?? package_json_1.default.name} wants to read your health data`;
+        if (props?.NSHealthUpdateUsageDescription !== false) {
+            const existingUpdateDescription = configPlist.modResults.NSHealthUpdateUsageDescription;
+            configPlist.modResults.NSHealthUpdateUsageDescription =
+                typeof props?.NSHealthUpdateUsageDescription === 'string'
+                    ? props.NSHealthUpdateUsageDescription
+                    : typeof existingUpdateDescription === 'string'
+                        ? existingUpdateDescription
+                        : `${config.name ?? package_json_1.default.name} wants to update your health data`;
+        }
+        return configPlist;
+    });
+};
+const healthkitAppPlugin = (config, props) => {
+    return (0, config_plugins_1.withPlugins)(config, [
+        [withEntitlementsPlugin, props],
+        [withInfoPlistPlugin, props],
+    ]);
+};
+exports.default = (0, config_plugins_1.createRunOncePlugin)(healthkitAppPlugin, package_json_1.default.name, package_json_1.default.version);

package/app.plugin.ts

@@ -1,7 +1,6 @@
 import {
   type ConfigPlugin,
   createRunOncePlugin,
-  withAppDelegate,
   withEntitlementsPlist,
   withInfoPlist,
   withPlugins,
@@ -17,6 +16,12 @@ type InfoPlistConfig = {
 }
 
 type AppPluginConfig = InfoPlistConfig & {
+  /**
+   * Adds the background-delivery entitlement. Enabled by default; set to
+   * `false` to opt out. Launch-time observer registration needs no AppDelegate
+   * change: the pod hooks UIApplicationDidFinishLaunchingNotification itself
+   * (see ios/BackgroundLaunchHook.mm).
+   */
   background?: BackgroundConfig
 }
 
@@ -64,49 +69,10 @@ const withInfoPlistPlugin: ConfigPlugin<InfoPlistConfig> = (config, props) => {
   })
 }
 
-const withAppDelegatePlugin: ConfigPlugin<{
-  background?: BackgroundConfig
-}> = (config, props) => {
-  if (props?.background === false) {
-    return config
-  }
-
-  return withAppDelegate(config, (configDelegate) => {
-    const contents = configDelegate.modResults.contents
-
-    // Add import for HealthKit if not already present
-    if (!contents.includes('import HealthKit')) {
-      configDelegate.modResults.contents =
-        configDelegate.modResults.contents.replace(
-          /^(import .+\n)/m,
-          '$1import HealthKit\n',
-        )
-    }
-
-    // Insert BackgroundDeliveryManager setup into didFinishLaunchingWithOptions
-    const setupCall =
-      '    BackgroundDeliveryManager.shared.setupBackgroundObservers()\n'
-
-    if (
-      !configDelegate.modResults.contents.includes('BackgroundDeliveryManager')
-    ) {
-      // Match the opening of didFinishLaunchingWithOptions and insert after the opening brace
-      configDelegate.modResults.contents =
-        configDelegate.modResults.contents.replace(
-          /(func application\(.+didFinishLaunchingWithOptions.+\{)\n/,
-          `$1\n${setupCall}`,
-        )
-    }
-
-    return configDelegate
-  })
-}
-
 const healthkitAppPlugin: ConfigPlugin<AppPluginConfig> = (config, props) => {
   return withPlugins(config, [
     [withEntitlementsPlugin, props],
     [withInfoPlistPlugin, props],
-    [withAppDelegatePlugin, props],
   ])
 }
 

package/ios/BackgroundDeliveryManager.swift

@@ -1,18 +1,23 @@
 import Foundation
 import HealthKit
+import os.log
+
+private let bgLog = OSLog(subsystem: "com.kingstinct.healthkit", category: "BackgroundDelivery")
 
 /// Manages HealthKit background delivery by registering observer queries at app launch,
 /// before the JS bridge is available. This is required by Apple — observer queries must
 /// be set up in `application(_:didFinishLaunchingWithOptions:)` to receive background
 /// delivery callbacks after the app has been terminated.
 ///
-/// Usage from AppDelegate.swift:
-///   BackgroundDeliveryManager.shared.setupBackgroundObservers()
+/// `BackgroundLaunchHook.mm` calls `setupBackgroundObservers()` on
+/// UIApplicationDidFinishLaunchingNotification, so no AppDelegate change is needed.
+/// The `@objc(BackgroundDeliveryManager)` name is what that hook looks up at runtime.
 ///
 /// The types to observe are persisted in UserDefaults by `configureBackgroundTypes()`
 /// called from JS. On subsequent cold launches, the manager reads these and registers
 /// observers immediately, queuing any events until JS subscribes via `drainPendingEvents()`.
-@objc public class BackgroundDeliveryManager: NSObject {
+@objc(BackgroundDeliveryManager)
+public class BackgroundDeliveryManager: NSObject {
   @objc public static let shared = BackgroundDeliveryManager()
 
   private let healthStore = HKHealthStore()
@@ -20,6 +25,11 @@ import HealthKit
   private var observerQueries: [String: HKObserverQuery] = [:]
   private var pendingEvents: [(typeIdentifier: String, errorMessage: String?)] = []
   private var jsCallback: ((String, String?) -> Void)?
+  // Per-type callbacks, checked before the global `jsCallback` above. Lets
+  // CoreModule.subscribeToObserverQuery route a JS subscription for a
+  // background-configured type through this manager's already-running
+  // HKObserverQuery instead of registering a second, independent one.
+  private var typeCallbacks: [String: (String, String?) -> Void] = [:]
   private var isSetUp = false
 
   static let typesKey = "com.kingstinct.healthkit.backgroundTypes"
@@ -29,18 +39,23 @@ import HealthKit
     super.init()
   }
 
-  /// Call this from AppDelegate.didFinishLaunchingWithOptions to register observer queries
-  /// for any previously configured background delivery types.
+  /// Registers observer queries for any previously configured background delivery
+  /// types. Called at launch by `BackgroundLaunchHook.mm`; safe to call again.
   @objc public func setupBackgroundObservers() {
     guard HKHealthStore.isHealthDataAvailable() else { return }
 
     guard let typeIdentifiers = UserDefaults.standard.stringArray(forKey: BackgroundDeliveryManager.typesKey) else {
+      os_log("launch: no background delivery types configured, nothing to register", log: bgLog, type: .debug)
       return
     }
 
     let frequencyRaw = UserDefaults.standard.integer(forKey: BackgroundDeliveryManager.frequencyKey)
     let frequency = HKUpdateFrequency(rawValue: frequencyRaw) ?? .immediate
 
+    os_log(
+      "launch: registering %d background observer(s): %{public}@", log: bgLog, type: .info,
+      typeIdentifiers.count, typeIdentifiers.joined(separator: ", "))
+
     registerObservers(typeIdentifiers: typeIdentifiers, frequency: frequency)
   }
 
@@ -85,6 +100,37 @@ import HealthKit
     }
   }
 
+  /// Subscribe a JS callback for a specific type. Any events for this type
+  /// that arrived before JS subscribed (e.g. from a background wake, queued
+  /// in `pendingEvents` above) are flushed immediately.
+  func setCallback(typeIdentifier: String, callback: @escaping (String, String?) -> Void) {
+    queue.sync(flags: .barrier) {
+      self.typeCallbacks[typeIdentifier] = callback
+      let matching = self.pendingEvents.filter { $0.typeIdentifier == typeIdentifier }
+      self.pendingEvents.removeAll { $0.typeIdentifier == typeIdentifier }
+      for event in matching {
+        callback(typeIdentifier, event.errorMessage)
+      }
+    }
+  }
+
+  /// Remove the per-type JS callback (e.g., on unsubscribe).
+  func removeCallback(typeIdentifier: String) {
+    queue.sync(flags: .barrier) {
+      self.typeCallbacks.removeValue(forKey: typeIdentifier)
+    }
+  }
+
+  /// True if `typeIdentifier` has a native HKObserverQuery registered by
+  /// `registerObservers` — i.e. background delivery is configured for it.
+  /// CoreModule.subscribeToObserverQuery checks this before deciding whether
+  /// to reuse this manager's observer or register its own.
+  func isBackgroundConfigured(typeIdentifier: String) -> Bool {
+    return queue.sync {
+      self.observerQueries[typeIdentifier] != nil
+    }
+  }
+
   /// Stop all observer queries and clear state.
   func tearDown() {
     queue.sync(flags: .barrier) {
@@ -92,6 +138,7 @@ import HealthKit
         self.healthStore.stop(query)
       }
       self.observerQueries = [:]
+      self.typeCallbacks = [:]
       self.isSetUp = false
     }
   }
@@ -121,6 +168,11 @@ import HealthKit
         sampleType: sampleType,
         predicate: nil
       ) { [weak self] (_: HKObserverQuery, completionHandler: @escaping HKObserverQueryCompletionHandler, error: Error?) in
+        // handleObserverCallback opens a beginBackgroundTask() window as its
+        // first, synchronous action, before this returns to call
+        // completionHandler() — otherwise iOS is free to suspend the process
+        // the moment HealthKit's own completion handler fires, possibly
+        // before Hermes has finished booting to run the JS callback.
         self?.handleObserverCallback(
           typeIdentifier: typeIdentifier,
           error: error
@@ -147,18 +199,54 @@ import HealthKit
 
   private func handleObserverCallback(typeIdentifier: String, error: Error?) {
     let errorMessage = error?.localizedDescription
+    os_log("observer fired: %{public}@", log: bgLog, type: .info, typeIdentifier)
+
+    // Ask iOS for real execution time before doing anything else, so the
+    // process survives long enough for Hermes to boot and the JS callback to
+    // run — see the comment at this query's registration above.
+    var backgroundTaskId = UIBackgroundTaskIdentifier.invalid
+    let endTask: () -> Void = { [weak self] in
+      self?.queue.sync(flags: .barrier) {
+        guard backgroundTaskId != .invalid else { return }
+        UIApplication.shared.endBackgroundTask(backgroundTaskId)
+        backgroundTaskId = .invalid
+      }
+    }
+    backgroundTaskId = UIApplication.shared.beginBackgroundTask(withName: "healthkit-observer-\(typeIdentifier)") {
+      os_log("background task expired: %{public}@", log: bgLog, type: .info, typeIdentifier)
+      endTask()
+    }
+    os_log("background task started: %{public}@", log: bgLog, type: .info, typeIdentifier)
 
     queue.sync(flags: .barrier) {
-      if let callback = self.jsCallback {
+      if let callback = self.typeCallbacks[typeIdentifier] {
+        DispatchQueue.main.async {
+          os_log("dispatching to per-type JS callback: %{public}@", log: bgLog, type: .info, typeIdentifier)
+          callback(typeIdentifier, errorMessage)
+        }
+      } else if let callback = self.jsCallback {
         // JS is connected — dispatch to main thread for JSI safety
         DispatchQueue.main.async {
+          os_log("dispatching to global JS callback: %{public}@", log: bgLog, type: .info, typeIdentifier)
           callback(typeIdentifier, errorMessage)
         }
       } else {
         // JS not ready yet — queue the event for later
+        os_log("no JS callback yet, queuing: %{public}@", log: bgLog, type: .info, typeIdentifier)
         self.pendingEvents.append((typeIdentifier: typeIdentifier, errorMessage: errorMessage))
       }
     }
+
+    // Hold the task open for a fixed, generous window rather than trying to
+    // ack precisely when JS finishes — Hermes boot plus the JS callback's own
+    // async work (HealthKit reads + Supabase upsert) is unpredictable, and a
+    // completion-ack channel back from JS isn't worth building on the first
+    // pass for a personal-use app. First place to revisit if verification
+    // shows this window is too tight.
+    DispatchQueue.main.asyncAfter(deadline: .now() + 25) {
+      os_log("background task window elapsed: %{public}@", log: bgLog, type: .info, typeIdentifier)
+      endTask()
+    }
   }
 
   // Local type resolution that doesn't depend on NitroModules (which isn't available at AppDelegate time).
@@ -169,7 +257,7 @@ import HealthKit
       return HKSampleType.quantityType(forIdentifier: typeId)
     }
     if identifier.starts(with: "HKCategoryTypeIdentifier") {
-      let typeId = HKCategoryTypeIdentifier(rawValue: identifier)
+      let typeId = hkCategoryTypeIdentifier(fromIdentifierName: identifier)
       return HKSampleType.categoryType(forIdentifier: typeId)
     }
     if identifier == "HKWorkoutTypeIdentifier" {

package/ios/BackgroundLaunchHook.mm

@@ -0,0 +1,41 @@
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+/// Registers the launch-time observer setup without any AppDelegate changes.
+///
+/// `+load` runs when the binary is loaded, before `main`. It subscribes to
+/// UIApplicationDidFinishLaunchingNotification, which UIKit posts synchronously
+/// right after `application(_:didFinishLaunchingWithOptions:)` returns and
+/// before the run loop continues, so observer queries are still registered
+/// during launch as HealthKit background delivery requires. The manager is
+/// looked up by name at runtime: importing this pod's Swift module from the
+/// app's AppDelegate would drag NitroModules' C++ headers into a target
+/// compiled without C++ interop and fail to build.
+@interface BackgroundLaunchHook : NSObject
+@end
+
+@implementation BackgroundLaunchHook
+
++ (void)load {
+  [[NSNotificationCenter defaultCenter]
+      addObserverForName:UIApplicationDidFinishLaunchingNotification
+                  object:nil
+                   queue:nil
+              usingBlock:^(NSNotification *_Nonnull note) {
+                Class managerClass = NSClassFromString(@"BackgroundDeliveryManager");
+                SEL sharedSelector = NSSelectorFromString(@"shared");
+                SEL setupSelector = NSSelectorFromString(@"setupBackgroundObservers");
+                if (managerClass == nil || ![managerClass respondsToSelector:sharedSelector]) {
+                  return;
+                }
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Warc-performSelector-leaks"
+                id shared = [managerClass performSelector:sharedSelector];
+                if ([shared respondsToSelector:setupSelector]) {
+                  [shared performSelector:setupSelector];
+                }
+#pragma clang diagnostic pop
+              }];
+}
+
+@end

package/ios/Constants.swift

@@ -34,3 +34,27 @@ let SpeedUnit =  HKUnit(from: "m/s") // HKUnit.meter().unitDivided(by: HKUnit.se
 let METUnit = HKUnit(from: "kcal/hr·kg")
 
 let DEFAULT_QUERY_LIMIT = 20
+
+/// Apple renamed `HKCategoryTypeIdentifierAudioExposureEvent` to
+/// `HKCategoryTypeIdentifierEnvironmentalAudioExposureEvent` in iOS 14, but the new
+/// constant still carries the old raw string at runtime. Building the identifier from the
+/// modern name as a raw string therefore makes `categoryType(forIdentifier:)` return nil,
+/// and samples read back from HealthKit report the legacy name. These helpers translate
+/// in both directions so JS only ever sees the modern identifier.
+let HKCategoryTypeIdentifierEnvironmentalAudioExposureEvent_NAME =
+  "HKCategoryTypeIdentifierEnvironmentalAudioExposureEvent"
+let HKCategoryTypeIdentifierAudioExposureEvent_NAME = "HKCategoryTypeIdentifierAudioExposureEvent"
+
+func hkCategoryTypeIdentifier(fromIdentifierName name: String) -> HKCategoryTypeIdentifier {
+  if name == HKCategoryTypeIdentifierEnvironmentalAudioExposureEvent_NAME {
+    return .environmentalAudioExposureEvent
+  }
+  return HKCategoryTypeIdentifier(rawValue: name)
+}
+
+func categoryTypeIdentifierName(fromHealthKitIdentifier identifier: String) -> String {
+  if identifier == HKCategoryTypeIdentifierAudioExposureEvent_NAME {
+    return HKCategoryTypeIdentifierEnvironmentalAudioExposureEvent_NAME
+  }
+  return identifier
+}

package/ios/CoreModule.swift

@@ -157,21 +157,27 @@ class CoreModule: HybridCoreModuleSpec {
             returning: .unnecessary
           )
         }
-        return store.getRequestStatusForAuthorization(toShare: toShare, read: toRead) {
-          status, error in
-          DispatchQueue.main.async {
-            if let error = error {
-              continuation.resume(throwing: error)
-            } else {
-              if let authStatus = AuthorizationRequestStatus(rawValue: Int32(status.rawValue)) {
-                continuation.resume(returning: authStatus)
+        var caughtError: NSError?
+        let started = RunBlockCatchingObjCExceptions({
+          store.getRequestStatusForAuthorization(toShare: toShare, read: toRead) {
+            status, error in
+            DispatchQueue.main.async {
+              if let error = error {
+                continuation.resume(throwing: error)
               } else {
-                continuation.resume(
-                  throwing: runtimeErrorWithPrefix(
-                    "Unrecognized authStatus returned: \(status.rawValue)"))
+                if let authStatus = AuthorizationRequestStatus(rawValue: Int32(status.rawValue)) {
+                  continuation.resume(returning: authStatus)
+                } else {
+                  continuation.resume(
+                    throwing: runtimeErrorWithPrefix(
+                      "Unrecognized authStatus returned: \(status.rawValue)"))
+                }
               }
             }
           }
+        }, &caughtError)
+        if !started, let caughtError {
+          continuation.resume(throwing: caughtError)
         }
       }
     }
@@ -183,14 +189,20 @@ class CoreModule: HybridCoreModuleSpec {
       let toRead = objectTypesFromArray(typeIdentifiers: toRequest.toRead ?? [])
 
       return try await withCheckedThrowingContinuation { continuation in
-        store.requestAuthorization(toShare: share, read: toRead) { status, error in
-          DispatchQueue.main.async {
-            if let error = error {
-              continuation.resume(throwing: error)
-            } else {
-              continuation.resume(returning: status)
+        var caughtError: NSError?
+        let started = RunBlockCatchingObjCExceptions({
+          store.requestAuthorization(toShare: share, read: toRead) { status, error in
+            DispatchQueue.main.async {
+              if let error = error {
+                continuation.resume(throwing: error)
+              } else {
+                continuation.resume(returning: status)
+              }
             }
           }
+        }, &caughtError)
+        if !started, let caughtError {
+          continuation.resume(throwing: caughtError)
         }
       }
     }
@@ -308,7 +320,11 @@ class CoreModule: HybridCoreModuleSpec {
   }
 
   func isProtectedDataAvailableAsync() -> Promise<Bool> {
-    return Promise.resolved(withResult: UIApplication.shared.isProtectedDataAvailable)
+    return Promise.async {
+      return await MainActor.run {
+        UIApplication.shared.isProtectedDataAvailable
+      }
+    }
   }
 
   func isHealthDataAvailable() -> Bool {
@@ -349,6 +365,10 @@ class CoreModule: HybridCoreModuleSpec {
   }
 
   var _runningQueries: [String: HKQuery] = [:]
+  // queryId -> typeIdentifier for subscriptions routed through
+  // BackgroundDeliveryManager instead of getting their own HKObserverQuery
+  // (see subscribeToObserverQuery below).
+  var _backgroundRoutedQueries: [String: String] = [:]
 
   func deleteObjects(objectTypeIdentifier: SampleTypeIdentifierWriteable, filter: FilterForSamples)
     -> Promise<Double> {
@@ -377,6 +397,25 @@ class CoreModule: HybridCoreModuleSpec {
     typeIdentifier: SampleTypeIdentifier,
     callback: @escaping (OnChangeCallbackArgs) -> Void
   ) throws -> String {
+    let typeIdString = typeIdentifier.stringValue
+
+    if BackgroundDeliveryManager.shared.isBackgroundConfigured(typeIdentifier: typeIdString) {
+      // BackgroundDeliveryManager already has an HKObserverQuery running for
+      // this type (registered at launch, survives termination) — route
+      // through it instead of registering a second, independent observer for
+      // the same type.
+      let queryId = UUID().uuidString
+      BackgroundDeliveryManager.shared.setCallback(typeIdentifier: typeIdString) {
+        (_, errorMessage) in
+        DispatchQueue.main.async {
+          callback(
+            OnChangeCallbackArgs(typeIdentifier: typeIdentifier, errorMessage: errorMessage))
+        }
+      }
+      self._backgroundRoutedQueries[queryId] = typeIdString
+      return queryId
+    }
+
     let sampleType = try sampleTypeFrom(sampleTypeIdentifier: typeIdentifier)
 
     let predicate = HKQuery.predicateForSamples(
@@ -411,6 +450,13 @@ class CoreModule: HybridCoreModuleSpec {
   }
 
   func unsubscribeQuery(queryId: String) throws -> Bool {
+    if let typeIdString = self._backgroundRoutedQueries[queryId] {
+      BackgroundDeliveryManager.shared.removeCallback(typeIdentifier: typeIdString)
+      self._backgroundRoutedQueries.removeValue(forKey: queryId)
+
+      return true
+    }
+
     guard let query = self._runningQueries[queryId] else {
       warnWithPrefix("unsubscribeQuery: Query with id \(queryId) not found")
 

package/ios/ExceptionCatcher.h

@@ -2,3 +2,4 @@
 #import <HealthKit/HealthKit.h>
 
 HKUnit * _Nullable HKUnitFromStringCatchingExceptions(NSString * _Nonnull unitString, NSError * _Nullable * _Nullable outError);
+BOOL RunBlockCatchingObjCExceptions(void (NS_NOESCAPE ^_Nonnull block)(void), NSError * _Nullable * _Nullable outError);