feature: add unit option to nearest-point (#2415)

* feature: add unit option to nearest-point * chore: update types & docs * chore: add js-doc param * chore: update nearest-point readme --------- Co-authored-by: Rowan Winsemius <rowanwins@yahoo.com.au>
Turfjs · May 8, 2023 · 88dfdbb · 88dfdbb
1 parent ab2456f
commit 88dfdbb
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 6 deletions.
diff --git a/packages/turf-nearest-point/README.md b/packages/turf-nearest-point/README.md
@@ -13,6 +13,9 @@ is geodesic.
 
 *   `targetPoint` **[Coord][2]** the reference point
 *   `points` **[FeatureCollection][3]<[Point][4]>** against input point set
+*   `options` **[Object][5]** Optional parameters (optional, default `{}`)
+
+    *   `options.units` **[string][6]** the units of the numeric result (optional, default `'kilometers'`)
 
 ### Examples
 
@@ -31,7 +34,7 @@ var addToMap = [targetPoint, points, nearest];
 nearest.properties['marker-color'] = '#F00';
 ```
 
-Returns **[Feature][5]<[Point][4]>** the closest point in the set to the reference point
+Returns **[Feature][7]<[Point][4]>** the closest point in the set to the reference point
 
 [1]: https://tools.ietf.org/html/rfc7946#section-3.1.2
 
@@ -41,7 +44,11 @@ Returns **[Feature][5]<[Point][4]>** the closest point in the set to the referen
 
 [4]: https://tools.ietf.org/html/rfc7946#section-3.1.2
 
-[5]: https://tools.ietf.org/html/rfc7946#section-3.2
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[7]: https://tools.ietf.org/html/rfc7946#section-3.2
 
 <!-- This file is automatically generated. Please don't edit it directly:
 if you find an error, edit the source file (likely index.js), and re-run

diff --git a/packages/turf-nearest-point/index.ts b/packages/turf-nearest-point/index.ts
@@ -1,5 +1,5 @@
 import { Feature, FeatureCollection, Point } from "geojson";
-import { Coord } from "@turf/helpers";
+import { Coord, Units } from "@turf/helpers";
 import clone from "@turf/clone";
 import distance from "@turf/distance";
 import { featureEach } from "@turf/meta";
@@ -21,6 +21,8 @@ export interface NearestPoint extends Feature<Point> {
  * @name nearestPoint
  * @param {Coord} targetPoint the reference point
  * @param {FeatureCollection<Point>} points against input point set
+ * @param {Object} [options={}] Optional parameters
+ * @param {string} [options.units='kilometers'] the units of the numeric result
  * @returns {Feature<Point>} the closest point in the set to the reference point
  * @example
  * var targetPoint = turf.point([28.965797, 41.010086], {"marker-color": "#0F0"});
@@ -38,7 +40,10 @@ export interface NearestPoint extends Feature<Point> {
  */
 function nearestPoint(
   targetPoint: Coord,
-  points: FeatureCollection<Point>
+  points: FeatureCollection<Point>,
+  options: {
+    units?: Units;
+  } = {}
 ): NearestPoint {
   // Input validation
   if (!targetPoint) throw new Error("targetPoint is required");
@@ -47,7 +52,7 @@ function nearestPoint(
   let minDist = Infinity;
   let bestFeatureIndex = 0;
   featureEach(points, (pt, featureIndex) => {
-    const distanceToPoint = distance(targetPoint, pt);
+    const distanceToPoint = distance(targetPoint, pt, options);
     if (distanceToPoint < minDist) {
       bestFeatureIndex = featureIndex;
       minDist = distanceToPoint;

diff --git a/packages/turf-nearest-point/test.js b/packages/turf-nearest-point/test.js
@@ -59,3 +59,19 @@ test("nearest-point -- prevent input mutation", (t) => {
   t.deepEqual(pt2.properties, { distanceToPoint: "bar" });
   t.end();
 });
+
+test("nearest-point -- use different units", (t) => {
+  const pt1 = point([40, 50], { featureIndex: "foo" });
+  const pt2 = point([20, -10], { distanceToPoint: "bar" });
+  const pts = featureCollection([pt1, pt2]);
+  const distanceInKilometers = nearestPoint([0, 0], pts).properties
+    .distanceToPoint;
+  const distanceInMeters = nearestPoint([0, 0], pts, { units: "meters" })
+    .properties.distanceToPoint;
+  const oneKilometerInMeters = 1000;
+
+  // Check if the proper distance gets returned when using "units" option
+  t.equal(distanceInKilometers, distanceInMeters / oneKilometerInMeters);
+
+  t.end();
+});
diff --git a/packages/turf-nearest-point/types.ts b/packages/turf-nearest-point/types.ts
@@ -7,6 +7,6 @@ const points = featureCollection([
   point([28.948459, 41.024204]),
   point([28.938674, 41.013324]),
 ]);
-const nearest = nearestPoint(targetPoint, points);
+const nearest = nearestPoint(targetPoint, points, { units: "kilometers" });
 nearest.properties.distanceToPoint;
 nearest.properties.featureIndex;