geo-relative-position 1.0.0

package/dist/index.mjs

@@ -0,0 +1,638 @@
+// src/constants.ts
+var EARTH_RADIUS_METERS = 6371e3;
+var STATIONARY_SPEED_THRESHOLD = 0.5;
+var ORIENTATION_THRESHOLDS = {
+  /** Threshold for "directly ahead" (+/- degrees from 0) */
+  DIRECTLY_AHEAD: 10,
+  /** Threshold for "ahead" region (within +/- degrees from 0) */
+  AHEAD: 45,
+  /** Threshold for "behind" region (beyond +/- degrees from 0) */
+  BEHIND: 135,
+  /** Threshold for "directly behind" (+/- degrees from 180) */
+  DIRECTLY_BEHIND: 170
+};
+var COMPASS_BOUNDARIES = {
+  NORTH_END: 22.5,
+  NORTHEAST_END: 67.5,
+  EAST_END: 112.5,
+  SOUTHEAST_END: 157.5,
+  SOUTH_END: 202.5,
+  SOUTHWEST_END: 247.5,
+  WEST_END: 292.5,
+  NORTHWEST_END: 337.5
+};
+
+// src/utils/math.ts
+function toRadians(degrees) {
+  return degrees * (Math.PI / 180);
+}
+function toDegrees(radians) {
+  return radians * (180 / Math.PI);
+}
+function normalizeAngle(degrees) {
+  let normalized = degrees % 360;
+  if (normalized < 0) {
+    normalized += 360;
+  }
+  return normalized;
+}
+function normalizeLongitude(longitude) {
+  let normalized = longitude % 360;
+  if (normalized > 180) {
+    normalized -= 360;
+  }
+  if (normalized < -180) {
+    normalized += 360;
+  }
+  return normalized;
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function roundTo(value, decimals) {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+// src/core/distance.ts
+function getDistance(from, to) {
+  if (from.latitude === to.latitude && from.longitude === to.longitude) {
+    return 0;
+  }
+  const lat1Rad = toRadians(from.latitude);
+  const lat2Rad = toRadians(to.latitude);
+  const deltaLat = toRadians(to.latitude - from.latitude);
+  const deltaLon = toRadians(to.longitude - from.longitude);
+  const a = Math.sin(deltaLat / 2) * Math.sin(deltaLat / 2) + Math.cos(lat1Rad) * Math.cos(lat2Rad) * Math.sin(deltaLon / 2) * Math.sin(deltaLon / 2);
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return EARTH_RADIUS_METERS * c;
+}
+function getDistanceKm(from, to) {
+  return getDistance(from, to) / 1e3;
+}
+
+// src/core/bearing.ts
+function getBearing(from, to) {
+  if (from.latitude === to.latitude && from.longitude === to.longitude) {
+    return 0;
+  }
+  const lat1 = toRadians(from.latitude);
+  const lat2 = toRadians(to.latitude);
+  const deltaLon = toRadians(to.longitude - from.longitude);
+  const y = Math.sin(deltaLon) * Math.cos(lat2);
+  const x = Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(deltaLon);
+  const bearing = toDegrees(Math.atan2(y, x));
+  return normalizeAngle(bearing);
+}
+function getRelativeBearing(userBearing, targetBearing) {
+  let relative = targetBearing - userBearing;
+  while (relative > 180) {
+    relative -= 360;
+  }
+  while (relative < -180) {
+    relative += 360;
+  }
+  return relative;
+}
+function getFinalBearing(from, to) {
+  const reverseBearing = getBearing(to, from);
+  return normalizeAngle(reverseBearing + 180);
+}
+
+// src/core/orientation.ts
+function getSimpleOrientation(relativeBearing) {
+  const abs = Math.abs(relativeBearing);
+  if (abs <= ORIENTATION_THRESHOLDS.AHEAD) {
+    return "ahead";
+  }
+  if (abs >= ORIENTATION_THRESHOLDS.BEHIND) {
+    return "behind";
+  }
+  return relativeBearing > 0 ? "right" : "left";
+}
+function getCompassOrientation(absoluteBearing) {
+  const normalized = normalizeAngle(absoluteBearing);
+  if (normalized < COMPASS_BOUNDARIES.NORTH_END || normalized >= COMPASS_BOUNDARIES.NORTHWEST_END) {
+    return "north";
+  }
+  if (normalized < COMPASS_BOUNDARIES.NORTHEAST_END) {
+    return "northeast";
+  }
+  if (normalized < COMPASS_BOUNDARIES.EAST_END) {
+    return "east";
+  }
+  if (normalized < COMPASS_BOUNDARIES.SOUTHEAST_END) {
+    return "southeast";
+  }
+  if (normalized < COMPASS_BOUNDARIES.SOUTH_END) {
+    return "south";
+  }
+  if (normalized < COMPASS_BOUNDARIES.SOUTHWEST_END) {
+    return "southwest";
+  }
+  if (normalized < COMPASS_BOUNDARIES.WEST_END) {
+    return "west";
+  }
+  return "northwest";
+}
+function getDetailedOrientation(relativeBearing) {
+  const abs = Math.abs(relativeBearing);
+  const isLeft = relativeBearing < 0;
+  if (abs <= ORIENTATION_THRESHOLDS.DIRECTLY_AHEAD) {
+    return "directly_ahead";
+  }
+  if (abs <= ORIENTATION_THRESHOLDS.AHEAD) {
+    return isLeft ? "ahead_left" : "ahead_right";
+  }
+  if (abs <= ORIENTATION_THRESHOLDS.BEHIND) {
+    return isLeft ? "left" : "right";
+  }
+  if (abs <= ORIENTATION_THRESHOLDS.DIRECTLY_BEHIND) {
+    return isLeft ? "behind_left" : "behind_right";
+  }
+  return "directly_behind";
+}
+function getOrientationDescription(orientation) {
+  const descriptions = {
+    // Simple
+    ahead: "ahead of you",
+    behind: "behind you",
+    left: "to your left",
+    right: "to your right",
+    // Compass
+    north: "to the north",
+    northeast: "to the northeast",
+    east: "to the east",
+    southeast: "to the southeast",
+    south: "to the south",
+    southwest: "to the southwest",
+    west: "to the west",
+    northwest: "to the northwest",
+    // Detailed
+    directly_ahead: "directly ahead",
+    ahead_left: "ahead on your left",
+    ahead_right: "ahead on your right",
+    behind_left: "behind you on the left",
+    behind_right: "behind you on the right",
+    directly_behind: "directly behind you"
+  };
+  return descriptions[orientation] ?? orientation;
+}
+
+// src/core/closest-point.ts
+function getClosestPoint(user, poi) {
+  const distance = getDistance(user, poi);
+  const bearing = getBearing(user, poi);
+  const poiRadius = poi.radiusMeters ?? 0;
+  const isInside = distance <= poiRadius;
+  if (poiRadius === 0) {
+    return {
+      closestPoint: { latitude: poi.latitude, longitude: poi.longitude },
+      distanceMeters: Math.round(distance),
+      bearing,
+      isInside: false
+    };
+  }
+  if (isInside) {
+    return {
+      closestPoint: { latitude: poi.latitude, longitude: poi.longitude },
+      distanceMeters: 0,
+      bearing,
+      isInside: true
+    };
+  }
+  const distanceToEdge = distance - poiRadius;
+  const bearingFromPOIToUser = getBearing(poi, user);
+  const closestPoint = destinationPoint(poi, bearingFromPOIToUser, poiRadius);
+  return {
+    closestPoint,
+    distanceMeters: Math.round(distanceToEdge),
+    bearing,
+    isInside: false
+  };
+}
+function destinationPoint(start, bearing, distanceMeters) {
+  if (distanceMeters === 0) {
+    return { latitude: start.latitude, longitude: start.longitude };
+  }
+  const angularDistance = distanceMeters / EARTH_RADIUS_METERS;
+  const bearingRad = toRadians(bearing);
+  const lat1 = toRadians(start.latitude);
+  const lon1 = toRadians(start.longitude);
+  const lat2 = Math.asin(
+    Math.sin(lat1) * Math.cos(angularDistance) + Math.cos(lat1) * Math.sin(angularDistance) * Math.cos(bearingRad)
+  );
+  const lon2 = lon1 + Math.atan2(
+    Math.sin(bearingRad) * Math.sin(angularDistance) * Math.cos(lat1),
+    Math.cos(angularDistance) - Math.sin(lat1) * Math.sin(lat2)
+  );
+  return {
+    latitude: toDegrees(lat2),
+    longitude: normalizeLongitude(toDegrees(lon2))
+  };
+}
+function getDistanceToEdge(user, poi) {
+  const distance = getDistance(user, poi);
+  const poiRadius = poi.radiusMeters ?? 0;
+  return Math.max(0, distance - poiRadius);
+}
+function isWithinPOI(point, poi) {
+  const distance = getDistance(point, poi);
+  const poiRadius = poi.radiusMeters ?? 0;
+  return distance <= poiRadius;
+}
+
+// src/utils/formatting.ts
+function formatDuration(seconds) {
+  if (!isFinite(seconds) || seconds < 0) {
+    return "Unknown";
+  }
+  if (seconds < 60) {
+    return `${Math.round(seconds)} sec`;
+  }
+  if (seconds < 3600) {
+    const minutes2 = Math.floor(seconds / 60);
+    const secs = Math.round(seconds % 60);
+    return secs > 0 ? `${minutes2} min ${secs} sec` : `${minutes2} min`;
+  }
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.round(seconds % 3600 / 60);
+  return minutes > 0 ? `${hours} hr ${minutes} min` : `${hours} hr`;
+}
+function formatDurationShort(seconds) {
+  if (!isFinite(seconds) || seconds < 0) {
+    return "--";
+  }
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  if (seconds < 3600) {
+    return `${Math.round(seconds / 60)}m`;
+  }
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.round(seconds % 3600 / 60);
+  return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+}
+function formatDistance(meters) {
+  if (!isFinite(meters) || meters < 0) {
+    return "Unknown";
+  }
+  if (meters < 1e3) {
+    return `${Math.round(meters)} m`;
+  }
+  const km = meters / 1e3;
+  if (km < 10) {
+    return `${km.toFixed(1)} km`;
+  }
+  return `${Math.round(km)} km`;
+}
+
+// src/core/eta.ts
+function getETA(user, poi, relativePosition) {
+  const distanceMeters = relativePosition?.distanceMeters ?? getDistance(user, poi);
+  const distanceToEdgeMeters = relativePosition?.distanceToEdgeMeters ?? getDistanceToEdge(user, poi);
+  const poiRadius = poi.radiusMeters ?? 0;
+  if (distanceMeters <= poiRadius) {
+    return {
+      etaSeconds: 0,
+      etaToEdgeSeconds: 0,
+      formatted: "At destination",
+      formattedShort: "0m",
+      isValid: false,
+      invalidReason: "at_destination"
+    };
+  }
+  if (user.speedMps === void 0 || user.speedMps === null) {
+    return {
+      etaSeconds: Infinity,
+      etaToEdgeSeconds: Infinity,
+      formatted: "Unknown",
+      formattedShort: "--",
+      isValid: false,
+      invalidReason: "no_speed_data"
+    };
+  }
+  if (user.speedMps < STATIONARY_SPEED_THRESHOLD) {
+    return {
+      etaSeconds: Infinity,
+      etaToEdgeSeconds: Infinity,
+      formatted: "Stationary",
+      formattedShort: "--",
+      isValid: false,
+      invalidReason: "stationary"
+    };
+  }
+  let relativeBearing = relativePosition?.relativeBearing;
+  if (relativeBearing === void 0 && user.bearing !== void 0) {
+    const absoluteBearing = getBearing(user, poi);
+    relativeBearing = getRelativeBearing(user.bearing, absoluteBearing);
+  }
+  if (relativeBearing !== void 0 && Math.abs(relativeBearing) > 90) {
+    return {
+      etaSeconds: Infinity,
+      etaToEdgeSeconds: Infinity,
+      formatted: "Moving away",
+      formattedShort: "--",
+      isValid: false,
+      invalidReason: "moving_away"
+    };
+  }
+  let effectiveSpeed = user.speedMps;
+  if (relativeBearing !== void 0) {
+    const angleRadians = toRadians(Math.abs(relativeBearing));
+    effectiveSpeed = user.speedMps * Math.cos(angleRadians);
+  }
+  if (effectiveSpeed <= 0) {
+    return {
+      etaSeconds: Infinity,
+      etaToEdgeSeconds: Infinity,
+      formatted: "Moving away",
+      formattedShort: "--",
+      isValid: false,
+      invalidReason: "moving_away"
+    };
+  }
+  const etaSeconds = distanceMeters / effectiveSpeed;
+  const etaToEdgeSeconds = distanceToEdgeMeters / effectiveSpeed;
+  return {
+    etaSeconds: Math.round(etaSeconds),
+    etaToEdgeSeconds: Math.round(etaToEdgeSeconds),
+    formatted: formatDuration(etaSeconds),
+    formattedShort: formatDurationShort(etaSeconds),
+    isValid: true
+  };
+}
+function getSimpleETA(distanceMeters, speedMps) {
+  if (speedMps <= 0 || !isFinite(speedMps)) {
+    return Infinity;
+  }
+  if (distanceMeters <= 0) {
+    return 0;
+  }
+  return distanceMeters / speedMps;
+}
+
+// src/core/relative-position.ts
+function getRelativePosition(user, poi) {
+  const distanceMeters = getDistance(user, poi);
+  const distanceKm = distanceMeters / 1e3;
+  const distanceToEdgeMeters = getDistanceToEdge(user, poi);
+  const absoluteBearing = getBearing(user, poi);
+  const userBearing = user.bearing ?? 0;
+  const relativeBearing = getRelativeBearing(userBearing, absoluteBearing);
+  const simpleOrientation = getSimpleOrientation(relativeBearing);
+  const compassOrientation = getCompassOrientation(absoluteBearing);
+  const detailedOrientation = getDetailedOrientation(relativeBearing);
+  const poiRadius = poi.radiusMeters ?? 0;
+  const isWithinPOI2 = distanceMeters <= poiRadius;
+  const approachStatus = determineApproachStatus(relativeBearing, user.speedMps, user.bearing);
+  return {
+    distanceMeters: Math.round(distanceMeters),
+    distanceKm: roundTo(distanceKm, 2),
+    distanceToEdgeMeters: Math.round(distanceToEdgeMeters),
+    absoluteBearing: roundTo(absoluteBearing, 1),
+    relativeBearing: roundTo(relativeBearing, 1),
+    simpleOrientation,
+    compassOrientation,
+    detailedOrientation,
+    isWithinPOI: isWithinPOI2,
+    approachStatus
+  };
+}
+function determineApproachStatus(relativeBearing, speedMps, userBearing) {
+  if (userBearing === void 0) {
+    return "unknown";
+  }
+  if (speedMps === void 0 || speedMps === null) {
+    return "unknown";
+  }
+  if (speedMps < STATIONARY_SPEED_THRESHOLD) {
+    return "stationary";
+  }
+  const abs = Math.abs(relativeBearing);
+  if (abs <= 90) {
+    return "approaching";
+  }
+  return "receding";
+}
+
+// src/batch/sort.ts
+function sortByDistance(user, pois, config = { by: "distance", direction: "asc" }) {
+  const results = pois.map((poi) => {
+    const relativePosition = getRelativePosition(user, poi);
+    return {
+      ...poi,
+      relativePosition,
+      eta: user.speedMps !== void 0 ? getETA(user, poi, relativePosition) : void 0
+    };
+  });
+  return results.sort((a, b) => {
+    let valueA;
+    let valueB;
+    switch (config.by) {
+      case "distance":
+        valueA = a.relativePosition.distanceMeters;
+        valueB = b.relativePosition.distanceMeters;
+        break;
+      case "eta":
+        valueA = a.eta?.etaSeconds ?? Infinity;
+        valueB = b.eta?.etaSeconds ?? Infinity;
+        break;
+      case "relativeBearing":
+        valueA = Math.abs(a.relativePosition.relativeBearing);
+        valueB = Math.abs(b.relativePosition.relativeBearing);
+        break;
+      default:
+        valueA = a.relativePosition.distanceMeters;
+        valueB = b.relativePosition.distanceMeters;
+    }
+    return config.direction === "asc" ? valueA - valueB : valueB - valueA;
+  });
+}
+function getNearestPOIs(user, pois, count) {
+  return sortByDistance(user, pois, { by: "distance", direction: "asc" }).slice(0, count);
+}
+function getNextArrivals(user, pois, count) {
+  return sortByDistance(user, pois, { by: "eta", direction: "asc" }).filter((poi) => poi.eta?.isValid).slice(0, count);
+}
+
+// src/batch/filter.ts
+function filterByProximity(user, pois, filter) {
+  return pois.map((poi) => {
+    const relativePosition = getRelativePosition(user, poi);
+    return {
+      ...poi,
+      relativePosition,
+      eta: user.speedMps !== void 0 ? getETA(user, poi, relativePosition) : void 0
+    };
+  }).filter((poi) => {
+    const distance = poi.relativePosition.distanceMeters;
+    if (distance > filter.maxDistanceMeters) {
+      return false;
+    }
+    if (filter.minDistanceMeters !== void 0 && distance < filter.minDistanceMeters) {
+      return false;
+    }
+    if (filter.approachingOnly && poi.relativePosition.approachStatus !== "approaching") {
+      return false;
+    }
+    return true;
+  }).sort((a, b) => a.relativePosition.distanceMeters - b.relativePosition.distanceMeters);
+}
+function filterByCone(user, pois, cone) {
+  return pois.map((poi) => {
+    const relativePosition = getRelativePosition(user, poi);
+    return {
+      ...poi,
+      relativePosition,
+      eta: user.speedMps !== void 0 ? getETA(user, poi, relativePosition) : void 0
+    };
+  }).filter((poi) => {
+    const distance = poi.relativePosition.distanceMeters;
+    const relativeBearing = Math.abs(poi.relativePosition.relativeBearing);
+    if (distance > cone.maxDistanceMeters) {
+      return false;
+    }
+    if (cone.minDistanceMeters !== void 0 && distance < cone.minDistanceMeters) {
+      return false;
+    }
+    if (relativeBearing > cone.halfAngle) {
+      return false;
+    }
+    return true;
+  }).sort((a, b) => a.relativePosition.distanceMeters - b.relativePosition.distanceMeters);
+}
+function filterInsidePOIs(user, pois) {
+  return pois.map((poi) => {
+    const relativePosition = getRelativePosition(user, poi);
+    return {
+      ...poi,
+      relativePosition,
+      eta: void 0
+      // ETA doesn't make sense when inside
+    };
+  }).filter((poi) => poi.relativePosition.isWithinPOI);
+}
+function filterByOrientation(user, pois, orientations) {
+  return pois.map((poi) => {
+    const relativePosition = getRelativePosition(user, poi);
+    return {
+      ...poi,
+      relativePosition,
+      eta: user.speedMps !== void 0 ? getETA(user, poi, relativePosition) : void 0
+    };
+  }).filter((poi) => orientations.includes(poi.relativePosition.simpleOrientation)).sort((a, b) => a.relativePosition.distanceMeters - b.relativePosition.distanceMeters);
+}
+
+// src/utils/validation.ts
+function isValidCoordinates(coords) {
+  return typeof coords.latitude === "number" && typeof coords.longitude === "number" && !isNaN(coords.latitude) && !isNaN(coords.longitude) && isFinite(coords.latitude) && isFinite(coords.longitude) && coords.latitude >= -90 && coords.latitude <= 90 && coords.longitude >= -180 && coords.longitude <= 180;
+}
+function isValidBearing(bearing) {
+  if (bearing === void 0) {
+    return true;
+  }
+  return typeof bearing === "number" && !isNaN(bearing) && isFinite(bearing);
+}
+function isValidSpeed(speed) {
+  if (speed === void 0) {
+    return true;
+  }
+  return typeof speed === "number" && !isNaN(speed) && isFinite(speed) && speed >= 0;
+}
+function isValidRadius(radius) {
+  if (radius === void 0) {
+    return true;
+  }
+  return typeof radius === "number" && !isNaN(radius) && isFinite(radius) && radius >= 0;
+}
+function validateUserPosition(user) {
+  if (!isValidCoordinates(user)) {
+    return { isValid: false, error: "Invalid coordinates: latitude must be -90 to 90, longitude must be -180 to 180" };
+  }
+  if (!isValidBearing(user.bearing)) {
+    return { isValid: false, error: "Invalid bearing: must be a finite number" };
+  }
+  if (!isValidSpeed(user.speedMps)) {
+    return { isValid: false, error: "Invalid speed: must be a non-negative number" };
+  }
+  return { isValid: true };
+}
+function validatePOI(poi) {
+  if (!isValidCoordinates(poi)) {
+    return { isValid: false, error: "Invalid coordinates: latitude must be -90 to 90, longitude must be -180 to 180" };
+  }
+  if (!isValidRadius(poi.radiusMeters)) {
+    return { isValid: false, error: "Invalid radius: must be a non-negative number" };
+  }
+  return { isValid: true };
+}
+
+// src/index.ts
+function convertSpeed(value, from, to) {
+  let mps;
+  switch (from) {
+    case "mps":
+      mps = value;
+      break;
+    case "kmh":
+      mps = value / 3.6;
+      break;
+    case "mph":
+      mps = value / 2.237;
+      break;
+  }
+  switch (to) {
+    case "mps":
+      return mps;
+    case "kmh":
+      return mps * 3.6;
+    case "mph":
+      return mps * 2.237;
+  }
+}
+export {
+  COMPASS_BOUNDARIES,
+  EARTH_RADIUS_METERS,
+  ORIENTATION_THRESHOLDS,
+  STATIONARY_SPEED_THRESHOLD,
+  clamp,
+  convertSpeed,
+  destinationPoint,
+  filterByCone,
+  filterByOrientation,
+  filterByProximity,
+  filterInsidePOIs,
+  formatDistance,
+  formatDuration,
+  formatDurationShort,
+  getBearing,
+  getClosestPoint,
+  getCompassOrientation,
+  getDetailedOrientation,
+  getDistance,
+  getDistanceKm,
+  getDistanceToEdge,
+  getETA,
+  getFinalBearing,
+  getNearestPOIs,
+  getNextArrivals,
+  getOrientationDescription,
+  getRelativeBearing,
+  getRelativePosition,
+  getSimpleETA,
+  getSimpleOrientation,
+  isValidBearing,
+  isValidCoordinates,
+  isValidRadius,
+  isValidSpeed,
+  isWithinPOI,
+  normalizeAngle,
+  normalizeLongitude,
+  roundTo,
+  sortByDistance,
+  toDegrees,
+  toRadians,
+  validatePOI,
+  validateUserPosition
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "geo-relative-position",
+  "version": "1.0.0",
+  "description": "Stateless library for calculating relative positions and navigation metrics between users and POIs",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build && npm test",
+    "publish:npm": "npm publish --access public"
+  },
+  "keywords": [
+    "geo",
+    "gps",
+    "location",
+    "distance",
+    "bearing",
+    "navigation",
+    "haversine",
+    "poi",
+    "coordinates",
+    "geolocation"
+  ],
+  "author": "Paul Aschmann",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}