@usefy/use-geolocation 0.0.28

package/dist/index.d.mts

@@ -0,0 +1,283 @@
+/**
+ * Geolocation coordinates data
+ * Note: Named GeoCoordinates to avoid conflict with native GeolocationCoordinates type
+ */
+interface GeoCoordinates {
+    /** Latitude in decimal degrees */
+    latitude: number;
+    /** Longitude in decimal degrees */
+    longitude: number;
+    /** Altitude in meters above the WGS 84 ellipsoid (null if unavailable) */
+    altitude: number | null;
+    /** Accuracy of latitude/longitude in meters */
+    accuracy: number;
+    /** Accuracy of altitude in meters (null if unavailable) */
+    altitudeAccuracy: number | null;
+    /** Direction of travel in degrees (0-360, null if unavailable) */
+    heading: number | null;
+    /** Speed in meters per second (null if unavailable) */
+    speed: number | null;
+}
+/**
+ * Position data with timestamp
+ * Note: Named GeoPosition to avoid conflict with native GeolocationPosition type
+ */
+interface GeoPosition {
+    /** Coordinates and related data */
+    coords: GeoCoordinates;
+    /** Timestamp when position was acquired */
+    timestamp: number;
+}
+/**
+ * Geolocation error types
+ */
+type GeolocationErrorCode = "PERMISSION_DENIED" | "POSITION_UNAVAILABLE" | "TIMEOUT" | "NOT_SUPPORTED";
+/**
+ * Custom error object for geolocation failures
+ */
+interface GeolocationError {
+    /** Error code */
+    code: GeolocationErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Original native error (if available) */
+    nativeError?: GeolocationPositionError;
+}
+/**
+ * Permission state for geolocation
+ */
+type PermissionState = "prompt" | "granted" | "denied" | "unavailable";
+/**
+ * Options for useGeolocation hook
+ */
+interface UseGeolocationOptions {
+    /**
+     * Enable high accuracy mode (uses GPS instead of network)
+     * WARNING: High accuracy mode may consume more battery power
+     * @default false
+     */
+    enableHighAccuracy?: boolean;
+    /**
+     * Maximum age of cached position in milliseconds
+     * Set to 0 to always request fresh position
+     * @default 0
+     */
+    maximumAge?: number;
+    /**
+     * Timeout in milliseconds for position request
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Start watching position immediately on mount
+     * When true, automatically starts continuous position tracking
+     * @default false
+     */
+    watch?: boolean;
+    /**
+     * Get initial position immediately on mount
+     * When true, automatically fetches position once on mount
+     * @default true
+     */
+    immediate?: boolean;
+    /**
+     * Callback when position is successfully retrieved
+     * @param position - The geolocation position data
+     */
+    onSuccess?: (position: GeoPosition) => void;
+    /**
+     * Callback when an error occurs
+     * @param error - The geolocation error
+     */
+    onError?: (error: GeolocationError) => void;
+    /**
+     * Callback when position changes (during watch mode)
+     * @param position - The updated geolocation position data
+     */
+    onPositionChange?: (position: GeoPosition) => void;
+    /**
+     * Callback when permission state changes
+     * @param state - The new permission state
+     */
+    onPermissionChange?: (state: PermissionState) => void;
+}
+/**
+ * Return type for useGeolocation hook
+ */
+interface UseGeolocationReturn {
+    /** Current position data (null if not yet retrieved) */
+    position: GeoPosition | null;
+    /** Loading state (true while fetching position) */
+    loading: boolean;
+    /** Error object (null if no error) */
+    error: GeolocationError | null;
+    /** Current permission state */
+    permission: PermissionState;
+    /** Whether geolocation is supported in this environment */
+    isSupported: boolean;
+    /**
+     * Manually get current position (one-time request)
+     */
+    getCurrentPosition: () => void;
+    /**
+     * Start watching position for real-time updates
+     */
+    watchPosition: () => void;
+    /**
+     * Stop watching position
+     */
+    clearWatch: () => void;
+    /**
+     * Calculate distance from current position to target coordinates in meters
+     * Uses Haversine formula (assumes spherical Earth, ~0.5% error margin)
+     * @param latitude - Target latitude in decimal degrees
+     * @param longitude - Target longitude in decimal degrees
+     * @returns Distance in meters, or null if position unavailable
+     */
+    distanceFrom: (latitude: number, longitude: number) => number | null;
+    /**
+     * Calculate bearing/direction from current position to target coordinates
+     * @param latitude - Target latitude in decimal degrees
+     * @param longitude - Target longitude in decimal degrees
+     * @returns Bearing in degrees (0-360, where 0=North, 90=East, 180=South, 270=West), or null if position unavailable
+     */
+    bearingTo: (latitude: number, longitude: number) => number | null;
+}
+
+/**
+ * A React hook for accessing device geolocation with real-time tracking and distance calculation.
+ *
+ * Features:
+ * - Get current position (one-time)
+ * - Watch position for real-time updates
+ * - Permission state tracking
+ * - Distance calculation using Haversine formula
+ * - Bearing/direction calculation
+ * - SSR compatible
+ * - TypeScript support
+ *
+ * @param options - Configuration options
+ * @returns Geolocation state and control functions
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - get current position
+ * function MyLocation() {
+ *   const { position, loading, error } = useGeolocation();
+ *
+ *   if (loading) return <p>Loading location...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *   if (!position) return <p>No position yet</p>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Latitude: {position.coords.latitude}</p>
+ *       <p>Longitude: {position.coords.longitude}</p>
+ *       <p>Accuracy: {position.coords.accuracy}m</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Real-time tracking with watch
+ * function LiveTracking() {
+ *   const { position, watchPosition, clearWatch } = useGeolocation({
+ *     immediate: false,
+ *     watch: false,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={watchPosition}>Start Tracking</button>
+ *       <button onClick={clearWatch}>Stop Tracking</button>
+ *       {position && (
+ *         <p>Current: {position.coords.latitude}, {position.coords.longitude}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Distance calculation
+ * function DistanceToDestination() {
+ *   const { position, distanceFrom } = useGeolocation();
+ *
+ *   // New York City coordinates
+ *   const nyLat = 40.7128;
+ *   const nyLon = -74.0060;
+ *
+ *   const distance = distanceFrom(nyLat, nyLon);
+ *
+ *   return (
+ *     <div>
+ *       {distance && (
+ *         <p>Distance to NYC: {(distance / 1000).toFixed(2)} km</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With callbacks and high accuracy
+ * const geolocation = useGeolocation({
+ *   enableHighAccuracy: true,
+ *   timeout: 10000,
+ *   onSuccess: (pos) => console.log('Got position:', pos),
+ *   onError: (err) => console.error('Geolocation error:', err),
+ *   onPositionChange: (pos) => console.log('Position updated:', pos),
+ *   onPermissionChange: (state) => console.log('Permission:', state),
+ * });
+ * ```
+ */
+declare function useGeolocation(options?: UseGeolocationOptions): UseGeolocationReturn;
+
+/**
+ * Calculate distance between two points using Haversine formula
+ *
+ * The Haversine formula determines the great-circle distance between two points
+ * on a sphere given their longitudes and latitudes. This assumes a spherical Earth,
+ * which introduces an error of up to 0.5% compared to more accurate ellipsoidal models.
+ *
+ * @param lat1 - Latitude of first point in decimal degrees
+ * @param lon1 - Longitude of first point in decimal degrees
+ * @param lat2 - Latitude of second point in decimal degrees
+ * @param lon2 - Longitude of second point in decimal degrees
+ * @returns Distance in meters
+ *
+ * @example
+ * ```typescript
+ * // Distance from San Francisco to Los Angeles
+ * const distance = haversineDistance(37.7749, -122.4194, 34.0522, -118.2437);
+ * console.log(distance); // ~559,000 meters (559 km)
+ * ```
+ */
+declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Calculate initial bearing (forward azimuth) from point 1 to point 2
+ *
+ * The bearing is the direction you would need to travel from the first point
+ * to reach the second point along a great circle path. Note that the bearing
+ * may change along the path (except when traveling due north/south or along the equator).
+ *
+ * @param lat1 - Latitude of first point in decimal degrees
+ * @param lon1 - Longitude of first point in decimal degrees
+ * @param lat2 - Latitude of second point in decimal degrees
+ * @param lon2 - Longitude of second point in decimal degrees
+ * @returns Bearing in degrees (0-360, where 0=North, 90=East, 180=South, 270=West)
+ *
+ * @example
+ * ```typescript
+ * // Bearing from New York to London
+ * const bearing = calculateBearing(40.7128, -74.0060, 51.5074, -0.1278);
+ * console.log(bearing); // ~51 degrees (Northeast)
+ * ```
+ */
+declare function calculateBearing(lat1: number, lon1: number, lat2: number, lon2: number): number;
+
+export { type GeoCoordinates, type GeoPosition, type GeolocationError, type GeolocationErrorCode, type PermissionState, type UseGeolocationOptions, type UseGeolocationReturn, calculateBearing, haversineDistance, useGeolocation };

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Geolocation coordinates data
+ * Note: Named GeoCoordinates to avoid conflict with native GeolocationCoordinates type
+ */
+interface GeoCoordinates {
+    /** Latitude in decimal degrees */
+    latitude: number;
+    /** Longitude in decimal degrees */
+    longitude: number;
+    /** Altitude in meters above the WGS 84 ellipsoid (null if unavailable) */
+    altitude: number | null;
+    /** Accuracy of latitude/longitude in meters */
+    accuracy: number;
+    /** Accuracy of altitude in meters (null if unavailable) */
+    altitudeAccuracy: number | null;
+    /** Direction of travel in degrees (0-360, null if unavailable) */
+    heading: number | null;
+    /** Speed in meters per second (null if unavailable) */
+    speed: number | null;
+}
+/**
+ * Position data with timestamp
+ * Note: Named GeoPosition to avoid conflict with native GeolocationPosition type
+ */
+interface GeoPosition {
+    /** Coordinates and related data */
+    coords: GeoCoordinates;
+    /** Timestamp when position was acquired */
+    timestamp: number;
+}
+/**
+ * Geolocation error types
+ */
+type GeolocationErrorCode = "PERMISSION_DENIED" | "POSITION_UNAVAILABLE" | "TIMEOUT" | "NOT_SUPPORTED";
+/**
+ * Custom error object for geolocation failures
+ */
+interface GeolocationError {
+    /** Error code */
+    code: GeolocationErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Original native error (if available) */
+    nativeError?: GeolocationPositionError;
+}
+/**
+ * Permission state for geolocation
+ */
+type PermissionState = "prompt" | "granted" | "denied" | "unavailable";
+/**
+ * Options for useGeolocation hook
+ */
+interface UseGeolocationOptions {
+    /**
+     * Enable high accuracy mode (uses GPS instead of network)
+     * WARNING: High accuracy mode may consume more battery power
+     * @default false
+     */
+    enableHighAccuracy?: boolean;
+    /**
+     * Maximum age of cached position in milliseconds
+     * Set to 0 to always request fresh position
+     * @default 0
+     */
+    maximumAge?: number;
+    /**
+     * Timeout in milliseconds for position request
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Start watching position immediately on mount
+     * When true, automatically starts continuous position tracking
+     * @default false
+     */
+    watch?: boolean;
+    /**
+     * Get initial position immediately on mount
+     * When true, automatically fetches position once on mount
+     * @default true
+     */
+    immediate?: boolean;
+    /**
+     * Callback when position is successfully retrieved
+     * @param position - The geolocation position data
+     */
+    onSuccess?: (position: GeoPosition) => void;
+    /**
+     * Callback when an error occurs
+     * @param error - The geolocation error
+     */
+    onError?: (error: GeolocationError) => void;
+    /**
+     * Callback when position changes (during watch mode)
+     * @param position - The updated geolocation position data
+     */
+    onPositionChange?: (position: GeoPosition) => void;
+    /**
+     * Callback when permission state changes
+     * @param state - The new permission state
+     */
+    onPermissionChange?: (state: PermissionState) => void;
+}
+/**
+ * Return type for useGeolocation hook
+ */
+interface UseGeolocationReturn {
+    /** Current position data (null if not yet retrieved) */
+    position: GeoPosition | null;
+    /** Loading state (true while fetching position) */
+    loading: boolean;
+    /** Error object (null if no error) */
+    error: GeolocationError | null;
+    /** Current permission state */
+    permission: PermissionState;
+    /** Whether geolocation is supported in this environment */
+    isSupported: boolean;
+    /**
+     * Manually get current position (one-time request)
+     */
+    getCurrentPosition: () => void;
+    /**
+     * Start watching position for real-time updates
+     */
+    watchPosition: () => void;
+    /**
+     * Stop watching position
+     */
+    clearWatch: () => void;
+    /**
+     * Calculate distance from current position to target coordinates in meters
+     * Uses Haversine formula (assumes spherical Earth, ~0.5% error margin)
+     * @param latitude - Target latitude in decimal degrees
+     * @param longitude - Target longitude in decimal degrees
+     * @returns Distance in meters, or null if position unavailable
+     */
+    distanceFrom: (latitude: number, longitude: number) => number | null;
+    /**
+     * Calculate bearing/direction from current position to target coordinates
+     * @param latitude - Target latitude in decimal degrees
+     * @param longitude - Target longitude in decimal degrees
+     * @returns Bearing in degrees (0-360, where 0=North, 90=East, 180=South, 270=West), or null if position unavailable
+     */
+    bearingTo: (latitude: number, longitude: number) => number | null;
+}
+
+/**
+ * A React hook for accessing device geolocation with real-time tracking and distance calculation.
+ *
+ * Features:
+ * - Get current position (one-time)
+ * - Watch position for real-time updates
+ * - Permission state tracking
+ * - Distance calculation using Haversine formula
+ * - Bearing/direction calculation
+ * - SSR compatible
+ * - TypeScript support
+ *
+ * @param options - Configuration options
+ * @returns Geolocation state and control functions
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - get current position
+ * function MyLocation() {
+ *   const { position, loading, error } = useGeolocation();
+ *
+ *   if (loading) return <p>Loading location...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *   if (!position) return <p>No position yet</p>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Latitude: {position.coords.latitude}</p>
+ *       <p>Longitude: {position.coords.longitude}</p>
+ *       <p>Accuracy: {position.coords.accuracy}m</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Real-time tracking with watch
+ * function LiveTracking() {
+ *   const { position, watchPosition, clearWatch } = useGeolocation({
+ *     immediate: false,
+ *     watch: false,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={watchPosition}>Start Tracking</button>
+ *       <button onClick={clearWatch}>Stop Tracking</button>
+ *       {position && (
+ *         <p>Current: {position.coords.latitude}, {position.coords.longitude}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Distance calculation
+ * function DistanceToDestination() {
+ *   const { position, distanceFrom } = useGeolocation();
+ *
+ *   // New York City coordinates
+ *   const nyLat = 40.7128;
+ *   const nyLon = -74.0060;
+ *
+ *   const distance = distanceFrom(nyLat, nyLon);
+ *
+ *   return (
+ *     <div>
+ *       {distance && (
+ *         <p>Distance to NYC: {(distance / 1000).toFixed(2)} km</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With callbacks and high accuracy
+ * const geolocation = useGeolocation({
+ *   enableHighAccuracy: true,
+ *   timeout: 10000,
+ *   onSuccess: (pos) => console.log('Got position:', pos),
+ *   onError: (err) => console.error('Geolocation error:', err),
+ *   onPositionChange: (pos) => console.log('Position updated:', pos),
+ *   onPermissionChange: (state) => console.log('Permission:', state),
+ * });
+ * ```
+ */
+declare function useGeolocation(options?: UseGeolocationOptions): UseGeolocationReturn;
+
+/**
+ * Calculate distance between two points using Haversine formula
+ *
+ * The Haversine formula determines the great-circle distance between two points
+ * on a sphere given their longitudes and latitudes. This assumes a spherical Earth,
+ * which introduces an error of up to 0.5% compared to more accurate ellipsoidal models.
+ *
+ * @param lat1 - Latitude of first point in decimal degrees
+ * @param lon1 - Longitude of first point in decimal degrees
+ * @param lat2 - Latitude of second point in decimal degrees
+ * @param lon2 - Longitude of second point in decimal degrees
+ * @returns Distance in meters
+ *
+ * @example
+ * ```typescript
+ * // Distance from San Francisco to Los Angeles
+ * const distance = haversineDistance(37.7749, -122.4194, 34.0522, -118.2437);
+ * console.log(distance); // ~559,000 meters (559 km)
+ * ```
+ */
+declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Calculate initial bearing (forward azimuth) from point 1 to point 2
+ *
+ * The bearing is the direction you would need to travel from the first point
+ * to reach the second point along a great circle path. Note that the bearing
+ * may change along the path (except when traveling due north/south or along the equator).
+ *
+ * @param lat1 - Latitude of first point in decimal degrees
+ * @param lon1 - Longitude of first point in decimal degrees
+ * @param lat2 - Latitude of second point in decimal degrees
+ * @param lon2 - Longitude of second point in decimal degrees
+ * @returns Bearing in degrees (0-360, where 0=North, 90=East, 180=South, 270=West)
+ *
+ * @example
+ * ```typescript
+ * // Bearing from New York to London
+ * const bearing = calculateBearing(40.7128, -74.0060, 51.5074, -0.1278);
+ * console.log(bearing); // ~51 degrees (Northeast)
+ * ```
+ */
+declare function calculateBearing(lat1: number, lon1: number, lat2: number, lon2: number): number;
+
+export { type GeoCoordinates, type GeoPosition, type GeolocationError, type GeolocationErrorCode, type PermissionState, type UseGeolocationOptions, type UseGeolocationReturn, calculateBearing, haversineDistance, useGeolocation };