react-native-nitro-geolocation 0.1.0 → 0.1.2

package/ios/LocationManager.swift

@@ -10,10 +10,11 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
     }
 
     private struct LocationRequest {
+        let id: UUID = UUID()
         let success: (GeolocationResponse) -> Void
         let error: ((GeolocationError) -> Void)?
         let options: ParsedOptions
-        var timer: Timer?
+        var timer: DispatchSourceTimer?
     }
 
     private struct WatchSubscription {
@@ -22,7 +23,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         let options: ParsedOptions
     }
 
-    private struct ParsedOptions {
+    struct ParsedOptions {
         let timeout: Double
         let maximumAge: Double
         let accuracy: CLLocationAccuracy
@@ -51,7 +52,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
     // MARK: - Properties
 
     private var locationManager: CLLocationManager?
-    private var lastLocation: CLLocation?
+    internal private(set) var lastLocation: CLLocation?
     private var usingSignificantChanges: Bool = false
 
     // Authorization
@@ -84,36 +85,32 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         success: (() -> Void)?,
         error: ((GeolocationError) -> Void)?
     ) {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self else { return }
-
-            self.initializeLocationManagerIfNeeded()
-            self.enqueueAuthorizationCallbacks(success: success, error: error)
-
-            // Skip permission requests if configured
-            if skipPermissionRequests {
-                if enableBackgroundLocationUpdates {
-                    self.enableBackgroundLocationUpdatesIfNeeded()
-                }
-                self.handleAuthorizationSuccess()
-                return
-            }
+        initializeLocationManagerIfNeeded()
+        enqueueAuthorizationCallbacks(success: success, error: error)
 
-            // Check if already authorized
-            let currentStatus = CLLocationManager.authorizationStatus()
-            if currentStatus == .authorizedAlways || currentStatus == .authorizedWhenInUse {
-                self.handleAuthorizationSuccess()
-                return
+        // Skip permission requests if configured
+        if skipPermissionRequests {
+            if enableBackgroundLocationUpdates {
+                enableBackgroundLocationUpdatesIfNeeded()
             }
+            handleAuthorizationSuccess()
+            return
+        }
 
-            if currentStatus == .denied || currentStatus == .restricted {
-                self.handleAuthorizationError(for: currentStatus)
-                return
-            }
+        // Check if already authorized
+        let currentStatus = CLLocationManager.authorizationStatus()
+        if currentStatus == .authorizedAlways || currentStatus == .authorizedWhenInUse {
+            handleAuthorizationSuccess()
+            return
+        }
 
-            // Not determined yet, request permission
-            self.requestPermission(for: authType)
+        if currentStatus == .denied || currentStatus == .restricted {
+            handleAuthorizationError(for: currentStatus)
+            return
         }
+
+        // Not determined yet, request permission
+        requestPermission(for: authType)
     }
 
     private func enqueueAuthorizationCallbacks(
@@ -153,63 +150,51 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         error: ((GeolocationError) -> Void)?,
         options: GeolocationOptions?
     ) {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self else { return }
-
-            let parsedOptions = ParsedOptions.parse(from: options)
-
-            // Check authorization
-            let status = CLLocationManager.authorizationStatus()
-            if status == .denied || status == .restricted {
-                let message =
-                    status == .restricted
-                    ? "This application is not authorized to use location services"
-                    : "User denied access to location services."
-                error?(self.createError(code: self.PERMISSION_DENIED, message: message))
-                return
-            }
-
-            if !CLLocationManager.locationServicesEnabled() {
-                error?(
-                    self.createError(
-                        code: self.POSITION_UNAVAILABLE, message: "Location services disabled."))
-                return
-            }
+        let parsedOptions = ParsedOptions.parse(from: options)
+
+        // Check authorization
+        let status = CLLocationManager.authorizationStatus()
+        if status == .denied || status == .restricted {
+            let message =
+                status == .restricted
+                ? "This application is not authorized to use location services"
+                : "User denied access to location services."
+            error?(createError(code: PERMISSION_DENIED, message: message))
+            return
+        }
 
-            // Check cached location
-            if let cached = self.lastLocation,
-                self.isCachedLocationValid(cached, options: parsedOptions)
-            {
-                success(self.locationToPosition(cached))
-                return
-            }
+        if !CLLocationManager.locationServicesEnabled() {
+            error?(createError(code: POSITION_UNAVAILABLE, message: "Location services disabled."))
+            return
+        }
 
-            self.initializeLocationManagerIfNeeded()
+        initializeLocationManagerIfNeeded()
 
-            // Configure location manager (use best accuracy from all pending requests)
-            self.updateLocationManagerConfiguration()
+        // Configure location manager
+        locationManager?.desiredAccuracy = parsedOptions.accuracy
+        locationManager?.distanceFilter = parsedOptions.distanceFilter
 
-            // Create request
-            var request = LocationRequest(
-                success: success,
-                error: error,
-                options: parsedOptions,
-                timer: nil
-            )
+        // Create request
+        var request = LocationRequest(
+            success: success,
+            error: error,
+            options: parsedOptions,
+            timer: nil
+        )
 
-            // Setup timeout
-            let timer = Timer.scheduledTimer(
-                withTimeInterval: parsedOptions.timeout / 1000.0, repeats: false
-            ) { [weak self] timer in
-                self?.handleTimeout(for: timer)
-            }
-            request.timer = timer
+        // Setup timeout with DispatchSourceTimer (no run loop needed)
+        let timer = DispatchSource.makeTimerSource(queue: .main)
+        timer.schedule(deadline: .now() + parsedOptions.timeout / 1000.0)
+        timer.setEventHandler { [weak self] in
+            self?.handleTimeout(for: request.id)
+        }
+        timer.resume()
+        request.timer = timer
 
-            self.pendingRequests.append(request)
+        pendingRequests.append(request)
 
-            // Start location updates
-            self.startMonitoring()
-        }
+        // Start location updates
+        startMonitoring()
     }
 
     // MARK: - Watch Position
@@ -219,56 +204,44 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         error: ((GeolocationError) -> Void)?,
         options: GeolocationOptions?
     ) -> Double {
-        var resultWatchId: Double = 0
-
-        DispatchQueue.main.sync { [weak self] in
-            guard let self = self else { return }
-
-            let parsedOptions = ParsedOptions.parse(from: options)
-            let watchId = self.nextWatchId
-            self.nextWatchId += 1
+        let parsedOptions = ParsedOptions.parse(from: options)
+        let watchId = nextWatchId
+        nextWatchId += 1
+
+        let subscription = WatchSubscription(
+            success: success,
+            error: error,
+            options: parsedOptions
+        )
 
-            let subscription = WatchSubscription(
-                success: success,
-                error: error,
-                options: parsedOptions
-            )
+        activeWatches[watchId] = subscription
 
-            self.activeWatches[watchId] = subscription
+        initializeLocationManagerIfNeeded()
 
-            self.initializeLocationManagerIfNeeded()
-            self.updateLocationManagerConfiguration()
-            self.startMonitoring()
+        // Configure location manager
+        locationManager?.desiredAccuracy = parsedOptions.accuracy
+        locationManager?.distanceFilter = parsedOptions.distanceFilter
 
-            resultWatchId = watchId
-        }
+        startMonitoring()
 
-        return resultWatchId
+        return watchId
     }
 
     func clearWatch(watchId: Double) {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self else { return }
-
-            self.activeWatches.removeValue(forKey: watchId)
+        activeWatches.removeValue(forKey: watchId)
 
-            // Stop monitoring if no more watches or pending requests
-            if self.activeWatches.isEmpty && self.pendingRequests.isEmpty {
-                self.stopMonitoring()
-            }
+        // Stop monitoring if no more watches or pending requests
+        if activeWatches.isEmpty && pendingRequests.isEmpty {
+            stopMonitoring()
         }
     }
 
     func stopObserving() {
-        DispatchQueue.main.async { [weak self] in
-            guard let self = self else { return }
+        activeWatches.removeAll()
 
-            self.activeWatches.removeAll()
-
-            // Stop monitoring if no pending requests
-            if self.pendingRequests.isEmpty {
-                self.stopMonitoring()
-            }
+        // Stop monitoring if no pending requests
+        if pendingRequests.isEmpty {
+            stopMonitoring()
         }
     }
 
@@ -298,7 +271,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
 
         // 1. Fire all pending getCurrentPosition requests
         for request in pendingRequests {
-            request.timer?.invalidate()
+            request.timer?.cancel()
             request.success(position)
         }
         pendingRequests.removeAll()
@@ -338,7 +311,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
 
         // Fire all pending requests with error
         for request in pendingRequests {
-            request.timer?.invalidate()
+            request.timer?.cancel()
             request.error?(geoError)
         }
         pendingRequests.removeAll()
@@ -355,8 +328,17 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
 
     private func initializeLocationManagerIfNeeded() {
         guard locationManager == nil else { return }
-        locationManager = CLLocationManager()
-        locationManager?.delegate = self
+
+        // CLLocationManager must be created on main thread for delegate callbacks
+        if Thread.isMainThread {
+            locationManager = CLLocationManager()
+            locationManager?.delegate = self
+        } else {
+            DispatchQueue.main.sync {
+                locationManager = CLLocationManager()
+                locationManager?.delegate = self
+            }
+        }
     }
 
     private func updateLocationManagerConfiguration() {
@@ -408,7 +390,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         }
     }
 
