react-native-nitro-geolocation 0.1.2 → 0.2.0

package/src/compat/requestAuthorization.ts

@@ -0,0 +1,9 @@
+import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
+import type { GeolocationError } from "../types";
+
+export function requestAuthorization(
+  success?: () => void,
+  error?: (error: GeolocationError) => void
+): void {
+  NitroGeolocationHybridCompatObject.requestAuthorization(success, error);
+}

package/src/{setRNConfiguration.ts → compat/setRNConfiguration.ts}

@@ -1,6 +1,6 @@
-import type { RNConfigurationInternal } from "./NitroGeolocation.nitro";
-import { NitroGeolocationHybridObject } from "./NitroGeolocationModule";
-import type { GeolocationConfiguration } from "./types";
+import type { RNConfigurationInternal } from "../NitroGeolocationCompat.nitro";
+import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
+import type { GeolocationConfiguration } from "../types";
 
 // Mapping layer: convert "android" to "android_platform" for C++
 function mapConfigToInternal(
@@ -18,5 +18,7 @@ function mapConfigToInternal(
 }
 
 export function setRNConfiguration(config: GeolocationConfiguration): void {
-  NitroGeolocationHybridObject.setRNConfiguration(mapConfigToInternal(config));
+  NitroGeolocationHybridCompatObject.setRNConfiguration(
+    mapConfigToInternal(config)
+  );
 }

package/src/{stopObserving.ts → compat/stopObserving.ts}

@@ -1,5 +1,5 @@
 import { NitroModules } from "react-native-nitro-modules";
-import type { NitroGeolocation } from "./NitroGeolocation.nitro";
+import type { NitroGeolocationCompat } from "../NitroGeolocationCompat.nitro";
 
 /**
  * Stops observing all location updates.
@@ -7,6 +7,8 @@ import type { NitroGeolocation } from "./NitroGeolocation.nitro";
  */
 export function stopObserving(): void {
   const nitroGeolocation =
-    NitroModules.createHybridObject<NitroGeolocation>("NitroGeolocation");
+    NitroModules.createHybridObject<NitroGeolocationCompat>(
+      "NitroGeolocationCompat"
+    );
   nitroGeolocation.stopObserving();
 }

package/src/{watchPosition.ts → compat/watchPosition.ts}

@@ -1,10 +1,9 @@
-import { NitroModules } from "react-native-nitro-modules";
-import type { NitroGeolocation } from "./NitroGeolocation.nitro";
+import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
 import type {
   GeolocationError,
   GeolocationOptions,
   GeolocationResponse
-} from "./types";
+} from "../types";
 
 /**
  * Invokes the success callback whenever the location changes.
@@ -20,7 +19,9 @@ export function watchPosition(
   error?: (error: GeolocationError) => void,
   options?: GeolocationOptions
 ): number {
-  const nitroGeolocation =
-    NitroModules.createHybridObject<NitroGeolocation>("NitroGeolocation");
-  return nitroGeolocation.watchPosition(success, error, options);
+  return NitroGeolocationHybridCompatObject.watchPosition(
+    success,
+    error,
+    options
+  );
 }

package/src/components/GeolocationProvider.tsx

@@ -0,0 +1,91 @@
+import React, { createContext, useContext } from "react";
+import type { GeolocationClient } from "../GeolocationClient";
+
+/**
+ * Geolocation context value.
+ */
+export interface GeolocationContextValue {
+  client: GeolocationClient;
+}
+
+/**
+ * Geolocation context.
+ */
+const GeolocationContext = createContext<GeolocationContextValue | null>(null);
+
+/**
+ * Hook to access GeolocationClient from context.
+ * Throws error if used outside GeolocationClientProvider.
+ */
+export function useGeolocationClient(): GeolocationClient {
+  const context = useContext(GeolocationContext);
+
+  if (!context) {
+    throw new Error(
+      "useGeolocationClient must be used within GeolocationClientProvider. " +
+        "Wrap your component with <GeolocationClientProvider client={...}> at the root level."
+    );
+  }
+
+  return context.client;
+}
+
+/**
+ * Props for GeolocationProvider component.
+ */
+export interface GeolocationProviderProps {
+  /**
+   * GeolocationClient instance (required).
+   * Create with: new GeolocationClient({...config})
+   */
+  client: GeolocationClient;
+
+  /**
+   * Child components that can use geolocation hooks.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Provider component for GeolocationClient.
+ *
+ * This component should wrap your app at the root level.
+ * It provides a GeolocationClient instance to all child components via context.
+ *
+ * @example
+ * ```tsx
+ * // Create client instance
+ * const geolocationClient = new GeolocationClient({
+ *   authorizationLevel: 'whenInUse',
+ *   enableBackgroundLocationUpdates: false,
+ *   locationProvider: 'auto'
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <GeolocationClientProvider client={geolocationClient}>
+ *       <NavigationContainer>
+ *         <YourApp />
+ *       </NavigationContainer>
+ *     </GeolocationClientProvider>
+ *   );
+ * }
+ * ```
+ */
+export function GeolocationProvider({
+  client,
+  children
+}: GeolocationProviderProps) {
+  const value: GeolocationContextValue = {
+    client
+  };
+
+  return (
+    <GeolocationContext.Provider value={value}>
+      {children}
+    </GeolocationContext.Provider>
+  );
+}
+
+// Modern alias (preferred)
+export const GeolocationClientProvider = GeolocationProvider;

package/src/components/index.ts

@@ -0,0 +1,13 @@
+/**
+ * React components for geolocation.
+ */
+
+export {
+  GeolocationProvider,
+  GeolocationClientProvider,
+  useGeolocationClient
+} from "./GeolocationProvider";
+export type {
+  GeolocationProviderProps,
+  GeolocationContextValue
+} from "./GeolocationProvider";

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Modern React hooks for geolocation.
+ * These hooks provide a declarative, React-friendly API for location services.
+ */
+
+export * from "./useCheckPermission";
+export * from "./useRequestPermission";
+export * from "./useGetCurrentPosition";
+export * from "./useWatchPosition";

package/src/hooks/useCheckPermission.ts

@@ -0,0 +1,46 @@
+import type { PermissionStatus } from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+
+/**
+ * Hook that returns a function to check current location permission status.
+ * Does NOT request permission, only checks current state.
+ *
+ * Must be used within GeolocationClientProvider.
+ *
+ * @returns Object containing checkPermission function
+ *
+ * @example
+ * ```tsx
+ * const geolocationClient = new GeolocationClient({...config});
+ *
+ * function App() {
+ *   return (
+ *     <GeolocationClientProvider client={geolocationClient}>
+ *       <MyComponent />
+ *     </GeolocationClientProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { checkPermission } = useCheckPermission();
+ *
+ *   const handleCheck = async () => {
+ *     const status = await checkPermission();
+ *     if (status === 'granted') {
+ *       // Can use location
+ *     }
+ *   };
+ *
+ *   return <Button onPress={handleCheck} />;
+ * }
+ * ```
+ */
+export function useCheckPermission() {
+  const client = useGeolocationClient();
+
+  return {
+    checkPermission: (): Promise<PermissionStatus> => {
+      return client.checkPermission();
+    }
+  };
+}

package/src/hooks/useGetCurrentPosition.ts

@@ -0,0 +1,44 @@
+import type { LocationRequestOptions } from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+import type { GeolocationResponse } from "../types";
+
+/**
+ * Hook that returns a function to get current location (one-time request).
+ * The returned function throws error if permission denied, timeout, or unavailable.
+ *
+ * @returns Object containing getCurrentPosition function
+ * @throws LocationError with code and message
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { getCurrentPosition } = useGetCurrentPosition();
+ *
+ *   const handleGetLocation = async () => {
+ *     try {
+ *       const position = await getCurrentPosition({
+ *         enableHighAccuracy: true,
+ *         timeout: 15000,
+ *       });
+ *       console.log('Lat:', position.coords.latitude);
+ *       console.log('Lng:', position.coords.longitude);
+ *     } catch (error) {
+ *       console.error('Location error:', error.message);
+ *     }
+ *   };
+ *
+ *   return <Button onPress={handleGetLocation} />;
+ * }
+ * ```
+ */
+export function useGetCurrentPosition() {
+  const client = useGeolocationClient();
+
+  return {
+    getCurrentPosition: (
+      options?: LocationRequestOptions
+    ): Promise<GeolocationResponse> => {
+      return client.getCurrentPosition(options);
+    }
+  };
+}

package/src/hooks/useRequestPermission.ts

@@ -0,0 +1,38 @@
+import type { PermissionStatus } from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+
+/**
+ * Hook that returns a function to request location permission from the user.
+ * Shows system permission dialog if not yet determined.
+ *
+ * @returns Object containing requestPermission function
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { requestPermission } = useRequestPermission();
+ *
+ *   const handleRequest = async () => {
+ *     try {
+ *       const status = await requestPermission();
+ *       if (status === 'granted') {
+ *         console.log('Permission granted!');
+ *       }
+ *     } catch (error) {
+ *       console.error('Permission error:', error);
+ *     }
+ *   };
+ *
+ *   return <Button onPress={handleRequest} />;
+ * }
+ * ```
+ */
+export function useRequestPermission() {
+  const client = useGeolocationClient();
+
+  return {
+    requestPermission: (): Promise<PermissionStatus> => {
+      return client.requestPermission();
+    }
+  };
+}

package/src/hooks/useWatchPosition.ts

@@ -0,0 +1,127 @@
+import { useEffect, useRef, useState } from "react";
+import type {
+  LocationError,
+  LocationRequestOptions
+} from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+import type { GeolocationResponse } from "../types";
+
+/**
+ * Options for useWatchPosition hook.
+ */
+export interface UseWatchPositionOptions extends LocationRequestOptions {
+  /**
+   * Whether to actively watch for location updates.
+   * When false, watching is paused and cleanup is performed.
+   * @default false
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Hook for continuous location tracking.
+ * Automatically subscribes/unsubscribes based on component lifecycle.
+ *
+ * The subscription token is completely hidden from the user.
+ * Cleanup is automatic via useEffect.
+ *
+ * @param options - Location request options
+ * @returns Object containing current position data, error, and watching status
+ *
+ * @example
+ * ```tsx
+ * function LiveTracking() {
+ *   const { data, error, isWatching } = useWatchPosition({
+ *     enabled: true,
+ *     enableHighAccuracy: true,
+ *     distanceFilter: 10  // Update every 10 meters
+ *   });
+ *
+ *   if (!isWatching) return <Text>Not watching</Text>;
+ *   if (error) return <Text>Error: {error.message}</Text>;
+ *   if (!data) return <Text>Waiting for location...</Text>;
+ *
+ *   return (
+ *     <Text>
+ *       Current: {data.coords.latitude}, {data.coords.longitude}
+ *       Accuracy: {data.coords.accuracy}m
+ *     </Text>
+ *   );
+ * }
+ * ```
+ */
+export function useWatchPosition(options?: UseWatchPositionOptions) {
+  const client = useGeolocationClient();
+
+  const [data, setData] = useState<GeolocationResponse | null>(null);
+  const [isWatching, setIsWatching] = useState(false);
+
+  // Store subscription token (hidden from user!)
+  const tokenRef = useRef<string | null>(null);
+
+  // Track if component is mounted to prevent state updates after unmount
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    const enabled = options?.enabled ?? false;
+
+    if (!enabled) {
+      // Not enabled, ensure cleanup
+      if (tokenRef.current) {
+        client.unwatch(tokenRef.current);
+        tokenRef.current = null;
+      }
+      setIsWatching(false);
+      return;
+    }
+
+    // Start watching
+    setIsWatching(true);
+
+    const token = client.watchPosition(
+      (position: GeolocationResponse) => {
+        // Success callback
+        if (!isMountedRef.current) return;
+        setData(position);
+      },
+      (err: LocationError) => {
+        // Error callback - throw to be caught by Error Boundary
+        if (!isMountedRef.current) return;
+        throw new Error(err.message);
+      },
+      options
+    );
+
+    tokenRef.current = token;
+
+    // Cleanup function
+    return () => {
+      if (token) {
+        client.unwatch(token);
+      }
+    };
+  }, [
+    client,
+    options?.enabled,
+    options?.enableHighAccuracy,
+    options?.distanceFilter,
+    options?.interval,
+    options?.fastestInterval,
+    options?.timeout,
+    options?.maximumAge,
+    options?.useSignificantChanges
+  ]);
+
+  // Track mount status
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  return {
+    data,
+    isWatching
+  };
+}

