JSTS: JavaScript Topology Suite

Common errors

• TypeError: require is not a function

  cause Attempting to use CommonJS `require()` syntax in an ES module context or with JSTS versions that are ESM-only.
  fix Use ES `import` statements with specific deep paths, e.g., `import GeoJSONReader from 'jsts/org/locationtech/jts/io/GeoJSONReader.js'`.

• TopologyException: Points of linear element are not distinct.

  cause Geometric operations failing due to invalid input geometries or floating-point precision issues.
  fix Validate input geometries (`geometry.isValid()`). If valid, consider reducing precision using `new GeometryPrecisionReducer(precisionModel).reduce(geometry)`.

• TypeError: Cannot read properties of undefined (reading 'buffer')

  cause Trying to call a shortcut method (like `buffer`, `intersects`) directly on a `Geometry` object in the ES module build of JSTS, where these methods are not directly attached.
  fix Use the dedicated operation classes, e.g., `import BufferOp from 'jsts/org/locationtech/jts/operation/buffer/BufferOp.js'; const buffered = new BufferOp(geometry, distance).getResultGeometry();`.

• ReferenceError: jsts is not defined

  cause In a browser environment, the `jsts` global object is not available, typically because the UMD build script was not correctly included or executed.
  fix Ensure the JSTS UMD build (e.g., `jsts.min.js`) is correctly included via a `<script>` tag in your HTML before attempting to access `jsts`.

Warnings

• breaking JSTS is delivered as ES Modules only for Node.js (since version 1.4.0, solidified for Node.js 14+). CommonJS `require()` statements will no longer work and will result in errors.
  Fix: Refactor `require()` statements to `import` statements and use specific deep import paths, e.g., `import GeoJSONReader from 'jsts/org/locationtech/jts/io/GeoJSONReader.js'`.
• gotcha Direct shortcut methods like `.buffer()`, `.intersects()`, or `.union()` are not available on `Geometry` objects in the ES Modules build for Node.js. These methods are monkey-patched only into the bundled ES5 browser version.
  Fix: Use dedicated processor classes from `jsts/org/locationtech/jts/operation/` (e.g., `BufferOp`, `IntersectionOp`) or `jsts/org/locationtech/jts/algorithm/` to perform operations.
• gotcha Due to JavaScript's lack of function overloading, some JTS methods like `GeometryFactory.createMultiPoint` may only accept specific argument types (e.g., `Point[]`) unlike their Java counterparts.
  Fix: Consult the JSTS API documentation or JTS Javadoc to determine the exact expected argument types for methods that have overloaded signatures in Java.
• gotcha Calculations may throw a `TopologyException` (as a JavaScript `Error`) if precision issues arise or input geometries are invalid according to the OGC Simple Features specification.
  Fix: Ensure input geometries are valid (`geometry.isValid()`). Use `jsts/org/locationtech/jts/precision/GeometryPrecisionReducer.js` to reduce precision if needed, or validate geometries with `jsts/org/locationtech/jts/geom/Geometry.isValid()`.
• breaking JSTS requires Node.js version 18 or higher for execution as specified in its `engines` field. Older Node.js versions may encounter compatibility issues or fail to run.
  Fix: Upgrade your Node.js environment to version 18 or later using `nvm` or your preferred Node.js version manager.

Install

• npm install jsts npm
• yarn add jsts yarn
• pnpm add jsts pnpm

Imports

• GeoJSONReader
  wrong:

  const GeoJSONReader = require('jsts').io.GeoJSONReader;

  correct:

  import GeoJSONReader from 'jsts/org/locationtech/jts/io/GeoJSONReader.js';

  JSTS delivers as ES Modules for Node.js (v14+). Direct deep imports are required for specific classes from version 1.4.0+.
• GeometryFactory
  wrong:

  const GeometryFactory = require('jsts/org/locationtech/jts/geom/GeometryFactory');

  correct:

  import GeometryFactory from 'jsts/org/locationtech/jts/geom/GeometryFactory.js';

  Remember to import other geometry types (Point, Polygon, etc.) similarly if needed for the factory.
• WKTReader

  import WKTReader from 'jsts/org/locationtech/jts/io/WKTReader.js';

  For browser environments, a global `jsts` object is exposed when including the UMD build via a `<script>` tag, allowing access like `jsts.org.locationtech.jts.io.WKTReader`.
• Point

  import Point from 'jsts/org/locationtech/jts/geom/Point.js';

  Most geometry types (Point, LineString, Polygon) are imported from the `jsts/org/locationtech/jts/geom/` path.

Quickstart

This quickstart demonstrates reading GeoJSON input, performing a buffer operation on a point geometry, creating a new point with `GeometryFactory`, and serializing the buffered geometry back into GeoJSON using JSTS ES modules.

import GeoJSONReader from 'jsts/org/locationtech/jts/io/GeoJSONReader.js';
import GeoJSONWriter from 'jsts/org/locationtech/jts/io/GeoJSONWriter.js';
import GeometryFactory from 'jsts/org/locationtech/jts/geom/GeometryFactory.js';
import Point from 'jsts/org/locationtech/jts/geom/Point.js';
import BufferOp from 'jsts/org/locationtech/jts/operation/buffer/BufferOp.js';

// 1. Read a GeoJSON string into a JSTS Geometry object
const geoJsonInput = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [10, 20]
  },
  properties: {
    name: 'Example Point'
  }
};

const reader = new GeoJSONReader();
const geometry = reader.read(geoJsonInput);

console.log('Original Geometry (JSTS):', geometry.toString());
// Expected: POINT (10 20)

// 2. Perform a spatial operation, e.g., buffer
const distance = 5;
const bufferOp = new BufferOp(geometry, distance);
const bufferedGeometry = bufferOp.getResultGeometry();

console.log('Buffered Geometry (JSTS):', bufferedGeometry.toString());
// Expected: POLYGON ((...))

// 3. Create a new geometry using GeometryFactory
const factory = new GeometryFactory();
// JSTS Coordinate is expected by createPoint
const newPoint = factory.createPoint(new Point.Coordinate(15, 25));

console.log('Newly Created Point (JSTS):', newPoint.toString());
// Expected: POINT (15 25)

// 4. Write a JSTS Geometry object back to GeoJSON
const writer = new GeoJSONWriter();
const bufferedGeoJson = writer.write(bufferedGeometry);

console.log('Buffered Geometry (GeoJSON):', JSON.stringify(bufferedGeoJson, null, 2));

/*
Expected output example for bufferedGeoJson (simplified):
{
  "type": "Polygon",
  "coordinates": [
    [
      [5.000..., 20.000...],
      ...
    ]
  ]
}
*/