@symbiote-native/location 0.1.0

package/src/core/location.ts

@@ -0,0 +1,313 @@
+import { createPermissionHook, Platform } from 'expo-modules-core';
+import { expoLocation } from './native-module';
+import {
+  headingSubscriber,
+  locationErrorSubscriber,
+  locationSubscriber,
+  motionActivitySubscriber,
+} from './subscribers';
+import { LocationAccuracy } from './types';
+import type {
+  ILocationCallback,
+  ILocationErrorCallback,
+  ILocationGeocodedAddress,
+  ILocationGeocodedLocation,
+  ILocationHeadingCallback,
+  ILocationHeadingObject,
+  ILocationLastKnownOptions,
+  ILocationObject,
+  ILocationOptions,
+  ILocationPermissionResponse,
+  ILocationProviderStatus,
+  ILocationRegion,
+  ILocationSubscription,
+  ILocationTaskOptions,
+  IMotionActivityCallback,
+  IMotionActivityObject,
+  PermissionResponse,
+} from './types';
+
+export async function getProviderStatusAsync(): Promise<ILocationProviderStatus> {
+  return expoLocation.getProviderStatusAsync();
+}
+
+/** @platform android */
+export async function enableNetworkProviderAsync(): Promise<void> {
+  if (Platform.OS === 'android') {
+    return expoLocation.enableNetworkProviderAsync();
+  }
+}
+
+export async function getCurrentPositionAsync(
+  options: ILocationOptions = {},
+): Promise<ILocationObject> {
+  return expoLocation.getCurrentPositionAsync(options);
+}
+
+export async function getLastKnownPositionAsync(
+  options: ILocationLastKnownOptions = {},
+): Promise<ILocationObject | null> {
+  return expoLocation.getLastKnownPositionAsync(options);
+}
+
+export async function watchPositionAsync(
+  options: ILocationOptions,
+  callback: ILocationCallback,
+  errorHandler?: ILocationErrorCallback,
+): Promise<ILocationSubscription> {
+  const watchId = locationSubscriber.registerCallback(callback);
+  if (errorHandler)
+    locationErrorSubscriber.registerCallbackForId(watchId, errorHandler);
+
+  await expoLocation.watchPositionImplAsync(watchId, options);
+
+  return {
+    remove() {
+      locationSubscriber.unregisterCallback(watchId);
+      if (errorHandler) locationErrorSubscriber.unregisterCallback(watchId);
+    },
+  };
+}
+
+export async function watchHeadingAsync(
+  callback: ILocationHeadingCallback,
+  errorHandler?: ILocationErrorCallback,
+): Promise<ILocationSubscription> {
+  const watchId = headingSubscriber.registerCallback(callback);
+  if (errorHandler)
+    locationErrorSubscriber.registerCallbackForId(watchId, errorHandler);
+
+  await expoLocation.watchDeviceHeading(watchId);
+
+  return {
+    remove() {
+      headingSubscriber.unregisterCallback(watchId);
+      if (errorHandler) locationErrorSubscriber.unregisterCallback(watchId);
+    },
+  };
+}
+
+/** Waits for a couple of heading updates and returns the first accurate-enough one. */
+export async function getHeadingAsync(): Promise<ILocationHeadingObject> {
+  return new Promise((resolve, reject) => {
+    let tries = 0;
+    let subscriber: ILocationSubscription | undefined;
+
+    watchHeadingAsync(
+      heading => {
+        if (heading.accuracy > 1 || tries > 5) {
+          subscriber?.remove();
+          resolve(heading);
+        } else {
+          tries += 1;
+        }
+      },
+      reason => {
+        subscriber?.remove();
+        reject(new Error(reason));
+      },
+    )
+      .then(sub => {
+        subscriber = sub;
+      })
+      .catch(reject);
+  });
+}
+
+export async function geocodeAsync(
+  address: string,
+): Promise<ILocationGeocodedLocation[]> {
+  if (typeof address !== 'string') {
+    throw new TypeError(
+      `Address to geocode must be a string. Got ${address} instead.`,
+    );
+  }
+  return expoLocation.geocodeAsync(address);
+}
+
+export async function reverseGeocodeAsync(
+  location: Pick<ILocationGeocodedLocation, 'latitude' | 'longitude'>,
+): Promise<ILocationGeocodedAddress[]> {
+  if (
+    typeof location.latitude !== 'number' ||
+    typeof location.longitude !== 'number'
+  ) {
+    throw new TypeError(
+      'Location to reverse-geocode must be an object with number properties `latitude` and `longitude`.',
+    );
+  }
+  return expoLocation.reverseGeocodeAsync(location);
+}
+
+export async function getForegroundPermissionsAsync(): Promise<ILocationPermissionResponse> {
+  return expoLocation.getForegroundPermissionsAsync();
+}
+
+export async function requestForegroundPermissionsAsync(): Promise<ILocationPermissionResponse> {
+  return expoLocation.requestForegroundPermissionsAsync();
+}
+
+export const useForegroundPermissions = createPermissionHook({
+  getMethod: getForegroundPermissionsAsync,
+  requestMethod: requestForegroundPermissionsAsync,
+});
+
+export async function getBackgroundPermissionsAsync(): Promise<PermissionResponse> {
+  return expoLocation.getBackgroundPermissionsAsync();
+}
+
+export async function requestBackgroundPermissionsAsync(): Promise<PermissionResponse> {
+  return expoLocation.requestBackgroundPermissionsAsync();
+}
+
+export const useBackgroundPermissions = createPermissionHook({
+  getMethod: getBackgroundPermissionsAsync,
+  requestMethod: requestBackgroundPermissionsAsync,
+});
+
+export async function hasServicesEnabledAsync(): Promise<boolean> {
+  return expoLocation.hasServicesEnabledAsync();
+}
+
+export async function getMotionActivityPermissionsAsync(): Promise<PermissionResponse> {
+  return expoLocation.getMotionActivityPermissionsAsync();
+}
+
+export async function requestMotionActivityPermissionsAsync(): Promise<PermissionResponse> {
+  return expoLocation.requestMotionActivityPermissionsAsync();
+}
+
+export const useMotionActivityPermissions = createPermissionHook({
+  getMethod: getMotionActivityPermissionsAsync,
+  requestMethod: requestMotionActivityPermissionsAsync,
+});
+
+/** No location permission required — uses Play Services activity recognition / the iOS motion
+ *  coprocessor directly. */
+export async function getMotionActivityAsync(): Promise<IMotionActivityObject> {
+  return new Promise((resolve, reject) => {
+    let subscriber: ILocationSubscription | undefined;
+    watchMotionActivityAsync(
+      activity => {
+        subscriber?.remove();
+        resolve(activity);
+      },
+      reason => {
+        subscriber?.remove();
+        reject(new Error(reason));
+      },
+    )
+      .then(sub => {
+        subscriber = sub;
+      })
+      .catch(reject);
+  });
+}
+
+/** Foreground-only — updates pause while the app is backgrounded. */
+export async function watchMotionActivityAsync(
+  callback: IMotionActivityCallback,
+  errorHandler?: ILocationErrorCallback,
+): Promise<ILocationSubscription> {
+  const watchId = motionActivitySubscriber.registerCallback(callback);
+  if (errorHandler)
+    locationErrorSubscriber.registerCallbackForId(watchId, errorHandler);
+
+  await expoLocation.watchMotionActivityImplAsync(watchId);
+
+  return {
+    remove() {
+      motionActivitySubscriber.unregisterCallback(watchId);
+      // forgetCallback, not unregisterCallback: the native watch was already torn down above by
+      // motionActivitySubscriber; re-issuing removeWatchAsync for the same id would hit this
+      // native module's location-permission guard and throw for a motion-activity-only caller.
+      if (errorHandler) locationErrorSubscriber.forgetCallback(watchId);
+    },
+  };
+}
+
+function assertValidTaskName(taskName: unknown): asserts taskName is string {
+  if (!taskName || typeof taskName !== 'string') {
+    throw new Error(
+      `\`taskName\` must be a non-empty string. Got ${taskName} instead.`,
+    );
+  }
+}
+
+function assertValidRegions(regions: ILocationRegion[]): void {
+  if (!regions || regions.length === 0) {
+    throw new Error(
+      'Regions array cannot be empty. Use `stopGeofencingAsync` if you want to stop geofencing all regions',
+    );
+  }
+  for (const region of regions) {
+    if (typeof region.latitude !== 'number') {
+      throw new TypeError(
+        `Region's latitude must be a number. Got '${region.latitude}' instead.`,
+      );
+    }
+    if (typeof region.longitude !== 'number') {
+      throw new TypeError(
+        `Region's longitude must be a number. Got '${region.longitude}' instead.`,
+      );
+    }
+    if (typeof region.radius !== 'number') {
+      throw new TypeError(
+        `Region's radius must be a number. Got '${region.radius}' instead.`,
+      );
+    }
+  }
+}
+
+export async function isBackgroundLocationAvailableAsync(): Promise<boolean> {
+  const providerStatus = await getProviderStatusAsync();
+  return providerStatus.backgroundModeEnabled;
+}
+
+/** Register a task (defined with `@symbiote-native/task-manager`'s `defineTask`) to keep
+ *  receiving location updates while the app is backgrounded. */
+export async function startLocationUpdatesAsync(
+  taskName: string,
+  options: ILocationTaskOptions = { accuracy: LocationAccuracy.Balanced },
+): Promise<void> {
+  assertValidTaskName(taskName);
+  await expoLocation.startLocationUpdatesAsync(taskName, options);
+}
+
+export async function stopLocationUpdatesAsync(
+  taskName: string,
+): Promise<void> {
+  assertValidTaskName(taskName);
+  await expoLocation.stopLocationUpdatesAsync(taskName);
+}
+
+export async function hasStartedLocationUpdatesAsync(
+  taskName: string,
+): Promise<boolean> {
+  assertValidTaskName(taskName);
+  return expoLocation.hasStartedLocationUpdatesAsync(taskName);
+}
+
+/** Register a task (defined with `@symbiote-native/task-manager`'s `defineTask`) to receive
+ *  enter/exit events for the given regions, including while the app is backgrounded. Calling
+ *  this again with a new region array replaces the regions already being watched. */
+export async function startGeofencingAsync(
+  taskName: string,
+  regions: ILocationRegion[] = [],
+): Promise<void> {
+  assertValidTaskName(taskName);
+  assertValidRegions(regions);
+  await expoLocation.startGeofencingAsync(taskName, { regions });
+}
+
+export async function stopGeofencingAsync(taskName: string): Promise<void> {
+  assertValidTaskName(taskName);
+  await expoLocation.stopGeofencingAsync(taskName);
+}
+
+export async function hasStartedGeofencingAsync(
+  taskName: string,
+): Promise<boolean> {
+  assertValidTaskName(taskName);
+  return expoLocation.hasStartedGeofencingAsync(taskName);
+}

