@turf/helpers 7.0.0-alpha.2 → 7.0.0

package/dist/{es/index.js → cjs/index.d.cts}

@@ -1,3 +1,52 @@
+import { GeoJSON, Feature, Point, Position, LineString, MultiLineString, Polygon, MultiPolygon, FeatureCollection, Geometry, GeometryCollection, GeometryObject, GeoJsonProperties, BBox, MultiPoint } from 'geojson';
+
+/**
+ * Id
+ *
+ * https://tools.ietf.org/html/rfc7946#section-3.2
+ * If a Feature has a commonly used identifier, that identifier SHOULD be included as a member of
+ * the Feature object with the name "id", and the value of this member is either a JSON string or number.
+ *
+ * Should be contributed to @types/geojson
+ */
+type Id = string | number;
+
+/**
+
+ * GeoJSON equality checking utility.
+ * Adapted from https://github.com/geosquare/geojson-equality
+ *
+ * @memberof helpers
+ * @type {Class}
+ */
+declare class GeojsonEquality {
+    private precision;
+    private direction;
+    private compareProperties;
+    constructor(opts?: {
+        precision?: number;
+        direction?: boolean;
+        compareProperties?: boolean;
+    });
+    compare(g1: GeoJSON, g2: GeoJSON): boolean;
+    private compareCoord;
+    private compareLine;
+    private fixStartIndex;
+    private comparePath;
+    private comparePolygon;
+    private compareGeometryCollection;
+    private compareFeature;
+    private compareFeatureCollection;
+    private compareBBox;
+}
+
+type Coord = Feature<Point> | Point | Position;
+type Units = "meters" | "metres" | "millimeters" | "millimetres" | "centimeters" | "centimetres" | "kilometers" | "kilometres" | "miles" | "nauticalmiles" | "inches" | "yards" | "feet" | "radians" | "degrees";
+type AreaUnits = Exclude<Units, "radians" | "degrees"> | "acres" | "hectares";
+type Grid = "point" | "square" | "hex" | "triangle";
+type Corners = "sw" | "se" | "nw" | "ne" | "center" | "centroid";
+type Lines = LineString | MultiLineString | Polygon | MultiPolygon;
+type AllGeoJSON = Feature | FeatureCollection | Geometry | GeometryCollection;
 /**
  * @module helpers
  */
@@ -7,7 +56,7 @@
  * @memberof helpers
  * @type {number}
  */
-export const earthRadius = 6371008.8;
+declare const earthRadius = 6371008.8;
 /**
  * Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
  *
@@ -16,23 +65,7 @@ export const earthRadius = 6371008.8;
  * @memberof helpers
  * @type {Object}
  */
-export const factors = {
-    centimeters: earthRadius * 100,
-    centimetres: earthRadius * 100,
-    degrees: 360 / (2 * Math.PI),
-    feet: earthRadius * 3.28084,
-    inches: earthRadius * 39.37,
-    kilometers: earthRadius / 1000,
-    kilometres: earthRadius / 1000,
-    meters: earthRadius,
-    metres: earthRadius,
-    miles: earthRadius / 1609.344,
-    millimeters: earthRadius * 1000,
-    millimetres: earthRadius * 1000,
-    nauticalmiles: earthRadius / 1852,
-    radians: 1,
-    yards: earthRadius * 1.0936,
-};
+declare const factors: Record<Units, number>;
 /**
 
  * Area of measurement factors based on 1 square meter.
@@ -40,23 +73,7 @@ export const factors = {
  * @memberof helpers
  * @type {Object}
  */
