@kingstinct/react-native-healthkit 14.1.0 → 16.0.0

package/README.md

@@ -23,6 +23,8 @@ This library is provided as-is without any warranty and is not affiliated with A
 
 ## Installation
 
+[`@react-native-healthkit/core`](packages/core) holds the code shared with [`@react-native-healthkit/health-records`](packages/health-records): types, config plugin building blocks and the `ReactNativeHealthkitCore` pod. It is a regular dependency pinned to an exact version, so your package manager installs the matching copy for you and there is no version to keep in sync. In a bare React Native app you additionally need it in your own `package.json`, because the React Native CLI only autolinks packages listed there.
+
 ### Expo
 Usage with Expo is possible - just keep in mind it will not work in Expo Go and [you'll need to roll your own Dev Client](https://docs.expo.dev/development/getting-started/). 
 
@@ -52,7 +54,9 @@ this will give you defaults that make the app build without any further configur
 3. Build a new Dev Client
 
 ### Native or Expo Bare Workflow
-1. `yarn add @kingstinct/react-native-healthkit react-native-nitro-modules`
+1. `yarn add @kingstinct/react-native-healthkit @react-native-healthkit/core react-native-nitro-modules`
+
+   `@react-native-healthkit/core` is installed automatically as a dependency, but the React Native CLI only autolinks packages listed in your own `package.json`, so name it explicitly here.
 2. `npx pod-install`
 3. Set `NSHealthUpdateUsageDescription` and `NSHealthShareUsageDescription` in your `Info.plist` 
 4. Enable the HealthKit capability for the project in Xcode.
@@ -121,13 +125,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 +158,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/ReactNativeHealthkit.podspec

@@ -16,20 +16,15 @@ Pod::Spec.new do |s|
   s.source_files = [
     # Implementation (Swift)
     "ios/**/*.{swift}",
-    # Autolinking/Registration (Objective-C++)
-    "ios/**/*.{m,mm}",
-    # Implementation (C++ objects)
+        # Implementation (C++ objects)
     "cpp/**/*.{hpp,cpp}",
   ]
 
-  s.public_header_files = "ios/**/*.h"
-
   s.pod_target_xcconfig = {
     # C++ compiler flags, mainly for folly.
     "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) FOLLY_NO_CONFIG FOLLY_CFG_NO_COROUTINES",
     # Allow importing Objective-C headers in Swift without bridging header
-    "CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES" => "YES",
-    "SWIFT_INCLUDE_PATHS" => "$(inherited) $(PODS_TARGET_SRCROOT)/ios"
+    "CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES" => "YES"
   }
 
   load 'nitrogen/generated/ios/ReactNativeHealthkit+autolinking.rb'
@@ -45,6 +40,15 @@ Pod::Spec.new do |s|
     :execution_position => :before_compile,
   }
 
+  # The three packages are released in lockstep on a single version (changesets
+  # `fixed`), so the only combination this pod is ever built and tested against
+  # is a core of the exact same version. Requiring that here turns a mismatch --
+  # including a mixed-version family, e.g. this pod at 16.0.0 next to its
+  # sibling at 16.1.0 -- into a `pod install` version conflict naming both pods,
+  # instead of a Swift compile error inside Pods or a runtime surprise. Core's
+  # Swift surface is internal to these packages and is not semver-managed, so a
+  # same-major requirement would not be enough.
+  s.dependency 'ReactNativeHealthkitCore', s.version.to_s
   s.dependency 'React-jsi'
   s.dependency 'React-callinvoker'
   install_modules_dependencies(s)

package/app.plugin.js

@@ -1,94 +1,33 @@
-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 plugin_1 = require("@react-native-healthkit/core/plugin");
+const package_json_1 = __importDefault(require("./package.json"));
+const healthkitAppPlugin = (config, props) => {
+    const withUpdateUsageDescription = (config) => props?.NSHealthUpdateUsageDescription === false
+        ? config
+        : (0, plugin_1.withUsageDescription)(config, {
+            key: 'NSHealthUpdateUsageDescription',
+            value: props?.NSHealthUpdateUsageDescription,
+            fallback: (appName) => `${appName} wants to update your health data`,
+            fallbackAppName: package_json_1.default.name,
+        });
+    return (0, config_plugins_1.withPlugins)(config, [
+        [
+            plugin_1.withHealthKit,
+            {
+                background: props?.background,
+                NSHealthShareUsageDescription: props?.NSHealthShareUsageDescription,
+                fallbackAppName: package_json_1.default.name,
+            },
+        ],
+        withUpdateUsageDescription,
+    ]);
+};
+exports.default = (0, config_plugins_1.createRunOncePlugin)(healthkitAppPlugin, package_json_1.default.name, package_json_1.default.version);

