Haversine

Fast accurate Haversine distance calculator for coordinates.

Installation

Choose your preferred package manager:

# npm package
npm install @neabyte/haversine

# Deno module
deno add jsr:@neabyte/haversine

Usage

import Haversine from '@neabyte/haversine'

// Calculate distance in kilometers
const distanceKm = Haversine.calculate(
  { lat: 40.7128, lon: -74.006 }, // New York
  { lat: 51.5074, lon: -0.1278 }, // London
  'km'
)

// Calculate distance in meters
const distanceM = Haversine.calculate(
  { lat: 40.7128, lon: -74.006 }, // New York
  { lat: 51.5074, lon: -0.1278 }, // London
  'm'
)

console.log(`Distance: ${distanceKm} km`) // Distance: 5570.23 km
console.log(`Distance: ${distanceM} m`) // Distance: 5570228.56 m

API Reference

Haversine.calculate(firstLocation, secondLocation, distanceUnit)

Calculate the distance between two coordinate points using the Haversine formula.

Parameters:

• firstLocation: Location - First coordinate pair with lat and lon properties
• secondLocation: Location - Second coordinate pair with lat and lon properties
• distanceUnit: DistanceUnit - Either 'km' for kilometers or 'm' for meters

Returns: number - The calculated distance in the specified unit

Types:

interface Location {
  lat: number // Latitude in degrees (-90 to 90)
  lon: number // Longitude in degrees (-180 to 180)
}

type DistanceUnit = 'km' | 'm'

Error Handling

The library validates all inputs and provides clear error messages:

// Invalid coordinates
Haversine.calculate({ lat: 'invalid', lon: 74 }, location, 'km')
// Throws: "First location must have numeric latitude and longitude values"

// Invalid distance unit
Haversine.calculate(location1, location2, 'feet')
// Throws: "Distance unit must be either \"km\" for kilometers or \"m\" for meters"

// Missing location
Haversine.calculate(null, location, 'km')
// Throws: "First location parameter is required"

License

This project is licensed under the MIT license. See the LICENSE file for more info.