haversine-toolkit

A lightweight, dependency-free TypeScript library for calculating distances between GPS coordinates using the Haversine formula.

haversine-toolkit calculates the great-circle distance between two latitude/longitude points, checks whether a coordinate falls inside a search radius, builds geographic bounding boxes for database queries, and finds the midpoint between two locations — all with zero runtime dependencies and full TypeScript support.

If you are searching for a Haversine formula npm package, a distance between coordinates JavaScript library, or a way to do geospatial calculations in TypeScript without pulling in a heavy GIS dependency, this package is built for that.

Table of contents

• Why use haversine-toolkit
• Installation
• Quick start
• API reference
  • calculateDistance()
  • isWithinRadius()
  • boundingBox()
  • midpoint()
• Use cases
• Frequently asked questions
• Roadmap
• Contributing
• License

Why use haversine-toolkit

• Accurate: implements the standard Haversine great-circle distance formula for latitude/longitude pairs.
• Zero dependencies: no bloat, no supply-chain risk from transitive packages.
• Fully typed: written in TypeScript with complete type definitions included.
• Tree-shakeable: import only the functions you use.
• Dual module support: works with both ESM (import) and CommonJS (require).
• Tested: covered by a Vitest test suite.
• Small footprint: suitable for backend APIs, browser apps, mobile apps (React Native/Expo), and edge functions alike.

Common alternatives either require installing a full GIS library, ship with unnecessary dependencies, or lack TypeScript types. haversine-toolkit focuses on the specific set of operations most apps actually need: distance, radius checks, bounding boxes, and midpoints.

Installation

npm install haversine-toolkit

yarn add haversine-toolkit

pnpm add haversine-toolkit

Quick start

import { calculateDistance } from "haversine-toolkit";

const algiers = {
  latitude: 36.7538,
  longitude: 3.0588,
};

const oran = {
  latitude: 35.6981,
  longitude: -0.6348,
};

const distance = calculateDistance(algiers, oran);

console.log(distance);
// 364.8 km

API reference

calculateDistance()

Calculates the great-circle distance between two geographic coordinates using the Haversine formula.

calculateDistance(pointA, pointB, unit?)

Parameters

| Name | Type | Description | |------|------|-------------| | pointA | Coordinate | Starting location ({ latitude, longitude }) | | pointB | Coordinate | Destination location | | unit | "km" \| "m" \| "mi" | Unit of the returned distance (default: "km") |

Returns: number

isWithinRadius()

Checks whether two coordinates are within a specified search radius. Useful for "find locations near me" style features.

isWithinRadius(pointA, pointB, radius)

Returns: boolean

boundingBox()

Creates a geographic bounding box around a center coordinate. Useful for pre-filtering rows before an exact distance calculation in:

• PostgreSQL / PostGIS
• Prisma
• MongoDB geospatial queries
• OpenStreetMap and Google Maps integrations

const box = boundingBox(center, 5); // 5 km radius

Returns

{
  minLatitude: number,
  maxLatitude: number,
  minLongitude: number,
  maxLongitude: number
}

midpoint()

Calculates the geographic midpoint between two GPS coordinates.

const center = midpoint(pointA, pointB);

Use cases

haversine-toolkit is commonly used to build:

• Delivery and last-mile logistics applications
• Ride-sharing and carpooling apps
• GPS tracking and fleet management systems
• Waste collection and recycling platforms
• Food delivery services
• Store and dealer locator features
• Mapping and location-based search tools
• Travel planning applications

Frequently asked questions

What formula does this library use to calculate distance? It uses the Haversine formula, which calculates the great-circle distance between two points on a sphere given their latitude and longitude.

Does haversine-toolkit account for the Earth's ellipsoid shape (like Vincenty's formula)? No. Haversine assumes a spherical Earth, which is accurate to within about 0.5% for most applications. For survey-grade precision, a Vincenty or geodesic library is more appropriate.

Can I get the distance in miles instead of kilometers? Yes. Pass "mi" as the third argument to calculateDistance(). Supported units are "km", "m", and "mi".

Does this work in the browser and in React Native? Yes. The package has zero runtime dependencies and ships both ESM and CommonJS builds, so it works in Node.js backends, browser frontends, and React Native/Expo apps.

Is haversine-toolkit compatible with PostGIS or MongoDB geospatial queries? boundingBox() generates a min/max latitude and longitude box you can use to pre-filter rows in PostgreSQL, PostGIS, Prisma, or MongoDB before running an exact distance calculation in application code.

Roadmap

Version 1.0.0 (current)

• calculateDistance()
• isWithinRadius()
• boundingBox()
• midpoint()

Version 1.1.0 (planned)

• bearing()
• destinationPoint()

Future

• nearestPoint()
• sortByDistance()
• GeoJSON helpers
• Polygon utilities

Contributing

Contributions are welcome. If you find a bug, have a feature idea, or want to improve the documentation, please open an issue or submit a pull request on GitHub.

License

MIT (c) 2026 Ilyes Mekalfa