@trackunit/geo-json-utils 1.11.57 → 1.11.58

package/index.esm.js

@@ -1,44 +1,95 @@
 import { z } from 'zod';
 import polygonClipping from 'polygon-clipping';
 
-// * NOTE: For simplicity these tools are built for 2D coordinate space only!
+//* -------- Position -------- *//
+/**
+ * A Position is an array of coordinates. [longitude, latitude] or [longitude, latitude, altitude]
+ * RFC 7946 Section 3.1.1: "There MUST be two or more elements. The first two elements
+ * are longitude and latitude [...] Altitude or elevation MAY be included as an optional
+ * third element."
+ */
+const geoJsonPosition2dSchema = z.tuple([z.number(), z.number()]);
+const geoJsonPosition3dSchema = z.tuple([z.number(), z.number(), z.number()]);
+const geoJsonPositionSchema = z
+    .union([geoJsonPosition2dSchema, geoJsonPosition3dSchema])
+    .refine(([lng, lat]) => lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90, {
+    message: "Invalid position: longitude must be between -180 and 180, latitude must be between -90 and 90 (RFC 7946 Section 4).",
+});
+//* -------- Bbox -------- *//
 /**
- * A Position is an array of coordinates. [x, y]
- * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ * 2D bounding box of the GeoJSON object.
+ * The value of the bbox member is an array of length 4.
+ *
+ * [west, south, east, north]
+ *
+ * Note: west may be greater than east for bboxes that cross the
+ * antimeridian (RFC 7946 Section 5.2).
+ *
+ * Zero-height bboxes (north === south) are rejected per RFC 7946 Section 5.2:
+ * "The latitude of the northeast corner is always greater than the latitude
+ * of the southwest corner." Zero-width bboxes (west === east) are not explicitly
+ * forbidden by the RFC for non-antimeridian cases, so they pass.
  */
-const geoJsonPositionSchema = z.tuple([z.number(), z.number()]);
+const geoJsonBboxSchema = z
+    .tuple([z.number(), z.number(), z.number(), z.number()])
+    .refine(([, south, , north]) => north > south, {
+    message: "Invalid bounding box: north latitude must be greater than south latitude (RFC 7946 Section 5.2).",
+})
+    .refine(([, south, , north]) => {
+    const latInRange = (lat) => lat >= -90 && lat <= 90;
+    return latInRange(south) && latInRange(north);
+}, {
+    message: "Invalid bounding box: latitude must be between -90 and 90 (RFC 7946 Section 5.3).",
+})
+    .refine(([west, , east]) => {
+    const lngInRange = (lng) => lng >= -180 && lng <= 180;
+    return lngInRange(west) && lngInRange(east);
+}, {
+    message: "Invalid bounding box: longitude must be between -180 and 180 (RFC 7946 Section 5).",
+});
+//* -------- Geometry Objects -------- *//
 /**
  * Point geometry object.
+ * Uses z.object() (not strictObject) so RFC 7946 Section 6.1 "foreign members"
+ * (crs, vendor extensions, etc.) are accepted and stripped during parse.
  * https://tools.ietf.org/html/rfc7946#section-3.1.2
  */
