react-native-nitro-geolocation 0.1.0 → 0.1.1

package/README.md

@@ -1,598 +1,318 @@
 # 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++
+[![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)
 
 ---
 
-## 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
+## 📘 Documentation
+
+Full documentation available at:
+👉 [https://react-native-nitro-geolocation.pages.dev](https://react-native-nitro-geolocation.pages.dev)
 
 ---
 
-### 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
+## 🧭 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
 
 ---
 
-### 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)
+### ⚡ 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
 
 ---
 
-### 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** |
+## ⚡ 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
+~~~
 
 ---
 
-### 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
+### 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>
+~~~
 
 ---
 
-### 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
+### 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" />
+~~~
 
 ---
 
-## Overall Performance Summary
+### 4. Usage Example
 
-### Latency Comparison
+~~~tsx
+import Geolocation from 'react-native-nitro-geolocation';
 
-| 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** |
+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),
+);
+~~~
 
-### 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 |
+### Migrating from `@react-native-community/geolocation`
 
-**Total memory savings**: ~2-5KB per active watch session
+Nitro Geolocation is **100% API-compatible** with the original package.
+You can migrate simply by replacing imports:
 
-### Thread Safety
+~~~diff
+- import Geolocation from '@react-native-community/geolocation';
++ import Geolocation from 'react-native-nitro-geolocation';
+~~~
 
-| 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 |
+**Benefits:**
+- Better performance via JSI
+- Reduced bridge overhead
+- Improved permission consistency
+- Built-in TypeScript definitions
 
 ---
 
-## 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
+## 🧠 API Methods
+
+### Summary
+- `setRNConfiguration`
+- `requestAuthorization`
+- `getCurrentPosition`
+- `watchPosition`
+- `clearWatch`
+- `stopObserving`
 
 ---
 
-## Build Size Comparison
+### `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',
+});
 
-| Component | Bridge | Nitro |
-|-----------|--------|-------|
-| Java/Kotlin code | ~15KB | ~18KB |
-| C++ code | 0KB | ~25KB (Nitro runtime) |
-| JavaScript | ~8KB | ~6KB (less event handling) |
-| **Total overhead** | ~23KB | ~49KB |
+// recommended
+import { setRNConfiguration } from 'react-native-nitro-geolocation';
 
-**Note**: Nitro adds ~26KB, but this is one-time cost shared across all Nitro modules in your app.
+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)*
 
 ---
 
-## Type Safety
+### `requestAuthorization()`
 
-### Bridge (Runtime Type Checking)
-```typescript
-// ❌ No compile-time safety
-getCurrentPosition(
-  (position) => {
-    console.log(position.coords.latitude); // Could be undefined at runtime
-  }
-);
-```
+Requests location permission from the system.
 
-### Nitro (Compile-Time Type Checking)
-```typescript
-// ✅ Full TypeScript + C++ type safety
-getCurrentPosition(
-  (position: GeolocationResponse) => {
-    console.log(position.coords.latitude); // Guaranteed to exist
-  }
+~~~tsx
+import Geolocation from 'react-native-nitro-geolocation';
+
+Geolocation.requestAuthorization(
+  () => console.log('Permission granted'),
+  (error) => console.error('Permission error:', error),
 );
-```
 
-C++ generates type-safe bindings:
-```cpp
-// Generated by Nitrogen
-struct GeolocationResponse {
-  GeolocationCoordinates coords;
-  double timestamp;
-};
-```
+// recommended
+import { requestAuthorization } from 'react-native-nitro-geolocation';
 
-**Benefit**: Catch type errors at compile time, not in production.
+requestAuthorization(
+  () => console.log('Permission granted'),
+  (error) => console.error('Permission error:', error),
+);
+~~~
 
 ---
 
-## Migration Guide
+### `getCurrentPosition()`
 
-Since this is a **drop-in replacement** for `@react-native-community/geolocation`, migration is trivial:
+Retrieves the current device location once.
 
-```diff
-- import Geolocation from '@react-native-community/geolocation';
-+ import Geolocation from 'react-native-nitro-geolocation';
+~~~tsx
+import Geolocation from 'react-native-nitro-geolocation';
 
-// API is 100% identical
-Geolocation.watchPosition(
-  position => console.log(position),
-  error => console.error(error),
-  { enableHighAccuracy: true }
+Geolocation.getCurrentPosition(
+  (position) => console.log(position),
+  (error) => console.error(error),
+  { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 },
 );
-```
 
-**No code changes required!**
+// recommended
+import { getCurrentPosition } from 'react-native-nitro-geolocation';
+
+getCurrentPosition(
+  (position) => console.log(position),
+  (error) => console.error(error),
+  { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 },
+);
+~~~
 
 ---
 
-## Why Choose Nitro Geolocation?
+### `watchPosition()`
 
-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
+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';
 
-## Benchmarks
+const id = watchPosition(
+  (position) => console.log('Position:', position),
+  (error) => console.error(error),
+  { interval: 5000, distanceFilter: 10 },
+);
 
-See [BENCHMARKS.md](./BENCHMARKS.md) for detailed performance measurements.
+~~~
 
 ---
 
-## License
+### `clearWatch()`
+
+Stops watching location updates for a given watch ID.
 
-MIT
+~~~tsx
+import Geolocation from 'react-native-nitro-geolocation';
+Geolocation.clearWatch(id);
+
+// recommended
+import { clearWatch } from 'react-native-nitro-geolocation';
+clearWatch(id);
+~~~
+
+---
 
-Original work Copyright (c) 2022-present, React Native Community
-Modified work Copyright (c) 2025, jingjing2222
+## 🧪 Summary
 
-This project is a Nitro Modules port of `@react-native-community/geolocation`.
+**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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "⚡🚀Blazing-fast geolocation for React Native powered by Nitro Modules",
   "main": "src/index",
   "source": "src/index",