Foundation Modules

Purpose and Scope

This page documents the three core foundation modules in Turf.js: @turf/helpers, @turf/meta, and @turf/invariant. These modules provide the fundamental building blocks used by all other modules in the library. They handle GeoJSON object creation, iteration over GeoJSON structures, input validation, and unit conversions.

For information about how these foundation modules fit into the broader module categorization, see Module Categories. For details on the dependency hierarchy and how foundation modules support higher-tier operations, see Dependency Hierarchy.

Overview

The foundation layer consists of three packages that form the basis of all Turf.js operations:

Package	Primary Purpose	Usage Frequency	Dependencies
@turf/helpers	GeoJSON factory functions and unit conversions	Used by ALL modules	None
@turf/meta	Iteration utilities for traversing GeoJSON structures	Used by 50+ modules	@turf/helpers
@turf/invariant	Input validation and data extraction	Used by 70+ modules	@turf/helpers

100%

Diagram: Foundation Module Dependencies

@turf/helpers

The @turf/helpers module provides factory functions for creating GeoJSON objects and utilities for unit conversions. This module has no dependencies on other Turf packages and serves as the base for all GeoJSON operations.

GeoJSON Factory Functions

The module exports functions that construct valid GeoJSON Feature and Geometry objects:

100%

Diagram: GeoJSON Factory Functions

Function	Input	Output	Location
point()	Position, properties?, options?	Feature<Point>	packages/turf-helpers/index.ts254-277
lineString()	Position[], properties?, options?	Feature<LineString>	packages/turf-helpers/index.ts405-418
polygon()	Position[][], properties?, options?	Feature<Polygon>	packages/turf-helpers/index.ts327-355
feature()	Geometry, properties?, options?	Feature	packages/turf-helpers/index.ts175-193
featureCollection()	Feature[], options?	FeatureCollection	packages/turf-helpers/index.ts474-490
geometry()	type, coordinates	Geometry	packages/turf-helpers/index.ts210-237

Unit Conversion System

The module provides a comprehensive unit conversion system based on spherical Earth calculations:

100%

Diagram: Unit Conversion Architecture

Key conversion functions:

Function	Purpose	Location
radiansToLength()	Convert radians to distance units	packages/turf-helpers/index.ts648-657
lengthToRadians()	Convert distance to radians	packages/turf-helpers/index.ts669-678
lengthToDegrees()	Convert distance to degrees	packages/turf-helpers/index.ts690-692
convertLength()	Convert between length units	packages/turf-helpers/index.ts766-775
convertArea()	Convert between area units	packages/turf-helpers/index.ts786-809

The earthRadius constant (6,371,008.8 meters) represents the mean radius of Earth and is used by all distance calculations in Turf.js that model Earth as a sphere.

Type Definitions

The module exports TypeScript types that are used throughout Turf.js:

100%

Diagram: Helper Type System

@turf/meta

The @turf/meta module provides iteration utilities for traversing and processing GeoJSON structures. It implements functional programming patterns (forEach, reduce) optimized for geospatial data.

Iteration Function Families

The module organizes iteration functions into six families based on what they iterate over:

100%

Diagram: Meta Iteration Function Families

Coordinate Iteration

The coordinate iteration functions traverse all coordinate positions in any GeoJSON object:

100%

Diagram: coordEach() Traversal Logic

The coordEach() function is optimized for performance by avoiding temporary array allocations. It uses nested loops and conditional logic to handle all GeoJSON geometry types without normalizing the input structure.

Key implementation details:

• Handles null geometries by skipping them packages/turf-meta/index.js38-39
• Supports excludeWrapCoord parameter to skip the closing coordinate of LinearRings packages/turf-meta/index.js92-96
• Provides five callback parameters for precise location tracking packages/turf-meta/index.js4-12
• Recursively processes GeometryCollection packages/turf-meta/index.js176-183

Segment Iteration

Segment iteration functions process 2-vertex line segments, which is fundamental for line operations:

100%

Diagram: Segment Iteration for Line Operations

The segmentEach() function internally uses coordEach() to generate 2-vertex LineString features representing consecutive coordinate pairs. This abstraction simplifies line-based geometric operations.

Geometry and Feature Iteration

The module provides iteration over geometries and features with access to properties and metadata:

