@turf/helpers - npm Package Compare versions

Comparing version 4.2.0 to 4.3.0

index.d.ts

@@ -15,14 +15,21 @@ /// <reference types="geojson" />
 export type MultiPolygon = GeoJSON.Feature<GeoJSON.MultiPolygon>;
-export type Features = GeoJSON.FeatureCollection<any>;
-export type Feature = GeoJSON.Feature<any>;
 export type Position = GeoJSON.Position;
 export type LineStringFeatures = LineString | LineStrings | MultiLineString | MultiLineStrings | GeoJSON.LineString | GeoJSON.MultiLineString
 export type PolygonFeatures = Polygon | Polygons | MultiPolygon | MultiPolygons | GeoJSON.Polygon | GeoJSON.MultiPolygon
+export type Features<Geom extends GeometryObject> = GeoJSON.FeatureCollection<Geom>;
+export type Feature<Geom extends GeometryObject> = GeoJSON.Feature<Geom>;
 export type Units = "miles" | "nauticalmiles" | "degrees" | "radians" | "inches" | "yards" | "meters" | "metres" | "kilometers" | "kilometres";
 export type BBox = [number, number, number, number];
+export type GeometryObject = GeoJSON.GeometryObject;
+export type GeometryCollection = GeoJSON.GeometryCollection;
+export type Geoms = GeoJSON.Point | GeoJSON.LineString | GeoJSON.Polygon | GeoJSON.MultiPoint | GeoJSON.MultiLineString | GeoJSON.MultiPolygon;
 
+export interface FeatureGeometryCollection extends GeoJSON.Feature<any> {
+  geometry: GeometryCollection
+}
+
 /**
  * http://turfjs.org/docs/#feature
  */
-export function feature(geometry: GeoJSON.GeometryObject, properties?: any): Feature;
+export function feature<Geom extends GeometryObject>(geometry: Geom, properties?: any): Feature<Geom>;
 
@@ -47,11 +54,7 @@ /**
  */
-export const featureCollection: {
-    (features: Array<Point>): Points;
-    (features: Array<LineString>): LineStrings;
-    (features: Array<Polygon>): Polygons;
-    (features: Array<MultiPoint>): MultiPoints;
-    (features: Array<MultiLineString>): MultiLineStrings;
-    (features: Array<MultiPolygon>): MultiPolygons;
-    (features: Array<Feature>): Features;
-};
+interface featureCollection {
+  <Geom extends Geoms>(features: Feature<Geom>[]): Features<Geom>;
+  (features: Feature<any>[]): Features<any>;
+}
+export const featureCollection: featureCollection;
 
@@ -76,3 +79,3 @@ /**
  */
-export function geometryCollection(geometries: Array<GeoJSON.GeometryObject>, properties?: any): GeoJSON.GeometryCollection;
+export function geometryCollection(geometries: GeometryObject[], properties?: any): FeatureGeometryCollection;
 
@@ -97,2 +100,22 @@ /**
  */
-export function bearingToAngle(alpha: number): number
+export function bearingToAngle(bearing: number): number
+
+/**
+ * http://turfjs.org/docs/#radians2degrees
+ */
+export function radians2degrees(radians: number): number
+
+/**
+ * http://turfjs.org/docs/#degrees2radians
+ */
+export function degrees2radians(degrees: number): number
+
+/**
+ * http://turfjs.org/docs/#round
+ */
+export function round(num: number, precision?: number): number
+
+/**
+ * http://turfjs.org/docs/#convertdistance
+ */
+export function convertDistance(distance: number, originalUnit: Units, finalUnit?: Units): number

index.js

