feat: getGeoDiff

[DoneDeal0]

🌎 NEW FEATURE: getGeoDiff

import { getGeoDiff } from "@donedeal0/superdiff";

Returns a structured diff between two geographical coordinates. Supports 9 distance units, locale‑aware output, and two accuracy modes.

• High‑accuracy mode is based on the Vincenty formulae (ellipsoidal Earth model, higher precision).
• Normal-accuracy mode is based on the Haversine formulae (spherical Earth model, faster, slightly less precise).

FORMAT

Input

  previousCoordinates: [number, number] | null | undefined;
  coordinates: [number, number] | null | undefined;
  options?: {
    unit?: "centimeter" | "foot" | "inch" | "kilometer" | "meter" | "mile" | "mile-scandinavian" | "millimeter" | "yard"; // "kilometer" by default
    accuracy?: "normal" | "high"; // "normal" by default
    maxDecimals?: number; // 2 by default,
    locale?: Intl.Locale | string; // "en-US" by default
  }

• previousCoordinates: the original coordinates ([Longitude, Latitude]).
• coordinates: the new coordinates ([Longitude, Latitude]).
• options
  • unit: the unit used for the returned distance.
  • accuracy:
    • normal (default): fastest mode, with a small error margin, based on Haversine formula.
    • high: slower but highly precise distance. Based on Vincenty formula.
  • maxDecimals: maximal decimals for the distance. Defaults to 2.
  • locale: the locale of your distance. Enables a locale‑aware distance label.

Output

type GeoDiff = {
    type: "geo";
    status: "added" | "deleted" | "error" | "equal" | "updated";
    diff: {
        coordinates: [number, number] | null;
        previousCoordinates: [number, number] | null;
        distance: number;
        unit: "centimeter" | "foot" | "inch" | "kilometer" | "meter" | "mile" | "mile-scandinavian" | "millimeter" | "yard";
        label: string,
        direction: "east" | "north" | "south" | "west" | "north-east" | "north-west" | "south-east" | "south-west" | "stationary";
    };
}

USAGE

Input

getGeoDiff(
- [2.3522, 48.8566],
+ [-0.1278, 51.5074]
);

Coordinates follow GeoJSON order: [longitude, latitude].

Output

{
      type: "geo",
+     status: "updated",
      diff: {
+          coordinates: [-0.1278, 51.5074],
           previousCoordinates: [2.3522, 48.8566],
+          direction: "north-west",
+          distance: 343.56,
+          label: "343.56 kilometers",
+          unit: "kilometer"
        }
}

---

See our website documentation

[github-actions]

🎉 This PR is included in version 4.2.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