Function	Iterates Over	Callback Parameters	Location
geomEach()	Geometries	currentGeometry, featureIndex, featureProperties, featureBBox, featureId	packages/turf-meta/index.js514-630
featureEach()	Features	currentFeature, featureIndex	packages/turf-meta/index.js395-403
propEach()	Properties	currentProperties, featureIndex	packages/turf-meta/index.js297-309
flattenEach()	Flattened features	currentFeature, featureIndex, multiFeatureIndex	packages/turf-meta/index.js738-790

The flattenEach() function breaks multi-geometries into individual features, converting MultiPoint to multiple Point features, MultiLineString to multiple LineString features, etc.

@turf/invariant

The @turf/invariant module provides input validation and data extraction utilities. It ensures GeoJSON inputs are in the expected format and extracts specific components with proper error handling.

Data Extraction Functions

100%

Diagram: Invariant Data Extraction Functions

Type Validation Functions

The module provides three validation functions that throw errors if inputs don't match expectations:

100%

Diagram: Type Validation Flow

Function	Purpose	Throws On	Location
geojsonType()	Validate GeoJSON type matches expected	Type mismatch	packages/turf-invariant/README.md53-67
featureOf()	Validate Feature geometry type	Geometry type mismatch	packages/turf-invariant/README.md69-84
collectionOf()	Validate all features in collection	Any feature type mismatch	packages/turf-invariant/README.md86-99

These validation functions are used throughout Turf.js to provide clear error messages when incorrect geometry types are passed to functions.

Common Usage Pattern

The getGeom() function is one of the most frequently used invariant utilities:

100%

Diagram: getGeom() Usage Pattern

Example from @turf/boolean-overlap:

const geom1 = getGeom(feature1);
const geom2 = getGeom(feature2);

This pattern allows functions to accept either Feature or Geometry objects as input, automatically extracting the geometry component when needed.

Inter-Module Dependencies

The three foundation modules have a clear dependency hierarchy:

100%

Diagram: Foundation Module Dependencies

Dependency Details

@turf/helpers packages/turf-helpers/package.json70-73:

"dependencies": {
  "@types/geojson": "^7946.0.10",
  "tslib": "^2.8.1"
}

@turf/meta packages/turf-meta/package.json84-87:

"dependencies": {
  "@turf/helpers": "workspace:*",
  "@types/geojson": "^7946.0.10"
}

Imports from helpers: packages/turf-meta/index.js1

@turf/invariant packages/turf-invariant/package.json67-71:

"dependencies": {
  "@turf/helpers": "workspace:*",
  "@types/geojson": "^7946.0.10",
  "tslib": "^2.8.1"
}

Build Configuration

All three foundation modules use the same build configuration defined in the repository root:

100%

Diagram: Foundation Module Build Process

Each module's package.json specifies dual exports for both ES modules and CommonJS:

"exports": {
  ".": {
    "import": {
      "types": "./dist/esm/index.d.ts",
      "default": "./dist/esm/index.js"
    },
    "require": {
      "types": "./dist/cjs/index.d.cts",
      "default": "./dist/cjs/index.cjs"
    }
  }
}

This allows consumers to use either module system depending on their environment.

Usage Examples

Creating and Processing GeoJSON

Typical workflow combining all three foundation modules:

100%

Diagram: Typical Foundation Module Usage Flow

Example from @turf/boolean-overlap packages/turf-boolean-overlap/index.ts1-94:

1. Extract geometries using getGeom() from @turf/invariant
2. Iterate over segments using segmentEach() from @turf/meta
3. Compare segments using geometric calculations

Iteration Patterns

Common pattern for coordinate processing:

Pattern	Functions Used	Use Case
Transform all coordinates	coordEach()	Apply projection, round precision
Aggregate coordinates	coordReduce()	Calculate bounds, collect unique coords
Process line segments	segmentEach()	Find intersections, measure angles
Separate multi-geometries	flattenEach()	Process each component independently

Performance Considerations

The foundation modules are heavily optimized because they are called by every other module:

@turf/helpers Optimizations

• Direct object creation without intermediate structures packages/turf-helpers/index.ts254-277
• Minimal validation (just type checks) for performance
• Reusable factory pattern

@turf/meta Optimizations

• Avoids creating temporary arrays during iteration packages/turf-meta/index.js55-66
• Direct coordinate access without normalization
• Short-circuit evaluation with early return support packages/turf-meta/index.js110-111

@turf/invariant Optimizations

• Lightweight type checking
• Direct property access
• Minimal object allocation