package/src/index.tsx

@@ -1,34 +1,79 @@
-// Export methods
-export { clearWatch } from "./clearWatch";
-export { getCurrentPosition } from "./getCurrentPosition";
-export { requestAuthorization } from "./requestAuthorization";
-export { setRNConfiguration } from "./setRNConfiguration";
-export { stopObserving } from "./stopObserving";
-export { watchPosition } from "./watchPosition";
+/**
+ * Modern Geolocation API for React Native.
+ *
+ * This is the main entry point for the modern, React-friendly API.
+ * For legacy compatibility, use: import Geolocation from 'react-native-nitro-geolocation/compat'
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   GeolocationClient,
+ *   GeolocationClientProvider,
+ *   useRequestPermission,
+ *   useGetCurrentPosition,
+ *   useWatchPosition
+ * } from 'react-native-nitro-geolocation';
+ *
+ * // Create GeolocationClient instance
+ * const geolocationClient = new GeolocationClient({
+ *   authorizationLevel: 'whenInUse',
+ *   enableBackgroundLocationUpdates: false,
+ *   locationProvider: 'auto'
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <GeolocationClientProvider client={geolocationClient}>
+ *       <YourApp />
+ *     </GeolocationClientProvider>
+ *   );
+ * }
+ *
+ * function LocationButton() {
+ *   const { getCurrentPosition } = useGetCurrentPosition();
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   const handlePress = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const pos = await getCurrentPosition({ enableHighAccuracy: true });
+ *       console.log('Position:', pos);
+ *     } catch (error) {
+ *       console.error('Error:', error);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return <Button onPress={handlePress} disabled={loading} />;
+ * }
+ * ```
+ */
 
