react-native-nitro-geolocation 0.1.2 → 0.2.0

package/src/utils/config.ts

@@ -0,0 +1,93 @@
+/**
+ * Represents a location request with its configuration options.
+ */
+export interface LocationRequest {
+  /** Whether high accuracy mode is enabled */
+  enableHighAccuracy: boolean;
+  /** Minimum distance change (in meters) for updates */
+  distanceFilter: number;
+}
+
+/**
+ * Accuracy level for location services.
+ * - 'high': GPS-level accuracy (~5-10 meters)
+ * - 'medium': Network-assisted accuracy (~100 meters)
+ * - 'low': Cell tower accuracy (~1000+ meters)
+ */
+export type AccuracyLevel = "high" | "medium" | "low";
+
+/**
+ * Merged configuration representing the optimal settings
+ * for multiple concurrent location requests.
+ */
+export interface MergedConfiguration {
+  /** The best (highest) accuracy level among all requests */
+  bestAccuracy: AccuracyLevel;
+  /** The smallest (most sensitive) distance filter among all requests */
+  smallestDistanceFilter: number;
+}
+
+/**
+ * Merges multiple location request configurations to determine
+ * the optimal settings that satisfy all requests.
+ *
+ * This is important for battery optimization - when multiple watches
+ * or getCurrentPosition calls are active simultaneously, we should use
+ * the most demanding settings to satisfy all requests with a single
+ * location subscription.
+ *
+ * Strategy:
+ * - Use the highest accuracy level requested by any client
+ * - Use the smallest distance filter to ensure all clients get updates
+ *
+ * @param requests - Array of location requests to merge
+ * @returns Merged configuration with optimal settings
+ *
+ * @example
+ * ```ts
+ * const requests = [
+ *   { enableHighAccuracy: false, distanceFilter: 100 },
+ *   { enableHighAccuracy: true, distanceFilter: 10 },
+ *   { enableHighAccuracy: false, distanceFilter: 50 }
+ * ];
+ *
+ * const merged = mergeConfigurations(requests);
+ * // Result: { bestAccuracy: 'high', smallestDistanceFilter: 10 }
+ * ```
+ */
+export function mergeConfigurations(
+  requests: LocationRequest[]
+): MergedConfiguration {
+  // If no requests, return default low-power settings
+  if (requests.length === 0) {
+    return {
+      bestAccuracy: "low",
+      smallestDistanceFilter: 0
+    };
+  }
+
+  let bestAccuracy: AccuracyLevel = "low";
+  let smallestDistanceFilter = Number.POSITIVE_INFINITY;
+
+  // Iterate through all requests to find the most demanding settings
+  for (const request of requests) {
+    // If any request needs high accuracy, use high accuracy
+    if (request.enableHighAccuracy) {
+      bestAccuracy = "high";
+    }
+
+    // Use the smallest distance filter
+    smallestDistanceFilter = Math.min(
+      smallestDistanceFilter,
+      request.distanceFilter
+    );
+  }
+
+  return {
+    bestAccuracy,
+    smallestDistanceFilter:
+      smallestDistanceFilter === Number.POSITIVE_INFINITY
+        ? 0
+        : smallestDistanceFilter
+  };
+}

package/src/utils/errors.ts