package/src/core/native-module.ts

@@ -0,0 +1,62 @@
+import { requireNativeModule, type EventSubscription } from 'expo-modules-core';
+import type {
+  ILocationGeocodedAddress,
+  ILocationGeocodedLocation,
+  ILocationLastKnownOptions,
+  ILocationObject,
+  ILocationOptions,
+  ILocationPermissionResponse,
+  ILocationProviderStatus,
+  ILocationRegion,
+  ILocationTaskOptions,
+  PermissionResponse,
+} from './types';
+
+const EXPO_LOCATION_MODULE_NAME = 'ExpoLocation';
+
+export type INativeLocationModule = {
+  addListener(
+    eventName: string,
+    listener: (event: unknown) => void,
+  ): EventSubscription;
+  getProviderStatusAsync(): Promise<ILocationProviderStatus>;
+  enableNetworkProviderAsync(): Promise<void>;
+  getCurrentPositionAsync(options: ILocationOptions): Promise<ILocationObject>;
+  getLastKnownPositionAsync(
+    options: ILocationLastKnownOptions,
+  ): Promise<ILocationObject | null>;
+  watchPositionImplAsync(
+    watchId: number,
+    options: ILocationOptions,
+  ): Promise<void>;
+  watchDeviceHeading(watchId: number): Promise<void>;
+  removeWatchAsync(watchId: number): Promise<void>;
+  geocodeAsync(address: string): Promise<ILocationGeocodedLocation[]>;
+  reverseGeocodeAsync(
+    location: Pick<ILocationGeocodedLocation, 'latitude' | 'longitude'>,
+  ): Promise<ILocationGeocodedAddress[]>;
+  getForegroundPermissionsAsync(): Promise<ILocationPermissionResponse>;
+  requestForegroundPermissionsAsync(): Promise<ILocationPermissionResponse>;
+  getBackgroundPermissionsAsync(): Promise<PermissionResponse>;
+  requestBackgroundPermissionsAsync(): Promise<PermissionResponse>;
+  hasServicesEnabledAsync(): Promise<boolean>;
+  getMotionActivityPermissionsAsync(): Promise<PermissionResponse>;
+  requestMotionActivityPermissionsAsync(): Promise<PermissionResponse>;
+  watchMotionActivityImplAsync(watchId: number): Promise<void>;
+  startLocationUpdatesAsync(
+    taskName: string,
+    options: ILocationTaskOptions,
+  ): Promise<void>;
+  stopLocationUpdatesAsync(taskName: string): Promise<void>;
+  hasStartedLocationUpdatesAsync(taskName: string): Promise<boolean>;
+  startGeofencingAsync(
+    taskName: string,
+    options: { regions: ILocationRegion[] },
+  ): Promise<void>;
+  stopGeofencingAsync(taskName: string): Promise<void>;
+  hasStartedGeofencingAsync(taskName: string): Promise<boolean>;
+};
+
+export const expoLocation = requireNativeModule<INativeLocationModule>(
+  EXPO_LOCATION_MODULE_NAME,
+);