-// Default export for compatibility
-import { clearWatch } from "./clearWatch";
-import { getCurrentPosition } from "./getCurrentPosition";
-import { requestAuthorization } from "./requestAuthorization";
-import { setRNConfiguration } from "./setRNConfiguration";
-import { stopObserving } from "./stopObserving";
-import { watchPosition } from "./watchPosition";
+// Core
+export { GeolocationClient } from "./GeolocationClient";
+export type { GeolocationClientConfig } from "./GeolocationClient";
 
-const Geolocation = {
-  setRNConfiguration,
-  requestAuthorization,
-  getCurrentPosition,
-  watchPosition,
-  clearWatch,
-  stopObserving
-};
+// Components
+export * from "./components";
+
+// Hooks
+export * from "./hooks";
+
+// Types from Nitro spec
+export type {
+  PermissionStatus,
+  LocationRequestOptions,
+  LocationError
+} from "./NitroGeolocation.nitro";
 
-// Export types
 export type {
-  GeolocationConfiguration,
   GeolocationResponse,
-  GeolocationError,
-  GeolocationOptions
+  GeolocationCoordinates,
+  AuthorizationLevel,
+  LocationProvider,
+  ModernGeolocationConfiguration
 } from "./types";
 
-export default Geolocation;
+// Pure utility functions (advanced users only)
+export * from "./utils";

