Merge pull request #16 from gabriel-sisjr/feature/play-services-properties

Feature - Extending Coords object with all Play-Services-Location properties

Author: gabriel-sisjr

CHANGELOG.md

@@ -5,6 +5,108 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-11-14
+
+### Added
+
+- 📍 **Extended Location Properties**: Full support for all location data from play-services-location:21.3.0
+  - `accuracy` - Horizontal accuracy in meters
+  - `altitude` - Altitude in meters above sea level
+  - `speed` - Speed in meters per second
+  - `bearing` - Bearing in degrees (0-360)
+  - `verticalAccuracyMeters` - Vertical accuracy in meters (Android API 26+)
+  - `speedAccuracyMetersPerSecond` - Speed accuracy in meters per second (Android API 26+)
+  - `bearingAccuracyDegrees` - Bearing accuracy in degrees (Android API 26+)
+  - `elapsedRealtimeNanos` - Elapsed realtime in nanoseconds since system boot
+  - `provider` - Location provider (gps, network, passive, etc.)
+  - `isFromMockProvider` - Whether the location is from a mock provider (Android API 18+)
+  - All properties are optional and only included when available from the location provider
+
+- 🛠️ **Utility Functions**: New utility module for object manipulation
+  - `extractDefinedProperties()` - Generic function to extract all defined properties from objects
+  - Located in `src/utils/objectUtils.ts` for reusability across the codebase
+  - Automatically handles optional properties without manual field listing
+
+- 📱 **Enhanced Example App**: Updated example app to demonstrate extended location properties
+  - Displays all available location properties in real-time
+  - Shows formatted values (speed in km/h, elapsed time in ms, etc.)
+  - Visual separation between required and optional properties
+  - Demonstrates proper usage of extended location data
+
+### Changed
+
+- 🔧 **TypeScript Interfaces**: Extended `Coords` and `LocationUpdateEvent` interfaces
+  - Added 10 new optional properties with full JSDoc documentation
+  - Maintains backward compatibility (all new fields are optional)
+  - Type-safe access to all location data from play-services-location API
+
+- 🔄 **Hook Implementation**: Enhanced `useLocationUpdates` hook
+  - Automatically extracts and includes all available location properties
+  - Uses generic utility function for property extraction
+  - No manual field mapping required for future property additions
+
+- 📦 **Native Android Module**: Extended LocationService and LocationStorage
+  - `LocationService.handleLocation()` now extracts all available location data
+  - `LocationService.sendLocationUpdateEvent()` includes all properties in events
+  - `LocationStorage.saveLocation()` stores all available properties
+  - `LocationStorage.getLocations()` returns all stored properties
+  - Proper handling of API-level specific properties (Android 18+, 26+)
+
+### Technical Details
+
+**File Changes:**
+- `android/src/main/java/com/backgroundlocation/LocationService.kt`: Extended to extract and emit all location properties
+- `android/src/main/java/com/backgroundlocation/LocationStorage.kt`: Extended to save and retrieve all location properties
+- `src/types/tracking.ts`: Added optional properties to `Coords` and `LocationUpdateEvent` interfaces
+- `src/hooks/useLocationUpdates.ts`: Enhanced to map all properties using `extractDefinedProperties`
+- `src/utils/objectUtils.ts`: New utility module for generic property extraction
+- `example/src/App.tsx`: Updated to display all location properties
+- `example/src/styles.ts`: Added styles for additional properties display
+
+**Architecture:**
+- Generic property extraction eliminates manual field mapping
+- Future-proof design automatically includes new properties
+- Type-safe access to all location data
+- Backward compatible (existing code continues to work)
+- Proper handling of optional and API-level specific properties
+
+### Migration Guide
+
+If upgrading from 0.4.0:
+
+**No Breaking Changes** - All existing code continues to work without modifications.
+
+**New Features Available:**
+
+```typescript
+// Existing code still works
+const { locations } = useLocationUpdates();
+locations.forEach((location) => {
+  console.log(location.latitude);
+  console.log(location.longitude);
+  console.log(location.timestamp);
+});
+
+// New properties are now available (when provided by location provider)
+locations.forEach((location) => {
+  if (location.accuracy !== undefined) {
+    console.log(`Accuracy: ${location.accuracy} meters`);
+  }
+  if (location.speed !== undefined) {
+    console.log(`Speed: ${location.speed} m/s`);
+  }
+  if (location.altitude !== undefined) {
+    console.log(`Altitude: ${location.altitude} meters`);
+  }
+  // ... and more properties
+});
+```
+
+**Best Practices:**
+- Always check for `undefined` before using optional properties
+- Properties may not be available on all devices or Android versions
+- Some properties require specific Android API levels (18+, 26+)
+
 ## [0.4.0] - 2025-11-05
 
 ### Added

README.md