package/src/core/subscribers.ts

@@ -0,0 +1,101 @@
+import type { EventSubscription } from 'expo-modules-core';
+import { expoLocation } from './native-module';
+import type {
+  ILocationCallback,
+  ILocationErrorCallback,
+  ILocationHeadingCallback,
+  IMotionActivityCallback,
+} from './types';
+
+type IEventObject = { watchId: number; [key: string]: unknown };
+
+let nextWatchId = 0;
+
+class Subscriber<
+  TCallback extends
+    | ILocationCallback
+    | ILocationHeadingCallback
+    | ILocationErrorCallback
+    | IMotionActivityCallback,
+> {
+  private callbacks: Record<number, TCallback> = {};
+  private eventSubscription: EventSubscription | null = null;
+
+  constructor(
+    private eventName: string,
+    private eventDataField: string,
+  ) {}
+
+  private maybeInitializeSubscription(): void {
+    if (this.eventSubscription) return;
+    this.eventSubscription = expoLocation.addListener(
+      this.eventName,
+      (event: unknown) => this.trigger(event as IEventObject),
+    );
+  }
+
+  registerCallback(callback: TCallback): number {
+    this.maybeInitializeSubscription();
+    const id = ++nextWatchId;
+    this.callbacks[id] = callback;
+    return id;
+  }
+
+  registerCallbackForId(watchId: number, callback: TCallback): number {
+    this.maybeInitializeSubscription();
+    this.callbacks[watchId] = callback;
+    return watchId;
+  }
+
+  unregisterCallback(id: number): void {
+    if (!this.callbacks[id]) return;
+    delete this.callbacks[id];
+    void expoLocation.removeWatchAsync(id);
+    this.releaseSubscriptionIfIdle();
+  }
+
+  /** Drops the local callback without calling native removeWatchAsync — used when another
+   *  subscriber already tore down the same watchId natively. */
+  forgetCallback(id: number): void {
+    if (!this.callbacks[id]) return;
+    delete this.callbacks[id];
+    this.releaseSubscriptionIfIdle();
+  }
+
+  private releaseSubscriptionIfIdle(): void {
+    if (Object.keys(this.callbacks).length === 0 && this.eventSubscription) {
+      this.eventSubscription.remove();
+      this.eventSubscription = null;
+    }
+  }
+
+  private trigger(event: IEventObject): void {
+    const callback = this.callbacks[event.watchId];
+    if (callback) {
+      (callback as (arg: unknown) => unknown)(event[this.eventDataField]);
+    } else {
+      void expoLocation.removeWatchAsync(event.watchId);
+    }
+  }
+}
+
+export const locationSubscriber = new Subscriber<ILocationCallback>(
+  'Expo.locationChanged',
+  'location',
+);
+export const headingSubscriber = new Subscriber<ILocationHeadingCallback>(
+  'Expo.headingChanged',
+  'heading',
+);
+export const locationErrorSubscriber = new Subscriber<ILocationErrorCallback>(
+  'Expo.locationError',
+  'reason',
+);
+export const motionActivitySubscriber = new Subscriber<IMotionActivityCallback>(
+  'Expo.motionActivityChanged',
+  'activity',
+);
+
+export function getCurrentWatchId(): number {
+  return nextWatchId;
+}