-export const areaFactors = {
-    acres: 0.000247105,
-    centimeters: 10000,
-    centimetres: 10000,
-    feet: 10.763910417,
-    hectares: 0.0001,
-    inches: 1550.003100006,
-    kilometers: 0.000001,
-    kilometres: 0.000001,
-    meters: 1,
-    metres: 1,
-    miles: 3.86e-7,
-    nauticalmiles: 2.9155334959812285e-7,
-    millimeters: 1000000,
-    millimetres: 1000000,
-    yards: 1.195990046,
-};
+declare const areaFactors: Record<AreaUnits, number>;
 /**
  * Wraps a GeoJSON {@link Geometry} in a GeoJSON {@link Feature}.
  *
@@ -77,18 +94,10 @@ export const areaFactors = {
  *
  * //=feature
  */
-export function feature(geom, properties, options = {}) {
-    const feat = { type: "Feature" };
-    if (options.id === 0 || options.id) {
-        feat.id = options.id;
-    }
-    if (options.bbox) {
-        feat.bbox = options.bbox;
-    }
-    feat.properties = properties || {};
-    feat.geometry = geom;
-    return feat;
-}
+declare function feature<G extends GeometryObject = Geometry, P extends GeoJsonProperties = GeoJsonProperties>(geom: G | null, properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<G, P>;
 /**
  * Creates a GeoJSON {@link Geometry} from a Geometry string type & coordinates.
  * For GeometryCollection type use `helpers.geometryCollection`
@@ -104,24 +113,7 @@ export function feature(geom, properties, options = {}) {
  * var geometry = turf.geometry(type, coordinates);
  * // => geometry
  */
-export function geometry(type, coordinates, _options = {}) {
-    switch (type) {
-        case "Point":
-            return point(coordinates).geometry;
-        case "LineString":
-            return lineString(coordinates).geometry;
-        case "Polygon":
-            return polygon(coordinates).geometry;
-        case "MultiPoint":
-            return multiPoint(coordinates).geometry;
-        case "MultiLineString":
-            return multiLineString(coordinates).geometry;
-        case "MultiPolygon":
-            return multiPolygon(coordinates).geometry;
-        default:
-            throw new Error(type + " is invalid");
-    }
-}
+declare function geometry(type: "Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon", coordinates: any[], _options?: Record<string, never>): Point | MultiPoint | LineString | MultiLineString | Polygon | MultiPolygon;
 /**
  * Creates a {@link Point} {@link Feature} from a Position.
  *
@@ -137,25 +129,10 @@ export function geometry(type, coordinates, _options = {}) {
  *
  * //=point
  */
-export function point(coordinates, properties, options = {}) {
-    if (!coordinates) {
-        throw new Error("coordinates is required");
-    }
-    if (!Array.isArray(coordinates)) {
-        throw new Error("coordinates must be an Array");
-    }
-    if (coordinates.length < 2) {
-        throw new Error("coordinates must be at least 2 numbers long");
-    }
-    if (!isNumber(coordinates[0]) || !isNumber(coordinates[1])) {
-        throw new Error("coordinates must contain numbers");
-    }
-    const geom = {
-        type: "Point",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function point<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position, properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<Point, P>;
 /**
  * Creates a {@link Point} {@link FeatureCollection} from an Array of Point coordinates.
  *
@@ -176,11 +153,10 @@ export function point(coordinates, properties, options = {}) {
  *
  * //=points
  */
-export function points(coordinates, properties, options = {}) {
-    return featureCollection(coordinates.map((coords) => {
-        return point(coords, properties);
-    }), options);
-}
+declare function points<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): FeatureCollection<Point, P>;
 /**
  * Creates a {@link Polygon} {@link Feature} from an Array of LinearRings.
  *
@@ -196,27 +172,10 @@ export function points(coordinates, properties, options = {}) {
  *
  * //=polygon
  */
-export function polygon(coordinates, properties, options = {}) {
-    for (const ring of coordinates) {
-        if (ring.length < 4) {
-            throw new Error("Each LinearRing of a Polygon must have 4 or more Positions.");
-        }
-        if (ring[ring.length - 1].length !== ring[0].length) {
-            throw new Error("First and last Position are not equivalent.");
-        }
-        for (let j = 0; j < ring[ring.length - 1].length; j++) {
-            // Check if first point of Polygon contains two numbers
-            if (ring[ring.length - 1][j] !== ring[0][j]) {
-                throw new Error("First and last Position are not equivalent.");
-            }
-        }
-    }
-    const geom = {
-        type: "Polygon",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function polygon<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[][], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<Polygon, P>;
 /**
  * Creates a {@link Polygon} {@link FeatureCollection} from an Array of Polygon coordinates.
  *
@@ -235,11 +194,10 @@ export function polygon(coordinates, properties, options = {}) {
  *
  * //=polygons
  */
-export function polygons(coordinates, properties, options = {}) {
-    return featureCollection(coordinates.map((coords) => {
-        return polygon(coords, properties);
-    }), options);
-}
+declare function polygons<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[][][], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): FeatureCollection<Polygon, P>;
 /**
  * Creates a {@link LineString} {@link Feature} from an Array of Positions.
  *
@@ -257,16 +215,10 @@ export function polygons(coordinates, properties, options = {}) {
  * //=linestring1
  * //=linestring2
  */
-export function lineString(coordinates, properties, options = {}) {
-    if (coordinates.length < 2) {
-        throw new Error("coordinates must be an array of two or more positions");
-    }
-    const geom = {
-        type: "LineString",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function lineString<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<LineString, P>;
 /**
  * Creates a {@link LineString} {@link FeatureCollection} from an Array of LineString coordinates.
  *
@@ -286,11 +238,10 @@ export function lineString(coordinates, properties, options = {}) {
  *
  * //=linestrings
  */
-export function lineStrings(coordinates, properties, options = {}) {
-    return featureCollection(coordinates.map((coords) => {
-        return lineString(coords, properties);
-    }), options);
-}
+declare function lineStrings<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[][], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): FeatureCollection<LineString, P>;
 /**
  * Takes one or more {@link Feature|Features} and creates a {@link FeatureCollection}.
  *
@@ -313,17 +264,10 @@ export function lineStrings(coordinates, properties, options = {}) {
  *
  * //=collection
  */
-export function featureCollection(features, options = {}) {
-    const fc = { type: "FeatureCollection" };
-    if (options.id) {
-        fc.id = options.id;
-    }
-    if (options.bbox) {
-        fc.bbox = options.bbox;
-    }
-    fc.features = features;
-    return fc;
-}
+declare function featureCollection<G extends GeometryObject = Geometry, P extends GeoJsonProperties = GeoJsonProperties>(features: Array<Feature<G, P>>, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): FeatureCollection<G, P>;
 /**
  * Creates a {@link Feature<MultiLineString>} based on a
  * coordinate array. Properties can be added optionally.
@@ -341,13 +285,10 @@ export function featureCollection(features, options = {}) {
  *
  * //=multiLine
  */
-export function multiLineString(coordinates, properties, options = {}) {
-    const geom = {
-        type: "MultiLineString",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function multiLineString<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[][], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<MultiLineString, P>;
 /**
  * Creates a {@link Feature<MultiPoint>} based on a
  * coordinate array. Properties can be added optionally.
@@ -365,13 +306,10 @@ export function multiLineString(coordinates, properties, options = {}) {
  *
  * //=multiPt
  */
-export function multiPoint(coordinates, properties, options = {}) {
-    const geom = {
-        type: "MultiPoint",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function multiPoint<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<MultiPoint, P>;
 /**
  * Creates a {@link Feature<MultiPolygon>} based on a
  * coordinate array. Properties can be added optionally.
@@ -390,13 +328,10 @@ export function multiPoint(coordinates, properties, options = {}) {
  * //=multiPoly
  *
  */
-export function multiPolygon(coordinates, properties, options = {}) {
-    const geom = {
-        type: "MultiPolygon",
-        coordinates,
-    };
-    return feature(geom, properties, options);
-}
+declare function multiPolygon<P extends GeoJsonProperties = GeoJsonProperties>(coordinates: Position[][][], properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<MultiPolygon, P>;
 /**
  * Creates a {@link Feature<GeometryCollection>} based on a
  * coordinate array. Properties can be added optionally.
@@ -415,13 +350,10 @@ export function multiPolygon(coordinates, properties, options = {}) {
  *
  * // => collection
  */
-export function geometryCollection(geometries, properties, options = {}) {
-    const geom = {
-        type: "GeometryCollection",
-        geometries,
-    };
-    return feature(geom, properties, options);
-}
+declare function geometryCollection<P extends GeoJsonProperties = GeoJsonProperties>(geometries: Array<Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon>, properties?: P, options?: {
+    bbox?: BBox;
+    id?: Id;
+}): Feature<GeometryCollection, P>;
 /**
  * Round number to precision
  *
@@ -435,13 +367,7 @@ export function geometryCollection(geometries, properties, options = {}) {
  * turf.round(120.4321, 2)
  * //=120.43
  */
-export function round(num, precision = 0) {
-    if (precision && !(precision >= 0)) {
-        throw new Error("precision must be a positive number");
-    }
-    const multiplier = Math.pow(10, precision || 0);
-    return Math.round(num * multiplier) / multiplier;
-}
+declare function round(num: number, precision?: number): number;
 /**
  * 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
@@ -452,13 +378,7 @@ export function round(num, precision = 0) {
  * meters, kilometres, kilometers.
  * @returns {number} distance
  */
-export function radiansToLength(radians, units = "kilometers") {
-    const factor = factors[units];
-    if (!factor) {
-        throw new Error(units + " units is invalid");
-    }
-    return radians * factor;
-}
+declare function radiansToLength(radians: number, units?: Units): number;
 /**
  * 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
@@ -469,13 +389,7 @@ export function radiansToLength(radians, units = "kilometers") {
  * meters, kilometres, kilometers.
  * @returns {number} radians
  */
-export function lengthToRadians(distance, units = "kilometers") {
-    const factor = factors[units];
-    if (!factor) {
-        throw new Error(units + " units is invalid");
-    }
-    return distance / factor;
-}
+declare function lengthToRadians(distance: number, units?: Units): number;
 /**
  * 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
@@ -486,9 +400,7 @@ export function lengthToRadians(distance, units = "kilometers") {
  * meters, kilometres, kilometers.
  * @returns {number} degrees
  */
-export function lengthToDegrees(distance, units) {
-    return radiansToDegrees(lengthToRadians(distance, units));
-}
+declare function lengthToDegrees(distance: number, units?: Units): number;
 /**
  * Converts any bearing angle from the north line direction (positive clockwise)
  * and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line
@@ -497,13 +409,7 @@ export function lengthToDegrees(distance, units) {
  * @param {number} bearing angle, between -180 and +180 degrees
  * @returns {number} angle between 0 and 360 degrees
  */
-export function bearingToAzimuth(bearing) {
-    let angle = bearing % 360;
-    if (angle < 0) {
-        angle += 360;
-    }
-    return angle;
-}
+declare function bearingToAzimuth(bearing: number): number;
 /**
  * Converts an angle in radians to degrees
  *
@@ -511,10 +417,7 @@ export function bearingToAzimuth(bearing) {
  * @param {number} radians angle in radians
  * @returns {number} degrees between 0 and 360 degrees
  */
-export function radiansToDegrees(radians) {
-    const degrees = radians % (2 * Math.PI);
-    return (degrees * 180) / Math.PI;
-}
+declare function radiansToDegrees(radians: number): number;
 /**
  * Converts an angle in degrees to radians
  *
@@ -522,10 +425,7 @@ export function radiansToDegrees(radians) {
  * @param {number} degrees angle between 0 and 360 degrees
  * @returns {number} angle in radians
  */
-export function degreesToRadians(degrees) {
-    const radians = degrees % 360;
-    return (radians * Math.PI) / 180;
-}
+declare function degreesToRadians(degrees: number): number;
 /**
  * Converts a length to the requested unit.
  * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
@@ -535,12 +435,7 @@ export function degreesToRadians(degrees) {
  * @param {Units} [finalUnit="kilometers"] returned unit
  * @returns {number} the converted length
  */
-export function convertLength(length, originalUnit = "kilometers", finalUnit = "kilometers") {
-    if (!(length >= 0)) {
-        throw new Error("length must be a positive number");
-    }
-    return radiansToLength(lengthToRadians(length, originalUnit), finalUnit);
-}
+declare function convertLength(length: number, originalUnit?: Units, finalUnit?: Units): number;
 /**
  * Converts a area to the requested unit.
  * Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares
@@ -549,20 +444,7 @@ export function convertLength(length, originalUnit = "kilometers", finalUnit = "
  * @param {Units} [finalUnit="kilometers"] returned unit
  * @returns {number} the converted area
  */
-export function convertArea(area, originalUnit = "meters", finalUnit = "kilometers") {
-    if (!(area >= 0)) {
-        throw new Error("area must be a positive number");
-    }
-    const startFactor = areaFactors[originalUnit];
-    if (!startFactor) {
-        throw new Error("invalid original units");
-    }
-    const finalFactor = areaFactors[finalUnit];
-    if (!finalFactor) {
-        throw new Error("invalid final units");
-    }
-    return (area / startFactor) * finalFactor;
-}
+declare function convertArea(area: number, originalUnit?: AreaUnits, finalUnit?: AreaUnits): number;
 /**
  * isNumber
  *
@@ -574,9 +456,7 @@ export function convertArea(area, originalUnit = "meters", finalUnit = "kilomete
  * turf.isNumber('foo')
  * //=false
  */
-export function isNumber(num) {
-    return !isNaN(num) && num !== null && !Array.isArray(num);
-}
+declare function isNumber(num: any): boolean;
 /**
  * isObject
  *
@@ -588,9 +468,7 @@ export function isNumber(num) {
  * turf.isObject('foo')
  * //=false
  */
-export function isObject(input) {
-    return input !== null && typeof input === "object" && !Array.isArray(input);
-}
+declare function isObject(input: any): boolean;
 /**
  * Validate BBox
  *
@@ -612,22 +490,7 @@ export function isObject(input) {
  * validateBBox(undefined)
  * //=Error
  */
-export function validateBBox(bbox) {
-    if (!bbox) {
-        throw new Error("bbox is required");
-    }
-    if (!Array.isArray(bbox)) {
-        throw new Error("bbox must be an Array");
-    }
-    if (bbox.length !== 4 && bbox.length !== 6) {
-        throw new Error("bbox must be an Array of 4 or 6 numbers");
-    }
-    bbox.forEach((num) => {
-        if (!isNumber(num)) {
-            throw new Error("bbox must only contain numbers");
-        }
-    });
-}
+declare function validateBBox(bbox: any): void;
 /**
  * Validate Id
  *
@@ -649,11 +512,6 @@ export function validateBBox(bbox) {
  * validateId(undefined)
  * //=Error
  */
-export function validateId(id) {
-    if (!id) {
-        throw new Error("id is required");
-    }
-    if (["string", "number"].indexOf(typeof id) === -1) {
-        throw new Error("id must be a number or a string");
-    }
-}
+declare function validateId(id: any): void;
+
+export { type AllGeoJSON, type AreaUnits, type Coord, type Corners, GeojsonEquality, type Grid, type Id, type Lines, type Units, areaFactors, bearingToAzimuth, convertArea, convertLength, degreesToRadians, earthRadius, factors, feature, featureCollection, geometry, geometryCollection, isNumber, isObject, lengthToDegrees, lengthToRadians, lineString, lineStrings, multiLineString, multiPoint, multiPolygon, point, points, polygon, polygons, radiansToDegrees, radiansToLength, round, validateBBox, validateId };