@turf/invariant

What is @turf/invariant?

@turf/invariant is a module within the Turf.js library that provides utility functions for validating and extracting GeoJSON objects. It ensures that the input data conforms to the expected GeoJSON format, which is crucial for performing various geospatial operations.

What are @turf/invariant's main functionalities?

getCoord

The `getCoord` function extracts the coordinates from a GeoJSON Point feature. This is useful when you need to work directly with the coordinates of a point.

const turf = require('@turf/invariant');
const point = { type: 'Feature', geometry: { type: 'Point', coordinates: [102.0, 0.5] } };
const coord = turf.getCoord(point);
console.log(coord); // [102.0, 0.5]

getCoords

The `getCoords` function extracts the coordinates from a GeoJSON LineString or Polygon feature. This is useful for accessing the array of coordinates that make up the geometry.

const turf = require('@turf/invariant');
const line = { type: 'Feature', geometry: { type: 'LineString', coordinates: [[102.0, 0.0], [103.0, 1.0]] } };
const coords = turf.getCoords(line);
console.log(coords); // [[102.0, 0.0], [103.0, 1.0]]

getGeom

The `getGeom` function extracts the geometry object from a GeoJSON feature. This is useful when you need to work with the geometry independently of the feature properties.

const turf = require('@turf/invariant');
const feature = { type: 'Feature', geometry: { type: 'Polygon', coordinates: [[[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [102.0, 0.0]]] } };
const geom = turf.getGeom(feature);
console.log(geom); // { type: 'Polygon', coordinates: [[[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [102.0, 0.0]]] }

getType

The `getType` function returns the type of a GeoJSON object. This is useful for validating the type of geometry you are working with.

const turf = require('@turf/invariant');
const feature = { type: 'Feature', geometry: { type: 'Polygon', coordinates: [[[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [102.0, 0.0]]] } };
const type = turf.getType(feature);
console.log(type); // 'Polygon'

Other packages similar to @turf/invariant

geojson-validation

The `geojson-validation` package provides functions to validate GeoJSON objects against the GeoJSON specification. It is similar to @turf/invariant in that it ensures the input data conforms to the expected GeoJSON format, but it focuses more on validation rather than extraction of specific components.

geojson-utils

The `geojson-utils` package offers a set of utility functions for working with GeoJSON data, including validation, distance calculations, and bounding box operations. It provides broader functionality compared to @turf/invariant, which is more focused on validation and extraction.

README

@turf/invariant

getCoord

Unwrap a coordinate from a Point Feature, Geometry or a single coordinate.

Parameters

• obj (Array<number> | Geometry<Point> | Feature<Point>) Object

Examples

var pt = turf.point([10, 10]);

var coord = turf.getCoord(pt);
//= [10, 10]

Returns Array<number> coordinates

getCoords

Unwrap coordinates from a Feature, Geometry Object or an Array of numbers

Parameters

• obj (Array<number> | Geometry | Feature) Object

Examples

var poly = turf.polygon([[[119.32, -8.7], [119.55, -8.69], [119.51, -8.54], [119.32, -8.7]]]);

var coord = turf.getCoords(poly);
//= [[[119.32, -8.7], [119.55, -8.69], [119.51, -8.54], [119.32, -8.7]]]

Returns Array<number> coordinates

containsNumber

Checks if coordinates contains a number

Parameters

• coordinates Array<any> GeoJSON Coordinates

Returns boolean true if Array contains a number

geojsonType

Enforce expectations about types of GeoJSON objects for Turf.

Parameters

• value GeoJSON any GeoJSON object

• type string expected GeoJSON type

• name string name of calling function

• Throws Error if value is not the expected type.

featureOf

Enforce expectations about types of Feature inputs for Turf. Internally this uses geojsonType to judge geometry types.

Parameters

• feature Feature a feature with an expected geometry type

• type string expected GeoJSON type

• name string name of calling function

• Throws Error error if value is not the expected type.

collectionOf

Enforce expectations about types of FeatureCollection inputs for Turf. Internally this uses geojsonType to judge geometry types.

Parameters

• featureCollection FeatureCollection a FeatureCollection for which features will be judged

• type string expected GeoJSON type

• name string name of calling function

• Throws Error if value is not the expected type.

getGeom

Get Geometry from Feature or Geometry Object

Parameters

• geojson (Feature | Geometry) GeoJSON Feature or Geometry Object

Examples

var point = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [110, 40]
  }
}
var geom = turf.getGeom(point)
//={"type": "Point", "coordinates": [110, 40]}

• Throws Error if geojson is not a Feature or Geometry Object

