@kingstinct/react-native-healthkit 7.0.4 → 7.0.6

package/lib/typescript/src/types.d.ts

@@ -1,13 +1,27 @@
 import type { EnergyUnit, HKCategorySampleRaw, HKCategoryTypeIdentifier, HKCorrelationRaw, HKCorrelationTypeIdentifier, HKDevice, HKHeartbeatSeriesSampleRaw, HKQuantityTypeIdentifier, HKSourceRevision, HKUnit, HKWorkoutRaw, LengthUnit, MetadataMapperForQuantityIdentifier, QueryStatisticsResponseRaw, UnitForIdentifier } from './native-types';
 export * from './native-types';
+/**
+ * Options for querying workouts.
+ * @template TEnergy The energy unit type.
+ * @template TDistance The distance unit type.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkworkout Apple Docs HKWorkout}
+ */
 export interface QueryWorkoutsOptions<TEnergy extends HKUnit, TDistance extends HKUnit> extends GenericQueryOptions {
     readonly energyUnit?: TEnergy;
     readonly distanceUnit?: TDistance;
 }
+/**
+ * Represents a category sample.
+ * @template T The category type identifier.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkcategorysample Apple Docs HKCategorySample}
+ */
 export interface HKCategorySample<T extends HKCategoryTypeIdentifier = HKCategoryTypeIdentifier> extends Omit<HKCategorySampleRaw<T>, 'endDate' | 'startDate'> {
     readonly startDate: Date;
     readonly endDate: Date;
 }
