react-native-nitro-geolocation 0.1.2 → 0.3.0

package/src/index.tsx

@@ -1,34 +1,79 @@
-// Export methods
-export { clearWatch } from "./clearWatch";
-export { getCurrentPosition } from "./getCurrentPosition";
-export { requestAuthorization } from "./requestAuthorization";
-export { setRNConfiguration } from "./setRNConfiguration";
-export { stopObserving } from "./stopObserving";
-export { watchPosition } from "./watchPosition";
+/**
+ * Modern Geolocation API for React Native.
+ *
+ * This is the main entry point for the modern, React-friendly API.
+ * For legacy compatibility, use: import Geolocation from 'react-native-nitro-geolocation/compat'
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   GeolocationClient,
+ *   GeolocationClientProvider,
+ *   useRequestPermission,
+ *   useGetCurrentPosition,
+ *   useWatchPosition
+ * } from 'react-native-nitro-geolocation';
+ *
+ * // Create GeolocationClient instance
+ * const geolocationClient = new GeolocationClient({
+ *   authorizationLevel: 'whenInUse',
+ *   enableBackgroundLocationUpdates: false,
+ *   locationProvider: 'auto'
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <GeolocationClientProvider client={geolocationClient}>
+ *       <YourApp />
+ *     </GeolocationClientProvider>
+ *   );
+ * }
+ *
+ * function LocationButton() {
+ *   const { getCurrentPosition } = useGetCurrentPosition();
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   const handlePress = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const pos = await getCurrentPosition({ enableHighAccuracy: true });
+ *       console.log('Position:', pos);
+ *     } catch (error) {
+ *       console.error('Error:', error);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return <Button onPress={handlePress} disabled={loading} />;
+ * }
+ * ```
+ */
 
-// Default export for compatibility
-import { clearWatch } from "./clearWatch";
-import { getCurrentPosition } from "./getCurrentPosition";
-import { requestAuthorization } from "./requestAuthorization";
-import { setRNConfiguration } from "./setRNConfiguration";
-import { stopObserving } from "./stopObserving";
-import { watchPosition } from "./watchPosition";
+// Core
+export { GeolocationClient } from "./GeolocationClient";
+export type { GeolocationClientConfig } from "./GeolocationClient";
 
-const Geolocation = {
-  setRNConfiguration,
-  requestAuthorization,
-  getCurrentPosition,
-  watchPosition,
-  clearWatch,
-  stopObserving
-};
+// Components
+export * from "./components";
+
+// Hooks
+export * from "./hooks";
+
+// Types from Nitro spec
+export type {
+  PermissionStatus,
+  LocationRequestOptions,
+  LocationError
+} from "./NitroGeolocation.nitro";
 
-// Export types
 export type {
-  GeolocationConfiguration,
   GeolocationResponse,
-  GeolocationError,
-  GeolocationOptions
+  GeolocationCoordinates,
+  AuthorizationLevel,
+  LocationProvider,
+  ModernGeolocationConfiguration
 } from "./types";
 
-export default Geolocation;
+// Pure utility functions (advanced users only)
+export * from "./utils";

package/src/types.ts

@@ -1,6 +1,34 @@
 // Public API types (compatible with @react-native-community/geolocation)
 export type AuthorizationLevel = "always" | "whenInUse" | "auto";
 export type LocationProvider = "playServices" | "android" | "auto";
+export type NullableDouble = number | null;
+
+/**
+ * User-facing geolocation configuration.
+ * This uses "android" instead of "android_platform" for better DX.
+ */
+export interface ModernGeolocationConfiguration {
+  /**
+   * Automatically request location permission when GeolocationProvider mounts.
+   * @default false
+   */
+  autoRequestPermission?: boolean;
+
+  /**
+   * iOS: Authorization level
+   */
+  authorizationLevel?: AuthorizationLevel;
+
+  /**
+   * iOS: Enable background location updates.
+   */
+  enableBackgroundLocationUpdates?: boolean;
+
+  /**
+   * Android: Location provider
+   */
+  locationProvider?: LocationProvider;
+}
 
 export interface GeolocationConfiguration {
   skipPermissionRequests: boolean;
@@ -12,11 +40,11 @@ export interface GeolocationConfiguration {
 export interface GeolocationCoordinates {
   latitude: number;
   longitude: number;
-  altitude: number | null;
+  altitude: NullableDouble;
   accuracy: number;
-  altitudeAccuracy: number | null;
-  heading: number | null;
-  speed: number | null;
+  altitudeAccuracy: NullableDouble;
+  heading: NullableDouble;
+  speed: NullableDouble;
 }
 
 export interface GeolocationResponse {

package/src/utils/cache.ts

@@ -0,0 +1,25 @@
+/**
+ * Validates whether a cached location is still fresh based on its age.
+ *
+ * @param timestampMs - The timestamp of the cached location (in milliseconds)
+ * @param currentTimeMs - The current time (in milliseconds)
+ * @param maximumAgeMs - The maximum age allowed for the cache (in milliseconds)
+ * @returns true if the cache is still valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * const timestampMs = Date.now() - 5000; // 5 seconds ago
+ * const currentTimeMs = Date.now();
+ * const maximumAgeMs = 10000; // 10 seconds
+ *
+ * isCachedLocationValid(timestampMs, currentTimeMs, maximumAgeMs); // true
+ * ```
+ */
+export function isCachedLocationValid(
+  timestampMs: number,
+  currentTimeMs: number,
+  maximumAgeMs: number
+): boolean {
+  const age = currentTimeMs - timestampMs;
+  return age < maximumAgeMs;
+}

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);
-}