-const geoJsonPointSchema = z.strictObject({
+const geoJsonPointSchema = z.object({
     type: z.literal("Point"),
     coordinates: geoJsonPositionSchema,
+    bbox: geoJsonBboxSchema.optional(),
 });
 /**
  * MultiPoint geometry object.
- *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.3
  */
-const geoJsonMultiPointSchema = z.strictObject({
+const geoJsonMultiPointSchema = z.object({
     type: z.literal("MultiPoint"),
     coordinates: z.array(geoJsonPositionSchema),
+    bbox: geoJsonBboxSchema.optional(),
 });
 /**
  * LineString geometry object.
  * Minimum length of 2 positions.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
  * https://tools.ietf.org/html/rfc7946#section-3.1.4
  */
-const geoJsonLineStringSchema = z.strictObject({
+const geoJsonLineStringSchema = z.object({
     type: z.literal("LineString"),
     coordinates: z.array(geoJsonPositionSchema).min(2),
+    bbox: geoJsonBboxSchema.optional(),
 });
 /**
  * MultiLineString geometry object.
+ * Each inner array is a LineString coordinate array (>= 2 positions per RFC 7946 Section 3.1.5).
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
  * https://tools.ietf.org/html/rfc7946#section-3.1.5
  */
-const geoJsonMultiLineStringSchema = z.strictObject({
+const geoJsonMultiLineStringSchema = z.object({
     type: z.literal("MultiLineString"),
-    coordinates: z.array(z.array(geoJsonPositionSchema)),
+    coordinates: z.array(z.array(geoJsonPositionSchema).min(2)),
+    bbox: geoJsonBboxSchema.optional(),
 });
 /**
  * Helper type for reuse across polygon schemas.
@@ -60,14 +111,12 @@ const geoJsonLinearRingSchema = z
     .superRefine((coords, ctx) => {
     const first = coords[0];
     const last = coords[coords.length - 1];
-    // Check if first and last coordinates match
     if (JSON.stringify(first) !== JSON.stringify(last)) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             message: "First and last coordinate positions must be identical (to close the linear ring aka polygon).",
         });
     }
-    // Check if consecutive points are identical (excluding first and last)
     for (let i = 1; i < coords.length - 1; i++) {
         if (JSON.stringify(coords[i]) === JSON.stringify(coords[i - 1])) {
             ctx.addIssue({
@@ -79,21 +128,34 @@ const geoJsonLinearRingSchema = z
 });
 /**
  * Polygon geometry object.
+ * Must have at least one ring (the exterior ring) per RFC 7946 Section 3.1.6.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
  * https://tools.ietf.org/html/rfc7946#section-3.1.6
  */
-const geoJsonPolygonSchema = z.strictObject({
+const geoJsonPolygonSchema = z.object({
     type: z.literal("Polygon"),
-    coordinates: z.array(geoJsonLinearRingSchema),
+    coordinates: z.array(geoJsonLinearRingSchema).min(1),
+    bbox: geoJsonBboxSchema.optional(),
 });
 /**
  * MultiPolygon geometry object.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
  * https://tools.ietf.org/html/rfc7946#section-3.1.7
  */
-const geoJsonMultiPolygonSchema = z.strictObject({
+const geoJsonMultiPolygonSchema = z.object({
     type: z.literal("MultiPolygon"),
     coordinates: z.array(z.array(geoJsonLinearRingSchema)),
+    bbox: geoJsonBboxSchema.optional(),
+});
+/**
+ * GeometryCollection schema.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
+ */
+const geoJsonGeometryCollectionSchema = z.object({
+    type: z.literal("GeometryCollection"),
+    geometries: z.array(z.lazy(() => geoJsonGeometrySchema)),
+    bbox: geoJsonBboxSchema.optional(),
 });
-// The same for Geometry, GeometryCollection, GeoJsonProperties, Feature, FeatureCollection, etc.
 const geoJsonGeometrySchema = z.union([
     geoJsonPointSchema,
     geoJsonMultiPointSchema,
@@ -101,18 +163,32 @@ const geoJsonGeometrySchema = z.union([
     geoJsonMultiLineStringSchema,
     geoJsonPolygonSchema,
     geoJsonMultiPolygonSchema,
+    geoJsonGeometryCollectionSchema,
 ]);
-//* -------- Bbox -------- *//
+//* -------- Feature -------- *//
+/**
+ * Feature object.
+ * Geometry may be null for unlocated features (RFC 7946 Section 3.2).
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
+ * https://tools.ietf.org/html/rfc7946#section-3.2
+ */
+const geoJsonFeatureSchema = z.object({
+    type: z.literal("Feature"),
+    geometry: geoJsonGeometrySchema.nullable(),
+    properties: z.record(z.string(), z.unknown()).nullable(),
+    id: z.union([z.string(), z.number()]).optional(),
+    bbox: geoJsonBboxSchema.optional(),
+});
+//* -------- FeatureCollection -------- *//
 /**
- * 2D bounding box of the GeoJSON object.
- * The value of the Bbox member is an array of length 4.
- *
- * [min_lon, min_lat, max_lon, max_lat]
+ * FeatureCollection object.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
+ * https://tools.ietf.org/html/rfc7946#section-3.3
  */
-const geoJsonBboxSchema = z
-    .tuple([z.number(), z.number(), z.number(), z.number()])
-    .refine(([minLng, minLat, maxLng, maxLat]) => maxLng > minLng && maxLat > minLat, {
-    message: "Invalid bounding box: maxLng should be greater than minLng, and maxLat should be greater than minLat.",
+const geoJsonFeatureCollectionSchema = z.object({
+    type: z.literal("FeatureCollection"),
+    features: z.array(geoJsonFeatureSchema),
+    bbox: geoJsonBboxSchema.optional(),
 });
 
 /**
@@ -168,21 +244,50 @@ const getMinMaxLongitudes = (longitudes) => {
     };
 };
 
-const EARTH_RADIUS = 6378137; // Earth’s mean radius in meters
+const EARTH_RADIUS = 6378137; // Earth's mean radius in meters
+const toClipPolygon = (coords) => coords.map(ring => ring.map(([lng, lat]) => [lng, lat]));
+const toClipMultiPolygon = (coords) => coords.map(polygon => toClipPolygon(polygon));
 /**
- * @description Creates a polygon (with no holes) from a bounding box.
+ * @description Creates a polygon from a bounding box.
+ * Handles antimeridian-crossing bboxes (where west > east) by splitting into
+ * a MultiPolygon with one polygon per hemisphere.
  */
 const getPolygonFromBbox = (bbox) => {
-    const [minLon, minLat, maxLon, maxLat] = bbox;
+    const [west, south, east, north] = bbox;
+    if (west > east) {
+        return {
+            type: "MultiPolygon",
+            coordinates: [
+                [
+                    [
+                        [west, south],
+                        [180, south],
+                        [180, north],
+                        [west, north],
+                        [west, south],
+                    ],
+                ],
+                [
+                    [
+                        [-180, south],
+                        [east, south],
+                        [east, north],
+                        [-180, north],
+                        [-180, south],
+                    ],
+                ],
+            ],
+        };
+    }
     return {
         type: "Polygon",
         coordinates: [
             [
-                [minLon, minLat],
-                [maxLon, minLat],
-                [maxLon, maxLat],
-                [minLon, maxLat],
-                [minLon, minLat],
+                [west, south],
+                [east, south],
+                [east, north],
+                [west, north],
+                [west, south],
             ],
         ],
     };
@@ -192,10 +297,13 @@ const getPolygonFromBbox = (bbox) => {
  * Handles cases where the polygon crosses the 180/-180 meridian.
  */
 const getBboxFromGeoJsonPolygon = (polygon) => {
-    // For MultiPolygon, we need to check all polygons to find the overall bounding box
     const allPoints = [];
     if (polygon.type === "MultiPolygon") {
-        polygon.coordinates.forEach(polygonCoords => {
+        const multiPolygonParsed = geoJsonMultiPolygonSchema.safeParse(polygon);
+        if (!multiPolygonParsed.success) {
+            return null;
+        }
+        multiPolygonParsed.data.coordinates.forEach(polygonCoords => {
             const outerRing = polygonCoords[0];
             if (outerRing) {
                 allPoints.push(...outerRing);
@@ -209,7 +317,6 @@ const getBboxFromGeoJsonPolygon = (polygon) => {
         }
         const points = polygonParsed.data.coordinates[0];
         if (!points) {
-            // Should never happen since the schema checks for it
             return null;
         }
         allPoints.push(...points);
@@ -217,142 +324,75 @@ const getBboxFromGeoJsonPolygon = (polygon) => {
     if (allPoints.length === 0) {
         return null;
     }
-    // Get all longitudes and check if we cross the meridian
     const longitudes = allPoints.map(point => point[0]);
     const latitudes = allPoints.map(point => point[1]);
     const { minLon, maxLon } = getMinMaxLongitudes(longitudes);
     return [minLon, Math.min(...latitudes), maxLon, Math.max(...latitudes)];
 };
+const normalizeLongitude = (lon) => ((lon + 540) % 360) - 180;
+const WESTERN_HEMISPHERE = [
+    [
+        [-180, -90],
+        [0, -90],
+        [0, 90],
+        [-180, 90],
+        [-180, -90],
+    ],
+];
+const EASTERN_HEMISPHERE = [
+    [
+        [0, -90],
+        [180, -90],
+        [180, 90],
+        [0, 90],
+        [0, -90],
+    ],
+];
 /**
  * @description Creates a round polygon from a point and a radius.
+ * Handles antimeridian crossing per RFC 7946 Section 3.1.9 by splitting
+ * into a MultiPolygon. Clamps polar latitudes to [-90, 90].
+ *
+ * Returns null when the polygon crosses the antimeridian but both hemisphere
+ * intersections yield zero polygons (e.g. very small polygons near the
+ * dateline). In that case, returning the original coordinates would produce
+ * invalid geometry per RFC 7946.
  */
 const getPolygonFromPointAndRadius = (point, radius) => {
     const [lon, lat] = point.coordinates;
-    // Adjust the number of points based on radius (resolution)
-    const pointsCount = Math.max(32, Math.floor(radius / 100)); // More points for larger radius
+    const pointsCount = Math.max(32, Math.floor(radius / 100));
     const angleStep = (2 * Math.PI) / pointsCount;
+    const deltaLat = (radius / EARTH_RADIUS) * (180 / Math.PI);
+    const deltaLon = deltaLat / Math.cos((lat * Math.PI) / 180);
     const coordinates = [];
     for (let i = 0; i <= pointsCount; i++) {
         const angle = i * angleStep;
-        // Calculate offset in latitude and longitude
-        const deltaLat = (radius / EARTH_RADIUS) * (180 / Math.PI);
-        const deltaLon = deltaLat / Math.cos((lat * Math.PI) / 180);
-        // Calculate new coordinates based on angle
-        const newLat = lat + deltaLat * Math.sin(angle);
-        const newLon = lon + deltaLon * Math.cos(angle);
+        const newLat = Math.max(-90, Math.min(90, lat + deltaLat * Math.sin(angle)));
+        const newLon = normalizeLongitude(lon + deltaLon * Math.cos(angle));
         coordinates.push([newLon, newLat]);
     }
-    return {
-        type: "Polygon",
-        coordinates: [coordinates],
-    };
-};
-/**
- * @description Creates a TU bounding box from a GeoJson Polygon.
- * Handles cases where the polygon crosses the 180/-180 meridian.
- */
-const getBoundingBoxFromGeoJsonPolygon = (polygon) => {
-    // For MultiPolygon, we need to check all polygons to find the overall bounding box
-    const allPoints = [];
-    if (polygon.type === "MultiPolygon") {
-        const multiPolygonParsed = geoJsonMultiPolygonSchema.safeParse(polygon);
-        if (!multiPolygonParsed.success) {
-            return null;
-        }
-        multiPolygonParsed.data.coordinates.forEach(polygonCoords => {
-            const outerRing = polygonCoords[0];
-            if (outerRing) {
-                allPoints.push(...outerRing);
-            }
-        });
-    }
-    else {
-        const polygonParsed = geoJsonPolygonSchema.safeParse(polygon);
-        if (!polygonParsed.success) {
-            return null;
+    const longitudes = coordinates.map(c => c[0]);
+    if (checkCrossesMeridian(longitudes)) {
+        const rawPolygon = [coordinates.map(c => [c[0], c[1]])];
+        const westPart = polygonClipping.intersection(rawPolygon, WESTERN_HEMISPHERE);
+        const eastPart = polygonClipping.intersection(rawPolygon, EASTERN_HEMISPHERE);
+        const allParts = [...westPart, ...eastPart];
+        if (allParts.length === 1 && allParts[0]) {
+            return { type: "Polygon", coordinates: allParts[0] };
         }
-        const points = polygonParsed.data.coordinates[0];
-        if (!points) {
-            // Should never happen since the schema checks for it
-            return null;
+        if (allParts.length > 1) {
+            return { type: "MultiPolygon", coordinates: allParts };
         }
-        allPoints.push(...points);
-    }
-    if (allPoints.length === 0) {
+        // Both hemisphere intersections produced zero polygons — degenerate case
+        // (e.g. very small polygon near antimeridian). Returning the original
+        // coordinates would produce invalid geometry per RFC 7946 Section 3.1.9.
         return null;
     }
-    // Get all longitudes and check if we cross the meridian
-    const longitudes = allPoints.map(point => point[0]);
-    const latitudes = allPoints.map(point => point[1]);
-    const { minLon, maxLon } = getMinMaxLongitudes(longitudes);
-    return {
-        nw: {
-            latitude: Math.max(...latitudes),
-            longitude: minLon,
-        },
-        se: {
-            latitude: Math.min(...latitudes),
-            longitude: maxLon,
-        },
-    };
-};
-/**
- * @description Creates a GeoJSON MultiPolygon from a TU bounding box.
- * It has to return a MultiPolygon because the polygon may cross the 180/-180 meridian
- * and we need to avoid the polygon being ambiguous about which side of the meridian it wraps around.
- * so if it crosses the meridian, we return a MultiPolygon with two polygons, one for the western hemisphere and one for the eastern hemisphere.
- * @param boundingBox The bounding box to create a polygon from
- * @returns {GeoJsonMultiPolygon | GeoJsonPolygon} The polygon created from the bounding box
- */
-const getGeoJsonPolygonFromBoundingBox = (boundingBox) => {
-    const { nw, se } = boundingBox;
-    if (nw.longitude > se.longitude) {
-        // crossing meridian
-        return {
-            type: "MultiPolygon",
-            coordinates: [
-                [
-                    [
-                        // western hemisphere
-                        [-180, nw.latitude], // Northwest corner
-                        [se.longitude, nw.latitude], // Northeast corner
-                        [se.longitude, se.latitude], // Southeast corner
-                        [-180, se.latitude], // Southwest corner
-                        [-180, nw.latitude], // Close the loop back to Northwest corner
-                    ],
-                ],
-                [
-                    [
-                        // eastern hemisphere
-                        [nw.longitude, nw.latitude], // Northwest corner
-                        [180, nw.latitude], // Northeast corner
-                        [180, se.latitude], // Southeast corner
-                        [nw.longitude, se.latitude], // Southwest corner
-                        [nw.longitude, nw.latitude], // Close the loop back to Northwest corner
-                    ],
-                ],
-            ],
-        };
-    }
     return {
         type: "Polygon",
-        coordinates: [
-            [
-                [nw.longitude, nw.latitude], // Northwest corner
-                [se.longitude, nw.latitude], // Northeast corner
-                [se.longitude, se.latitude], // Southeast corner
-                [nw.longitude, se.latitude], // Southwest corner
-                [nw.longitude, nw.latitude], // Close the loop back to Northwest corner
-            ],
-        ],
+        coordinates: [coordinates],
     };
 };
-/**
- * @description Creates TU point coordinate from a GeoJSON Point.
- */
-const getPointCoordinateFromGeoJsonPoint = (point) => {
-    return { latitude: point.coordinates[1], longitude: point.coordinates[0] };
-};
 /**
  * @description Gets the extreme point of a polygon in a given direction.
  * @param {object} params - The parameters object
@@ -367,7 +407,6 @@ const getExtremeGeoJsonPointFromPolygon = ({ polygon, direction, }) => {
     }
     const firstPoint = polygonParsed.data.coordinates[0]?.[0];
     if (!firstPoint) {
-        // Should never happen since the schema checks for it
         return null;
     }
     const extremePosition = polygonParsed.data.coordinates[0]?.reduce((extremePoint, currentPoint) => {
@@ -390,7 +429,7 @@ const getExtremeGeoJsonPointFromPolygon = ({ polygon, direction, }) => {
             type: "Point",
             coordinates: extremePosition,
         }
-        : null; // Should never happen since the schema checks for it
+        : null;
 };
 /**
  * Checks if a position is inside a linear ring. On edge is considered inside.
@@ -419,35 +458,80 @@ const isGeoJsonPositionInLinearRing = ({ position, linearRing, }) => {
 };
 /**
  * @description Checks if a point is inside a polygon.
+ * Correctly handles holes per RFC 7946 Section 3.1.6: the first ring is the
+ * exterior boundary, subsequent rings are holes. A point inside a hole is
+ * considered outside the polygon.
  */
 const isGeoJsonPointInPolygon = ({ point, polygon, }) => {
     const polygonParsed = geoJsonPolygonSchema.safeParse(polygon);
     if (!polygonParsed.success) {
         return null;
     }
-    return polygonParsed.data.coordinates.some(linearRing => isGeoJsonPositionInLinearRing({ position: point.coordinates, linearRing }));
+    const [exteriorRing, ...holeRings] = polygonParsed.data.coordinates;
+    if (!exteriorRing) {
+        return null;
+    }
+    // Explicit null checks are intentional: isGeoJsonPositionInLinearRing returns
+    // boolean | null, and using it directly in boolean expressions like
+    // `!result` or `.some()` would silently treat null as false/truthy, masking errors.
+    const insideExterior = isGeoJsonPositionInLinearRing({ position: point.coordinates, linearRing: exteriorRing });
+    if (insideExterior === null) {
+        return null;
+    }
+    if (!insideExterior) {
+        return false;
+    }
+    for (const hole of holeRings) {
+        const insideHole = isGeoJsonPositionInLinearRing({ position: point.coordinates, linearRing: hole });
+        if (insideHole === null) {
+            return null;
+        }
+        if (insideHole) {
+            return false;
+        }
+    }
+    return true;
 };
 /**
- * Checks if polygon1/multi-polygon1 is fully contained within polygon2/multi-polygon2
+ * Checks if polygon1 is fully contained within polygon2.
+ * Correctly handles holes per RFC 7946 Section 3.1.6: a polygon inside
+ * a hole of polygon2 is NOT considered contained.
  */
 const isFullyContainedInGeoJsonPolygon = (polygon1, polygon2) => {
     const polygon1Parsed = geoJsonPolygonSchema.safeParse(polygon1);
+    if (!polygon1Parsed.success) {
+        return null;
+    }
     const polygon2Parsed = geoJsonPolygonSchema.safeParse(polygon2);
-    // The schema checks more than a TypeScript type can represent
-    if (!polygon1Parsed.success || !polygon2Parsed.success) {
+    if (!polygon2Parsed.success) {
+        return null;
+    }
+    const outerRing1 = polygon1Parsed.data.coordinates[0];
+    if (!outerRing1) {
         return null;
     }
-    return polygon1Parsed.data.coordinates.every(linearRing => polygon2Parsed.data.coordinates.some(lr => linearRing.every(position => isGeoJsonPositionInLinearRing({ position, linearRing: lr }))));
+    // Explicit null handling: isGeoJsonPointInPolygon returns boolean | null,
+    // so we use a for-loop instead of .every() to avoid null being silently
+    // coerced to false (masking validation errors as "not contained").
+    for (const position of outerRing1) {
+        const contained = isGeoJsonPointInPolygon({ point: { coordinates: position }, polygon: polygon2 });
+        if (contained === null) {
+            return null;
+        }
+        if (!contained) {
+            return false;
+        }
+    }
+    return true;
 };
 /**
  * @description Gets the intersection between two GeoJSON polygons/multi-polygons.
  * Returns a MultiPolygon representing the intersection, or null if there is no intersection.
- * @param polygon1 The first polygon/multi-polygon to check intersection
- * @param polygon2 The second polygon/multi-polygon to check intersection
- * @returns {(GeoJsonMultiPolygon | GeoJsonPolygon)} The intersection as either a Polygon or MultiPolygon
  */
 const getGeoJsonPolygonIntersection = (polygon1, polygon2) => {
-    const intersectionResult = polygonClipping.intersection(polygon1.type === "MultiPolygon" ? polygon1.coordinates : [polygon1.coordinates], polygon2.type === "MultiPolygon" ? polygon2.coordinates : [polygon2.coordinates]);
+    const geom1 = polygon1.type === "MultiPolygon" ? toClipMultiPolygon(polygon1.coordinates) : [toClipPolygon(polygon1.coordinates)];
+    const geom2 = polygon2.type === "MultiPolygon" ? toClipMultiPolygon(polygon2.coordinates) : [toClipPolygon(polygon2.coordinates)];
+    const intersectionResult = polygonClipping.intersection(geom1, geom2);
     if (intersectionResult.length === 0) {
         return null;
     }
@@ -462,18 +546,6 @@ const getGeoJsonPolygonIntersection = (polygon1, polygon2) => {
         coordinates: intersectionResult,
     };
 };
-/**
- * @description Creates a TU bounding box from a GeoJSON Bbox.
- * @param bbox The GeoJSON Bbox to create a TU bounding box from
- * @returns {TuBoundingBox} The TU bounding box created from the GeoJSON Bbox
- */
-const getBoundingBoxFromGeoJsonBbox = (bbox) => {
-    const [minLon, minLat, maxLon, maxLat] = bbox;
-    return {
-        nw: { longitude: minLon, latitude: maxLat },
-        se: { longitude: maxLon, latitude: minLat },
-    };
-};
 
 //! These tools are used to bridge the gap with out poorly typed graphql types
 // Should be ideally be avoided but are needed until we fix the graphql types
@@ -551,14 +623,131 @@ const getMultipleCoordinatesFromGeoJsonObject = (geoObject) => {
     }
 };
 
+/**
+ * @description Converts a GeoJSON position (which may have altitude) to a 2D position.
+ */
+const toPosition2d = (position) => [position[0], position[1]];
+/**
+ * @description Creates a TU bounding box from a GeoJson Polygon.
+ * Handles cases where the polygon crosses the 180/-180 meridian.
+ */
+const getBoundingBoxFromGeoJsonPolygon = (polygon) => {
+    const allPoints = [];
+    if (polygon.type === "MultiPolygon") {
+        const multiPolygonParsed = geoJsonMultiPolygonSchema.safeParse(polygon);
+        if (!multiPolygonParsed.success) {
+            return null;
+        }
+        multiPolygonParsed.data.coordinates.forEach(polygonCoords => {
+            const outerRing = polygonCoords[0];
+            if (outerRing) {
+                allPoints.push(...outerRing);
+            }
+        });
+    }
+    else {
+        const polygonParsed = geoJsonPolygonSchema.safeParse(polygon);
+        if (!polygonParsed.success) {
+            return null;
+        }
+        const points = polygonParsed.data.coordinates[0];
+        if (!points) {
+            return null;
+        }
+        allPoints.push(...points);
+    }
+    if (allPoints.length === 0) {
+        return null;
+    }
+    const longitudes = allPoints.map(point => point[0]);
+    const latitudes = allPoints.map(point => point[1]);
+    const { minLon, maxLon } = getMinMaxLongitudes(longitudes);
+    return {
+        nw: {
+            latitude: Math.max(...latitudes),
+            longitude: minLon,
+        },
+        se: {
+            latitude: Math.min(...latitudes),
+            longitude: maxLon,
+        },
+    };
+};
+/**
+ * @description Creates a GeoJSON Polygon or MultiPolygon from a TU bounding box.
+ * Returns a MultiPolygon when the bounding box crosses the 180/-180 meridian,
+ * with one polygon per hemisphere.
+ *
+ * Returns a 2D-only coordinate type since bounding boxes have no altitude.
+ * The return type is assignable to both GeoJsonPolygon | GeoJsonMultiPolygon
+ * (for GeoJSON consumers) and GraphQL AreaInput (for query variables).
+ */
+const getGeoJsonPolygonFromBoundingBox = (boundingBox) => {
+    const { nw, se } = boundingBox;
+    if (nw.longitude > se.longitude) {
+        return {
+            type: "MultiPolygon",
+            coordinates: [
+                [
+                    [
+                        [nw.longitude, se.latitude],
+                        [180, se.latitude],
+                        [180, nw.latitude],
+                        [nw.longitude, nw.latitude],
+                        [nw.longitude, se.latitude],
+                    ],
+                ],
+                [
+                    [
+                        [-180, se.latitude],
+                        [se.longitude, se.latitude],
+                        [se.longitude, nw.latitude],
+                        [-180, nw.latitude],
+                        [-180, se.latitude],
+                    ],
+                ],
+            ],
+        };
+    }
+    return {
+        type: "Polygon",
+        coordinates: [
+            [
+                [nw.longitude, se.latitude],
+                [se.longitude, se.latitude],
+                [se.longitude, nw.latitude],
+                [nw.longitude, nw.latitude],
+                [nw.longitude, se.latitude],
+            ],
+        ],
+    };
+};
+/**
+ * @description Creates TU point coordinate from a GeoJSON Point.
+ */
+const getPointCoordinateFromGeoJsonPoint = (point) => {
+    return { latitude: point.coordinates[1], longitude: point.coordinates[0] };
+};
+/**
+ * @description Creates a TU bounding box from a GeoJSON Bbox.
+ */
+const getBoundingBoxFromGeoJsonBbox = (bbox) => {
+    const [west, south, east, north] = bbox;
+    return {
+        nw: { longitude: west, latitude: north },
+        se: { longitude: east, latitude: south },
+    };
+};
+
 //* -------- Trackunit-invented schemas and types to extend the GeoJson spec -------- *//
 /**
  * Polygon geometry object that explicitly disallows holes.
  *
  * Same as geoJsonPolygonSchema but type disallows holes by
  * using tuple of one single linear ring instead of an array.
+ * Foreign members (RFC 7946 Section 6.1) are stripped during parse.
  */
-const tuGeoJsonPolygonNoHolesSchema = z.strictObject({
+const tuGeoJsonPolygonNoHolesSchema = z.object({
     //The type is still "Polygon" (not PolygonNoHoles or similar) since it's always
     //compliant with Polygon, just not the other way around
     type: z.literal("Polygon"),
@@ -570,17 +759,19 @@ const tuGeoJsonPolygonNoHolesSchema = z.strictObject({
  * For when you wish to define an area by a point and a radius.
  *
  * radius is in meters
+ * Foreign members are stripped during parse.
  */
-const tuGeoJsonPointRadiusSchema = z.strictObject({
+const tuGeoJsonPointRadiusSchema = z.object({
     type: z.literal("PointRadius"),
     coordinates: geoJsonPositionSchema,
     radius: z.number().positive(), // in meters
 });
 /**
  * A Polygon with exactly 5 points and 4 horizontal/vertical sides that form a normal rectangular box.
+ * Foreign members are stripped during parse.
  */
 const tuGeoJsonRectangularBoxPolygonSchema = z
-    .strictObject({
+    .object({
     type: z.literal("Polygon"),
     coordinates: z.array(geoJsonLinearRingSchema),
 })
@@ -618,4 +809,4 @@ const tuGeoJsonRectangularBoxPolygonSchema = z
     }
 });
 
-export { EARTH_RADIUS, boundingBoxCrossesMeridian, checkCrossesMeridian, coordinatesToStandardFormat, denormalizeLongitude, geoJsonBboxSchema, geoJsonGeometrySchema, geoJsonLineStringSchema, geoJsonLinearRingSchema, geoJsonMultiLineStringSchema, geoJsonMultiPointSchema, geoJsonMultiPolygonSchema, geoJsonPointSchema, geoJsonPolygonSchema, geoJsonPositionSchema, getBboxFromGeoJsonPolygon, getBoundingBoxFromGeoJsonBbox, getBoundingBoxFromGeoJsonPolygon, getExtremeGeoJsonPointFromPolygon, getGeoJsonPolygonFromBoundingBox, getGeoJsonPolygonIntersection, getMinMaxLongitudes, getMultipleCoordinatesFromGeoJsonObject, getPointCoordinateFromGeoJsonObject, getPointCoordinateFromGeoJsonPoint, getPolygonFromBbox, getPolygonFromPointAndRadius, isFullyContainedInGeoJsonPolygon, isGeoJsonPointInPolygon, isGeoJsonPositionInLinearRing, normalizeLongitudes, tuGeoJsonPointRadiusSchema, tuGeoJsonPolygonNoHolesSchema, tuGeoJsonRectangularBoxPolygonSchema };
+export { EARTH_RADIUS, boundingBoxCrossesMeridian, checkCrossesMeridian, coordinatesToStandardFormat, denormalizeLongitude, geoJsonBboxSchema, geoJsonFeatureCollectionSchema, geoJsonFeatureSchema, geoJsonGeometryCollectionSchema, geoJsonGeometrySchema, geoJsonLineStringSchema, geoJsonLinearRingSchema, geoJsonMultiLineStringSchema, geoJsonMultiPointSchema, geoJsonMultiPolygonSchema, geoJsonPointSchema, geoJsonPolygonSchema, geoJsonPosition2dSchema, geoJsonPositionSchema, getBboxFromGeoJsonPolygon, getBoundingBoxFromGeoJsonBbox, getBoundingBoxFromGeoJsonPolygon, getExtremeGeoJsonPointFromPolygon, getGeoJsonPolygonFromBoundingBox, getGeoJsonPolygonIntersection, getMinMaxLongitudes, getMultipleCoordinatesFromGeoJsonObject, getPointCoordinateFromGeoJsonObject, getPointCoordinateFromGeoJsonPoint, getPolygonFromBbox, getPolygonFromPointAndRadius, isFullyContainedInGeoJsonPolygon, isGeoJsonPointInPolygon, isGeoJsonPositionInLinearRing, normalizeLongitudes, toPosition2d, tuGeoJsonPointRadiusSchema, tuGeoJsonPolygonNoHolesSchema, tuGeoJsonRectangularBoxPolygonSchema };