+/**
+ * Generic options for querying.
+ */
 export type GenericQueryOptions = {
     readonly from?: Date;
     readonly to?: Date;
@@ -15,14 +29,30 @@ export type GenericQueryOptions = {
     readonly ascending?: boolean;
     readonly anchor?: string;
 };
+/**
+ * Represents a workout.
+ * @template TEnergy The energy unit type.
+ * @template TDistance The distance unit type.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkworkout Apple Docs HKWorkout}
+ */
 export interface HKWorkout<TEnergy extends EnergyUnit = EnergyUnit, TDistance extends LengthUnit = LengthUnit> extends Omit<HKWorkoutRaw<TEnergy, TDistance>, 'endDate' | 'startDate'> {
     readonly startDate: Date;
     readonly endDate: Date;
 }
+/**
+ * Represents a heartbeat series sample.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkheartbeatseriessample Apple Docs HKHeartbeatSeriesSample}
+ */
 export interface HKHeartbeatSeriesSample extends Omit<HKHeartbeatSeriesSampleRaw, 'endDate' | 'startDate'> {
     readonly startDate: Date;
     readonly endDate: Date;
 }
+/**
+ * Represents a quantity sample.
+ * @template TIdentifier The quantity type identifier.
+ * @template TUnit The unit for the identifier.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkquantitysample Apple Docs HKQuantitySample}
+ */
 export interface HKQuantitySample<TIdentifier extends HKQuantityTypeIdentifier = HKQuantityTypeIdentifier, TUnit extends UnitForIdentifier<TIdentifier> = UnitForIdentifier<TIdentifier>> {
     readonly uuid: string;
     readonly device?: HKDevice;
@@ -34,14 +64,33 @@ export interface HKQuantitySample<TIdentifier extends HKQuantityTypeIdentifier =
     readonly startDate: Date;
     readonly endDate: Date;
 }
+/**
+ * Represents a response from a statistics query.
+ * @template TIdentifier The quantity type identifier.
+ * @template TUnit The unit for the identifier.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkstatisticsquery Apple Docs HKStatisticsQuery}
+ */
 export interface QueryStatisticsResponse<TIdentifier extends HKQuantityTypeIdentifier, TUnit extends UnitForIdentifier<TIdentifier> = UnitForIdentifier<TIdentifier>> extends Omit<QueryStatisticsResponseRaw<TIdentifier, TUnit>, 'mostRecentQuantityDateInterval'> {
     readonly mostRecentQuantityDateInterval?: {
         readonly from: Date;
         readonly to: Date;
     };
 }
+/**
+ * Represents a category sample for saving.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkcategorysample Apple Docs HKCategorySample}
+ */
 export type HKCategorySampleForSaving = Omit<HKCategorySample, 'device' | 'endDate' | 'startDate' | 'uuid'>;
+/**
+ * Represents a quantity sample for saving.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkquantitysample Apple Docs HKQuantitySample}
+ */
 export type HKQuantitySampleForSaving = Omit<HKQuantitySample, 'device' | 'endDate' | 'startDate' | 'uuid'>;
+/**
+ * Represents a correlation.
+ * @template TIdentifier The correlation type identifier.
+ * @see {@link https://developer.apple.com/documentation/healthkit/hkcorrelation Apple Docs HKCorrelation}
+ */
 export interface HKCorrelation<TIdentifier extends HKCorrelationTypeIdentifier> extends Omit<HKCorrelationRaw<TIdentifier>, 'endDate' | 'objects' | 'startDate'> {
     readonly objects: readonly (HKCategorySample | HKQuantitySample)[];
     readonly startDate: Date;

package/lib/typescript/src/utils/getMostRecentCategorySample.d.ts

@@ -1,3 +1,4 @@
 import type { HKCategoryTypeIdentifier } from '../native-types';
-declare function getMostRecentCategorySample<T extends HKCategoryTypeIdentifier>(identifier: T): Promise<import("..").HKCategorySample<T> | null>;
+import type { HKCategorySample } from '../types';
+declare function getMostRecentCategorySample<T extends HKCategoryTypeIdentifier>(identifier: T): Promise<HKCategorySample<T> | null>;
 export default getMostRecentCategorySample;

package/lib/typescript/src/utils/getMostRecentQuantitySample.d.ts

@@ -1,3 +1,4 @@
 import type { HKQuantityTypeIdentifier, UnitForIdentifier } from '../native-types';
-declare function getMostRecentQuantitySample<TIdentifier extends HKQuantityTypeIdentifier, TUnit extends UnitForIdentifier<TIdentifier>>(identifier: TIdentifier, unit: TUnit): Promise<import("..").HKQuantitySample<TIdentifier, UnitForIdentifier<TIdentifier>> | null>;
+import type { HKQuantitySample } from '../types';
+declare function getMostRecentQuantitySample<TIdentifier extends HKQuantityTypeIdentifier, TUnit extends UnitForIdentifier<TIdentifier>>(identifier: TIdentifier, unit: TUnit): Promise<HKQuantitySample<TIdentifier, TUnit> | null>;
 export default getMostRecentQuantitySample;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kingstinct/react-native-healthkit",
-  "version": "7.0.4",
+  "version": "7.0.6",
   "description": "React Native bindings for HealthKit",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",

package/src/hooks/useIsHealthDataAvailable.ts

@@ -2,6 +2,11 @@ import { useEffect, useState } from 'react'
 
 import Native from '../native-types'
 
+/**
+ * @description By default, HealthKit data is available on iOS and watchOS. HealthKit data is also available on iPadOS 17 or later. However, devices running in an enterprise environment may restrict access to HealthKit data.
+* @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614180-ishealthdataavailable Apple HealthKit isHealthDataAvailable}
+* @returns {boolean | null} true if HealthKit is available; otherwise, false. null while initializing.
+*/
 const useIsHealthDataAvailable = () => {
   const [isAvailable, setIsAvailable] = useState<boolean | null>(null)
 

package/src/index.ios.tsx

@@ -1,10 +1,12 @@
+import { Platform } from 'react-native'
+
 import useHealthkitAuthorization from './hooks/useHealthkitAuthorization'
 import useIsHealthDataAvailable from './hooks/useIsHealthDataAvailable'
 import useMostRecentCategorySample from './hooks/useMostRecentCategorySample'
 import useMostRecentQuantitySample from './hooks/useMostRecentQuantitySample'
 import useMostRecentWorkout from './hooks/useMostRecentWorkout'
 import useSubscribeToChanges from './hooks/useSubscribeToChanges'
-import Native from './native-types'
+import Native, { HKQuantityTypeIdentifier } from './native-types'
 import deleteQuantitySample from './utils/deleteQuantitySample'
 import deleteSamples from './utils/deleteSamples'
 import getDateOfBirth from './utils/getDateOfBirth'
@@ -31,31 +33,123 @@ import saveQuantitySample from './utils/saveQuantitySample'
 import saveWorkoutSample from './utils/saveWorkoutSample'
 import subscribeToChanges from './utils/subscribeToChanges'
 
-const Healthkit = {
-  authorizationStatusFor: Native.authorizationStatusFor.bind(Native),
+const currentMajorVersionIOS = Platform.OS === 'ios' ? parseInt(Platform.Version, 10) : 0
 
-  isHealthDataAvailable: Native.isHealthDataAvailable.bind(Native),
-  canAccessProtectedData: Native.canAccessProtectedData.bind(Native),
+const allQuantityTypesList = [...Object.values(HKQuantityTypeIdentifier)]
 
-  disableAllBackgroundDelivery:
-    Native.disableAllBackgroundDelivery.bind(Native),
-  disableBackgroundDelivery: Native.disableBackgroundDelivery.bind(Native),
-  enableBackgroundDelivery: Native.enableBackgroundDelivery.bind(Native),
+const availableQuantityTypes = (majorVersionIOS = currentMajorVersionIOS) => {
+  if (majorVersionIOS >= 17) {
+    return allQuantityTypesList
+  }
 
-  // simple convenience getters
-  getBiologicalSex: Native.getBiologicalSex.bind(Native),
-  getFitzpatrickSkinType: Native.getFitzpatrickSkinType.bind(Native),
-  getWheelchairUse: Native.getWheelchairUse.bind(Native),
-  getBloodType: Native.getBloodType.bind(Native),
+  // remove types that are not available before iOS 17
+  return allQuantityTypesList.filter((type) => ![
+    HKQuantityTypeIdentifier.cyclingCadence,
+    HKQuantityTypeIdentifier.cyclingFunctionalThresholdPower,
+    HKQuantityTypeIdentifier.cyclingPower,
+    HKQuantityTypeIdentifier.cyclingSpeed,
+    HKQuantityTypeIdentifier.physicalEffort,
+    HKQuantityTypeIdentifier.timeInDaylight,
+  ].includes(type))
+}
 
-  getWorkoutRoutes: Native.getWorkoutRoutes.bind(Native),
+const authorizationStatusFor = Native.authorizationStatusFor.bind(Native)
+const isHealthDataAvailable = Native.isHealthDataAvailable.bind(Native)
+// Todo [>8]: Rename to align with Apple function name (isProtectedDataAvailable)
+const canAccessProtectedData = Native.canAccessProtectedData.bind(Native)
+const disableBackgroundDelivery = Native.disableBackgroundDelivery.bind(Native)
+const disableAllBackgroundDelivery = Native.disableAllBackgroundDelivery.bind(Native)
+const enableBackgroundDelivery = Native.enableBackgroundDelivery.bind(Native)
+const getBiologicalSex = Native.getBiologicalSex.bind(Native)
+const getFitzpatrickSkinType = Native.getFitzpatrickSkinType.bind(Native)
+const getWheelchairUse = Native.getWheelchairUse.bind(Native)
+const getBloodType = Native.getBloodType.bind(Native)
+const getWorkoutRoutes = Native.getWorkoutRoutes.bind(Native)
+
+/**
+ * @see {@link https://developer.apple.com/documentation/healthkit/about_the_healthkit_framework About the HealthKit Framework (Apple Docs)}
+ */
+export default {
+  /**
+  * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614154-authorizationstatus authorizationStatus(for:) (Apple Docs) }
+  * @see {@link https://developer.apple.com/documentation/healthkit/authorizing_access_to_health_data Authorizing access to health data (Apple Docs) }
+  */
+  authorizationStatusFor,
+
+  /**
+   *
+   * @returns All available quantity types for the current iOS version (currently excluding types that are not available before iOS 17)
+   */
+  availableQuantityTypes,
+
+  /**
+    * @description By default, HealthKit data is available on iOS and watchOS. HealthKit data is also available on iPadOS 17 or later. However, devices running in an enterprise environment may restrict access to HealthKit data.
+    * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614180-ishealthdataavailable isHealthDataAvailable() (Apple Docs)}
+    * @returns {boolean} true if HealthKit is available; otherwise, false.
+    */
+  isHealthDataAvailable,
+
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614181-isprotecteddataavailable isProtectedDataAvailable() (Apple Docs)}
+   * @see {@link https://developer.apple.com/documentation/healthkit/protecting_user_privacy#3705074 Protecting User Privacy - Access encrypted data (Apple Docs)}
+   * @returns {boolean} A Boolean value that indicates whether content protection is active.
+   */
+  isProtectedDataAvailable: canAccessProtectedData,
+
+  // Todo [>8]: Remove to align with Apple function name (isProtectedDataAvailable)
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614181-isprotecteddataavailable isProtectedDataAvailable() (Apple Docs)}
+   * @see {@link https://developer.apple.com/documentation/healthkit/protecting_user_privacy#3705074 Protecting User Privacy - Access encrypted data (Apple Docs)}
+   * @deprecated Use {@link isProtectedDataAvailable} instead. Will be removed in next major version.
+   * @returns {boolean} A Boolean value that indicates whether content protection is active.
+   */
+  canAccessProtectedData,
+
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614158-disableallbackgrounddelivery disableAllBackgroundDelivery(completion:) (Apple Docs)}
+   */
+  disableAllBackgroundDelivery,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614177-disablebackgrounddelivery disableBackgroundDelivery(for:withCompletion:) (Apple Docs)}
+   */
+  disableBackgroundDelivery,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614175-enablebackgrounddelivery enableBackgroundDelivery(for:frequency:withCompletion:) (Apple Docs)}
+   */
+  enableBackgroundDelivery,
 
+  // simple convenience getters
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614171-biologicalsex biologicalSex() (Apple Docs)}
+   */
+  getBiologicalSex,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614161-fitzpatrickskintype fitzpatrickSkinType() (Apple Docs)}
+   */
+  getFitzpatrickSkinType,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1648356-wheelchairuse wheelchairUse() (Apple Docs)}
+   */
+  getWheelchairUse,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614164-bloodtype bloodType() (Apple Docs)}
+   */
+  getBloodType,
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1648357-dateofbirthcomponents dateOfBirthComponents() (Apple Docs)}
+   */
   getDateOfBirth,
 
   getMostRecentQuantitySample,
   getMostRecentCategorySample,
   getMostRecentWorkout,
 