@@ -7,11 +7,8 @@ /**
  * @param {Object} properties properties
- * @returns {FeatureCollection} a FeatureCollection of input features
+ * @returns {Feature} a GeoJSON Feature
  * @example
  * var geometry = {
- *      "type": "Point",
- *      "coordinates": [
- *        67.5,
- *        32.84267363195431
- *      ]
- *    }
+ *   "type": "Point",
+ *   "coordinates": [110, 50]
+ * };
  *
@@ -41,5 +38,5 @@ * var feature = turf.feature(geometry);
  * @example
- * var pt1 = turf.point([-75.343, 39.984]);
+ * var point = turf.point([-75.343, 39.984]);
  *
- * //=pt1
+ * //=point
  */
@@ -66,11 +63,10 @@ function point(coordinates, properties) {
  * @throws {Error} throw an error if a LinearRing of the polygon has too few positions
- * or if a LinearRing of the Polygon does not have matching Positions at the
- * beginning & end.
+ * or if a LinearRing of the Polygon does not have matching Positions at the beginning & end.
  * @example
  * var polygon = turf.polygon([[
- *  [-2.275543, 53.464547],
- *  [-2.275543, 53.489271],
- *  [-2.215118, 53.489271],
- *  [-2.215118, 53.464547],
- *  [-2.275543, 53.464547]
+ *   [-2.275543, 53.464547],
+ *   [-2.275543, 53.489271],
+ *   [-2.215118, 53.489271],
+ *   [-2.215118, 53.464547],
+ *   [-2.275543, 53.464547]
  * ]], { name: 'poly1', population: 400});
@@ -130,2 +126,3 @@ *
     if (!coordinates) throw new Error('No coordinates passed');
+    if (coordinates.length < 2) throw new Error('Coordinates must be an array of two or more positions');
 
@@ -151,5 +148,5 @@ return feature({
  *
- * var fc = turf.featureCollection(features);
+ * var collection = turf.featureCollection(features);
  *
- * //=fc
+ * //=collection
  */
@@ -178,3 +175,2 @@ function featureCollection(features) {
  * //=multiLine
- *
  */
@@ -203,3 +199,2 @@ function multiLineString(coordinates, properties) {
  * //=multiPt
- *
  */
@@ -215,3 +210,2 @@ function multiPoint(coordinates, properties) {
 
-
 /**
@@ -263,3 +257,3 @@ * Creates a {@link Feature<MultiPolygon>} based on a
 function geometryCollection(geometries, properties) {
-    if (!geometries) throw new Error('No geometries passed');
+    if (!geometries) throw new Error('geometries is required');
 
@@ -272,2 +266,3 @@ return feature({
 
+// https://en.wikipedia.org/wiki/Great-circle_distance#Radius_for_spherical_Earth
 var factors = {
@@ -282,2 +277,4 @@ miles: 3960,
     metres: 6373000,
+    centimeters: 6.373e+8,
+    centimetres: 6.373e+8,
     kilometers: 6373,
@@ -289,4 +286,25 @@ kilometres: 6373,
 /**
- * Convert a distance measurement from radians to a more friendly unit.
+ * Round number to precision
  *
+ * @param {number} num Number
+ * @param {number} [precision=0] Precision
+ * @returns {number} rounded number
+ * @example
+ * round(120.4321)
+ * //=120
+ *
+ * round(120.4321, 2)
+ * //=120.43
+ */
+function round(num, precision) {
+    if (num === undefined || num === null || isNaN(num)) throw new Error('num is required');
+    if (precision && !(precision >= 0)) throw new Error('precision must be a positive number');
+    var multiplier = Math.pow(10, precision || 0);
+    return Math.round(num * multiplier) / multiplier;
+}
+
+/**
+ * Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
+ *
  * @name radiansToDistance
@@ -298,5 +316,6 @@ * @param {number} radians in radians across the sphere
 function radiansToDistance(radians, units) {
+    if (radians === undefined || radians === null) throw new Error('radians is required');
+
     var factor = factors[units || 'kilometers'];
-    if (factor === undefined) throw new Error('Invalid unit');
-
+    if (!factor) throw new Error('units is invalid');
     return radians * factor;
@@ -306,3 +325,4 @@ }
 /**
- * Convert a distance measurement from a real-world unit into radians
+ * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
  *
@@ -315,5 +335,6 @@ * @name distanceToRadians
 function distanceToRadians(distance, units) {
+    if (distance === undefined || distance === null) throw new Error('distance is required');
+
     var factor = factors[units || 'kilometers'];
-    if (factor === undefined) throw new Error('Invalid unit');
-
+    if (!factor) throw new Error('units is invalid');
     return distance / factor;
@@ -323,3 +344,4 @@ }
 /**
- * Convert a distance measurement from a real-world unit into degrees
+ * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
  *
@@ -332,9 +354,5 @@ * @name distanceToDegrees
 function distanceToDegrees(distance, units) {
-    var factor = factors[units || 'kilometers'];
-    if (factor === undefined) throw new Error('Invalid unit');
-
-    return (distance / factor) * 57.2958;
+    return radians2degrees(distanceToRadians(distance, units));
 }
 
-
 /**
@@ -345,14 +363,60 @@ * Converts any bearing angle from the north line direction (positive clockwise)
  * @name bearingToAngle
- * @param {number} alpha angle
+ * @param {number} bearing angle, between -180 and +180 degrees
  * @returns {number} angle between 0 and 360 degrees
  */
-function bearingToAngle(alpha) {
-    var beta = alpha % 360;
-    if (beta < 0) {
-        beta += 360;
-    }
-    return beta;
+function bearingToAngle(bearing) {
+    if (bearing === null || bearing === undefined) throw new Error('bearing is required');
+
+    var angle = bearing % 360;
+    if (angle < 0) angle += 360;
+    return angle;
 }
 
+/**
+ * Converts an angle in radians to degrees
+ *
+ * @name radians2degrees
+ * @param {number} radians angle in radians
+ * @returns {number} degrees between 0 and 360 degrees
+ */
+function radians2degrees(radians) {
+    if (radians === null || radians === undefined) throw new Error('radians is required');
 
+    var degrees = radians % (2 * Math.PI);
+    return degrees * 180 / Math.PI;
+}
+
+/**
+ * Converts an angle in degrees to radians
+ *
+ * @name degrees2radians
+ * @param {number} degrees angle between 0 and 360 degrees
+ * @returns {number} angle in radians
+ */
+function degrees2radians(degrees) {
+    if (degrees === null || degrees === undefined) throw new Error('degrees is required');
+
+    var radians = degrees % 360;
+    return radians * Math.PI / 180;
+}
+
+
+/**
+ * Converts a distance to the requested unit.
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
+ *
+ * @param {number} distance to be converted
+ * @param {string} originalUnit of the distance
+ * @param {string} [finalUnit=kilometers] returned unit
+ * @returns {number} the converted distance
+ */
+function convertDistance(distance, originalUnit, finalUnit) {
+    if (distance === null || distance === undefined) throw new Error('distance is required');
+    if (!(distance >= 0)) throw new Error('distance must be a positive number');
+
+    var convertedDistance = radiansToDistance(distanceToRadians(distance, originalUnit), finalUnit || 'kilometers');
+    return convertedDistance;
+}
+
+
 module.exports = {
@@ -371,3 +435,7 @@ feature: feature,
     distanceToDegrees: distanceToDegrees,
-    bearingToAngle: bearingToAngle
+    radians2degrees: radians2degrees,
+    degrees2radians: degrees2radians,
+    bearingToAngle: bearingToAngle,
+    convertDistance: convertDistance,
+    round: round
 };

package.json

 {
   "name": "@turf/helpers",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "turf helpers module",
@@ -26,2 +26,7 @@ "main": "index.js",
   "author": "Turf Authors",
+  "contributors": [
+    "Tom MacWright <@tmcw>",
+    "Stefano Borghi <@stebogit>",
+    "Denis Carriere <@DenisCarriere>"
+  ],
   "license": "MIT",
@@ -33,7 +38,6 @@ "bugs": {
   "devDependencies": {
-    "@turf/distance": "^4.2.0",
-    "benchmark": "^2.1.3",
-    "tape": "^3.5.0"
+    "benchmark": "^2.1.4",
+    "tape": "^4.6.3"
   },
   "dependencies": {}
 }

README.md

@@ -16,8 +16,5 @@ # @turf/helpers
 var geometry = {
-     "type": "Point",
-     "coordinates": [
-       67.5,
-       32.84267363195431
-     ]
-   }
+  "type": "Point",
+  "coordinates": [110, 50]
+};
 
@@ -29,3 +26,3 @@ var feature = turf.feature(geometry);
 
-Returns **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** a FeatureCollection of input features
+Returns **[Feature](http://geojson.org/geojson-spec.html#feature-objects)** a GeoJSON Feature
 
@@ -45,5 +42,5 @@ # point
 ```javascript
-var pt1 = turf.point([-75.343, 39.984]);
+var point = turf.point([-75.343, 39.984]);
 
-//=pt1
+//=point
 ```
@@ -66,7 +63,7 @@
 var polygon = turf.polygon([[
- [-2.275543, 53.464547],
- [-2.275543, 53.489271],
- [-2.215118, 53.489271],
- [-2.215118, 53.464547],
- [-2.275543, 53.464547]
+  [-2.275543, 53.464547],
+  [-2.275543, 53.489271],
+  [-2.215118, 53.489271],
+  [-2.215118, 53.464547],
+  [-2.275543, 53.464547]
 ]], { name: 'poly1', population: 400});
@@ -78,4 +75,3 @@
 -   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** throw an error if a LinearRing of the polygon has too few positions
-    or if a LinearRing of the Polygon does not have matching Positions at the
-    beginning & end.
+    or if a LinearRing of the Polygon does not have matching Positions at the beginning & end.
 
@@ -136,5 +132,5 @@ Returns **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Polygon](http://geojson.org/geojson-spec.html#polygon)>** a Polygon feature
 
-var fc = turf.featureCollection(features);
+var collection = turf.featureCollection(features);
 
-//=fc
+//=collection
 ```
@@ -238,5 +234,27 @@
 
+# round
+
+Round number to precision
+
+**Parameters**
+
+-   `num` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Number
+-   `precision` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Precision (optional, default `0`)
+
+**Examples**
+
+```javascript
+round(120.4321)
+//=120
+
+round(120.4321, 2)
+//=120.43
+```
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** rounded number
+
 # radiansToDistance
 
-Convert a distance measurement from radians to a more friendly unit.
+Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 
@@ -252,3 +270,4 @@ **Parameters**
 
-Convert a distance measurement from a real-world unit into radians
+Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 
@@ -264,3 +283,4 @@ **Parameters**
 
-Convert a distance measurement from a real-world unit into degrees
+Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
 
@@ -281,6 +301,39 @@ **Parameters**
 
--   `alpha` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle
+-   `bearing` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle, between -180 and +180 degrees
 
 Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle between 0 and 360 degrees
 
+# radians2degrees
+
+Converts an angle in radians to degrees
+
+**Parameters**
+
+-   `radians` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle in radians
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** degrees between 0 and 360 degrees
+
+# degrees2radians
+
+Converts an angle in degrees to radians
+
+**Parameters**
+
+-   `degrees` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle between 0 and 360 degrees
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle in radians
+
+# convertDistance
+
+Converts a distance to the requested unit.
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
+
+**Parameters**
+
+-   `distance` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** to be converted
+-   `originalUnit` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** of the distance
+-   `finalUnit` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** returned unit (optional, default `kilometers`)
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the converted distance
+
 <!-- This file is automatically generated. Please don't edit it directly:
@@ -287,0 +340,0 @@ if you find an error, edit the source file (likely index.js), and re-run

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

34747

increased by21.33%

Dev dependency count

2

decreased by-33.33%

Lines of code

484

increased by20.1%

Number of lines in readme file

353

increased by17.67%

No dependency changes