@gabriel-sisjr/react-native-background-location/src/types/hooks.ts

React Native library for background location tracking using TurboModules. Track user location even when the app is minimized or in the background.

/**
 * Types and interfaces for React hooks
 */

import type { Coords, TrackingOptions } from './tracking';

/**
 * Result type for useBackgroundLocation hook
 */
export interface UseBackgroundLocationResult {
  /**
   * Current trip ID if tracking is active
   */
  tripId: string | null;

  /**
   * Whether location tracking is currently active
   */
  isTracking: boolean;

  /**
   * All locations collected for the current trip
   */
  locations: Coords[];

  /**
   * Whether an operation is in progress
   */
  isLoading: boolean;

  /**
   * Last error that occurred
   */
  error: Error | null;

  /**
   * Start tracking with optional custom trip ID and options
   */
  startTracking: (
    customTripId?: string,
    options?: TrackingOptions
  ) => Promise<string | null>;

  /**
   * Stop tracking
   */
  stopTracking: () => Promise<void>;

  /**
   * Refresh locations for current trip
   */
  refreshLocations: () => Promise<void>;

  /**
   * Clear all data for current trip
   */
  clearCurrentTrip: () => Promise<void>;

  /**
   * Clear error state
   */
  clearError: () => void;
}

/**
 * Options for useLocationTracking hook
 */
export interface UseLocationTrackingOptions {
  /**
   * Automatically start tracking when component mounts
   * @default false
   */
  autoStart?: boolean;

  /**
   * Custom trip ID to use
   */
  tripId?: string;

  /**
   * Tracking configuration options
   */
  options?: TrackingOptions;

  /**
   * Callback when tracking starts
   */
  onTrackingStart?: (tripId: string) => void;

  /**
   * Callback when tracking stops
   */
  onTrackingStop?: () => void;

  /**
   * Callback when error occurs
   */
  onError?: (error: Error) => void;
}

/**
 * Options for useLocationUpdates hook
 */
export interface UseLocationUpdatesOptions {
  /**
   * Specific trip ID to watch
   * If not provided, watches updates for any active trip
   */
  tripId?: string;

  /**
   * Callback when a new location is received
   */
  onLocationUpdate?: (location: Coords) => void;

  /**
   * Whether to automatically load existing locations on mount
   * @default true
   */
  autoLoad?: boolean;
}

/**
 * Result type for useLocationUpdates hook
 */
export interface UseLocationUpdatesResult {
  /**
   * Current trip ID being watched
   */
  tripId: string | null;

  /**
   * Whether location tracking is currently active
   */
  isTracking: boolean;

  /**
   * All locations received for the current trip
   * Updates automatically as new locations arrive
   */
  locations: Coords[];

  /**
   * The most recent location received
   */
  lastLocation: Coords | null;

  /**
   * Whether data is being loaded
   */
  isLoading: boolean;

  /**
   * Last error that occurred
   */
  error: Error | null;

  /**
   * Clear error state
   */
  clearError: () => void;

  /**
   * Clear all locations for current trip
   */
  clearLocations: () => Promise<void>;
}