react-native-nitro-geolocation 0.1.1 → 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/README.md

@@ -1,318 +0,0 @@
-# react-native-nitro-geolocation
-
-[![NPM](https://img.shields.io/npm/v/react-native-nitro-geolocation)](https://www.npmjs.com/package/react-native-nitro-geolocation)
-
-[`@react-native-community/geolocation`](https://github.com/michalchudziak/react-native-geolocation)
-for the **React Native New Architecture** — with 100% API compatibility.
-
-![react-native-nitro-geolocation)(https://raw.githubusercontent.com/jingjing2222/react-native-nitro-geolocation/main/demo.gif)
-
----
-
-## 📘 Documentation
-
-Full documentation available at:
-👉 [https://react-native-nitro-geolocation.pages.dev](https://react-native-nitro-geolocation.pages.dev)
-
----
-
-## 🧭 Introduction
-
-The `@react-native-community/geolocation` package has long been the standard way to access device location in React Native apps.
-
-With React Native moving toward **Nitro Modules**, **Fabric**, and **JSI**,
-this project — **React Native Nitro Geolocation** — brings the same familiar API to the new architecture.
-
-It provides the **same API surface** with:
-
-- 🚀 Faster performance via direct **JSI bindings**
-- 📱 Improved native consistency (Android + iOS)
-- 🔁 Seamless migration from `@react-native-community/geolocation`
-- 🧩 TypeScript-first developer experience
-- 🔄 100% API compatibility (drop-in replacement)
-
-Whether upgrading an existing app or building a new one,
-**React Native Nitro Geolocation** keeps the simplicity you know — with modern internals.
-
-## 🏗 Architecture Comparison
-
-### 🧩 Origin: Event-based Architecture (`@react-native-community/geolocation`)
-
-~~~
-JavaScript
-  ↓ EventEmitter.addListener('geolocationDidChange', callback)
-  ↓ (Callback stored in JS)
-React Native Bridge (JSON serialization)
-  ↓
-Native Layer (Android/iOS)
-  ↓ LocationListener receives updates
-  ↓ emit('geolocationDidChange', data)
-  ↓
-EventEmitter dispatches to all listeners
-  ↓
-User callback executed
-~~~
-
-**Key traits:**
-- Callbacks stored only in JS
-- Bridge serialization on every update
-- One shared event stream
-
----
-
-### ⚡ Modern: Direct Callback Architecture (`react-native-nitro-geolocation`)
-
-~~~
-JavaScript
-  ↓ Geolocation.watchPosition(success, error)
-  ↓ (Callbacks passed directly to native via JSI)
-JSI Layer (No Bridge!)
-  ↓
-Native Layer (Kotlin/Swift)
-  ↓ callback.success(position) → JSI direct call
-  ↓
-User callback executed immediately
-~~~
-
-**Key traits:**
-- Callbacks passed as native JSI references
-- No Bridge serialization
-- Independent callback per watcher
-- Native → JS communication in real time
-
----
-
-## ⚡ Quick Start
-
-### 1. Installation
-
-~~~bash
-# Install Nitro core and Geolocation module
-yarn add react-native-nitro-modules react-native-nitro-geolocation
-
-# or using npm
-npm install react-native-nitro-modules react-native-nitro-geolocation
-~~~
-
-After installation, rebuild your native app:
-
-~~~bash
-cd ios && pod install
-~~~
-
----
-
-### 2. iOS Setup
-
-Add the following permissions to your **Info.plist**:
-
-~~~xml
-<key>NSLocationWhenInUseUsageDescription</key>
-<string>This app requires access to your location while it’s in use.</string>
-<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>This app requires access to your location at all times.</string>
-~~~
-
----
-
-### 3. Android Setup
-
-Add these permissions to your **AndroidManifest.xml**:
-
-~~~xml
-<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
-~~~
-
-Optional (for background access):
-
-~~~xml
-<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
-~~~
-
----
-
-### 4. Usage Example
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-
-Geolocation.getCurrentPosition(
-  (position) => {
-    console.log('Latitude:', position.coords.latitude);
-    console.log('Longitude:', position.coords.longitude);
-  },
-  (error) => {
-    console.error('Location error:', error);
-  },
-  { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 }
-);
-
-// Subscribe to continuous updates
-const watchId = Geolocation.watchPosition(
-  (position) => {
-    console.log('Updated position:', position);
-  },
-  (error) => console.error(error),
-);
-~~~
-
----
-
-### Migrating from `@react-native-community/geolocation`
-
-Nitro Geolocation is **100% API-compatible** with the original package.
-You can migrate simply by replacing imports:
-
-~~~diff
-- import Geolocation from '@react-native-community/geolocation';
-+ import Geolocation from 'react-native-nitro-geolocation';
-~~~
-
-**Benefits:**
-- Better performance via JSI
-- Reduced bridge overhead
-- Improved permission consistency
-- Built-in TypeScript definitions
-
----
-
-## 🧠 API Methods
-
-### Summary
-- `setRNConfiguration`
-- `requestAuthorization`
-- `getCurrentPosition`
-- `watchPosition`
-- `clearWatch`
-- `stopObserving`
-
----
-
-### `setRNConfiguration()`
-
-Sets configuration options used for all location requests.
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-
-Geolocation.setRNConfiguration({
-  skipPermissionRequests: false,
-  authorizationLevel: 'auto',
-  enableBackgroundLocationUpdates: true,
-  locationProvider: 'auto',
-});
-
-// recommended
-import { setRNConfiguration } from 'react-native-nitro-geolocation';
-
-setRNConfiguration({
-  skipPermissionRequests: false,
-  authorizationLevel: 'auto',
-  enableBackgroundLocationUpdates: true,
-  locationProvider: 'auto',
-});
-~~~
-
-**Options:**
-- `skipPermissionRequests` — default `false`
-- `authorizationLevel` — `'always' | 'whenInUse' | 'auto'` *(iOS only)*
-- `enableBackgroundLocationUpdates` — *(iOS only)*
-- `locationProvider` — `'playServices' | 'android' | 'auto'` *(Android only)*
-
----
-
-### `requestAuthorization()`
-
-Requests location permission from the system.
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-
-Geolocation.requestAuthorization(
-  () => console.log('Permission granted'),
-  (error) => console.error('Permission error:', error),
-);
-
-// recommended
-import { requestAuthorization } from 'react-native-nitro-geolocation';
-
-requestAuthorization(
-  () => console.log('Permission granted'),
-  (error) => console.error('Permission error:', error),
-);
-~~~
-
----
-
-### `getCurrentPosition()`
-
-Retrieves the current device location once.
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-
-Geolocation.getCurrentPosition(
-  (position) => console.log(position),
-  (error) => console.error(error),
-  { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 },
-);
-
-// recommended
-import { getCurrentPosition } from 'react-native-nitro-geolocation';
-
-getCurrentPosition(
-  (position) => console.log(position),
-  (error) => console.error(error),
-  { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 },
-);
-~~~
-
----
-
-### `watchPosition()`
-
-Watches location changes and calls the success callback each time.
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-
-const id = Geolocation.watchPosition(
-  (position) => console.log('Position:', position),
-  (error) => console.error(error),
-  { interval: 5000, distanceFilter: 10 },
-);
-
-// recommended
-import { watchPosition } from 'react-native-nitro-geolocation';
-
-const id = watchPosition(
-  (position) => console.log('Position:', position),
-  (error) => console.error(error),
-  { interval: 5000, distanceFilter: 10 },
-);
-
-~~~
-
----
-
-### `clearWatch()`
-
-Stops watching location updates for a given watch ID.
-
-~~~tsx
-import Geolocation from 'react-native-nitro-geolocation';
-Geolocation.clearWatch(id);
-
-// recommended
-import { clearWatch } from 'react-native-nitro-geolocation';
-clearWatch(id);
-~~~
-
----
-
-## 🧪 Summary
-
-**React Native Nitro Geolocation** transforms the geolocation API
-from a bridge-based, event-driven system into a **JSI-powered direct-callback model** —
-delivering native-level performance with **zero API changes** for developers.

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