or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-turf--invariant

GeoJSON validation and type checking utilities for the Turf.js ecosystem

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@turf/invariant@7.2.x

To install, run

npx @tessl/cli install tessl/npm-turf--invariant@7.2.0

index.mddocs/

@turf/invariant

@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.

Package Information

  • Package Name: @turf/invariant
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @turf/invariant@7.2.0

Core Imports

import { getCoord, getCoords, getGeom, getType, geojsonType, featureOf, collectionOf, containsNumber } from "@turf/invariant";
import { isNumber } from "@turf/helpers";

For CommonJS:

const { getCoord, getCoords, getGeom, getType, geojsonType, featureOf, collectionOf, containsNumber } = require("@turf/invariant");

Basic Usage

import { getCoord, getCoords, getGeom, getType } from "@turf/invariant";

// Extract coordinates from a Point
const point = {
  type: "Feature",
  geometry: { type: "Point", coordinates: [10, 20] },
  properties: {}
};

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

// Working with GeometryCollection
const geometryCollection = {
  type: "GeometryCollection",
  geometries: [
    { type: "Point", coordinates: [10, 20] },
    { type: "LineString", coordinates: [[0, 0], [1, 1]] }
  ]
};
const gcType = getType(geometryCollection); // "GeometryCollection"

Capabilities

Coordinate Extraction

Functions for extracting coordinate data from GeoJSON objects.

Get Single Coordinate

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

/**
 * Unwrap a coordinate from a Point Feature, Geometry or a single coordinate
 * @param coord - GeoJSON Point Feature, Point Geometry, or Array of numbers
 * @returns Array of numbers (coordinates)
 * @throws Error if coord is invalid or not provided
 */
function getCoord(coord: Feature<Point> | Point | number[]): number[];

Get All Coordinates

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

/**
 * Unwrap coordinates from a Feature, Geometry Object or an Array
 * @param coords - Feature, Geometry Object, or Array
 * @returns Array of coordinates (structure depends on geometry type)
 * @throws Error if coords is invalid
 */
function getCoords<G extends Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon>(
  coords: any[] | Feature<G> | G
): any[];

Geometry Operations

Functions for extracting and working with geometry objects.

Get Geometry

Get Geometry from Feature or Geometry Object.

/**
 * Get Geometry from Feature or Geometry Object
 * @param geojson - GeoJSON Feature or Geometry Object
 * @returns GeoJSON Geometry Object (can be null if Feature has null geometry)
 * @throws Error if geojson is not a Feature or Geometry Object
 */
function getGeom<G extends Geometry>(geojson: Feature<G> | G): G;

Get Type

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

/**
 * Get GeoJSON object's type, Geometry type is prioritized
 * @param geojson - GeoJSON object (Feature, FeatureCollection, GeometryCollection, or Geometry)
 * @param _name - Optional name parameter (unused, for legacy compatibility)
 * @returns String representing the GeoJSON type
 */
function getType(
  geojson: Feature<any> | FeatureCollection<any> | GeometryCollection | Geometry,
  _name?: string
): string;

Type Validation

Functions for enforcing expectations about GeoJSON object types.

Validate GeoJSON Type

Enforce expectations about types of GeoJSON objects for Turf.

/**
 * Enforce expectations about types of GeoJSON objects for Turf
 * @param value - Any GeoJSON object
 * @param type - Expected GeoJSON type string
 * @param name - Name of calling function (for error messages)
 * @throws Error if value is not the expected type
 */
function geojsonType(value: any, type: string, name: string): void;

Validate Feature Type

Enforce expectations about types of Feature inputs for Turf.

/**
 * Enforce expectations about types of Feature inputs for Turf
 * @param feature - Feature with an expected geometry type
 * @param type - Expected GeoJSON geometry type string
 * @param name - Name of calling function (for error messages)
 * @throws Error if feature is invalid or geometry type doesn't match
 */
function featureOf(feature: Feature<any>, type: string, name: string): void;

Validate FeatureCollection Type

Enforce expectations about types of FeatureCollection inputs for Turf.

/**
 * Enforce expectations about types of FeatureCollection inputs for Turf
 * @param featureCollection - FeatureCollection for which features will be validated
 * @param type - Expected GeoJSON geometry type string for all features
 * @param name - Name of calling function (for error messages)
 * @throws Error if FeatureCollection is invalid or contains features with wrong geometry types
 */
function collectionOf(
  featureCollection: FeatureCollection<any>,
  type: string,
  name: string
): void;

Coordinate Validation

Function for validating coordinate structures.

Contains Number Check

Validates that coordinates contain only numbers (recursive validation).

/**
 * Checks if coordinates contains a number (recursive validation)
 * @param coordinates - GeoJSON Coordinates array
 * @returns Boolean (true if array contains numbers at the base level)
 * @throws Error if coordinates contain non-numeric values
 */
function containsNumber(coordinates: any[]): boolean;

Types

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

// GeoJSON types (imported from 'geojson')
interface Feature<G extends Geometry | null = Geometry> {
  type: "Feature";
  geometry: G;
  properties: any;
}

interface GeometryCollection {
  type: "GeometryCollection";
  geometries: Geometry[];
}

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

interface Point {
  type: "Point";
  coordinates: number[];
}

interface LineString {
  type: "LineString";
  coordinates: number[][];
}

interface Polygon {
  type: "Polygon";
  coordinates: number[][][];
}

interface MultiPoint {
  type: "MultiPoint";
  coordinates: number[][];
}

interface MultiLineString {
  type: "MultiLineString";
  coordinates: number[][][];
}

interface MultiPolygon {
  type: "MultiPolygon";
  coordinates: number[][][][];
}

type Geometry = Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection;

Error Handling

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.

Common error patterns:

  • 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"
  • Type validation errors: "Invalid input to [functionName]: must be a [expectedType], given [actualType]"
  • Missing data errors: "No feature passed", "No featureCollection passed", "type and name required"
  • Validation requirement errors: ".featureOf() requires a name", ".collectionOf() requires a name"
  • Feature validation errors: "Invalid input to [functionName], Feature with geometry required", "Invalid input to [functionName], FeatureCollection required"
  • Coordinate validation errors: "coordinates must only contain numbers"

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