@@ -157,7 +157,15 @@ function TrackingScreen() {
       <Text>Status: {isTracking ? 'Tracking' : 'Stopped'}</Text>
       <Text>Locations: {locations.length}</Text>
       {lastLocation && (
-        <Text>Last: {lastLocation.latitude}, {lastLocation.longitude}</Text>
+        <>
+          <Text>Last: {lastLocation.latitude}, {lastLocation.longitude}</Text>
+          {lastLocation.accuracy !== undefined && (
+            <Text>Accuracy: {lastLocation.accuracy.toFixed(2)} m</Text>
+          )}
+          {lastLocation.speed !== undefined && (
+            <Text>Speed: {(lastLocation.speed * 3.6).toFixed(2)} km/h</Text>
+          )}
+        </>
       )}
       <Button
         title={isTracking ? 'Stop' : 'Start'}
@@ -192,7 +200,15 @@ function LiveTrackingScreen() {
     <View>
       <Text>Locations: {locations.length}</Text>
       {lastLocation && (
-        <Text>Last: {lastLocation.latitude}, {lastLocation.longitude}</Text>
+        <>
+          <Text>Last: {lastLocation.latitude}, {lastLocation.longitude}</Text>
+          {lastLocation.accuracy !== undefined && (
+            <Text>Accuracy: {lastLocation.accuracy.toFixed(2)} m</Text>
+          )}
+          {lastLocation.speed !== undefined && (
+            <Text>Speed: {(lastLocation.speed * 3.6).toFixed(2)} km/h</Text>
+          )}
+        </>
       )}
     </View>
   );
@@ -245,6 +261,18 @@ locations.forEach((location) => {
   console.log(location.latitude); // string
   console.log(location.longitude); // string
   console.log(location.timestamp); // number (Unix timestamp in ms)
+  
+  // Extended properties (optional, check for undefined)
+  if (location.accuracy !== undefined) {
+    console.log(`Accuracy: ${location.accuracy} meters`);
+  }
+  if (location.speed !== undefined) {
+    console.log(`Speed: ${location.speed} m/s`);
+  }
+  if (location.altitude !== undefined) {
+    console.log(`Altitude: ${location.altitude} meters`);
+  }
+  // ... and more properties available
 });
 
 // Stop tracking
@@ -329,15 +357,25 @@ Retrieves all stored location points for a specific trip.
 - **Parameters:**
   - `tripId`: The trip identifier.
 
-- **Returns:** Promise resolving to array of location coordinates:
+- **Returns:** Promise resolving to array of location coordinates with extended properties:
 
   ```typescript
   {
     latitude: string; // Latitude as string
     longitude: string; // Longitude as string
     timestamp: number; // Unix timestamp in milliseconds
-  }
-  [];
+    // Extended properties (optional, available when provided by location provider)
+    accuracy?: number; // Horizontal accuracy in meters
+    altitude?: number; // Altitude in meters above sea level
+    speed?: number; // Speed in meters per second
+    bearing?: number; // Bearing in degrees (0-360)
+    verticalAccuracyMeters?: number; // Vertical accuracy (Android API 26+)
+    speedAccuracyMetersPerSecond?: number; // Speed accuracy (Android API 26+)
+    bearingAccuracyDegrees?: number; // Bearing accuracy (Android API 26+)
+    elapsedRealtimeNanos?: number; // Elapsed realtime in nanoseconds
+    provider?: string; // Location provider (gps, network, passive, etc.)
+    isFromMockProvider?: boolean; // Whether from mock provider (Android API 18+)
+  }[];
   ```
 
 - **Throws:**
@@ -361,9 +399,21 @@ Clears all stored location data for a specific trip.
 
 ```typescript
 interface Coords {
-  latitude: string;
-  longitude: string;
-  timestamp: number;
+  latitude: string; // Latitude in decimal degrees
+  longitude: string; // Longitude in decimal degrees
+  timestamp: number; // Timestamp in milliseconds since Unix epoch
+  
+  // Extended location properties (optional, available when provided by location provider)
+  accuracy?: number; // Horizontal accuracy in meters
+  altitude?: number; // Altitude in meters above sea level
+  speed?: number; // Speed in meters per second
+  bearing?: number; // Bearing in degrees (0-360)
+  verticalAccuracyMeters?: number; // Vertical accuracy in meters (Android API 26+)
+  speedAccuracyMetersPerSecond?: number; // Speed accuracy in meters per second (Android API 26+)
+  bearingAccuracyDegrees?: number; // Bearing accuracy in degrees (Android API 26+)
+  elapsedRealtimeNanos?: number; // Elapsed realtime in nanoseconds since system boot
+  provider?: string; // Location provider (gps, network, passive, etc.)
+  isFromMockProvider?: boolean; // Whether the location is from a mock provider (Android API 18+)
 }
 
 interface TrackingStatus {

android/src/main/java/com/backgroundlocation/LocationService.kt

@@ -11,6 +11,7 @@ import android.os.Looper
 import androidx.core.app.NotificationCompat
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.google.android.gms.location.*
 
@@ -126,11 +127,51 @@ class LocationService : Service() {
 
   private fun handleLocation(location: Location) {
     currentTripId?.let { tripId ->
+      // Extract all available location data
+      val accuracy = if (location.hasAccuracy()) location.accuracy else null
+      val altitude = if (location.hasAltitude()) location.altitude else null
+      val speed = if (location.hasSpeed()) location.speed else null
+      val bearing = if (location.hasBearing()) location.bearing else null
+      
+      // API 26+ fields - check if values are valid (not NaN)
+      val verticalAccuracyMeters = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        val value = location.verticalAccuracyMeters
+        if (!value.isNaN()) value else null
+      } else null
+      
+      val speedAccuracyMetersPerSecond = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        val value = location.speedAccuracyMetersPerSecond
+        if (!value.isNaN()) value else null
+      } else null
+      
+      val bearingAccuracyDegrees = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        val value = location.bearingAccuracyDegrees
+        if (!value.isNaN()) value else null
+      } else null
+      
+      val elapsedRealtimeNanos = location.elapsedRealtimeNanos
+      val provider = location.provider
+      
+      // API 18+ field
+      val isFromMockProvider = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR2) {
+        location.isFromMockProvider
+      } else null
+      
       storage.saveLocation(
         tripId = tripId,
         latitude = location.latitude,
         longitude = location.longitude,
-        timestamp = location.time
+        timestamp = location.time,
+        accuracy = accuracy,
+        altitude = altitude,
+        speed = speed,
+        bearing = bearing,
+        verticalAccuracyMeters = verticalAccuracyMeters,
+        speedAccuracyMetersPerSecond = speedAccuracyMetersPerSecond,
+        bearingAccuracyDegrees = bearingAccuracyDegrees,
+        elapsedRealtimeNanos = elapsedRealtimeNanos,
+        provider = provider,
+        isFromMockProvider = isFromMockProvider
       )
 
       // Emit location update event to React Native
@@ -139,17 +180,12 @@ class LocationService : Service() {
   }
 
   /**
-   * Sends a location update event to React Native
+   * Sends a location update event to React Native with extended location data
    */
   private fun sendLocationUpdateEvent(tripId: String, location: Location) {
     reactContext?.let { context ->
       try {
-        val eventData = Arguments.createMap().apply {
-          putString("tripId", tripId)
-          putString("latitude", location.latitude.toString())
-          putString("longitude", location.longitude.toString())
-          putDouble("timestamp", location.time.toDouble())
-        }
+        val eventData = createLocationMap(tripId, location)
 
         context
           .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
@@ -160,6 +196,60 @@ class LocationService : Service() {
       }
     }
   }
+  
+  /**
+   * Creates a WritableMap with all available location data
+   */
+  private fun createLocationMap(tripId: String, location: Location): WritableMap {
+    val map = Arguments.createMap().apply {
+      putString("tripId", tripId)
+      putString("latitude", location.latitude.toString())
+      putString("longitude", location.longitude.toString())
+      putDouble("timestamp", location.time.toDouble())
+      
+      // Add optional fields if available
+      if (location.hasAccuracy()) {
+        putDouble("accuracy", location.accuracy.toDouble())
+      }
+      if (location.hasAltitude()) {
+        putDouble("altitude", location.altitude)
+      }
+      if (location.hasSpeed()) {
+        putDouble("speed", location.speed.toDouble())
+      }
+      if (location.hasBearing()) {
+        putDouble("bearing", location.bearing.toDouble())
+      }
+      
+      // API 26+ fields - check if values are valid (not NaN)
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        val verticalAccuracy = location.verticalAccuracyMeters
+        if (!verticalAccuracy.isNaN()) {
+          putDouble("verticalAccuracyMeters", verticalAccuracy.toDouble())
+        }
+        
+        val speedAccuracy = location.speedAccuracyMetersPerSecond
+        if (!speedAccuracy.isNaN()) {
+          putDouble("speedAccuracyMetersPerSecond", speedAccuracy.toDouble())
+        }
+        
+        val bearingAccuracy = location.bearingAccuracyDegrees
+        if (!bearingAccuracy.isNaN()) {
+          putDouble("bearingAccuracyDegrees", bearingAccuracy.toDouble())
+        }
+      }
+      
+      // Always available fields
+      putDouble("elapsedRealtimeNanos", location.elapsedRealtimeNanos.toDouble())
+      location.provider?.let { putString("provider", it) }
+      
+      // API 18+ field
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR2) {
+        putBoolean("isFromMockProvider", location.isFromMockProvider)
+      }
+    }
+    return map
+  }
 
   private fun createNotificationChannel() {
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {