@it-mitra/utils

A collection of utility functions for geolocation, distance calculations, time formatting, polyline analysis, and map-related operations, built and maintained by the Mitra team.

📦 Installation

npm install @it-mitra/utils
# or
yarn add @it-mitra/utils

📖 Overview

The @it-mitra/utils package provides a set of reusable JavaScript functions for geospatial calculations, time formatting, and map animations. These utilities are designed to simplify tasks such as calculating distances, bearings, polyline turns, and formatting durations, primarily for React Native applications using map components.

🛠️ Features

• Geolocation Utilities: Calculate distances, bearings, and destination points using the Haversine formula.
• Polyline Analysis: Find the closest point on a polyline, detect turns, and calculate total distances and ETAs.
• Time Formatting: Convert durations and calculate remaining time from UTC timestamps.
• Map Animations: Smoothly animate map camera views to specific coordinates.
• Notifications: Trigger notifications via API endpoints.

📚 API Reference

1. Geolocation Utilities (geoUtils.js)

calculateDestinationPoint(start, bearing, distanceMeters)

Calculates the destination coordinate given a starting point, bearing, and distance.

• Parameters:
  • start: { latitude: number, longitude: number } - Starting coordinate.
  • bearing: number - Bearing in degrees (0° is north, 90° is east).
  • distanceMeters: number - Distance to travel in meters.
• Returns: { latitude: number, longitude: number } - Destination coordinate.

shiftCoordinateEast(coordinate, distanceMeters)

Shifts a coordinate eastward by a specified distance.

• Parameters:
  • coordinate: { latitude: number, longitude: number } - Starting coordinate.
  • distanceMeters: number - Distance to shift east in meters.
• Returns: { latitude: number, longitude: number } - New coordinate.

2. Distance Calculations (distance.js)

getDistance(coord1, coord2, unit = 'meters')

Calculates the Haversine distance between two coordinates.

• Parameters:
  • coord1: { latitude: number, longitude: number } - First coordinate.
  • coord2: { latitude: number, longitude: number } - Second coordinate.
  • unit: 'meters' | 'km' | 'miles' - Unit for the result (default: 'meters').
• Returns: number - Distance in the specified unit.

formatDistance(meters)

Formats a distance in meters into a human-readable string.

• Parameters:
  • meters: number - Distance in meters.
• Returns: string - Formatted string (e.g., "850 m" or "1.2 km").

getPolylineDistanceAndETA(polylineCoords, averageSpeedKmph = 30)

Calculates the total distance and estimated duration for a polyline route.

• Parameters:
  • polylineCoords: { latitude: number, longitude: number }[] - Array of coordinates.
  • averageSpeedKmph: number - Average speed in km/h (default: 30).
• Returns: { distanceInMeters: number, estimatedDurationInSec: number }.

isDriverFarFromEntirePolyline(driverLocation, polyline, threshold)

Checks if a driver is far from an entire polyline based on a threshold distance.

• Parameters:
  • driverLocation: { latitude: number, longitude: number } - Driver's coordinate.
  • polyline: { latitude: number, longitude: number }[] - Array of coordinates.
  • threshold: number - Maximum distance in meters.
• Returns: boolean - true if driver is farther than the threshold from all points.

3. Polyline Utilities (polylineUtils.js)

findClosestPointOnPolyline(targetPos, polyline)

Finds the closest point on a polyline to a given position.

• Parameters:
  • targetPos: { latitude: number, longitude: number } - Target coordinate.
  • polyline: { latitude: number, longitude: number }[] - Array of coordinates.
• Returns: { closestPoint: { latitude: number, longitude: number }, index: number }.

calculateBearingBetweenPoints(start, end)

Calculates the compass bearing from a start point to an end point.

• Parameters:
  • start: { latitude: number, longitude: number } - Starting coordinate.
  • end: { latitude: number, longitude: number } - Ending coordinate.
• Returns: number - Bearing in degrees (0°–360°).

detectNextTurnInPolyline(polyline, fromIndex, turnAngleThreshold = 30)

Detects the next significant turn in a polyline based on angular change.

