0
# @turf/invariant
1

2
@turf/invariant provides essential GeoJSON validation and type checking utilities for the Turf.js ecosystem. It offers a comprehensive set of invariant functions that enforce expectations about GeoJSON object types, extract coordinates and geometries from Features and Geometry objects, and validate the structure of geographic data.
3

4
## Package Information
5

6
- **Package Name**: @turf/invariant
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @turf/invariant@7.2.0`
10

11
## Core Imports
12

13
```typescript
14
import { getCoord, getCoords, getGeom, getType, geojsonType, featureOf, collectionOf, containsNumber } from "@turf/invariant";
15
import { isNumber } from "@turf/helpers";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { getCoord, getCoords, getGeom, getType, geojsonType, featureOf, collectionOf, containsNumber } = require("@turf/invariant");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { getCoord, getCoords, getGeom, getType } from "@turf/invariant";
28

29
// Extract coordinates from a Point
30
const point = {
31
  type: "Feature",
32
  geometry: { type: "Point", coordinates: [10, 20] },
33
  properties: {}
34
};
35

36
const coord = getCoord(point); // [10, 20]
37
const coords = getCoords(point); // [10, 20]
38
const geometry = getGeom(point); // { type: "Point", coordinates: [10, 20] }
39
const type = getType(point); // "Point"
40

41
// Working with GeometryCollection
42
const geometryCollection = {
43
  type: "GeometryCollection",
44
  geometries: [
45
    { type: "Point", coordinates: [10, 20] },
46
    { type: "LineString", coordinates: [[0, 0], [1, 1]] }
47
  ]
48
};
49
const gcType = getType(geometryCollection); // "GeometryCollection"
50
```
51

52
## Capabilities
53

54
### Coordinate Extraction
55

56
Functions for extracting coordinate data from GeoJSON objects.
57

58
#### Get Single Coordinate
59

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

62
```typescript { .api }
63
/**
64
 * Unwrap a coordinate from a Point Feature, Geometry or a single coordinate
65
 * @param coord - GeoJSON Point Feature, Point Geometry, or Array of numbers
66
 * @returns Array of numbers (coordinates)
67
 * @throws Error if coord is invalid or not provided
68
 */
69
function getCoord(coord: Feature<Point> | Point | number[]): number[];
70
```
71

72
#### Get All Coordinates
73

74
Unwrap coordinates from a Feature, Geometry Object or an Array.
75

76
```typescript { .api }
77
/**
78
 * Unwrap coordinates from a Feature, Geometry Object or an Array
79
 * @param coords - Feature, Geometry Object, or Array
80
 * @returns Array of coordinates (structure depends on geometry type)
81
 * @throws Error if coords is invalid
82
 */
83
function getCoords<G extends Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon>(
84
  coords: any[] | Feature<G> | G
85
): any[];
86
```
87

88
### Geometry Operations
89

90
Functions for extracting and working with geometry objects.
91

92
#### Get Geometry
93

94
Get Geometry from Feature or Geometry Object.
95

96
```typescript { .api }
97
/**
98
 * Get Geometry from Feature or Geometry Object
99
 * @param geojson - GeoJSON Feature or Geometry Object
100
 * @returns GeoJSON Geometry Object (can be null if Feature has null geometry)
101
 * @throws Error if geojson is not a Feature or Geometry Object
102
 */
103
function getGeom<G extends Geometry>(geojson: Feature<G> | G): G;
104
```
105

106
#### Get Type
107

108
Get GeoJSON object's type, with Geometry type prioritized.
109

110
```typescript { .api }
111
/**
112
 * Get GeoJSON object's type, Geometry type is prioritized
113
 * @param geojson - GeoJSON object (Feature, FeatureCollection, GeometryCollection, or Geometry)
114
 * @param _name - Optional name parameter (unused, for legacy compatibility)
115
 * @returns String representing the GeoJSON type
116
 */
117
function getType(
118
  geojson: Feature<any> | FeatureCollection<any> | GeometryCollection | Geometry,
119
  _name?: string
120
): string;
121
```
122

123
### Type Validation
124

125
Functions for enforcing expectations about GeoJSON object types.
126

127
#### Validate GeoJSON Type
128

129
Enforce expectations about types of GeoJSON objects for Turf.
130

131
```typescript { .api }
132
/**
133
 * Enforce expectations about types of GeoJSON objects for Turf
134
 * @param value - Any GeoJSON object
135
 * @param type - Expected GeoJSON type string
136
 * @param name - Name of calling function (for error messages)
137
 * @throws Error if value is not the expected type
138
 */
