react-native-healthkit

Since version 6.0, you can use HealthKit anchors to efficiently sync data and identify deleted items. An anchor is a base64-encoded string returned by HealthKit that contains sync information.

When performing a query, store the newAnchor returned in the result. For the next sync, pass this anchor into your query to only receive changes since the last sync.

• newAnchor: The anchor to use for the next query.
• samples: The array of retrieved samples.
• deletedSamples: The array of samples that were deleted.
• limit: An option to restrict the number of records considered (set to 0 for no limit).

// Initial query
const { newAnchor, samples, deletedSamples } = await queryQuantitySamplesWithAnchor('HKQuantityTypeIdentifierStepCount', {
  limit: 2,
});

// Subsequent query using the anchor
const nextResult = await queryQuantitySamplesWithAnchor('HKQuantityTypeIdentifierStepCount', {
  limit: 2,
  anchor: newAnchor,
});

The Interface Verification Utility is a TypeScript-only tool designed to ensure that a base interface (typically used for a native bridge, like one extending HybridObject) and a typed interface (used for better type safety with generics) remain in sync. It catches mismatches in method names and parameter counts at compile-time with zero runtime cost.

How it works

• Method name verification: Ensures both interfaces contain the same methods.
• Parameter count verification: Ensures corresponding methods have the same number of arguments.
• Compile-time checking: Errors are surfaced by TypeScript during development.

Quick Start Example

To verify your interfaces, define your base and typed versions, then use InterfaceAssertion to perform the check:

import type { InterfaceAssertion } from "../types/InterfaceVerification";

// 1. Base interface (e.g., for the native bridge)
export interface MyModule extends HybridObject<{ ios: "swift" }> {
	getData(id: string): Promise<string>;
	saveData(id: string, data: string): Promise<boolean>;
}

// 2. Typed interface (with generics for better DX)
export interface MyModuleTyped {
	getData<T extends string>(id: T): Promise<string>;
	saveData<T extends string>(id: T, data: string): Promise<boolean>;
}

// 3. Verification - will cause a TypeScript error if interfaces don't match
// Note: Always exclude inherited keys like `keyof HybridObject`
const _verification: InterfaceAssertion<MyModule, MyModuleTyped, keyof HybridObject> = true;

For non-hook usage, use the imperative API. Always check availability and request permissions first.

Check Availability

await isHealthDataAvailable()

Read Data

await getMostRecentQuantitySample(identifier) returns an object containing { quantity, unit, startDate, endDate }.

Subscribe to Changes

subscribeToChanges(identifier, callback) allows you to react to data updates. Remember to unsubscribe in the cleanup function of your effect.

Write Data

saveQuantitySample(identifier, unit, value, options) allows saving new samples. Metadata keys can be arbitrary strings or built-in HealthKit keys (use the string representation of the key, e.g., HKInsulinDeliveryReason instead of a variable).

import {
  isHealthDataAvailable,
  requestAuthorization,
  subscribeToChanges,
  saveQuantitySample,
  getMostRecentQuantitySample
} from '@kingstinct/react-native-healthkit';

// 1. Check availability
const isAvailable = await isHealthDataAvailable();

// 2. Request Read Permission
await requestAuthorization({ toRead: ['HKQuantityTypeIdentifierBodyFatPercentage'] });

// 3. Read latest sample
const { quantity, unit, startDate, endDate } = await getMostRecentQuantitySample('HKQuantityTypeIdentifierBodyFatPercentage');

// 4. Subscribe to changes
const unsubscribe = subscribeToChanges('HKQuantityTypeIdentifierHeartRate', () => {
  // refetch data
});

// 5. Write data
await requestAuthorization({ toShare: ['HKQuantityTypeIdentifierInsulinDelivery'] });
await saveQuantitySample(
  'HKQuantityTypeIdentifierInsulinDelivery',
  'IU',
  5.5,
  {
    metadata: {
      HKInsulinDeliveryReason: HKInsulinDeliveryReason.basal,
    },
  }
);

Depending on the specific query method being used, you can use specialized versions of GenericQueryOptions to add functionality:

• Sorting: Use QueryOptionsWithSortOrder to add an ascending?: boolean flag.
• Pagination/Anchors: Use QueryOptionsWithAnchor to add an anchor?: string for cursor-based fetching.
• Units: Use QueryOptionsWithSortOrderAndUnit or QueryOptionsWithAnchorAndUnit to specify a unit?: TUnit (e.g., for converting measurements during the query).

export interface QueryOptionsWithAnchor extends GenericQueryOptions {
  readonly anchor?: string
}

export interface QueryOptionsWithSortOrder extends GenericQueryOptions {
  readonly ascending?: boolean
}

export interface QueryOptionsWithSortOrderAndUnit<TUnit extends string = string>
  extends QueryOptionsWithSortOrder {
  readonly unit?: TUnit
}

export interface QueryOptionsWithAnchorAndUnit<TUnit extends string = string>
  extends QueryOptionsWithAnchor {
  readonly unit?: TUnit
}