+  /**
+  * @see {@link https://developer.apple.com/documentation/healthkit/workouts_and_activity_rings/reading_route_data Reading route data (Apple Docs)}
+  * @see {@link https://developer.apple.com/documentation/healthkit/hkworkoutroutequery HKWorkoutRouteQuery (Apple Docs)}
+   */
+  getWorkoutRoutes,
+
   getPreferredUnit,
   getPreferredUnits,
   getRequestStatusForAuthorization,
@@ -79,6 +173,10 @@ const Healthkit = {
   deleteSamples,
 
   // save methods
+  /**
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614168-savecategorysample save(_:withCompletion:) (Apple Docs)}
+   * @see {@link https://developer.apple.com/documentation/healthkit/saving_data_to_healthkit Saving data to HealthKit (Apple Docs)}
+   */
   saveCategorySample,
   saveCorrelationSample,
   saveQuantitySample,
@@ -87,18 +185,31 @@ const Healthkit = {
   // subscriptions
   subscribeToChanges,
 
-  // hooks
+  /**
+   * @returns the most recent sample for the given category type.
+   */
   useMostRecentCategorySample,
-
+  /**
+   * @returns the most recent sample for the given quantity type.
+   */
   useMostRecentQuantitySample,
+  /**
+   * @returns the most recent workout sample.
+   */
   useMostRecentWorkout,
-
   useSubscribeToChanges,
-
+  /**
+     * @description By default, HealthKit data is available on iOS and watchOS. HealthKit data is also available on iPadOS 17 or later. However, devices running in an enterprise environment may restrict access to HealthKit data.
+    * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614180-ishealthdataavailable Apple Docs}
+    * @returns {boolean | null} true if HealthKit is available; otherwise, false. null while initializing.
+    */
   useIsHealthDataAvailable,
+  /**
+   * @description Hook to retrieve the current authorization status for the given types, and request authorization if needed.
+   * @see {@link https://developer.apple.com/documentation/healthkit/hkhealthstore/1614152-requestauthorization Apple Docs - requestAuthorization}
+   * @see {@link https://developer.apple.com/documentation/healthkit/authorizing_access_to_health_data Apple Docs - Authorizing access to health data}
+   */
   useHealthkitAuthorization,
 }
 
 export * from './types'
-
-export default Healthkit

package/src/index.tsx

@@ -1,7 +1,7 @@
 import { Platform } from 'react-native'
 
 import {
-  HKAuthorizationRequestStatus, HKAuthorizationStatus, HKBiologicalSex, HKBloodType, HKFitzpatrickSkinType, HKUnits, HKWheelchairUse, QueryQuantitySamplesResponseRaw,
+  HKAuthorizationRequestStatus, HKAuthorizationStatus, HKBiologicalSex, HKBloodType, HKFitzpatrickSkinType, HKUnits, HKWheelchairUse,
 } from './native-types'
 
 import type ReactNativeHealthkit from './index.ios'
@@ -25,8 +25,9 @@ function UnavailableFn<T = unknown>(retVal: T) {
   }
 }
 
