Effect Schema GeoJSON

A comprehensive Effect Schema library for validating and parsing GeoJSON data types according to RFC 7946.

Installation

npm install effect-schema-geojson effect
# or
pnpm add effect-schema-geojson effect
# or
yarn add effect-schema-geojson effect

Note: This library requires effect as a peer dependency.

Features

• ✅ Complete GeoJSON specification support (RFC 7946)
• ✅ All geometry types: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection
• ✅ Feature and FeatureCollection support
• ✅ Bounding box validation
• ✅ LinearRing closure validation (first and last positions must match)
• ✅ Type-safe parsing and validation
• ✅ Built with Effect Schema for powerful composition and error handling

Quick Start

import { Effect, Schema } from "effect";
import { parseGeoJSON, isValidGeoJSON, Point } from "effect-schema-geojson";

// Validate any GeoJSON object
const someData = {
  type: "Point",
  coordinates: [102.0, 0.5]
};

// Type guard validation
if (isValidGeoJSON(someData)) {
  console.log("Valid GeoJSON!", someData);
}

// Effect-based parsing with detailed error handling
const parseResult = await Effect.runPromise(parseGeoJSON(someData));
console.log("Parsed GeoJSON:", parseResult);

// Create a Point schema directly
const pointData = {
  type: "Point",
  coordinates: [102.0, 0.5]
};

const pointResult = await Effect.runPromise(
  Schema.decodeUnknown(Point)(pointData)
);

API Reference

Geometry Types

Point

import { Point, parsePoint } from "effect-schema-geojson";

const point = {
  type: "Point",
  coordinates: [102.0, 0.5]
};

const result = await Effect.runPromise(parsePoint(point));

MultiPoint

import { MultiPoint } from "effect-schema-geojson";

const multiPoint = {
  type: "MultiPoint",
  coordinates: [
    [102.0, 0.5],
    [103.0, 1.0]
  ]
};

LineString

import { LineString } from "effect-schema-geojson";

const lineString = {
  type: "LineString",
  coordinates: [
    [102.0, 0.0],
    [103.0, 1.0],
    [104.0, 0.0],
    [105.0, 1.0]
  ]
};

MultiLineString

import { MultiLineString } from "effect-schema-geojson";

const multiLineString = {
  type: "MultiLineString",
  coordinates: [
    [
      [102.0, 0.0],
      [103.0, 1.0]
    ],
    [
      [104.0, 0.0],
      [105.0, 1.0]
    ]
  ]
};

Polygon

import { Polygon } from "effect-schema-geojson";

const polygon = {
  type: "Polygon",
  coordinates: [
    [
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 1.0],
      [100.0, 0.0]
    ]
  ]
};

MultiPolygon

import { MultiPolygon } from "effect-schema-geojson";

const multiPolygon = {
  type: "MultiPolygon",
  coordinates: [
    [
      [
        [102.0, 2.0],
        [103.0, 2.0],
        [103.0, 3.0],
        [102.0, 3.0],
        [102.0, 2.0]
      ]
    ],
    [
      [
        [100.0, 0.0],
        [101.0, 0.0],
        [101.0, 1.0],
        [100.0, 1.0],
        [100.0, 0.0]
      ]
    ]
  ]
};

GeometryCollection

import { GeometryCollection } from "effect-schema-geojson";

const geometryCollection = {
  type: "GeometryCollection",
  geometries: [
    {
      type: "Point",
      coordinates: [102.0, 0.5]
    },
    {
      type: "LineString",
      coordinates: [
        [102.0, 0.0],
        [103.0, 1.0]
      ]
    }
  ]
};

Feature and FeatureCollection

Feature

import { Feature } from "effect-schema-geojson";

const feature = {
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [102.0, 0.5]
  },
  properties: {
    name: "Sample Point",
    category: "landmark"
  },
  id: "point-001"
};

FeatureCollection

import { FeatureCollection } from "effect-schema-geojson";

const featureCollection = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [102.0, 0.5]
      },
      properties: {
        name: "Point 1"
      }
    },
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [103.0, 1.5]
      },
      properties: {
        name: "Point 2"
      }
    }
  ]
};

Utility Functions

Parsing Functions

All parsing functions return Effect<T, ParseError> for robust error handling:

