@umituz/react-native-location 1.0.0

package/src/domain/entities/Location.ts

@@ -0,0 +1,175 @@
+/**
+ * Location Domain Entities
+ *
+ * Core location types and interfaces for device location services
+ * and geolocation features
+ *
+ * Features:
+ * - Current location retrieval with GPS
+ * - Location permission management
+ * - Location caching (15-minute cache)
+ * - Reverse geocoding (address lookup)
+ * - Fallback strategies (High → Balanced → Cached)
+ * - Platform-aware (iOS/Android only, no web)
+ *
+ * Dependencies:
+ * - expo-location (GPS and permissions)
+ * - AsyncStorage (location cache)
+ */
+
+/**
+ * Location data with coordinates and optional address
+ */
+export interface LocationData {
+  /** Latitude coordinate */
+  latitude: number;
+
+  /** Longitude coordinate */
+  longitude: number;
+
+  /** Human-readable address (reverse geocoded) */
+  address?: string;
+
+  /** Timestamp when location was captured (milliseconds since epoch) */
+  timestamp: number;
+
+  /** GPS accuracy in meters (lower is better) */
+  accuracy?: number;
+
+  /** Whether this location is from cache (not fresh GPS) */
+  isCached?: boolean;
+}
+
+/**
+ * Location permission status
+ */
+export type LocationPermissionStatus = 'granted' | 'denied' | 'unknown';
+
+/**
+ * Location accuracy levels for GPS
+ */
+export enum LocationAccuracy {
+  /** Lowest accuracy, fastest response, battery-friendly */
+  Lowest = 1,
+
+  /** Low accuracy */
+  Low = 2,
+
+  /** Balanced accuracy (recommended for most use cases) */
+  Balanced = 3,
+
+  /** High accuracy (GPS-based) */
+  High = 4,
+
+  /** Highest accuracy (most battery-intensive) */
+  Highest = 5,
+
+  /** Best for navigation (continuous high accuracy) */
+  BestForNavigation = 6,
+}
+
+/**
+ * Location cache configuration
+ */
+export interface LocationCacheConfig {
+  /** Cache duration in milliseconds (default: 15 minutes) */
+  duration: number;
+
+  /** Storage key for cached location */
+  storageKey: string;
+}
+
+/**
+ * Location retrieval configuration
+ */
+export interface LocationRetrievalConfig {
+  /** Timeout for high accuracy request (milliseconds) */
+  highAccuracyTimeout: number;
+
+  /** Timeout for balanced accuracy request (milliseconds) */
+  balancedAccuracyTimeout: number;
+
+  /** Whether to enable reverse geocoding (address lookup) */
+  enableGeocoding: boolean;
+}
+
+/**
+ * Cached location storage format
+ */
+export interface CachedLocation {
+  /** Location data */
+  data: LocationData;
+
+  /** Timestamp when location was cached (milliseconds since epoch) */
+  cachedAt: number;
+}
+
+/**
+ * Location Service Interface
+ * Defines all location-related operations
+ */
+export interface ILocationService {
+  /**
+   * Request location permissions from user
+   * @returns Promise resolving to true if granted, false otherwise
+   */
+  requestPermissions(): Promise<boolean>;
+
+  /**
+   * Check if location permissions are granted
+   * @returns Promise resolving to true if granted, false otherwise
+   */
+  hasPermissions(): Promise<boolean>;
+
+  /**
+   * Get current permission status without requesting
+   * @returns Current permission status ('granted' | 'denied' | 'unknown')
+   */
+  getPermissionStatus(): LocationPermissionStatus;
+
+  /**
+   * Get current device location with fallback strategies
+   * Priority: High accuracy → Balanced accuracy → Cached location → null
+   * @returns Promise resolving to LocationData or null if unavailable
+   */
+  getCurrentLocation(): Promise<LocationData | null>;
+
+  /**
+   * Get cached location if available and not expired
+   * @returns Cached location or null
+   */
+  getCachedLocation(): LocationData | null;
+
+  /**
+   * Format location for display (address or coordinates)
+   * @param location - LocationData to format
+   * @returns Formatted string (address or "lat, lng")
+   */
+  formatLocation(location: LocationData): string;
+
+  /**
+   * Check if location services are available on this platform
+   * @returns True if available (iOS/Android), false otherwise (web)
+   */
+  isLocationAvailable(): boolean;
+}
+
+/**
+ * Location service constants
+ */
+export const LOCATION_CONSTANTS = {
+  /** Cache duration: 15 minutes */
+  CACHE_DURATION: 15 * 60 * 1000,
+
+  /** High accuracy timeout: 15 seconds */
+  HIGH_ACCURACY_TIMEOUT: 15000,
+
+  /** Balanced accuracy timeout: 8 seconds */
+  BALANCED_ACCURACY_TIMEOUT: 8000,
+
+  /** AsyncStorage key for cached location */
+  CACHE_KEY: '@location_cache',
+
+  /** Coordinate decimal precision for display */
+  COORDINATE_PRECISION: 4,
+} as const;

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Location Domain - Barrel Export
+ *
+ * Global infrastructure domain for device location services and geolocation
+ *
+ * Features:
+ * - Current location retrieval with GPS
+ * - Location permission management (iOS/Android)
+ * - 15-minute location caching for performance
+ * - Reverse geocoding (coordinates → address)
+ * - Multi-tier accuracy fallback (High → Balanced → Cached)
+ * - Platform-aware (iOS/Android only, no web support)
+ * - Silent failures (no console logging)
+ *
+ * Dependencies:
+ * - expo-location (GPS and permissions API)
+ * - AsyncStorage (cache persistence)
+ *
+ * USAGE:
+ * ```typescript
+ * // Recommended: Use hook in components
+ * import { useLocation } from '@umituz/react-native-location';
+ *
+ * const MyComponent = () => {
+ *   const {
+ *     location,
+ *     loading,
+ *     hasPermission,
+ *     requestPermission,
+ *     getCurrentLocation,
+ *     formatLocation,
+ *   } = useLocation();
+ *
+ *   useEffect(() => {
+ *     // Auto-fetch on mount
+ *     getCurrentLocation();
+ *   }, []);
+ *
+ *   if (loading) return <LoadingIndicator />;
+ *
+ *   return (
+ *     <View>
+ *       {location && (
+ *         <>
+ *           <Text>Location: {formatLocation(location)}</Text>
+ *           <Text>Lat: {location.latitude}</Text>
+ *           <Text>Lng: {location.longitude}</Text>
+ *           {location.accuracy && (
+ *             <Text>Accuracy: {location.accuracy.toFixed(0)}m</Text>
+ *           )}
+ *         </>
+ *       )}
+ *       <AtomicButton onPress={getCurrentLocation}>
+ *         Refresh Location
+ *       </AtomicButton>
+ *     </View>
+ *   );
+ * };
+ *
+ * // Alternative: Use service directly (for non-component code)
+ * import { locationService } from '@umituz/react-native-location';
+ *
+ * const location = await locationService.getCurrentLocation();
+ * if (location) {
+ *   console.log(locationService.formatLocation(location));
+ * }
+ * ```
+ *
+ * PLATFORM SUPPORT:
+ * - ✅ iOS: Full support (GPS, permissions, geocoding)
+ * - ✅ Android: Full support (GPS, permissions, geocoding)
+ * - ❌ Web: Not supported (returns null)
+ *
+ * PERMISSION FLOW:
+ * 1. Check: hasPermissions() → true/false
+ * 2. Request: requestPermissions() → true/false
+ * 3. Retrieve: getCurrentLocation() → LocationData | null
+ *
+ * FALLBACK STRATEGY:
+ * 1. High accuracy GPS (15s timeout)
+ * 2. Balanced accuracy GPS (8s timeout)
+ * 3. Cached location (15min cache)
+ * 4. null (no location available)
+ *
+ * CACHING:
+ * - Duration: 15 minutes
+ * - Storage: AsyncStorage (@location_cache)
+ * - Auto-refresh: On getCurrentLocation() if expired
+ */
+
+// Domain Entities
+export type {
+  LocationData,
+  LocationPermissionStatus,
+  CachedLocation,
+  LocationCacheConfig,
+  LocationRetrievalConfig,
+  ILocationService,
+} from './domain/entities/Location';
+export { LocationAccuracy, LOCATION_CONSTANTS } from './domain/entities/Location';
+
+// Infrastructure Services
+export { locationService } from './infrastructure/services/LocationService';
+
+// Presentation Hooks
+export { useLocation } from './presentation/hooks/useLocation';
+export type { UseLocationReturn } from './presentation/hooks/useLocation';