@@ -0,0 +1,82 @@
+/**
+ * Error codes for geolocation errors.
+ * These codes match the W3C Geolocation API specification.
+ */
+export enum LocationErrorCode {
+  /** User denied the request for Geolocation */
+  PERMISSION_DENIED = 1,
+  /** Location provider is unavailable */
+  POSITION_UNAVAILABLE = 2,
+  /** The request to get location timed out */
+  TIMEOUT = 3
+}
+
+/**
+ * Geolocation error object.
+ */
+export interface LocationError extends Error {
+  code: LocationErrorCode;
+  message: string;
+  PERMISSION_DENIED: LocationErrorCode.PERMISSION_DENIED;
+  POSITION_UNAVAILABLE: LocationErrorCode.POSITION_UNAVAILABLE;
+  TIMEOUT: LocationErrorCode.TIMEOUT;
+}
+
+/**
+ * Creates a standardized LocationError object.
+ *
+ * @param code - The error code from LocationErrorCode enum
+ * @param message - A human-readable error message
+ * @returns A LocationError object
+ *
+ * @example
+ * ```ts
+ * const error = createLocationError(
+ *   LocationErrorCode.PERMISSION_DENIED,
+ *   'User denied location permission'
+ * );
+ * ```
+ */
+export function createLocationError(
+  code: LocationErrorCode,
+  message: string
+): LocationError {
+  const error = new Error(message) as LocationError;
+  error.code = code;
+  error.PERMISSION_DENIED = LocationErrorCode.PERMISSION_DENIED;
+  error.POSITION_UNAVAILABLE = LocationErrorCode.POSITION_UNAVAILABLE;
+  error.TIMEOUT = LocationErrorCode.TIMEOUT;
+  return error;
+}
+
+/**
+ * Maps iOS CLError codes to LocationErrorCode.
+ *
+ * @param clErrorCode - The iOS CLError code
+ * @returns The corresponding LocationErrorCode
+ *
+ * @see https://developer.apple.com/documentation/corelocation/clerror/code
+ */
+export function mapCLErrorCode(clErrorCode: number): LocationErrorCode {
+  switch (clErrorCode) {
+    case 0: // kCLErrorDenied
+      return LocationErrorCode.PERMISSION_DENIED;
+    case 1: // kCLErrorLocationUnknown
+      return LocationErrorCode.POSITION_UNAVAILABLE;
+    default:
+      return LocationErrorCode.POSITION_UNAVAILABLE;
+  }
+}
+
+/**
+ * Maps Android exception types to LocationErrorCode.
+ *
+ * @param exceptionType - The Android exception class name
+ * @returns The corresponding LocationErrorCode
+ */
+export function mapAndroidException(exceptionType: string): LocationErrorCode {
+  if (exceptionType === "SecurityException") {
+    return LocationErrorCode.PERMISSION_DENIED;
+  }
+  return LocationErrorCode.POSITION_UNAVAILABLE;
+}

package/src/utils/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure utility functions for geolocation operations.
+ * These functions are platform-independent and can be tested with Jest.
+ */
+
+export { isCachedLocationValid } from "./cache";
+export {
+  LocationErrorCode,
+  createLocationError,
+  mapCLErrorCode,
+  mapAndroidException,
+  type LocationError
+} from "./errors";
+export {
+  isBetterLocation,
+  type LocationQuality
+} from "./quality";
+export {
+  selectProvider,
+  type Provider
+} from "./provider";
+export {
+  mergeConfigurations,
+  type LocationRequest,
+  type AccuracyLevel,
+  type MergedConfiguration
+} from "./config";

package/src/utils/provider.ts

@@ -0,0 +1,61 @@
+/**
+ * Location provider types supported on Android.
+ */
+export type Provider = "gps" | "network" | null;
+
+/**
+ * Selects the best available location provider based on user preferences
+ * and provider availability.
+ *
+ * This function implements a fallback strategy:
+ * - If high accuracy is requested, prefer GPS, fallback to Network
+ * - If low power is preferred, prefer Network, fallback to GPS
+ *
+ * @param enableHighAccuracy - Whether high accuracy mode is requested
+ * @param gpsAvailable - Whether GPS provider is available and enabled
+ * @param networkAvailable - Whether Network provider is available and enabled
+ * @returns The selected provider, or null if no providers are available
+ *
+ * @example
+ * ```ts
+ * // High accuracy mode with both providers available
+ * selectProvider(true, true, true); // 'gps'
+ *
+ * // High accuracy mode but GPS is disabled
+ * selectProvider(true, false, true); // 'network'
+ *
+ * // Low power mode with both providers available
+ * selectProvider(false, true, true); // 'network'
+ *
+ * // No providers available
+ * selectProvider(true, false, false); // null
+ * ```
+ */
+export function selectProvider(
+  enableHighAccuracy: boolean,
+  gpsAvailable: boolean,
+  networkAvailable: boolean
+): Provider {
+  // Determine preferred and fallback providers based on accuracy requirement
+  const preferredProvider = enableHighAccuracy ? "gps" : "network";
+  const fallbackProvider = enableHighAccuracy ? "network" : "gps";
+
+  // Check if preferred provider is available
+  const isPreferredAvailable =
+    preferredProvider === "gps" ? gpsAvailable : networkAvailable;
+
+  // Check if fallback provider is available
+  const isFallbackAvailable =
+    fallbackProvider === "gps" ? gpsAvailable : networkAvailable;
+
+  // Return the best available provider
+  if (isPreferredAvailable) {
+    return preferredProvider;
+  }
+
+  if (isFallbackAvailable) {
+    return fallbackProvider;
+  }
+
+  return null;
+}

