Fast, lightweight, and precise flat-earth geodesy based on WGS84 and GeoJSON for TypeScript.
While general-purpose libraries are great for global calculations, they are often overkill and slower due to full spherical/ellipsoid mathematics.
This library is specialized for local coordinates (e.g., within a city or a local site) using a flat-earth approximation. It offers ~1 cm accuracy for small distances while being significantly more performant.
- 🚀 Ultra-fast: Mathematical calculations based on Ed Williams' Aviation Formulary.
- 🎯 High Precision: Accuracy down to ~1 cm for local approximations.
- 📦 Zero Dependencies: No bloat, tiny bundle size.
- 🔷 TypeScript Native: Built with TS 6.0, providing full type safety and GeoJSON
Pointcompatibility. - 🌐 Modern ESM/CommonJS: Works in Node.js, Browsers, Deno, and Edge functions.
npm install micro-wgs84This package is available in two active major versions, depending on your project's module system:
| Version | Module System | Node.js Requirement |
|---|---|---|
v2.x (Latest) |
ES Modules (ESM) (import) |
Node.js 12.17+ |
v1.x (Legacy) |
CommonJS (CJS) (require) |
Node.js 10+ |
Designed for modern environments. Requires "type": "module" in your package.json or an ESM-compatible bundler.
import * as wgs84 from 'micro-wgs84';
// 1. Create points (lat, lon)
const p = wgs84.point(59.326634, 18.072837); // Royal castle, Stockholm
// 2. Project new coordinates
// Get a point 300m North and 400m East of origin
const p1: wgs84.Point = wgs84.pointEastOf(wgs84.pointNorthOf(p, 300), 400);
console.log(`lat=${p1.coordinates[1].toFixed(6)}, lon=${p1.coordinates[0].toFixed(6)}`); // GeoJSON uses [lon, lat] order!
// 3, Get the distance between the 2 points
console.log(`Total distance=${wgs84.distance(p, p1).toFixed(3)}m`);This will produce the following output
lat=59.329327, lon=18.079864
Total distance=500.025mThe library provides a clean API for geometric operations. For the full technical details, see the full documentation.
point(lat, lon, height?): Helper to construct a GeoJSON Point.distance(origin, target): Total distance between points in meters.bearing(origin, target): Bearing between points in degrees.distanceNorth / distanceEast / distanceUp: Component distances.pointNorthOf / pointEastOf / pointAbove: Project new points based on offset in meters.
Note that Points that are not valid (e.g. latitude > 90 degrees) will throw! Be sure to handle that!
This library uses a flat-earth approximation. While accurate for "small" distances (within a few kilometers), the error margin increases as the distance between points grows. For global-scale calculations, a spherical model is recommended.
All functions are fully unit-tested with Vitest.