-const Healthkit: typeof ReactNativeHealthkit = {
+const Healthkit = {
   authorizationStatusFor: UnavailableFn(Promise.resolve(HKAuthorizationStatus.notDetermined)),
+  availableQuantityTypes: UnavailableFn([]),
   disableAllBackgroundDelivery: UnavailableFn(Promise.resolve(false)),
   disableBackgroundDelivery: UnavailableFn(Promise.resolve(false)),
   enableBackgroundDelivery: UnavailableFn(Promise.resolve(false)),
@@ -88,8 +89,9 @@ const Healthkit: typeof ReactNativeHealthkit = {
   useHealthkitAuthorization: UnavailableFn([null, async () => Promise.resolve(HKAuthorizationRequestStatus.unknown)] as const),
   useIsHealthDataAvailable: () => false,
   canAccessProtectedData: async () => Promise.resolve(false),
-}
+  isProtectedDataAvailable: async () => Promise.resolve(false),
+} as typeof ReactNativeHealthkit
 
 export * from './types'
 
-export default Healthkit
+export default Healthkit as typeof ReactNativeHealthkit

package/src/jest.setup.ts

@@ -37,6 +37,7 @@ const mockModule: (NativeModule & typeof Native) = {
   saveWorkoutSample: jest.fn(),
   subscribeToObserverQuery: jest.fn(),
   unsubscribeQuery: jest.fn(),
+  // Todo [>8]: Remove to align with Apple function name (isProtectedDataAvailable)
   canAccessProtectedData: jest.fn(),
 }