package/src/utils/quality.ts

@@ -0,0 +1,98 @@
+/**
+ * Represents the quality characteristics of a location reading.
+ */
+export interface LocationQuality {
+  /** Timestamp in milliseconds since epoch */
+  timestampMs: number;
+  /** Horizontal accuracy in meters */
+  accuracyMeters: number;
+  /** Location provider type */
+  provider: "gps" | "network";
+}
+
+/** Time threshold for considering locations significantly newer/older (2 minutes) */
+const TWO_MINUTES_MS = 2 * 60 * 1000;
+
+/** Accuracy threshold for considering locations significantly less accurate (200 meters) */
+const SIGNIFICANT_ACCURACY_DIFFERENCE_METERS = 200;
+
+/**
+ * Determines whether a new location is better than the current best location.
+ * This algorithm considers both recency and accuracy of location readings.
+ *
+ * Based on Android's location quality evaluation best practices:
+ * @see https://developer.android.com/develop/sensors-and-location/location/strategies#BestEstimate
+ *
+ * @param newLocation - The new location to evaluate
+ * @param currentBest - The current best location, or null if none exists
+ * @returns true if the new location is better, false otherwise
+ *
+ * @example
+ * ```ts
+ * const newLoc: LocationQuality = {
+ *   timestampMs: Date.now(),
+ *   accuracyMeters: 10,
+ *   provider: 'gps'
+ * };
+ *
+ * const currentBest: LocationQuality = {
+ *   timestampMs: Date.now() - 60000, // 1 minute ago
+ *   accuracyMeters: 50,
+ *   provider: 'network'
+ * };
+ *
+ * isBetterLocation(newLoc, currentBest); // true (newer and more accurate)
+ * ```
+ */
+export function isBetterLocation(
+  newLocation: LocationQuality,
+  currentBest: LocationQuality | null
+): boolean {
+  // If there's no current best location, the new location is always better
+  if (!currentBest) {
+    return true;
+  }
+
+  // Calculate time difference between locations
+  const timeDelta = newLocation.timestampMs - currentBest.timestampMs;
+  const isSignificantlyNewer = timeDelta > TWO_MINUTES_MS;
+  const isSignificantlyOlder = timeDelta < -TWO_MINUTES_MS;
+
+  // If the new location is significantly newer, it's better
+  if (isSignificantlyNewer) {
+    return true;
+  }
+
+  // If the new location is significantly older, it's not better
+  if (isSignificantlyOlder) {
+    return false;
+  }
+
+  // Calculate accuracy difference
+  const accuracyDelta = newLocation.accuracyMeters - currentBest.accuracyMeters;
+  const isMoreAccurate = accuracyDelta < 0;
+  const isLessAccurate = accuracyDelta > 0;
+  const isSignificantlyLessAccurate =
+    accuracyDelta > SIGNIFICANT_ACCURACY_DIFFERENCE_METERS;
+
+  // Determine if location is newer
+  const isNewer = timeDelta > 0;
+
+  // Check if from same provider
+  const isFromSameProvider = newLocation.provider === currentBest.provider;
+
+  // Evaluate location quality based on accuracy and recency
+  if (isMoreAccurate) {
+    return true;
+  }
+
+  if (isNewer && !isLessAccurate) {
+    return true;
+  }
+
+  if (isNewer && !isSignificantlyLessAccurate && isFromSameProvider) {
+    return true;
+  }
+
+  return false;
+}

package/src/clearWatch.ts

@@ -1,13 +0,0 @@
-import { NitroModules } from "react-native-nitro-modules";
-import type { NitroGeolocation } from "./NitroGeolocation.nitro";
-
-/**
- * Clears a specific watch session identified by watchId.
- *
- * @param watchId - The ID returned by watchPosition()
- */
-export function clearWatch(watchId: number): void {
-  const nitroGeolocation =
-    NitroModules.createHybridObject<NitroGeolocation>("NitroGeolocation");
-  nitroGeolocation.clearWatch(watchId);
-}

package/src/requestAuthorization.ts

@@ -1,9 +0,0 @@
-import { NitroGeolocationHybridObject } from "./NitroGeolocationModule";
-import type { GeolocationError } from "./types";
-
-export function requestAuthorization(
-  success?: () => void,
-  error?: (error: GeolocationError) => void
-): void {
-  NitroGeolocationHybridObject.requestAuthorization(success, error);
-}