package/src/infrastructure/services/LocationService.ts

@@ -0,0 +1,298 @@
+/**
+ * Location Service Implementation
+ *
+ * Handles device location retrieval, permissions, caching, and reverse geocoding
+ * with intelligent fallback strategies
+ *
+ * Features:
+ * - Multi-tier accuracy fallback (High → Balanced → Cached)
+ * - 15-minute location caching for performance
+ * - Reverse geocoding with coordinate fallback
+ * - Platform detection (iOS/Android only, no web)
+ * - Silent failures (no console logging)
+ * - AsyncStorage persistence
+ *
+ * Dependencies:
+ * - expo-location (GPS and permissions API)
+ * - AsyncStorage (cache persistence)
+ *
+ * USAGE:
+ * ```typescript
+ * import { locationService } from '@umituz/react-native-location';
+ *
+ * // Check permission
+ * const hasPermission = await locationService.hasPermissions();
+ *
+ * // Request permission if needed
+ * if (!hasPermission) {
+ *   const granted = await locationService.requestPermissions();
+ * }
+ *
+ * // Get current location
+ * const location = await locationService.getCurrentLocation();
+ * if (location) {
+ *   console.log(location.latitude, location.longitude);
+ *   console.log(locationService.formatLocation(location));
+ * }
+ * ```
+ */
+
+import { Platform } from 'react-native';
+import * as Location from 'expo-location';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import type {
+  LocationData,
+  LocationPermissionStatus,
+  CachedLocation,
+  ILocationService,
+} from '../../domain/entities/Location';
+import { LOCATION_CONSTANTS } from '../../domain/entities/Location';
+
+class LocationService implements ILocationService {
+  private cachedLocation: LocationData | null = null;
+  private cachedAt: number = 0;
+  private permissionStatus: LocationPermissionStatus = 'unknown';
+
+  constructor() {
+    this.loadCachedLocation();
+  }
+
+  /**
+   * Check if location services are available on this platform
+   */
+  isLocationAvailable(): boolean {
+    // Location services not available on web
+    if (Platform.OS === 'web') {
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Load cached location from AsyncStorage
+   */
+  private async loadCachedLocation(): Promise<void> {
+    try {
+      const cached = await AsyncStorage.getItem(LOCATION_CONSTANTS.CACHE_KEY);
+      if (cached) {
+        const parsed: CachedLocation = JSON.parse(cached);
+        if (Date.now() - parsed.cachedAt < LOCATION_CONSTANTS.CACHE_DURATION) {
+          this.cachedLocation = parsed.data;
+          this.cachedAt = parsed.cachedAt;
+        } else {
+          // Expired cache, remove it
+          await AsyncStorage.removeItem(LOCATION_CONSTANTS.CACHE_KEY);
+        }
+      }
+    } catch (error) {
+      // Silent failure on cache load
+    }
+  }
+
+  /**
+   * Save location to cache (AsyncStorage + memory)
+   */
+  private async saveCachedLocation(location: LocationData): Promise<void> {
+    try {
+      const cached: CachedLocation = {
+        data: location,
+        cachedAt: Date.now(),
+      };
+      this.cachedLocation = location;
+      this.cachedAt = cached.cachedAt;
+      await AsyncStorage.setItem(
+        LOCATION_CONSTANTS.CACHE_KEY,
+        JSON.stringify(cached)
+      );
+    } catch (error) {
+      // Silent failure on cache save
+    }
+  }
+
+  /**
+   * Get cached location if available and not expired
+   */
+  getCachedLocation(): LocationData | null {
+    if (!this.cachedLocation) {
+      return null;
+    }
+    const age = Date.now() - this.cachedAt;
+    if (age < LOCATION_CONSTANTS.CACHE_DURATION) {
+      return { ...this.cachedLocation, isCached: true };
+    }
+    return null;
+  }
+
+  /**
+   * Request location permissions from user
+   */
+  async requestPermissions(): Promise<boolean> {
+    if (!this.isLocationAvailable()) {
+      this.permissionStatus = 'denied';
+      return false;
+    }
+
+    try {
+      const { status } = await Location.requestForegroundPermissionsAsync();
+      this.permissionStatus = status === 'granted' ? 'granted' : 'denied';
+      return status === 'granted';
+    } catch (error) {
+      this.permissionStatus = 'denied';
+      return false;
+    }
+  }
+
+  /**
+   * Check if location permissions are granted
+   */
+  async hasPermissions(): Promise<boolean> {
+    if (!this.isLocationAvailable()) {
+      return false;
+    }
+
+    // Use cached permission status if available
+    if (this.permissionStatus !== 'unknown') {
+      return this.permissionStatus === 'granted';
+    }
+
+    try {
+      const { status } = await Location.getForegroundPermissionsAsync();
+      this.permissionStatus = status === 'granted' ? 'granted' : 'denied';
+      return status === 'granted';
+    } catch (error) {
+      this.permissionStatus = 'denied';
+      return false;
+    }
+  }
+
+  /**
+   * Get permission status without requesting
+   */
+  getPermissionStatus(): LocationPermissionStatus {
+    return this.permissionStatus;
+  }
+
+  /**
+   * Get current location with fallback strategies
+   * Priority: High accuracy → Balanced accuracy → Cached location → null
+   */
+  async getCurrentLocation(): Promise<LocationData | null> {
+    if (!this.isLocationAvailable()) {
+      return null;
+    }
+
+    try {
+      const hasPermission = await this.hasPermissions();
+
+      if (!hasPermission) {
+        const granted = await this.requestPermissions();
+        if (!granted) {
+          // Return cached location if available
+          return this.getCachedLocation();
+        }
+      }
+
+      // Try high accuracy first
+      let locationData = await this.getLocationWithAccuracy(
+        Location.Accuracy.High,
+        LOCATION_CONSTANTS.HIGH_ACCURACY_TIMEOUT
+      );
+
+      // Fallback to balanced accuracy if high accuracy fails
+      if (!locationData) {
+        locationData = await this.getLocationWithAccuracy(
+          Location.Accuracy.Balanced,
+          LOCATION_CONSTANTS.BALANCED_ACCURACY_TIMEOUT
+        );
+      }
+
+      // Fallback to cached location
+      if (!locationData) {
+        return this.getCachedLocation();
+      }
+
+      // Cache the new location
+      await this.saveCachedLocation(locationData);
+
+      return locationData;
+    } catch (error) {
+      // Return cached location as last resort
+      return this.getCachedLocation();
+    }
+  }
+
+  /**
+   * Get location with specific accuracy and timeout
+   */
+  private async getLocationWithAccuracy(
+    accuracy: Location.LocationAccuracy,
+    timeout: number
+  ): Promise<LocationData | null> {
+    try {
+      const location = (await Promise.race([
+        Location.getCurrentPositionAsync({ accuracy }),
+        new Promise<null>((_, reject) =>
+          setTimeout(() => reject(new Error('Timeout')), timeout)
+        ),
+      ])) as Location.LocationObject | null;
+
+      if (!location) {
+        return null;
+      }
+
+      const locationData: LocationData = {
+        latitude: location.coords.latitude,
+        longitude: location.coords.longitude,
+        timestamp: Date.now(),
+        accuracy: location.coords.accuracy ?? undefined,
+        isCached: false,
+      };
+
+      // Try to get address (reverse geocoding)
+      try {
+        const addresses = await Location.reverseGeocodeAsync({
+          latitude: location.coords.latitude,
+          longitude: location.coords.longitude,
+        });
+
+        if (addresses && addresses.length > 0) {
+          const address = addresses[0];
+          const addressParts = [address.street, address.city, address.region].filter(
+            Boolean
+          );
+
+          locationData.address =
+            addressParts.join(', ') || 'Unknown location';
+        }
+      } catch (error) {
+        // Fallback to coordinates if geocoding fails
+        locationData.address = `${location.coords.latitude.toFixed(
+          LOCATION_CONSTANTS.COORDINATE_PRECISION
+        )}, ${location.coords.longitude.toFixed(LOCATION_CONSTANTS.COORDINATE_PRECISION)}`;
+      }
+
+      return locationData;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Format location for display (address or coordinates)
+   */
+  formatLocation(location: LocationData): string {
+    if (location.address) {
+      return location.address;
+    }
+    return `${location.latitude.toFixed(
+      LOCATION_CONSTANTS.COORDINATE_PRECISION
+    )}, ${location.longitude.toFixed(LOCATION_CONSTANTS.COORDINATE_PRECISION)}`;
+  }
+}
+
+/**
+ * Singleton instance
+ * Use this for all location operations
+ */
+export const locationService = new LocationService();