package/src/core/types.ts

@@ -0,0 +1,191 @@
+import type { PermissionResponse } from 'expo-modules-core';
+
+export enum LocationAccuracy {
+  Lowest = 1,
+  Low = 2,
+  Balanced = 3,
+  High = 4,
+  Highest = 5,
+  BestForNavigation = 6,
+}
+
+export enum LocationActivityType {
+  Other = 1,
+  AutomotiveNavigation = 2,
+  Fitness = 3,
+  OtherNavigation = 4,
+  /** @platform ios */
+  Airborne = 5,
+}
+
+export enum LocationGeofencingEventType {
+  Enter = 1,
+  Exit = 2,
+}
+
+export enum LocationGeofencingRegionState {
+  Unknown = 0,
+  Inside = 1,
+  Outside = 2,
+}
+
+export type ILocationOptions = {
+  accuracy?: LocationAccuracy;
+  /** @platform android */
+  mayShowUserSettingsDialog?: boolean;
+  /** @platform android */
+  timeInterval?: number;
+  distanceInterval?: number;
+};
+
+export type ILocationLastKnownOptions = {
+  maxAge?: number;
+  requiredAccuracy?: number;
+};
+
+export type ILocationTaskServiceOptions = {
+  notificationTitle: string;
+  notificationBody: string;
+  notificationColor?: string;
+  killServiceOnDestroy?: boolean;
+};
+
+export type ILocationTaskOptions = ILocationOptions & {
+  /** @platform ios */
+  showsBackgroundLocationIndicator?: boolean;
+  deferredUpdatesDistance?: number;
+  deferredUpdatesTimeout?: number;
+  deferredUpdatesInterval?: number;
+  /** @platform ios */
+  activityType?: LocationActivityType;
+  /** @platform ios */
+  pausesUpdatesAutomatically?: boolean;
+  foregroundService?: ILocationTaskServiceOptions;
+};
+
+export type ILocationRegion = {
+  identifier?: string;
+  latitude: number;
+  longitude: number;
+  radius: number;
+  /** @default true */
+  notifyOnEnter?: boolean;
+  /** @default true */
+  notifyOnExit?: boolean;
+  state?: LocationGeofencingRegionState;
+};
+
+export type ILocationObjectCoords = {
+  latitude: number;
+  longitude: number;
+  altitude: number | null;
+  accuracy: number | null;
+  altitudeAccuracy: number | null;
+  heading: number | null;
+  speed: number | null;
+};
+
+export type ILocationObject = {
+  coords: ILocationObjectCoords;
+  timestamp: number;
+  /** @platform android */
+  mocked?: boolean;
+};
+
+export type ILocationCallback = (location: ILocationObject) => unknown;
+export type ILocationErrorCallback = (reason: string) => void;
+
+export type ILocationProviderStatus = {
+  locationServicesEnabled: boolean;
+  backgroundModeEnabled: boolean;
+  /** @platform android */
+  gpsAvailable?: boolean;
+  /** @platform android */
+  networkAvailable?: boolean;
+  /** @platform android */
+  passiveAvailable?: boolean;
+};
+
+export type ILocationHeadingObject = {
+  trueHeading: number;
+  magHeading: number;
+  /** 0 none, 1 low, 2 medium, 3 high */
+  accuracy: number;
+};
+
+export type ILocationHeadingCallback = (
+  heading: ILocationHeadingObject,
+) => unknown;
+
+export type ILocationGeocodedLocation = {
+  latitude: number;
+  longitude: number;
+  altitude?: number;
+  accuracy?: number;
+};
+
+export type ILocationGeocodedAddress = {
+  city: string | null;
+  district: string | null;
+  streetNumber: string | null;
+  street: string | null;
+  region: string | null;
+  subregion: string | null;
+  country: string | null;
+  postalCode: string | null;
+  name: string | null;
+  isoCountryCode: string | null;
+  /** @platform ios */
+  timezone: string | null;
+  /** @platform android */
+  formattedAddress: string | null;
+};
+
+export type ILocationSubscription = {
+  remove: () => void;
+};
+
+export type IPermissionDetailsLocationIOS = {
+  scope: 'whenInUse' | 'always' | 'none';
+  accuracy: 'full' | 'reduced';
+};
+
+export type IPermissionDetailsLocationAndroid = {
+  accuracy: 'fine' | 'coarse' | 'none';
+};
+
+export type ILocationPermissionResponse = PermissionResponse & {
+  ios?: IPermissionDetailsLocationIOS;
+  android?: IPermissionDetailsLocationAndroid;
+};
+
+export type { PermissionResponse };
+
+export enum MotionActivityConfidence {
+  Low = 0,
+  Medium = 1,
+  High = 2,
+}
+
+export enum MotionActivityType {
+  Automotive = 'automotive',
+  Cycling = 'cycling',
+  Running = 'running',
+  Walking = 'walking',
+  Stationary = 'stationary',
+  Unknown = 'unknown',
+}
+
+export type IMotionActivityState = {
+  detected: boolean;
+  confidence: MotionActivityConfidence;
+};
+
+export type IMotionActivityObject = {
+  activities: Record<MotionActivityType, IMotionActivityState>;
+  timestamp: number;
+};
+
+export type IMotionActivityCallback = (
+  activity: IMotionActivityObject,
+) => unknown;