react-native-nitro-geolocation 0.1.2 → 0.3.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,140 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+  LocationError,
+  LocationRequestOptions
+} from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+import type { GeolocationResponse } from "../types";
+
+/**
+ * Options for useGetCurrentPosition hook (Query style).
+ */
+export interface UseGetCurrentPositionOptions extends LocationRequestOptions {
+  /**
+   * Whether to automatically fetch the current position.
+   * When false, only manual refetch() will trigger the request.
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Hook for getting current location (one-time request) in Query style.
+ * Provides loading, error states, and data similar to TanStack Query.
+ *
+ * @param options - Location request options and enabled flag
+ * @returns Object containing position, loading/error states, and refetch function
+ *
+ * @example
+ * ```tsx
+ * // Auto-fetch on mount
+ * function MyComponent() {
+ *   const {
+ *     position,
+ *     isLoading,
+ *     isError,
+ *     error,
+ *     refetch
+ *   } = useGetCurrentPosition({
+ *     enabled: true,
+ *     enableHighAccuracy: true,
+ *   });
+ *
+ *   if (isLoading) return <Text>Loading...</Text>;
+ *   if (isError) return <Text>Error: {error?.message}</Text>;
+ *   if (!position) return null;
+ *
+ *   return (
+ *     <View>
+ *       <Text>Lat: {position.coords.latitude}</Text>
+ *       <Text>Lng: {position.coords.longitude}</Text>
+ *       <Button title="Refresh" onPress={() => refetch()} />
+ *     </View>
+ *   );
+ * }
+ *
+ * // Manual trigger only
+ * function ManualComponent() {
+ *   const { position, isLoading, refetch } = useGetCurrentPosition({
+ *     enabled: false
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       <Button
+ *         title="Get Location"
+ *         onPress={() => refetch()}
+ *         disabled={isLoading}
+ *       />
+ *       {position && <Text>Lat: {position.coords.latitude}</Text>}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useGetCurrentPosition(options?: UseGetCurrentPositionOptions) {
+  const client = useGeolocationClient();
+
+  const [position, setPosition] = useState<GeolocationResponse | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isError, setIsError] = useState(false);
+  const [error, setError] = useState<LocationError | null>(null);
+
+  const isMountedRef = useRef(true);
+  const optionsRef = useRef(options);
+
+  // Update options ref when they change
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  const fetchPosition = useCallback(async () => {
+    if (!isMountedRef.current) return;
+
+    setIsLoading(true);
+    setIsError(false);
+    setError(null);
+
+    try {
+      const result = await client.getCurrentPosition(optionsRef.current);
+      if (!isMountedRef.current) return;
+
+      setPosition(result);
+      setIsLoading(false);
+    } catch (err) {
+      if (!isMountedRef.current) return;
+
+      setIsError(true);
+      setError(err as LocationError);
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  // Extract enabled flag for reactive dependency
+  const enabled = options?.enabled ?? true;
+
+  // Auto-fetch on mount if enabled
+  useEffect(() => {
+    if (enabled) {
+      fetchPosition();
+    }
+    // Only run when enabled changes, not when fetchPosition changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled]);
+
+  // Track mount status
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  return {
+    position,
+    isLoading,
+    isError,
+    error,
+    refetch: fetchPosition
+  };
+}

package/src/hooks/useRequestPermission.ts

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+  LocationError,
+  PermissionStatus
+} from "../NitroGeolocation.nitro";
+import { useGeolocationClient } from "../components/GeolocationProvider";
+
+/**
+ * Hook for requesting location permission in Mutation style.
+ * Provides pending, error states, and status similar to TanStack Query mutations.
+ *
+ * @returns Object containing requestPermission function, status, and state flags
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const {
+ *     requestPermission,
+ *     status,
+ *     isPending,
+ *     isError,
+ *     error
+ *   } = useRequestPermission();
+ *
+ *   const handleRequest = async () => {
+ *     const result = await requestPermission();
+ *     if (result === 'granted') {
+ *       console.log('Permission granted!');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Button
+ *         onPress={handleRequest}
+ *         disabled={isPending}
+ *       >
+ *         {isPending ? 'Requesting...' : 'Request Permission'}
+ *       </Button>
+ *       {isError && <Text>Error: {error?.message}</Text>}
+ *       {status && <Text>Status: {status}</Text>}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useRequestPermission() {
+  const client = useGeolocationClient();
+
+  const [status, setStatus] = useState<PermissionStatus | null>(null);
+  const [isPending, setIsPending] = useState(false);
+  const [isError, setIsError] = useState(false);
+  const [error, setError] = useState<LocationError | null>(null);
+
+  const isMountedRef = useRef(true);
+
+  const requestPermission = useCallback(async (): Promise<PermissionStatus> => {
+    if (!isMountedRef.current) {
+      throw new Error("Component unmounted");
+    }
+
+    setIsPending(true);
+    setIsError(false);
+    setError(null);
+
+    try {
+      const result = await client.requestPermission();
+      if (!isMountedRef.current) return result;
+
+      setStatus(result);
+      setIsPending(false);
+      return result;
+    } catch (err) {
+      if (!isMountedRef.current) throw err;
+
+      setIsError(true);
+      setError(err as LocationError);
+      setIsPending(false);
+      throw err;
+    }
+  }, [client]);
+
+  // Track mount status
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  return {
+    requestPermission,
+    status,
+    isPending,
+    isError,
+    error
+  };
+}

package/src/hooks/useWatchPosition.ts

@@ -0,0 +1,130 @@
+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, error, and watching status
+ *
+ * @example
+ * ```tsx
+ * function LiveTracking() {
+ *   const { position, 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 (!position) return <Text>Waiting for location...</Text>;
+ *
+ *   return (
+ *     <Text>
+ *       Current: {position.coords.latitude}, {position.coords.longitude}
+ *       Accuracy: {position.coords.accuracy}m
+ *     </Text>
+ *   );
+ * }
+ * ```
+ */
+export function useWatchPosition(options?: UseWatchPositionOptions) {
+  const client = useGeolocationClient();
+
+  const [position, setPosition] = useState<GeolocationResponse | null>(null);
+  const [isWatching, setIsWatching] = useState(false);
+  const [error, setError] = useState<LocationError | null>(null);
+
+  // 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);
+
+  // Store latest options in ref to avoid unnecessary re-subscriptions
+  const optionsRef = useRef(options);
+
+  // Update options ref whenever options change
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  // Extract enabled flag for reactive dependency
+  const enabled = options?.enabled ?? false;
+
+  useEffect(() => {
+    if (!enabled) {
+      // Not enabled, ensure cleanup
+      if (tokenRef.current) {
+        client.unwatch(tokenRef.current);
+        tokenRef.current = null;
+      }
+      setIsWatching(false);
+      return;
+    }
+
+    // Start watching with latest options
+    setIsWatching(true);
+    setError(null);
+
+    const token = client.watchPosition(
+      (result: GeolocationResponse) => {
+        // Success callback
+        if (!isMountedRef.current) return;
+        setPosition(result);
+        setError(null);
+      },
+      (err: LocationError) => {
+        // Error callback
+        if (!isMountedRef.current) return;
+        setError(err);
+      },
+      optionsRef.current
+    );
+
+    tokenRef.current = token;
+
+    // Cleanup function
+    return () => {
+      if (token) {
+        client.unwatch(token);
+      }
+    };
+  }, [enabled, client]); // Only re-subscribe when enabled/client changes
+
+  // Track mount status
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  return {
+    position,
+    error,
+    isWatching
+  };
+}