139
function geojsonType(value: any, type: string, name: string): void;
140
```
141

142
#### Validate Feature Type
143

144
Enforce expectations about types of Feature inputs for Turf.
145

146
```typescript { .api }
147
/**
148
 * Enforce expectations about types of Feature inputs for Turf
149
 * @param feature - Feature with an expected geometry type
150
 * @param type - Expected GeoJSON geometry type string
151
 * @param name - Name of calling function (for error messages)
152
 * @throws Error if feature is invalid or geometry type doesn't match
153
 */
154
function featureOf(feature: Feature<any>, type: string, name: string): void;
155
```
156

157
#### Validate FeatureCollection Type
158

159
Enforce expectations about types of FeatureCollection inputs for Turf.
160

161
```typescript { .api }
162
/**
163
 * Enforce expectations about types of FeatureCollection inputs for Turf
164
 * @param featureCollection - FeatureCollection for which features will be validated
165
 * @param type - Expected GeoJSON geometry type string for all features
166
 * @param name - Name of calling function (for error messages)
167
 * @throws Error if FeatureCollection is invalid or contains features with wrong geometry types
168
 */
169
function collectionOf(
170
  featureCollection: FeatureCollection<any>,
171
  type: string,
172
  name: string
173
): void;
174
```
175

176
### Coordinate Validation
177

178
Function for validating coordinate structures.
179

180
#### Contains Number Check
181

182
Validates that coordinates contain only numbers (recursive validation).
183

184
```typescript { .api }
185
/**
186
 * Checks if coordinates contains a number (recursive validation)
187
 * @param coordinates - GeoJSON Coordinates array
188
 * @returns Boolean (true if array contains numbers at the base level)
189
 * @throws Error if coordinates contain non-numeric values
190
 */
191
function containsNumber(coordinates: any[]): boolean;
192
```
193

194
## Types
195

196
The package uses GeoJSON types from the `geojson` module and helper types from `@turf/helpers`.
197

198
```typescript { .api }
199
// GeoJSON types (imported from 'geojson')
200
interface Feature<G extends Geometry | null = Geometry> {
201
  type: "Feature";
202
  geometry: G;
203
  properties: any;
204
}
205

206
interface GeometryCollection {
207
  type: "GeometryCollection";
208
  geometries: Geometry[];
209
}
210

211
interface FeatureCollection<G extends Geometry | null = Geometry> {
212
  type: "FeatureCollection";
213
  features: Feature<G>[];
214
}
215

216
interface Point {
217
  type: "Point";
218
  coordinates: number[];
219
}
220

221
interface LineString {
222
  type: "LineString";
223
  coordinates: number[][];
224
}
225

226
interface Polygon {
227
  type: "Polygon";
228
  coordinates: number[][][];
229
}
230

231
interface MultiPoint {
232
  type: "MultiPoint";
233
  coordinates: number[][];
234
}
235

236
interface MultiLineString {
237
  type: "MultiLineString";
238
  coordinates: number[][][];
239
}
240

241
interface MultiPolygon {
242
  type: "MultiPolygon";
243
  coordinates: number[][][][];
244
}
245

246
type Geometry = Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection;
247
```
248

249
## Error Handling
250

251
All validation functions (`geojsonType`, `featureOf`, `collectionOf`) throw errors rather than return boolean values. This design ensures that invalid data is caught early and prevents invalid data propagation through Turf.js processing pipelines.
252

253
Common error patterns:
254
- **Coordinate extraction errors**: "coord is required", "coord must be GeoJSON Point or an Array of numbers", "coords must be GeoJSON Feature, Geometry Object or an Array"
255
- **Type validation errors**: "Invalid input to [functionName]: must be a [expectedType], given [actualType]"
256
- **Missing data errors**: "No feature passed", "No featureCollection passed", "type and name required"
257
- **Validation requirement errors**: ".featureOf() requires a name", ".collectionOf() requires a name"
258
- **Feature validation errors**: "Invalid input to [functionName], Feature with geometry required", "Invalid input to [functionName], FeatureCollection required"
259
- **Coordinate validation errors**: "coordinates must only contain numbers"
260

261
All error messages include the calling function name when available to aid in debugging complex processing pipelines.