package/src/types.ts

@@ -1,6 +1,34 @@
 // Public API types (compatible with @react-native-community/geolocation)
 export type AuthorizationLevel = "always" | "whenInUse" | "auto";
 export type LocationProvider = "playServices" | "android" | "auto";
+export type NullableDouble = number | null;
+
+/**
+ * User-facing geolocation configuration.
+ * This uses "android" instead of "android_platform" for better DX.
+ */
+export interface ModernGeolocationConfiguration {
+  /**
+   * Automatically request location permission when GeolocationProvider mounts.
+   * @default false
+   */
+  autoRequestPermission?: boolean;
+
+  /**
+   * iOS: Authorization level
+   */
+  authorizationLevel?: AuthorizationLevel;
+
+  /**
+   * iOS: Enable background location updates.
+   */
+  enableBackgroundLocationUpdates?: boolean;
+
+  /**
+   * Android: Location provider
+   */
+  locationProvider?: LocationProvider;
+}
 
 export interface GeolocationConfiguration {
   skipPermissionRequests: boolean;
@@ -12,11 +40,11 @@ export interface GeolocationConfiguration {
 export interface GeolocationCoordinates {
   latitude: number;
   longitude: number;
-  altitude: number | null;
+  altitude: NullableDouble;
   accuracy: number;
-  altitudeAccuracy: number | null;
-  heading: number | null;
-  speed: number | null;
+  altitudeAccuracy: NullableDouble;
+  heading: NullableDouble;
+  speed: NullableDouble;
 }
 
 export interface GeolocationResponse {

package/src/utils/cache.ts

@@ -0,0 +1,25 @@
+/**
+ * Validates whether a cached location is still fresh based on its age.
+ *
+ * @param timestampMs - The timestamp of the cached location (in milliseconds)
+ * @param currentTimeMs - The current time (in milliseconds)
+ * @param maximumAgeMs - The maximum age allowed for the cache (in milliseconds)
+ * @returns true if the cache is still valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * const timestampMs = Date.now() - 5000; // 5 seconds ago
+ * const currentTimeMs = Date.now();
+ * const maximumAgeMs = 10000; // 10 seconds
+ *
+ * isCachedLocationValid(timestampMs, currentTimeMs, maximumAgeMs); // true
+ * ```
+ */
+export function isCachedLocationValid(
+  timestampMs: number,
+  currentTimeMs: number,
+  maximumAgeMs: number
+): boolean {
+  const age = currentTimeMs - timestampMs;
+  return age < maximumAgeMs;
+}