haversine-distance

haversine-distance is a single-purpose JavaScript utility that computes the great-circle distance between two points on Earth’s surface using the Haversine formula, returning the result in meters with no unit conversion required. It accepts coordinates in several common shapes — {latitude, longitude}, {lat, lng}, {lat, lon}, or a GeoJSON [longitude, latitude] tuple — so it drops into existing codebases without forcing a specific coordinate object shape.

The entire implementation is a single ~25-line file with zero runtime dependencies, published for both CommonJS and ESM consumers with hand-written TypeScript declarations included. It ships with a small tape-based test suite exercising real-world city-to-city distance fixtures, run automatically in CI on every push and pull request, and is published to npm via a GitHub Actions release workflow with provenance attestation.

What You Get

• A single exported function, haversineDistance(a, b), that returns the distance between two points in meters
• Flexible coordinate input: {latitude, longitude}, {lat, lng}, {lat, lon}, or GeoJSON [lng, lat] arrays, including mixed forms between the two arguments
• Zero runtime dependencies — the whole implementation is one small file using only built-in Math functions
• Hand-written TypeScript type declarations (index.d.ts) shipped alongside the JS, with no separate @types package needed
• Dual CommonJS/ESM support via the package’s exports map, so it works with both require and import

Common Use Cases

• Sorting or filtering a list of stores, drivers, or points of interest by proximity to a user’s location
• Computing straight-line distance for shipping/delivery radius checks without calling an external mapping API
• Geofencing checks — determining whether a device’s coordinates fall within a given radius of a fixed point
• Adding a lightweight ‘distance from you’ figure to search results or map markers without a full geospatial library

Under The Hood

Architecture The package is a single CommonJS module (index.js) exporting one function, haversineDistance(a, b), built from small named helper closures (squared, toRad, hav) that mirror the terms of the Haversine formula directly — there is no internal layering, class hierarchy, or state to reason about, and the only “integration point” is the flexible coordinate-shape parsing at the top of the function, which uses optional chaining and Array.isArray checks to accept {latitude, longitude}, {lat, lng}, {lat, lon}, or GeoJSON tuples interchangeably. Changing the core formula would only ever touch this one file.

Tech Stack The library has no runtime dependencies at all; the only dependency declared is the tape test framework as a devDependency. It uses pnpm (pinned via packageManager) for install/CI, targets Node 20 in GitHub Actions, and exposes both require and import entry points plus a hand-written index.d.ts through the package’s exports map rather than a TypeScript build step — there is no bundler, transpiler, or compiled output at all.

Code Quality Tests are written with tape against a JSON fixture file of real city-pair coordinates and their expected rounded distances, run in CI via GitHub Actions on every push and pull request. There is no linter or formatter configuration present in the current repository (the README’s “standard” style badge references a convention the repo no longer enforces via committed config), and there is no TypeScript source — type safety comes only from the hand-maintained .d.ts file, which must be kept in sync with index.js manually.

What Makes It Unique The library’s entire value proposition is scope discipline: rather than a general geospatial toolkit, it does one calculation, accepts an unusually wide range of coordinate object shapes without requiring the caller to normalize them first, and adds no dependencies or bundle weight. It is a deliberately minimal alternative to importing a much larger mapping/geo library when all an application needs is a distance number.