-    private func isCachedLocationValid(_ location: CLLocation, options: ParsedOptions) -> Bool {
+    func isCachedLocationValid(_ location: CLLocation, options: ParsedOptions) -> Bool {
         // Check if maximumAge is infinity
         if options.maximumAge.isInfinite {
             return true
@@ -428,13 +410,16 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         return true
     }
 
-    private func handleTimeout(for timer: Timer) {
-        // Find and remove the request with this timer
-        if let index = pendingRequests.firstIndex(where: { $0.timer === timer }) {
+    private func handleTimeout(for requestId: UUID) {
+        // Find and remove the request with this ID
+        if let index = pendingRequests.firstIndex(where: { $0.id == requestId }) {
             let request = pendingRequests[index]
             pendingRequests.remove(at: index)
 
-            // Always return timeout error
+            // Cancel timer
+            request.timer?.cancel()
+
+            // Return timeout error
             let timeoutSeconds = request.options.timeout / 1000.0
             let message = String(format: "Unable to fetch location within %.1fs.", timeoutSeconds)
             request.error?(createError(code: TIMEOUT, message: message))
@@ -493,7 +478,7 @@ class LocationManager: NSObject, CLLocationManagerDelegate {
         queuedAuthorizationCallbacks.removeAll()
     }
 
-    private func locationToPosition(_ location: CLLocation) -> GeolocationResponse {
+    func locationToPosition(_ location: CLLocation) -> GeolocationResponse {
         let altitude = location.verticalAccuracy < 0 ? 0.0 : location.altitude
         let altitudeAccuracy = location.verticalAccuracy < 0 ? 0.0 : location.verticalAccuracy
         let heading = location.course >= 0 ? location.course : -1.0

package/ios/NitroGeolocation.swift

@@ -38,6 +38,16 @@ class NitroGeolocation: HybridNitroGeolocationSpec {
         success: @escaping (GeolocationResponse) -> Void, error: ((GeolocationError) -> Void)?,
         options: GeolocationOptions?
     ) throws {
+        // Fast path: check cached location immediately (no dispatch overhead!)
+        let parsedOptions = LocationManager.ParsedOptions.parse(from: options)
+
+        if let cached = locationManager.lastLocation,
+           locationManager.isCachedLocationValid(cached, options: parsedOptions) {
+            success(locationManager.locationToPosition(cached))
+            return
+        }
+
+        // Slow path: need GPS
         locationManager.getCurrentPosition(success: success, error: error, options: options)
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "⚡🚀Blazing-fast geolocation for React Native powered by Nitro Modules",
   "main": "src/index",
   "source": "src/index",
@@ -43,7 +43,7 @@
     "@types/react-test-renderer": "^18.0.0",
     "react": "19.1.0",
     "react-native": "0.81.1",
-    "react-native-nitro-modules": "^0.29.7",
+    "react-native-nitro-modules": "^0.29.6",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {

package/README.md

@@ -1,598 +0,0 @@
-# react-native-nitro-geolocation
-
-A high-performance geolocation library for React Native, powered by [Nitro Modules](https://github.com/mrousavy/nitro). This is a complete rewrite of `@react-native-community/geolocation` using modern architecture for superior performance and developer experience.
-
-## Architecture Comparison
-
-### Bridge vs JSI Architecture
-
-#### `@react-native-community/geolocation` (Old Bridge)
-```
-┌─────────────┐
-│     JS      │
-└──────┬──────┘
-       │ serialize JSON
-       ▼
-┌─────────────┐
-│   Bridge    │ ← Async message queue
-└──────┬──────┘
-       │ deserialize JSON
-       ▼
-┌─────────────┐
-│  Java/ObjC  │
-└─────────────┘
-```
-
-**Characteristics:**
-- **Asynchronous**: All calls go through message queue
-- **Serialization overhead**: Every data structure must be serialized/deserialized
-- **Event emitter pattern**: Uses `DeviceEventEmitter` for location updates
-- **Indirect callbacks**: Events broadcast to all JS listeners
-
-#### `react-native-nitro-geolocation` (Nitro/JSI)
-```
-┌─────────────┐
-│     JS      │
-└──────┬──────┘
-       │ direct memory access
-       ▼
-┌─────────────┐
-│  C++ (JSI)  │ ← Type-safe bindings
-└──────┬──────┘
-       │ direct function call
-       ▼
-┌─────────────┐
-│Kotlin/Swift │
-└─────────────┘
-```
-
-**Characteristics:**
-- **Synchronous capable**: Direct C++ function calls (getCurrentPosition still async due to GPS)
-- **Zero serialization**: Shared memory between JS and native
-- **Direct callbacks**: Native directly invokes JS functions via JSI
-- **Type-safe**: Compile-time type checking in C++
-
----
-
-## Method-by-Method Architecture Analysis
-
-### 1. `setRNConfiguration(config)`
-
-#### Original (`@react-native-community/geolocation`)
-```java
-// GeolocationModule.java
-@ReactMethod
-public void setConfiguration(ReadableMap config) {
-    mConfiguration = Configuration.fromReactMap(config);
-    // Bridge automatically handles JSON deserialization
-}
-```
-
-**Architecture:**
-- `@ReactMethod` annotation → Bridge registers method
-- `ReadableMap` → Deserialized from JS object
-- Configuration stored in Java object
-
-#### Nitro Version
-```kotlin
-// NitroGeolocation.kt
-override fun setRNConfiguration(config: RNConfigurationInternal) {
-    configuration = config
-}
-```
-
-**Architecture:**
-- Direct C++ → Kotlin call via HybridObject
-- `RNConfigurationInternal` is C++ struct, no serialization
-- Type-safe: Compile error if structure changes
-
-**Performance Difference:**
-- **Bridge**: ~0.5-2ms (JSON parse + bridge overhead)
-- **Nitro**: ~0.01-0.05ms (direct memory copy)
-- **Speedup**: ~50-200x faster
-
----
-
-### 2. `requestAuthorization(success, error)`
-
-#### Original Architecture
-```java
-// GeolocationModule.java
-@ReactMethod
-public void requestAuthorization(final Callback success, final Callback error) {
-    // Bridge wraps JS callbacks as Java Callback objects
-    PermissionsModule.requestPermissions(..., new PromiseImpl(success, error));
-}
-```
-
-**Call flow:**
-1. JS calls method → Bridge enqueues
-2. Bridge deserializes callbacks → Creates Java `Callback` wrapper
-3. Permission result → `success.invoke()`
-4. Bridge serializes result → Enqueues back to JS
-5. JS callback executed
-
-**Overhead per call**: ~1-3ms
-
-#### Nitro Architecture
-```kotlin
-// NitroGeolocation.kt
-override fun requestAuthorization(
-    success: (() -> Unit)?,
-    error: ((error: GeolocationError) -> Unit)?
-) {
-    requestAuthorizationHandler.execute(success, error)
-}
-```
-
-**Call flow:**
-1. JS calls method → Direct C++ function call
-2. C++ passes function references (no wrapping)
-3. Permission result → `success?.invoke()`
-4. JSI directly executes JS function (shared memory)
-
-**Overhead per call**: ~0.01-0.1ms
-
-**Key Difference:**
-- **Bridge**: Callbacks are serialized as IDs, invoked through message queue
-- **Nitro**: Callbacks are actual C++ function pointers to JS functions
-
----
-
-### 3. `getCurrentPosition(success, error, options)`
-
-#### Original Architecture
-```java
-// AndroidLocationManager.java
-public void getCurrentLocationData(ReadableMap options, Callback success, Callback error) {
-    // Single callback instance for this request
-    new SingleUpdateRequest(locationManager, provider, timeout, success, error).invoke(location);
-}
-
-private static class SingleUpdateRequest {
-    private final Callback mSuccess;
-    private final LocationListener mLocationListener = new LocationListener() {
-        public void onLocationChanged(Location location) {
-            mSuccess.invoke(locationToMap(location)); // Bridge serialization
-        }
-    };
-}
-```
-
-**Data flow:**
-```
-Android LocationManager
-  → LocationListener.onLocationChanged(Location)
-  → locationToMap(Location) // Create WritableMap
-  → success.invoke(WritableMap) // Serialize to JSON
-  → Bridge message queue
-  → JS deserialize JSON
-  → User callback
-```
-
-**Overhead**: ~1-3ms per location update
-
-#### Nitro Architecture
-```kotlin
-// GetCurrentPosition.kt
-fun execute(
-    success: (position: GeolocationResponse) -> Unit,
-    error: ((error: GeolocationError) -> Unit)?,
-    options: GeolocationOptions?
-) {
-    val listener = object : LocationListener {
-        override fun onLocationChanged(location: Location) {
-            success(locationToPosition(location)) // Direct JSI call
-        }
-    }
-    locationManager.requestLocationUpdates(provider, 100, 1f, listener, Looper.getMainLooper())
-}
-```
-
-**Data flow:**
-```
-Android LocationManager
-  → LocationListener.onLocationChanged(Location)
-  → locationToPosition(Location) // Create Kotlin data class
-  → success(GeolocationResponse) // Direct JSI invocation
-  → User callback (zero serialization)
-```
-
-**Overhead**: ~0.01-0.1ms per location update
-
-**Additional Improvements:**
-1. **Better location algorithm**: Implements `isBetterLocation()` from Android docs
-2. **Modern API support**: Uses `getCurrentLocation()` API on Android 11+
-3. **Timeout with fallback**: Returns last known location on timeout (configurable)
-
----
-
-### 4. `watchPosition(success, error, options)`
-
-This is where architectural differences are most significant.
-
-#### Original Architecture
-```java
-// AndroidLocationManager.java
-private final LocationListener mLocationListener = new LocationListener() {
-    public void onLocationChanged(Location location) {
-        // Broadcast to ALL JS listeners via event emitter
-        mReactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
-            .emit("geolocationDidChange", locationToMap(location));
-    }
-};
-
-public void startObserving(ReadableMap options) {
-    // Single global listener for ALL watches
-    locationManager.requestLocationUpdates(provider, 1000, distanceFilter, mLocationListener);
-}
-```
-
-**Architecture:**
-```
-┌──────────────────────────────┐
-│   Android LocationManager    │
-└──────────────┬───────────────┘
-               │ Single LocationListener
-               ▼
-┌──────────────────────────────┐
-│    mLocationListener         │
-└──────────────┬───────────────┘
-               │ emit("geolocationDidChange", location)
-               ▼
-┌──────────────────────────────┐
-│    DeviceEventEmitter        │ ← Serialize location to JSON
-└──────────────┬───────────────┘
-               │ Bridge
-               ▼
-┌──────────────────────────────┐
-│    JS EventEmitter           │
-└──────────────┬───────────────┘
-               │ Broadcast to ALL listeners
-               ├──────┬──────┬──────┐
-               ▼      ▼      ▼      ▼
-            watch1 watch2 watch3 watch4 (all receive same event)
-```
-
-**Problems:**
-1. **Single global listener**: Cannot have different options per watch
-2. **Broadcast overhead**: All watches receive updates even if they have different filters
-3. **JS-side filtering**: Each watch must filter events in JS
-4. **Memory**: Event emitter maintains listener registry in JS
-
-**Data flow per update:**
-```
-Location update (native)
-  → serialize to JSON (1-2ms)
-  → emit to bridge queue
-  → deserialize in JS (1-2ms)
-  → broadcast to N listeners (0.1ms × N)
-  → each listener filters/processes
-Total: ~2-5ms + (0.1ms × N listeners)
-```
-
-#### Nitro Architecture
-```kotlin
-// WatchPosition.kt
-class WatchPosition(private val reactContext: ReactApplicationContext) {
-    // Multiple watches, each with its own callback and options
-    private val watchCallbacks = ConcurrentHashMap<Int, WatchCallback>()
-    private val watchIdGenerator = AtomicInteger(0)
-
-    data class WatchCallback(
-        val success: (GeolocationResponse) -> Unit,
-        val error: ((GeolocationError) -> Unit)?,
-        val options: GeolocationOptions?
-    )
-
-    fun watch(success: ..., error: ..., options: ...): Int {
-        val watchId = watchIdGenerator.incrementAndGet()
-        watchCallbacks[watchId] = WatchCallback(success, error, options)
-
-        // Start location updates only when first watch is added
-        if (watchCallbacks.size == 1) {
-            startObserving(options)
-        }
-        return watchId
-    }
-
-    private val locationListener = object : LocationListener {
-        override fun onLocationChanged(location: Location) {
-            val position = locationToPosition(location)
-            // Direct callback to each watch
-            watchCallbacks.values.forEach { callback ->
-                callback.success(position)
-            }
-        }
-    }
-}
-```
-
-**Architecture:**
-```
-┌──────────────────────────────┐
-│   Android LocationManager    │
-└──────────────┬───────────────┘
-               │ Single LocationListener (lazy start)
-               ▼
-┌──────────────────────────────┐
-│    locationListener          │
-└──────────────┬───────────────┘
-               │ Direct loop over watchCallbacks
-               ├──────┬──────┬──────┐
-               ▼      ▼      ▼      ▼
-           watch1  watch2  watch3  watch4
-           (direct JSI invocation to each callback)
-```
-
-**Advantages:**
-1. **Native watch management**: watchId and callbacks stored in native `ConcurrentHashMap`
-2. **Direct callbacks**: Each watch callback invoked directly via JSI (no event emitter)
-3. **Thread-safe**: `ConcurrentHashMap` + `AtomicInteger` for concurrent access
-4. **Lazy lifecycle**: Start location updates on first watch, stop on last clearWatch
-5. **Per-watch options**: Can support different options per watch (future enhancement)
-
-**Data flow per update:**
-```
-Location update (native)
-  → locationToPosition() (create Kotlin object, ~0.01ms)
-  → forEach watch callback
-     → Direct JSI call (0.01ms per watch)
-Total: ~0.01ms + (0.01ms × N watches)
-```
-
-**Performance Comparison:**
-
-| Scenario | Bridge | Nitro | Speedup |
-|----------|--------|-------|---------|
-| 1 watch, 1 update/sec | ~3ms/update | ~0.02ms/update | **150x** |
-| 4 watches, 1 update/sec | ~5ms/update | ~0.05ms/update | **100x** |
-| 1 watch, 10 updates/sec | ~30ms/sec | ~0.2ms/sec | **150x** |
-| 4 watches, 10 updates/sec | ~50ms/sec | ~0.5ms/sec | **100x** |
-
----
-
-### 5. `clearWatch(watchId)`
-
-#### Original Architecture
-```javascript
-// JS side (GeolocationModule wraps this)
-let watchID = 0;
-const subscriptions = new Map();
-
-function watchPosition(success, error, options) {
-  const watchID = ++watchID;
-  const subscription = DeviceEventEmitter.addListener('geolocationDidChange', success);
-  subscriptions.set(watchID, subscription);
-  return watchID;
-}
-
-function clearWatch(watchID) {
-  const subscription = subscriptions.get(watchID);
-  subscription?.remove(); // Removes JS listener only
-  subscriptions.delete(watchID);
-}
-```
-
-**Architecture:**
-- watchId managed in JS
-- No native call to `clearWatch()`
-- Native listener keeps running until `stopObserving()` called
-
-#### Nitro Architecture
-```kotlin
-// WatchPosition.kt
-fun clearWatch(watchId: Int) {
-    watchCallbacks.remove(watchId)
-
-    // Automatically stop observing if no more watches
-    if (watchCallbacks.isEmpty()) {
-        stopObserving()
-    }
-}
-```
-
-**Architecture:**
-- watchId managed in native (Kotlin)
-- Direct removal from `ConcurrentHashMap`
-- Automatic cleanup: stops LocationManager when last watch removed
-
-**Key Difference:**
-- **Bridge**: JS-only cleanup, native keeps running
-- **Nitro**: Native cleanup + automatic resource management
-
----
-
-### 6. `stopObserving()`
-
-#### Original Architecture
-```java
-// AndroidLocationManager.java
-public void stopObserving() {
-    LocationManager locationManager = (LocationManager) mReactContext.getSystemService(Context.LOCATION_SERVICE);
-    locationManager.removeUpdates(mLocationListener);
-    mWatchedProvider = null;
-}
-```
-
-- Single global listener removed
-- All watches stopped at once
-- No cleanup of watch callbacks (handled in JS)
-
-#### Nitro Architecture
-```kotlin
-// WatchPosition.kt
-fun stopObserving() {
-    val locationManager = reactContext.getSystemService(Context.LOCATION_SERVICE) as? LocationManager
-
-    locationListener?.let { listener ->
-        locationManager?.removeUpdates(listener)
-    }
-
-    // Complete cleanup
-    locationListener = null
-    watchedProvider = null
-    currentOptions = null
-    watchCallbacks.clear()
-}
-```
-
-**Additional cleanup:**
-- All watch callbacks cleared from `ConcurrentHashMap`
-- Explicit null assignment for GC
-- Complete resource release
-
----
-
-## Overall Performance Summary
-
-### Latency Comparison
-
-| Operation | Bridge Overhead | Nitro Overhead | Speedup |
-|-----------|----------------|----------------|---------|
-| Method call (e.g., setRNConfiguration) | 0.5-2ms | 0.01-0.05ms | **50-200x** |
-| Callback invocation | 1-3ms | 0.01-0.1ms | **30-100x** |
-| Location update (single) | 2-4ms | 0.02-0.15ms | **100-200x** |
-| Location update (4 watches) | 4-6ms | 0.05-0.4ms | **80-120x** |
-
-### Memory Comparison
-
-| Component | Bridge | Nitro |
-|-----------|--------|-------|
-| Serialization buffers | ~1KB per call | 0 bytes (shared memory) |
-| Event emitter registry | ~100 bytes per listener | 0 bytes (no event emitter) |
-| Watch callback storage | JS Map (~50 bytes/watch) | ConcurrentHashMap (~40 bytes/watch) |
-| JSON parsing overhead | ~500 bytes per location | 0 bytes |
-
-**Total memory savings**: ~2-5KB per active watch session
-
-### Thread Safety
-
-| Aspect | Bridge | Nitro |
-|--------|--------|-------|
-| Concurrent watches | ✅ Handled by React Native bridge | ✅ ConcurrentHashMap + AtomicInteger |
-| Callback invocation | ⚠️ Queued (serialized execution) | ✅ Thread-safe direct invocation |
-| Resource cleanup | ⚠️ JS GC dependent | ✅ Explicit native cleanup |
-
----
-
-## Battery Impact
-
-### Bridge Architecture
-```
-Location update (every 1s)
-  ├─ GPS wakes CPU (~5mW)
-  ├─ Serialize to JSON (~2mW for 2ms)
-  ├─ Bridge context switch (~1mW)
-  ├─ Deserialize in JS (~2mW for 2ms)
-  └─ JS callback execution (~1mW)
-Total: ~11mW per update = 39.6J per hour
-```
-
-### Nitro Architecture
-```
-Location update (every 1s)
-  ├─ GPS wakes CPU (~5mW)
-  ├─ Direct callback (~0.1mW for 0.02ms)
-  └─ JS callback execution (~1mW)
-Total: ~6.1mW per update = 22J per hour
-```
-
-**Battery savings**: ~45% less power consumption for continuous tracking
-
----
-
-## Build Size Comparison
-
-| Component | Bridge | Nitro |
-|-----------|--------|-------|
-| Java/Kotlin code | ~15KB | ~18KB |
-| C++ code | 0KB | ~25KB (Nitro runtime) |
-| JavaScript | ~8KB | ~6KB (less event handling) |
-| **Total overhead** | ~23KB | ~49KB |
-
-**Note**: Nitro adds ~26KB, but this is one-time cost shared across all Nitro modules in your app.
-
----
-
-## Type Safety
-
-### Bridge (Runtime Type Checking)
-```typescript
-// ❌ No compile-time safety
-getCurrentPosition(
-  (position) => {
-    console.log(position.coords.latitude); // Could be undefined at runtime
-  }
-);
-```
-
-### Nitro (Compile-Time Type Checking)
-```typescript
-// ✅ Full TypeScript + C++ type safety
-getCurrentPosition(
-  (position: GeolocationResponse) => {
-    console.log(position.coords.latitude); // Guaranteed to exist
-  }
-);
-```
-
-C++ generates type-safe bindings:
-```cpp
-// Generated by Nitrogen
-struct GeolocationResponse {
-  GeolocationCoordinates coords;
-  double timestamp;
-};
-```
-
-**Benefit**: Catch type errors at compile time, not in production.
-
----
-
-## Migration Guide
-
-Since this is a **drop-in replacement** for `@react-native-community/geolocation`, migration is trivial:
-
-```diff
-- import Geolocation from '@react-native-community/geolocation';
-+ import Geolocation from 'react-native-nitro-geolocation';
-
-// API is 100% identical
-Geolocation.watchPosition(
-  position => console.log(position),
-  error => console.error(error),
-  { enableHighAccuracy: true }
-);
-```
-
-**No code changes required!**
-
----
-
-## Why Choose Nitro Geolocation?
-
-1. **🚀 Performance**: 50-200x faster method calls, 100-200x faster location updates
-2. **🔋 Battery**: ~45% less power consumption for continuous tracking
-3. **🧵 Thread Safety**: Modern concurrent data structures (ConcurrentHashMap)
-4. **🎯 Type Safety**: Compile-time type checking via C++
-5. **🧹 Resource Management**: Automatic cleanup, explicit GC hints
-6. **📦 Drop-in Replacement**: Zero migration cost
-7. **🏗️ Modern Architecture**: JSI-based, ready for React Native's future
-
----
-
-## Benchmarks
-
-See [BENCHMARKS.md](./BENCHMARKS.md) for detailed performance measurements.
-
----
-
-## License
-
-MIT
-
-Original work Copyright (c) 2022-present, React Native Community
-Modified work Copyright (c) 2025, jingjing2222
-
-This project is a Nitro Modules port of `@react-native-community/geolocation`.