• parseGeoJSON(input: unknown) - Parse any GeoJSON object
• parseGeometry(input: unknown) - Parse any geometry
• parseFeature(input: unknown) - Parse a feature
• parseFeatureCollection(input: unknown) - Parse a feature collection
• parseGeometryCollection(input: unknown) - Parse a geometry collection
• parsePoint(input: unknown) - Parse a point geometry
• parseMultiPoint(input: unknown) - Parse a multipoint geometry
• parseLineString(input: unknown) - Parse a linestring geometry
• parseMultiLineString(input: unknown) - Parse a multilinestring geometry
• parsePolygon(input: unknown) - Parse a polygon geometry
• parseMultiPolygon(input: unknown) - Parse a multipolygon geometry

Validation Functions

Type guard functions that return boolean:

• isValidGeoJSON(input: unknown) - Check if input is valid GeoJSON
• isValidGeometry(input: unknown) - Check if input is valid geometry
• isValidFeature(input: unknown) - Check if input is valid feature
• isValidFeatureCollection(input: unknown) - Check if input is valid feature collection
• isValidGeometryCollection(input: unknown) - Check if input is valid geometry collection
• isValidPoint(input: unknown) - Check if input is valid point
• isValidMultiPoint(input: unknown) - Check if input is valid multipoint
• isValidLineString(input: unknown) - Check if input is valid linestring
• isValidMultiLineString(input: unknown) - Check if input is valid multilinestring
• isValidPolygon(input: unknown) - Check if input is valid polygon
• isValidMultiPolygon(input: unknown) - Check if input is valid multipolygon

Encoding Functions

For serialization back to unknown/JSON:

• encodeGeoJSON(input: GeoJSON) - Encode GeoJSON to unknown
• encodeGeometry(input: Geometry) - Encode geometry to unknown
• encodeFeature(input: Feature) - Encode feature to unknown
• encodeFeatureCollection(input: FeatureCollection) - Encode feature collection to unknown
• encodeGeometryCollection(input: GeometryCollection) - Encode geometry collection to unknown
• encodePoint(input: Point) - Encode point to unknown
• encodeMultiPoint(input: MultiPoint) - Encode multipoint to unknown
• encodeLineString(input: LineString) - Encode linestring to unknown
• encodeMultiLineString(input: MultiLineString) - Encode multilinestring to unknown
• encodePolygon(input: Polygon) - Encode polygon to unknown
• encodeMultiPolygon(input: MultiPolygon) - Encode multipolygon to unknown

Error Handling

import { Effect } from "effect";
import { parseGeoJSON } from "effect-schema-geojson";

const invalidData = { type: "InvalidType" };

const program = parseGeoJSON(invalidData).pipe(
  Effect.catchAll((error) => {
    console.error("Parsing failed:", error);
    return Effect.succeed(null);
  })
);

const result = await Effect.runPromise(program);

Working with Effect Schema

Since this library is built on Effect Schema, you can compose these schemas with other Effect Schema types and take advantage of all Effect Schema features like transformations, refinements, and more detailed error handling.

import { Schema } from "effect";
import { Point } from "effect-schema-geojson";

// Compose with other schemas
const LocationData = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  coordinates: Point,
  metadata: Schema.Record({ key: Schema.String, value: Schema.Unknown })
});

Bounding Boxes

All geometry types support optional bounding boxes:

const pointWithBbox = {
  type: "Point",
  coordinates: [102.0, 0.5],
  bbox: [102.0, 0.5, 102.0, 0.5] // [west, south, east, north]
};

TypeScript Types

The library exports TypeScript types for all GeoJSON objects:

import type {
  GeoJSON,
  Geometry,
  BasicGeometry,
  Point,
  MultiPoint,
  LineString,
  MultiLineString,
  Polygon,
  MultiPolygon,
  GeometryCollection,
  Feature,
  FeatureCollection,
  Position,
  BoundingBox,
  LinearRing
} from "effect-schema-geojson";

Effect Schema Integration

This library is built on Effect Schema, which means you can compose these schemas with other Effect Schema types:

import { Schema } from "effect";
import { Point } from "effect-schema-geojson";

const MyDataSchema = Schema.Struct({
  id: Schema.String,
  location: Point,
  metadata: Schema.Record({ key: Schema.String, value: Schema.String })
});

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests on GitHub.

License

MIT License - see LICENSE file for details.

Related

• Effect - The Effect ecosystem
• GeoJSON Specification (RFC 7946)
• @types/geojson - TypeScript definitions for GeoJSON