package/app.plugin.ts

@@ -1,11 +1,12 @@
 import {
   type ConfigPlugin,
   createRunOncePlugin,
-  withAppDelegate,
-  withEntitlementsPlist,
-  withInfoPlist,
   withPlugins,
 } from '@expo/config-plugins'
+import {
+  withHealthKit,
+  withUsageDescription,
+} from '@react-native-healthkit/core/plugin'
 
 import pkg from './package.json'
 
@@ -17,112 +18,36 @@ 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 core pod hooks UIApplicationDidFinishLaunchingNotification
+   * itself.
+   */
   background?: BackgroundConfig
 }
 
-const withEntitlementsPlugin: ConfigPlugin<{
-  background?: BackgroundConfig
-}> = (config, props) => {
-  return 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: ConfigPlugin<InfoPlistConfig> = (config, props) => {
-  return withInfoPlist(config, (configPlist) => {
-    const existingShareDescription =
-      configPlist.modResults.NSHealthShareUsageDescription
-    configPlist.modResults.NSHealthShareUsageDescription =
-      typeof props?.NSHealthShareUsageDescription === 'string'
-        ? props.NSHealthShareUsageDescription
-        : typeof existingShareDescription === 'string'
-          ? existingShareDescription
-          : `${config.name ?? pkg.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 ?? pkg.name} wants to update your health data`
-    }
-
-    return configPlist
-  })
-}
-
-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. `[^{]*` rather than `.+` for two reasons: `.` does not
-      // match newlines, and Expo SDK 54+ templates spread this signature over
-      // several lines; and refusing to cross a `{` keeps the match from
-      // spanning out of an earlier `application(...)` overload into this one.
-      const withSetup = configDelegate.modResults.contents.replace(
-        /(func application\([^{]*didFinishLaunchingWithOptions[^{]*\{)\n/,
-        `$1\n${setupCall}`,
-      )
-
-      if (withSetup === configDelegate.modResults.contents) {
-        // Don't fail the build, but don't fail silently either — background
-        // delivery just won't survive app termination, which is otherwise
-        // very hard to trace back to here.
-        console.warn(
-          '[react-native-healthkit] Could not find didFinishLaunchingWithOptions in AppDelegate; ' +
-            'BackgroundDeliveryManager.shared.setupBackgroundObservers() was not inserted. ' +
-            'HealthKit background delivery will not work until it is added manually.',
-        )
-      }
-
-      configDelegate.modResults.contents = withSetup
-    }
-
-    return configDelegate
-  })
-}
-
 const healthkitAppPlugin: ConfigPlugin<AppPluginConfig> = (config, props) => {
+  const withUpdateUsageDescription: ConfigPlugin = (config) =>
+    props?.NSHealthUpdateUsageDescription === false
+      ? config
+      : withUsageDescription(config, {
+          key: 'NSHealthUpdateUsageDescription',
+          value: props?.NSHealthUpdateUsageDescription,
+          fallback: (appName) => `${appName} wants to update your health data`,
+          fallbackAppName: pkg.name,
+        })
+
   return withPlugins(config, [
-    [withEntitlementsPlugin, props],
-    [withInfoPlistPlugin, props],
-    [withAppDelegatePlugin, props],
+    [
+      withHealthKit,
+      {
+        background: props?.background,
+        NSHealthShareUsageDescription: props?.NSHealthShareUsageDescription,
+        fallbackAppName: pkg.name,
+      },
+    ],
+    withUpdateUsageDescription,
   ])
 }
 

package/ios/CategoryTypeModule.swift

@@ -1,5 +1,6 @@
 import HealthKit
 import NitroModules
