react-native-nitro-geolocation 1.1.4 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![NPM](https://img.shields.io/npm/v/react-native-nitro-geolocation)](https://www.npmjs.com/package/react-native-nitro-geolocation)
 
-**Simple and Modern Geolocation for React Native** — Powered by Nitro Modules with JSI
+**Simple Native Geolocation for React Native** — Powered by Nitro Modules with JSI
 
 A complete reimplementation of [`@react-native-community/geolocation`](https://github.com/michalchudziak/react-native-geolocation) for the React Native New Architecture, featuring:
 
@@ -36,7 +36,17 @@ React Native Nitro Geolocation provides **two APIs** to fit your needs:
 import {
   setConfiguration,
   requestPermission,
+  requestLocationSettings,
+  getLocationAvailability,
   getCurrentPosition,
+  getLastKnownPosition,
+  geocode,
+  reverseGeocode,
+  getHeading,
+  watchHeading,
+  unwatch,
+  getAccuracyAuthorization,
+  requestTemporaryFullAccuracy,
   useWatchPosition,
 } from "react-native-nitro-geolocation";
 
@@ -49,16 +59,50 @@ setConfiguration({
 // Request permission
 const status = await requestPermission();
 
+// Android, v1.2+: ask the user to enable settings required for accurate location
+await requestLocationSettings({ accuracy: { android: "high" } });
+
+// v1.2+: check whether the platform can currently provide locations
+const availability = await getLocationAvailability();
+
 // Get current location
 const position = await getCurrentPosition({
-  enableHighAccuracy: true,
+  accuracy: { android: "high", ios: "best" },
+  granularity: "permission",
+  waitForAccurateLocation: true,
+});
+
+// v1.2+: read cached location explicitly without starting a fresh request
+const cached = await getLastKnownPosition({
+  maximumAge: 60_000,
+  accuracy: { android: "balanced", ios: "hundredMeters" },
+});
+
+// v1.2+: convert between addresses and coordinates with native geocoders
+const locations = await geocode("City Hall, Seoul, South Korea");
+const addresses = await reverseGeocode({
+  latitude: 37.5665,
+  longitude: 126.978,
+});
+
+// v1.2+: inspect precise/reduced accuracy authorization
+const accuracyAuthorization = await getAccuracyAuthorization();
+if (accuracyAuthorization === "reduced") {
+  await requestTemporaryFullAccuracy("TurnByTurnNavigation");
+}
+
+// v1.2+: read and watch compass heading
+const heading = await getHeading();
+const headingToken = watchHeading((nextHeading) => {
+  console.log(nextHeading.magneticHeading);
 });
+unwatch(headingToken);
 
 // Continuous tracking with hook
 function LocationTracker() {
   const { position, error, isWatching } = useWatchPosition({
     enabled: true,
-    enableHighAccuracy: true,
+    accuracy: { android: "high", ios: "bestForNavigation" },
     distanceFilter: 10,
   });
 
@@ -75,7 +119,7 @@ function LocationTracker() {
 
 **Benefits**:
 
-### 2. Legacy API (Compatibility)
+### 2. Compat API (Compatibility)
 
 **Drop-in replacement** for `@react-native-community/geolocation`:
 
@@ -150,7 +194,7 @@ Optional (for background):
 
 > **Prerequisites**: Requires [Rozenite DevTools](https://github.com/rozenite/rozenite) to be installed.
 >
-> **API Compatibility**: Only works with the Modern API. Does not support the Legacy API (`/compat`).
+> **API Compatibility**: Only works with the Modern API. Does not support the Compat API (`/compat`).
 
 Mock geolocation data during development with an interactive map interface:
 
@@ -200,16 +244,38 @@ function App() {
 
 ```tsx
 // Get current location
-const position = await getCurrentPosition({ enableHighAccuracy: true });
+const position = await getCurrentPosition({
+  accuracy: { android: "high", ios: "best" },
+});
 
 // Real-time tracking with hook
 const { position, error } = useWatchPosition({
   enabled: true,
+  accuracy: { android: "balanced", ios: "nearestTenMeters" },
   distanceFilter: 10
 });
 ```
 
-#### Legacy API (Compatibility)
+Accuracy presets are available since `v1.2`.
+
+`getLastKnownPosition(options?)`, `getLocationAvailability()`, `getHeading()`,
+`watchHeading()`, `geocode(address)`, `reverseGeocode(coords)`, selected
+Android request options (`granularity`, `waitForAccurateLocation`,
+`maxUpdateAge`, `maxUpdateDelay`, and `maxUpdates`), iOS tuning options
+(`activityType`, `pausesLocationUpdatesAutomatically`, and
+`showsBackgroundLocationIndicator`), `getAccuracyAuthorization()`, and
+`requestTemporaryFullAccuracy(purposeKey)` are available since `v1.2`.
+
+`enableHighAccuracy` is deprecated in the Modern API and remains supported only
+for v1 compatibility. Prefer `accuracy`; when `accuracy.android` or
+`accuracy.ios` is provided for the current platform, that explicit preset takes
+precedence over the boolean. `enableHighAccuracy` is expected to be removed from
+the Modern API in v2.
+
+The `/compat` API keeps `enableHighAccuracy` for drop-in compatibility with
+`@react-native-community/geolocation`.
+
+#### Compat API (Compatibility)
 
 ```tsx
 import Geolocation from "react-native-nitro-geolocation/compat";
@@ -238,7 +304,7 @@ Change the import to use `/compat` — 100% API compatible:
 - [Introduction](https://react-native-nitro-geolocation.pages.dev/guide/)
 - [Quick Start Guide](https://react-native-nitro-geolocation.pages.dev/guide/quick-start)
 - [Modern API Reference](https://react-native-nitro-geolocation.pages.dev/guide/modern-api)
-- [Legacy API Reference](https://react-native-nitro-geolocation.pages.dev/guide/legacy-api)
+- [Compat API Reference](https://react-native-nitro-geolocation.pages.dev/guide/compat-api)
 - [DevTools Plugin Guide](https://react-native-nitro-geolocation.pages.dev/guide/devtools)
 - [Why Nitro Module?](https://react-native-nitro-geolocation.pages.dev/guide/why-nitro-module)
 - [Benchmark Results](https://react-native-nitro-geolocation.pages.dev/guide/benchmark)

package/android/build.gradle

@@ -30,6 +30,10 @@ def getExtOrIntegerDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroGeolocation_" + name]).toInteger()
 }
 
+def getExtOrDefaultValue(name, defaultValue) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroGeolocation_" + name] ?: defaultValue)
+}
+
 android {
   namespace "com.margelo.nitro.nitrogeolocation"
 
@@ -123,6 +127,8 @@ def kotlin_version = getExtOrDefault("kotlinVersion")
 
 dependencies {
   implementation "com.facebook.react:react-android"
+  implementation "com.google.android.gms:play-services-base:${getExtOrDefaultValue('playServicesBaseVersion', '18.5.0')}"
+  implementation "com.google.android.gms:play-services-location:${getExtOrDefaultValue('playServicesLocationVersion', '21.3.0')}"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation project(":react-native-nitro-modules")
 }

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/AndroidAccuracy.kt

@@ -0,0 +1,105 @@
+package com.margelo.nitro.nitrogeolocation
+
+import android.location.LocationManager
+import com.google.android.gms.location.Granularity
+import com.google.android.gms.location.Priority
+
+internal enum class AndroidAccuracyMode {
+    HIGH,
+    BALANCED,
+    LOW,
+    PASSIVE
+}
+
+internal data class AndroidAccuracyResolution(
+    val mode: AndroidAccuracyMode,
+    val explicitPreset: AndroidAccuracyPreset?
+)
+
+internal fun resolveAndroidAccuracy(
+    accuracy: LocationAccuracyOptions?,
+    enableHighAccuracy: Boolean
+): AndroidAccuracyResolution {
+    val preset = accuracy?.android
+    val mode = when (preset) {
+        AndroidAccuracyPreset.HIGH -> AndroidAccuracyMode.HIGH
+        AndroidAccuracyPreset.BALANCED -> AndroidAccuracyMode.BALANCED
+        AndroidAccuracyPreset.LOW -> AndroidAccuracyMode.LOW
+        AndroidAccuracyPreset.PASSIVE -> AndroidAccuracyMode.PASSIVE
+        null -> if (enableHighAccuracy) AndroidAccuracyMode.HIGH else AndroidAccuracyMode.BALANCED
+    }
+
+    return AndroidAccuracyResolution(mode = mode, explicitPreset = preset)
+}
+
+internal fun AndroidAccuracyResolution.providerOrder(): List<String> {
+    return when (mode) {
+        AndroidAccuracyMode.HIGH -> listOf(
+            LocationManager.GPS_PROVIDER,
+            LocationManager.NETWORK_PROVIDER
+        )
+        AndroidAccuracyMode.BALANCED -> if (explicitPreset == null) {
+            listOf(LocationManager.NETWORK_PROVIDER, LocationManager.GPS_PROVIDER)
+        } else {
+            listOf(LocationManager.NETWORK_PROVIDER)
+        }
+        AndroidAccuracyMode.LOW -> listOf(
+            LocationManager.NETWORK_PROVIDER,
+            LocationManager.PASSIVE_PROVIDER
+        )
+        AndroidAccuracyMode.PASSIVE -> listOf(LocationManager.PASSIVE_PROVIDER)
+    }
+}
+
+internal fun AndroidAccuracyResolution.gmsPriority(): Int {
+    return when (mode) {
+        AndroidAccuracyMode.HIGH -> Priority.PRIORITY_HIGH_ACCURACY
+        AndroidAccuracyMode.BALANCED -> Priority.PRIORITY_BALANCED_POWER_ACCURACY
+        AndroidAccuracyMode.LOW -> Priority.PRIORITY_LOW_POWER
+        AndroidAccuracyMode.PASSIVE -> Priority.PRIORITY_PASSIVE
+    }
+}
+
+internal fun AndroidGranularity?.gmsGranularity(): Int {
+    return when (this) {
+        AndroidGranularity.COARSE -> Granularity.GRANULARITY_COARSE
+        AndroidGranularity.FINE -> Granularity.GRANULARITY_FINE
+        AndroidGranularity.PERMISSION,
+        null -> Granularity.GRANULARITY_PERMISSION_LEVEL
+    }
+}
+
+internal fun AndroidGranularity?.allowsProvider(provider: String): Boolean {
+    return when (this) {
+        AndroidGranularity.COARSE -> provider != LocationManager.GPS_PROVIDER
+        AndroidGranularity.FINE,
+        AndroidGranularity.PERMISSION,
+        null -> true
+    }
+}
+
+internal fun mostDemandingAndroidAccuracy(
+    current: AndroidAccuracyResolution?,
+    next: AndroidAccuracyResolution
+): AndroidAccuracyResolution {
+    if (current == null) return next
+
+    val currentRank = current.mode.demandRank()
+    val nextRank = next.mode.demandRank()
+
+    return when {
+        nextRank > currentRank -> next
+        nextRank < currentRank -> current
+        current.explicitPreset == null && next.explicitPreset != null -> next
+        else -> current
+    }
+}
+
+private fun AndroidAccuracyMode.demandRank(): Int {
+    return when (this) {
+        AndroidAccuracyMode.PASSIVE -> 0
+        AndroidAccuracyMode.LOW -> 1
+        AndroidAccuracyMode.BALANCED -> 2
+        AndroidAccuracyMode.HIGH -> 3
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/AndroidHeadingManager.kt

@@ -0,0 +1,313 @@
+package com.margelo.nitro.nitrogeolocation
+
+import android.content.Context
+import android.hardware.GeomagneticField
+import android.hardware.Sensor
+import android.hardware.SensorEvent
+import android.hardware.SensorEventListener
+import android.hardware.SensorManager
+import android.location.Location
+import android.os.Handler
+import android.os.Looper
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.math.abs
+
+private const val DEFAULT_HEADING_TIMEOUT_MS = 10_000L
+
+internal class AndroidHeadingManager(
+    context: Context,
+    private val createLocationError: (Double, String) -> LocationError,
+    private val getReferenceLocation: () -> Location?
+) {
+    private data class PendingHeadingRequest(
+        val id: UUID,
+        val success: (Heading) -> Unit,
+        val error: ((LocationError) -> Unit)?,
+        val timeoutRunnable: Runnable
+    )
+
+    private data class HeadingSubscription(
+        val token: String,
+        val success: (Heading) -> Unit,
+        val error: ((LocationError) -> Unit)?,
+        val headingFilter: Double,
+        var lastDeliveredHeading: Double?
+    )
+
+    private val sensorManager =
+        context.getSystemService(Context.SENSOR_SERVICE) as? SensorManager
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private val pendingRequests = ConcurrentHashMap<UUID, PendingHeadingRequest>()
+    private val subscriptions = ConcurrentHashMap<String, HeadingSubscription>()
+    private val rotationVectorSensor: Sensor? =
+        sensorManager?.getDefaultSensor(Sensor.TYPE_ROTATION_VECTOR)
+            ?: sensorManager?.getDefaultSensor(Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTOR)
+    private val accelerometerSensor: Sensor? =
+        sensorManager?.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)
+    private val magneticFieldSensor: Sensor? =
+        sensorManager?.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD)
+
+    private var isListening = false
+    private var sensorAccuracy: Int? = null
+    private var gravityValues: FloatArray? = null
+    private var magneticValues: FloatArray? = null
+
+    private val sensorListener = object : SensorEventListener {
+        override fun onSensorChanged(event: SensorEvent) {
+            val magneticHeading = when (event.sensor.type) {
+                Sensor.TYPE_ROTATION_VECTOR,
+                Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTOR -> {
+                    headingFromRotationVector(event.values)
+                }
+                Sensor.TYPE_ACCELEROMETER -> {
+                    gravityValues = event.values.clone()
+                    headingFromAccelerationAndMagnetometer()
+                }
+                Sensor.TYPE_MAGNETIC_FIELD -> {
+                    magneticValues = event.values.clone()
+                    headingFromAccelerationAndMagnetometer()
+                }
+                else -> null
+            } ?: return
+
+            emitHeading(createHeading(magneticHeading))
+        }
+
+        override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {
+            sensorAccuracy = accuracy
+        }
+    }
+
+    fun getHeading(
+        success: (Heading) -> Unit,
+        error: ((LocationError) -> Unit)?
+    ) {
+        if (!hasHeadingSensor()) {
+            error?.invoke(createUnavailableError())
+            return
+        }
+
+        val id = UUID.randomUUID()
+        val timeoutRunnable = Runnable {
+            pendingRequests.remove(id)?.error?.invoke(
+                createLocationError(
+                    TIMEOUT,
+                    "Unable to fetch heading within ${DEFAULT_HEADING_TIMEOUT_MS / 1000.0}s."
+                )
+            )
+            stopIfIdle()
+        }
+
+        pendingRequests[id] = PendingHeadingRequest(
+            id = id,
+            success = success,
+            error = error,
+            timeoutRunnable = timeoutRunnable
+        )
+        mainHandler.postDelayed(timeoutRunnable, DEFAULT_HEADING_TIMEOUT_MS)
+        startIfNeeded()
+    }
+
+    fun watchHeading(
+        success: (Heading) -> Unit,
+        error: ((LocationError) -> Unit)?,
+        options: HeadingOptions?
+    ): String {
+        val token = UUID.randomUUID().toString()
+        val headingFilter = options?.headingFilter ?: 0.0
+
+        if (!headingFilter.isFinite() || headingFilter < 0.0) {
+            error?.invoke(createLocationError(
+                INTERNAL_ERROR,
+                "headingFilter must be a finite number greater than or equal to 0."
+            ))
+            return token
+        }
+
+        if (!hasHeadingSensor()) {
+            error?.invoke(createUnavailableError())
+            return token
+        }
+
+        subscriptions[token] = HeadingSubscription(
+            token = token,
+            success = success,
+            error = error,
+            headingFilter = headingFilter,
+            lastDeliveredHeading = null
+        )
+        startIfNeeded()
+
+        return token
+    }
+
+    fun unwatch(token: String) {
+        subscriptions.remove(token)
+        stopIfIdle()
+    }
+
+    fun stopObserving() {
+        pendingRequests.values.forEach { request ->
+            mainHandler.removeCallbacks(request.timeoutRunnable)
+        }
+        pendingRequests.clear()
+        subscriptions.clear()
+        stopListening()
+    }
+
+    fun hasActiveWork(): Boolean {
+        return pendingRequests.isNotEmpty() || subscriptions.isNotEmpty()
+    }
+
+    private fun hasHeadingSensor(): Boolean {
+        return sensorManager != null &&
+            (rotationVectorSensor != null || (accelerometerSensor != null && magneticFieldSensor != null))
+    }
+
+    private fun startIfNeeded() {
+        if (isListening) return
+
+        val manager = sensorManager ?: return
+        val didRegister = if (rotationVectorSensor != null) {
+            manager.registerListener(
+                sensorListener,
+                rotationVectorSensor,
+                SensorManager.SENSOR_DELAY_UI,
+                mainHandler
+            )
+        } else {
+            val accelerometerRegistered = manager.registerListener(
+                sensorListener,
+                accelerometerSensor!!,
+                SensorManager.SENSOR_DELAY_UI,
+                mainHandler
+            )
+            val magneticRegistered = manager.registerListener(
+                sensorListener,
+                magneticFieldSensor!!,
+                SensorManager.SENSOR_DELAY_UI,
+                mainHandler
+            )
+            accelerometerRegistered && magneticRegistered
+        }
+
+        isListening = didRegister
+        if (!didRegister) {
+            val error = createUnavailableError()
+            pendingRequests.values.forEach { it.error?.invoke(error) }
+            subscriptions.values.forEach { it.error?.invoke(error) }
+            stopObserving()
+        }
+    }
+
+    private fun stopIfIdle() {
+        if (!hasActiveWork()) {
+            stopListening()
+        }
+    }
+
+    private fun stopListening() {
+        if (!isListening) return
+
+        try {
+            sensorManager?.unregisterListener(sensorListener)
+        } catch (_: Exception) {
+            // Ignore unregister races.
+        }
+        isListening = false
+        gravityValues = null
+        magneticValues = null
+    }
+
+    private fun headingFromRotationVector(values: FloatArray): Double? {
+        val rotationMatrix = FloatArray(9)
+        val orientation = FloatArray(3)
+        SensorManager.getRotationMatrixFromVector(rotationMatrix, values)
+        SensorManager.getOrientation(rotationMatrix, orientation)
+        return normalizeHeading(Math.toDegrees(orientation[0].toDouble()))
+    }
+
+    private fun headingFromAccelerationAndMagnetometer(): Double? {
+        val gravity = gravityValues ?: return null
+        val magnetic = magneticValues ?: return null
+        val rotationMatrix = FloatArray(9)
+        val inclinationMatrix = FloatArray(9)
+
+        if (!SensorManager.getRotationMatrix(rotationMatrix, inclinationMatrix, gravity, magnetic)) {
+            return null
+        }
+
+        val orientation = FloatArray(3)
+        SensorManager.getOrientation(rotationMatrix, orientation)
+        return normalizeHeading(Math.toDegrees(orientation[0].toDouble()))
+    }
+
+    private fun createHeading(magneticHeading: Double): Heading {
+        val referenceLocation = getReferenceLocation()
+        val trueHeading = referenceLocation?.let { location ->
+            val field = GeomagneticField(
+                location.latitude.toFloat(),
+                location.longitude.toFloat(),
+                if (location.hasAltitude()) location.altitude.toFloat() else 0f,
+                location.time
+            )
+            normalizeHeading(magneticHeading + field.declination)
+        }
+
+        return Heading(
+            magneticHeading = magneticHeading,
+            trueHeading = trueHeading,
+            accuracy = sensorAccuracy?.takeIf {
+                it != SensorManager.SENSOR_STATUS_UNRELIABLE
+            }?.toDouble(),
+            timestamp = System.currentTimeMillis().toDouble()
+        )
+    }
+
+    private fun emitHeading(heading: Heading) {
+        val pendingSnapshot = pendingRequests.values.toList()
+        pendingSnapshot.forEach { request ->
+            mainHandler.removeCallbacks(request.timeoutRunnable)
+            if (pendingRequests.remove(request.id) != null) {
+                request.success(heading)
+            }
+        }
+
+        subscriptions.values.forEach { subscription ->
+            val lastHeading = subscription.lastDeliveredHeading
+            if (
+                lastHeading == null ||
+                angularDistance(lastHeading, heading.magneticHeading) >= subscription.headingFilter
+            ) {
+                subscription.lastDeliveredHeading = heading.magneticHeading
+                subscription.success(heading)
+            }
+        }
+
+        stopIfIdle()
+    }
+
+    private fun angularDistance(first: Double, second: Double): Double {
+        val distance = abs(first - second) % 360.0
+        return if (distance > 180.0) 360.0 - distance else distance
+    }
+
+    private fun normalizeHeading(value: Double): Double {
+        val normalized = value % 360.0
+        return if (normalized < 0.0) normalized + 360.0 else normalized
+    }
+
+    private fun createUnavailableError(): LocationError {
+        return createLocationError(
+            POSITION_UNAVAILABLE,
+            "Heading sensor is not available."
+        )
+    }
+
+    private companion object {
+        private const val INTERNAL_ERROR = -1.0
+        private const val POSITION_UNAVAILABLE = 2.0
+        private const val TIMEOUT = 3.0
+    }
+}