@trackunit/geo-json-utils 1.15.18 → 1.15.19

package/index.cjs.js

@@ -1285,6 +1285,15 @@ const isFullyContainedInGeoJsonPolygon = (polygon1, polygon2) => {
 /**
  * @description Gets the intersection between two GeoJSON polygons/multi-polygons.
  * Returns a MultiPolygon representing the intersection, or null if there is no intersection.
+ *
+ * Delegates to `polygon-clipping`, which can **throw** `"Unable to complete output ring"`
+ * for degenerate or near-self-intersecting geometry that is still schema-valid. Callers must
+ * decide how to handle that: `null` here is reserved for a *provably empty* intersection, so
+ * a thrown failure must not be silently folded into `null` (see SAGA-743). Callers for which
+ * "no overlap" is a safe degradation (e.g. overlap grouping in `@trackunit/react-map`) should
+ * catch and treat the throw as no intersection; callers that turn `null` into "no spatial
+ * filter" (e.g. `mapUtils` viewport/area merges) must instead fall back to a conservative
+ * geometry rather than assume disjointness.
  */
 const getGeoJsonPolygonIntersection = (polygon1, polygon2) => {
     const geom1 = polygon1.type === "MultiPolygon" ? toClipMultiPolygon(polygon1.coordinates) : [toClipPolygon(polygon1.coordinates)];

package/index.esm.js

@@ -1283,6 +1283,15 @@ const isFullyContainedInGeoJsonPolygon = (polygon1, polygon2) => {
 /**
  * @description Gets the intersection between two GeoJSON polygons/multi-polygons.
  * Returns a MultiPolygon representing the intersection, or null if there is no intersection.
+ *
+ * Delegates to `polygon-clipping`, which can **throw** `"Unable to complete output ring"`
+ * for degenerate or near-self-intersecting geometry that is still schema-valid. Callers must
+ * decide how to handle that: `null` here is reserved for a *provably empty* intersection, so
+ * a thrown failure must not be silently folded into `null` (see SAGA-743). Callers for which
+ * "no overlap" is a safe degradation (e.g. overlap grouping in `@trackunit/react-map`) should
+ * catch and treat the throw as no intersection; callers that turn `null` into "no spatial
+ * filter" (e.g. `mapUtils` viewport/area merges) must instead fall back to a conservative
+ * geometry rather than assume disjointness.
  */
 const getGeoJsonPolygonIntersection = (polygon1, polygon2) => {
     const geom1 = polygon1.type === "MultiPolygon" ? toClipMultiPolygon(polygon1.coordinates) : [toClipPolygon(polygon1.coordinates)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/geo-json-utils",
-  "version": "1.15.18",
+  "version": "1.15.19",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/GeoJsonUtils.d.ts

@@ -100,6 +100,15 @@ export declare const isFullyContainedInGeoJsonPolygon: (polygon1: GeoJsonPolygon
 /**
  * @description Gets the intersection between two GeoJSON polygons/multi-polygons.
  * Returns a MultiPolygon representing the intersection, or null if there is no intersection.
+ *
+ * Delegates to `polygon-clipping`, which can **throw** `"Unable to complete output ring"`
+ * for degenerate or near-self-intersecting geometry that is still schema-valid. Callers must
+ * decide how to handle that: `null` here is reserved for a *provably empty* intersection, so
+ * a thrown failure must not be silently folded into `null` (see SAGA-743). Callers for which
+ * "no overlap" is a safe degradation (e.g. overlap grouping in `@trackunit/react-map`) should
+ * catch and treat the throw as no intersection; callers that turn `null` into "no spatial
+ * filter" (e.g. `mapUtils` viewport/area merges) must instead fall back to a conservative
+ * geometry rather than assume disjointness.
  */
 export declare const getGeoJsonPolygonIntersection: (polygon1: GeoJsonPolygon | GeoJsonMultiPolygon, polygon2: GeoJsonPolygon | GeoJsonMultiPolygon) => GeoJsonMultiPolygon | GeoJsonPolygon | null;
 /**