• Parameters:
  • polyline: { latitude: number, longitude: number }[] - Array of coordinates.
  • fromIndex: number - Starting index to check for turns.
  • turnAngleThreshold: number - Minimum angle change in degrees (default: 30).
• Returns: { distanceToTurn: number, turnAtIndex: number, turnAngle: number, turnPoint: { latitude: number, longitude: number } } | null.

getBearing(start, end)

Calculates the bearing between two points (similar to calculateBearingBetweenPoints).

• Parameters:
  • start: { latitude: number, longitude: number } - Starting coordinate.
  • end: { latitude: number, longitude: number } - Ending coordinate.
• Returns: number - Bearing in degrees (0°–360°).

4. Time Utilities (formatDuration.js, getRemainingTime.js)

formatDuration(seconds)

Formats a duration in seconds into a human-readable string (e.g., "1h 5m 10s").

• Parameters:
  • seconds: number - Duration in seconds.
• Returns: string - Formatted duration (e.g., "1h 5m 10s" or "1m" if zero).

getRemainingTime(utcStringTime, expirySeconds = 30, currentIsoTime = null)

Calculates remaining time until a UTC timestamp expires.

• Parameters:
  • utcStringTime: string - UTC time in ISO format (e.g., "2025-08-06T12:30:00Z").
  • expirySeconds: number - Seconds until expiry (default: 30).
  • currentIsoTime: string | null - Optional current time in ISO format (default: system time).
• Returns: number - Remaining seconds (or 0 if expired).

5. Map Animation (index.js)

animateMapToCoordinate(mapRef, center, bearing = 0, zoom = 18, duration = 500)

Smoothly animates the map camera to a specified coordinate.

• Parameters:
  • mapRef: React.RefObject<MapView> - Ref to the MapView component.
  • center: { latitude: number, longitude: number } - Target coordinate.
  • bearing: number - Camera heading in degrees (default: 0).
  • zoom: number - Zoom level (default: 18).
  • duration: number - Animation duration in milliseconds (default: 500).
• Returns: void.

6. Notifications (index.js)

triggerNotification(apiGet, endpoint, id, logger = console.log)

Triggers a notification via a GET request to an API endpoint.

• Parameters:
  • apiGet: Function - Function to perform GET request (e.g., axios wrapper).
  • endpoint: string - API endpoint base URL.
  • id: string - ID to append to endpoint.
  • logger: Function - Optional logger function (default: console.log).
• Returns: Promise<Object> - Response data.
• Throws: Error data if the request fails.

🚀 Usage Example

import {
  getDistance,
  formatDistance,
  findClosestPointOnPolyline,
  formatDuration,
  animateMapToCoordinate,
} from '@it-mitra/utils';

// Calculate distance between two points
const coord1 = { latitude: 12.9716, longitude: 77.5946 };
const coord2 = { latitude: 12.9352, longitude: 77.6142 };
const distance = getDistance(coord1, coord2, 'meters');
console.log(formatDistance(distance)); // e.g., "5050.4 m"

// Find closest point on a polyline
const polyline = [
  { latitude: 12.9716, longitude: 77.5946 },
  { latitude: 12.9352, longitude: 77.6142 },
];
const targetPos = { latitude: 12.9500, longitude: 77.6000 };
const { closestPoint, index } = findClosestPointOnPolyline(targetPos, polyline);
console.log(closestPoint, index); // Closest coordinate and its index

// Format duration
const seconds = 3665;
console.log(formatDuration(seconds)); // "1h 1m 5s"

// Animate map
const mapRef = useRef(null);
animateMapToCoordinate(mapRef, coord1, 90, 16, 1000);

📋 Requirements

• Node.js: Version 14 or higher.
• React Native: For animateMapToCoordinate, ensure compatibility with your map library (e.g., react-native-maps).

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/YourFeature).
3. Commit your changes (git commit -m 'Add YourFeature').
4. Push to the branch (git push origin feature/YourFeature).
5. Open a pull request.

📜 License

This project is licensed under the MIT License.

📬 Contact

For questions or feedback, reach out to the Mitra team at [email protected].