+import ReactNativeHealthkitCore
 
 class CategoryTypeModule: HybridCategoryTypeModuleSpec {
     func saveCategorySample(

package/ios/CharacteristicTypeModule.swift

@@ -1,5 +1,6 @@
 import HealthKit
 import NitroModules
+import ReactNativeHealthkitCore
 
 class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
   func getBloodTypeAsync() -> Promise<BloodType> {
@@ -32,10 +33,10 @@ class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
     }
   }
 
-  // Using the global 'store' instance defined in Auth.swift
+  // Uses the healthStore shared through ReactNativeHealthkitCore
 
   func getBiologicalSex() throws -> BiologicalSex {
-    let biologicalSexObject = try store.biologicalSex()
+    let biologicalSexObject = try healthStore.biologicalSex()
     if let biologicalSex = BiologicalSex(
       rawValue: Int32(biologicalSexObject.biologicalSex.rawValue)) {
       return biologicalSex
@@ -46,7 +47,7 @@ class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
 
   func getDateOfBirth() throws -> Date? {
     do {
-      let components = try store.dateOfBirthComponents()
+      let components = try healthStore.dateOfBirthComponents()
       return components.date
     } catch {
       let nsError = error as NSError
@@ -69,7 +70,7 @@ class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
   }
 
   func getBloodType() throws -> BloodType {
-    let bloodTypeObject = try store.bloodType()
+    let bloodTypeObject = try healthStore.bloodType()
 
     if let bloodType = BloodType(rawValue: Int32(bloodTypeObject.bloodType.rawValue)) {
       return bloodType
@@ -80,7 +81,7 @@ class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
   }
 
   func getFitzpatrickSkinType() throws -> FitzpatrickSkinType {
-    let skinTypeObject = try store.fitzpatrickSkinType()
+    let skinTypeObject = try healthStore.fitzpatrickSkinType()
 
     if let skinType = FitzpatrickSkinType(rawValue: Int32(skinTypeObject.skinType.rawValue)) {
       return skinType
@@ -91,7 +92,7 @@ class CharacteristicTypeModule: HybridCharacteristicTypeModuleSpec {
   }
 
   func getWheelchairUse() throws -> WheelchairUse {
-    let wheelchairUseObject = try store.wheelchairUse()
+    let wheelchairUseObject = try healthStore.wheelchairUse()
     if let wheelChairUse = WheelchairUse(
       rawValue: Int32(wheelchairUseObject.wheelchairUse.rawValue)) {
       return wheelChairUse

package/ios/Constants.swift

@@ -7,6 +7,15 @@
 
 import Foundation
 import HealthKit
+import ReactNativeHealthkitCore
+
+let logPrefix = "[react-native-healthkit]"
+
+/// Namespaces this package's persisted background-delivery types in the shared
+/// BackgroundDeliveryManager. The id matches the UserDefaults keys used before
+/// the manager moved to ReactNativeHealthkitCore, so existing installs keep
+/// their configuration.
+let backgroundDeliveryScope = BackgroundDeliveryScope(id: "com.kingstinct.healthkit")
 
 let INIT_ERROR = "HEALTHKIT_INIT_ERROR"
 let INIT_ERROR_MESSAGE = "HealthKit not initialized"
@@ -14,17 +23,7 @@ let TYPE_IDENTIFIER_ERROR = "HEALTHKIT_TYPE_IDENTIFIER_NOT_RECOGNIZED_ERROR"
 let QUERY_ERROR = "HEALTHKIT_QUERY_ERROR"
 let GENERIC_ERROR = "HEALTHKIT_ERROR"
 
-let HKCharacteristicTypeIdentifier_PREFIX = "HKCharacteristicTypeIdentifier"
-let HKQuantityTypeIdentifier_PREFIX = "HKQuantityTypeIdentifier"
-let HKCategoryTypeIdentifier_PREFIX = "HKCategoryTypeIdentifier"
-let HKCorrelationTypeIdentifier_PREFIX = "HKCorrelationTypeIdentifier"
 let HKActivitySummaryTypeIdentifier = "HKActivitySummaryTypeIdentifier"
-let HKAudiogramTypeIdentifier = "HKAudiogramSampleType"
-let HKWorkoutTypeIdentifier = "HKWorkoutTypeIdentifier"
-let HKWorkoutRouteTypeIdentifier = "HKWorkoutRouteTypeIdentifier"
-let HKDataTypeIdentifierHeartbeatSeries = "HKDataTypeIdentifierHeartbeatSeries"
-let HKStateOfMindTypeIdentifier = "HKStateOfMindTypeIdentifier"
-let HKElectrocardiogramType = "HKElectrocardiogramType"
 
 let HKWorkoutActivityTypePropertyName = "activityType"
 let HKWorkoutSessionLocationTypePropertyName = "locationType"