Returns (Geometry | null) GeoJSON Geometry Object

getGeomType

Get Geometry Type from Feature or Geometry Object

• Throws Error DEPRECATED in v5.0.0 in favor of getType

getType

Get GeoJSON object's type, Geometry type is prioritize.

Parameters

• geojson GeoJSON GeoJSON object
• name string? name of the variable to display in error message

Examples

var point = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [110, 40]
  }
}
var geom = turf.getType(point)
//="Point"

Returns string GeoJSON type

---

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

Installation

Install this module individually:

$ npm install @turf/invariant

Or install the Turf module that includes it as a function:

$ npm install @turf/turf

Changelog

5.0.0 🎉

⭐️ Major Updates

• TurfJS now supports ES Modules (Related PR's)
• Optional parameters are now defined as an Object.

🚀 New Modules

[@turf/voronoi][voronoi]

Takes a FeatureCollection of points, and a bounding box, and returns a FeatureCollection of Voronoi polygons. (PR https://github.com/Turfjs/turf/pull/1043 - Author @stevage)

[@turf/shortest-path][shortest-path]

Returns the shortest path from start to end without colliding with any feature in obstacles (PR https://github.com/Turfjs/turf/pull/956 - Author @stebogit)

[@turf/boolean-parallel][boolean-parallel]

Boolean-Parallel returns True if each segment of line1 is parallel to the correspondent segment of line2 (PR https://github.com/Turfjs/turf/pull/941 - Author @stebogit)

[@turf/nearest-point-on-line][nearest-point-on-line]

Takes a {@link Point} and a {@link LineString} and calculates the closest Point on the (Multi)LineString. (PR https://github.com/Turfjs/turf/pull/939 - Author @stebogit)

🏅 New Features/Enhancements

• Updates [@turf/unkink-polygon][unkink-polygon] testing & added flattenEach instead of using flatten. (PR https://github.com/Turfjs/turf/pull/889)

• Add multi-geomtry support to @turf/line-split (PR https://github.com/Turfjs/turf/pull/1078)

• Improve @turf/meta lineEach method to provide properties, id and bbox (PR https://github.com/Turfjs/turf/pull/1010)

🐛 Bug Fixes

• Fixes @turf/helpers earth radius variable (PR https://github.com/Turfjs/turf/pull/1012)

• Fixes @turf/polygon-tangents bug (PR https://github.com/Turfjs/turf/pull/1058)

• Fixes @turf/line-chunk bug when the number of segments is integer (PR https://github.com/Turfjs/turf/pull/1046)

• Fixes segmentEach and segmentReduce methods in @turf/meta to ensure something is returned (PR https://github.com/Turfjs/turf/pull/968)

⚠️ Breaking Change

• Optional parameters are now defined as an Object:

Before

var from = [-75.343, 39.984];
var to = [-75.534, 39.123];
var units = 'miles';
var distance = turf.distance(from, to, units);

After

var from = [-75.343, 39.984];
var to = [-75.534, 39.123];
var options = {units: 'miles'};
var distance = turf.distance(from, to, options);

• Reworked @turf/random PR https://github.com/Turfjs/turf/issues/994
• Deprecate @turf/idw Issue https://github.com/Turfjs/turf/issues/887
• Reworked Grid modules @turf/point-grid/hex/square/triangle PR https://github.com/Turfjs/turf/pull/1029
• Renamed Modules/Methods
  • [x] @turf/inside => @turf/boolean-point-in-polygon https://github.com/Turfjs/turf/issues/860#issuecomment-317216235
  • [x] @turf/within => @turf/points-within-polygon https://github.com/Turfjs/turf/issues/860#issuecomment-317216235
  • [x] @turf/bezier => @turf/bezier-spline Issue https://github.com/Turfjs/turf/issues/661
  • [x] @turf/nearest => @turf/nearest-point https://github.com/Turfjs/turf/pull/858#issuecomment-317197295
  • [x] @turf/point-on-line => @turf/nearest-point-on-line https://github.com/Turfjs/turf/pull/858#issuecomment-317197295
  • [x] @turf/lineDistance => @turf/length https://github.com/Turfjs/turf/issues/860#issuecomment-317229869
  • [x] @turf/helpers
    • [x] radians2degrees => radiansToDegrees
    • [x] degrees2radians => degreesToRadians
    • [x] distanceToDegrees => lengthToDegrees
    • [x] distanceToRadians => lengthToRadians
    • [x] radiansToDistance => radiansToLength
    • [x] bearingToAngle => bearingToAzimuth
    • [x] convertDistance => convertLength