@zero-deps-toolkit/geo

A zero-dependency TypeScript library for geographical calculations and operations. Built with performance and simplicity in mind.

Features

• Zero Dependencies: No external dependencies, minimal bundle size
• TypeScript First: Full TypeScript support with complete type definitions
• Tree-Shakeable: Import only what you need
• Well-Tested: Comprehensive test coverage
• ESM Support: Modern ES Module format

Installation

npm install @zero-deps-toolkit/geo

yarn add @zero-deps-toolkit/geo

pnpm add @zero-deps-toolkit/geo

Usage

Calculate Distance Between Coordinates

import { distanceInKm, distanceInMeters, haversineDistance } from '@zero-deps-toolkit/geo';

const pointA = { lat: 40.7128, lng: -74.0060 }; // New York
const pointB = { lat: 51.5074, lng: -0.1278 };  // London

// Distance in kilometers
const km = distanceInKm(pointA, pointB);
console.log(`Distance: ${km.toFixed(2)} km`); // Distance: 5570.27 km

// Distance in meters
const meters = distanceInMeters(pointA, pointB);
console.log(`Distance: ${meters.toFixed(2)} m`); // Distance: 5570274.48 m

// Using haversineDistance with explicit unit
const distance = haversineDistance(pointA, pointB, 'km');

API Reference

Types

LatLng

Represents a geographic coordinate with latitude and longitude.

interface LatLng {
  lat: number;  // Latitude in degrees (-90 to 90)
  lng: number;  // Longitude in degrees (-180 to 180)
}

Functions

haversineDistance(point1, point2, unit?)

Calculates the great circle distance between two points on Earth using the Haversine formula. This formula accounts for the spherical shape of the Earth and provides accurate distance calculations.

Parameters:

• point1: LatLng - First coordinate point
• point2: LatLng - Second coordinate point
• unit?: 'km' | 'm' - Unit of measurement (default: 'km')

Returns: number - Distance in the specified unit

Example:

const distance = haversineDistance(
  { lat: 48.8566, lng: 2.3522 },  // Paris
  { lat: 52.5200, lng: 13.4050 }, // Berlin
  'km'
);

distanceInKm(point1, point2)

Convenience function to calculate distance in kilometers.

Parameters:

• point1: LatLng - First coordinate point
• point2: LatLng - Second coordinate point

Returns: number - Distance in kilometers

Example:

const km = distanceInKm(
  { lat: 48.8566, lng: 2.3522 },
  { lat: 52.5200, lng: 13.4050 }
);

distanceInMeters(point1, point2)

Convenience function to calculate distance in meters.

Parameters:

• point1: LatLng - First coordinate point
• point2: LatLng - Second coordinate point

Returns: number - Distance in meters

Example:

const meters = distanceInMeters(
  { lat: 48.8566, lng: 2.3522 },
  { lat: 52.5200, lng: 13.4050 }
);

How It Works

The library uses the Haversine formula to calculate distances between coordinates. This formula determines the great-circle distance between two points on a sphere given their longitudes and latitudes.

The Haversine formula is:

a = sin²(Δφ/2) + cos φ1 ⋅ cos φ2 ⋅ sin²(Δλ/2)
c = 2 ⋅ atan2(√a, √(1−a))
d = R ⋅ c

Where:

• φ is latitude
• λ is longitude
• R is Earth's radius (6371 km or 6371000 m)
• Δ represents the difference between coordinates

This approach provides accurate results for most practical purposes, with typical accuracy within 0.5% for distances up to a few hundred kilometers.

Performance

The library is optimized for performance:

• Zero external dependencies
• Minimal computational overhead
• Small bundle size (~1KB minified)
• Tree-shakeable - only import what you need

Browser and Node.js Support

• Node.js: 14.x and above
• Browsers: All modern browsers (ES2015+)
• TypeScript: 4.0 and above

Contributing

Contributions are welcome! This package is part of the zero-deps-toolkit monorepo.

License

MIT

Links

• GitHub Repository
• npm Package
• Issue Tracker
• Monorepo