@trackunit/geo-json-utils 1.12.27 → 1.12.29

package/README.md

@@ -1,17 +1,32 @@
 # Trackunit geo-json-utils
 
-The `@trackunit/geo-json-utils` package is the home of Trackunits public react components used for...
+`@trackunit/geo-json-utils` is Trackunit's shared GeoJSON utility package.
+It contains runtime validation schemas, geometry helpers, and conversion utilities used by map adapters and other frontend libraries.
 
-This library is exposed publicly for use in the the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app).
-
-To browse all avaliable components visit the [Design System](https://design.iris.trackunit.com/).
+This library is published for use in the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app) and other npm consumers.
 
 For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
 
+## Exports
+
+The package entry (`src/index.ts`) exports these module surfaces:
+
+- **Runtime validation** (`GeoJsonRuntimeValidation`) — These helpers validate unknown input against GeoJSON schemas and log warnings for invalid values so callers can fail safely without throwing.
+- **Geometry helpers** (`GeoJsonGeometryUtils`)
+- **General GeoJSON utilities** (`GeoJsonUtils`)
+- **Zod schemas** — GeoJSON (`GeoJsonSchemas`) and Trackunit-oriented variants (`TuGeoJsonSchemas`)
+- **Meridian / longitude helpers** (`MeridianUtils`)
+- **Bridge utilities** — Trackunit GeoJSON bridging (`TuGeoJsonBridgeUtils`)
+- **Conversions** — Trackunit-oriented conversions (`TuGeoJsonConversions`)
+
 ## Development
 
 At this point this library is only developed by Trackunit Employees.  
-For development related information see the [development readme](https://github.com/Trackunit/manager/blob/master/libs/react/components/DEVELOPMENT.md).
+Run library targets through Nx:
+
+- `yarn nx run geo-json-utils:tsc-validate`
+- `yarn nx run geo-json-utils:test`
+- `yarn nx run geo-json-utils:build`
 
 ## Trackunit
 

package/index.cjs.js

@@ -455,6 +455,84 @@ const geoJsonFeatureCollectionSchema = zod.z.object({
     bbox: geoJsonBboxSchema.optional(),
 });
 
+/**
+ * Empty FeatureCollection fallback used when runtime validation fails.
+ */
+const EMPTY_FEATURE_COLLECTION = {
+    type: "FeatureCollection",
+    features: [],
+};
+/**
+ * Validates a GeoJSON position value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonPosition | null} Parsed position when valid, otherwise null.
+ */
+const validatePosition = (value, context) => {
+    const result = geoJsonPositionSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON position is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+/**
+ * Validates a GeoJSON bounding box value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox | null} Parsed bbox when valid, otherwise null.
+ */
+const validateBbox = (value, context) => {
+    const result = geoJsonBboxSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON bbox is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+/**
+ * Validates a GeoJSON bounding box and falls back to a provided default.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param fallback Bbox returned when validation fails.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox} Parsed bbox when valid, otherwise a copied fallback bbox.
+ */
+const validateBboxWithFallback = (value, fallback, context) => {
+    const result = geoJsonBboxSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON bbox is passed; fallback to provided default
+    console.warn(message);
+    const copiedFallback = [fallback[0], fallback[1], fallback[2], fallback[3]];
+    return copiedFallback;
+};
+/**
+ * Validates a GeoJSON FeatureCollection value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonFeatureCollection | null} Parsed feature collection when valid, otherwise null.
+ */
+const validateFeatureCollection = (value, context) => {
+    const result = geoJsonFeatureCollectionSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON FeatureCollection is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+
 /**
  * Utilities for handling coordinates and bounding boxes that cross the 180/-180 meridian.
  */
@@ -1442,6 +1520,7 @@ const tuGeoJsonRectangularBoxPolygonSchema = zod.z
 });
 
 exports.EARTH_RADIUS = EARTH_RADIUS;
+exports.EMPTY_FEATURE_COLLECTION = EMPTY_FEATURE_COLLECTION;
 exports.boundingBoxCrossesMeridian = boundingBoxCrossesMeridian;
 exports.checkCrossesMeridian = checkCrossesMeridian;
 exports.computeGeometryCentroid = computeGeometryCentroid;
@@ -1489,3 +1568,7 @@ exports.toPosition2d = toPosition2d;
 exports.tuGeoJsonPointRadiusSchema = tuGeoJsonPointRadiusSchema;
 exports.tuGeoJsonPolygonNoHolesSchema = tuGeoJsonPolygonNoHolesSchema;
 exports.tuGeoJsonRectangularBoxPolygonSchema = tuGeoJsonRectangularBoxPolygonSchema;
+exports.validateBbox = validateBbox;
+exports.validateBboxWithFallback = validateBboxWithFallback;
+exports.validateFeatureCollection = validateFeatureCollection;
+exports.validatePosition = validatePosition;

package/index.esm.js

@@ -453,6 +453,84 @@ const geoJsonFeatureCollectionSchema = z.object({
     bbox: geoJsonBboxSchema.optional(),
 });
 
+/**
+ * Empty FeatureCollection fallback used when runtime validation fails.
+ */
+const EMPTY_FEATURE_COLLECTION = {
+    type: "FeatureCollection",
+    features: [],
+};
+/**
+ * Validates a GeoJSON position value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonPosition | null} Parsed position when valid, otherwise null.
+ */
+const validatePosition = (value, context) => {
+    const result = geoJsonPositionSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON position is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+/**
+ * Validates a GeoJSON bounding box value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox | null} Parsed bbox when valid, otherwise null.
+ */
+const validateBbox = (value, context) => {
+    const result = geoJsonBboxSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON bbox is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+/**
+ * Validates a GeoJSON bounding box and falls back to a provided default.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param fallback Bbox returned when validation fails.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox} Parsed bbox when valid, otherwise a copied fallback bbox.
+ */
+const validateBboxWithFallback = (value, fallback, context) => {
+    const result = geoJsonBboxSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON bbox is passed; fallback to provided default
+    console.warn(message);
+    const copiedFallback = [fallback[0], fallback[1], fallback[2], fallback[3]];
+    return copiedFallback;
+};
+/**
+ * Validates a GeoJSON FeatureCollection value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonFeatureCollection | null} Parsed feature collection when valid, otherwise null.
+ */
+const validateFeatureCollection = (value, context) => {
+    const result = geoJsonFeatureCollectionSchema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const message = context ? `${context} ${result.error.message}` : result.error.message;
+    // eslint-disable-next-line no-console -- Intentional: warn developers when invalid GeoJSON FeatureCollection is passed; fallback to null
+    console.warn(message);
+    return null;
+};
+
 /**
  * Utilities for handling coordinates and bounding boxes that cross the 180/-180 meridian.
  */
@@ -1439,4 +1517,4 @@ const tuGeoJsonRectangularBoxPolygonSchema = z
     }
 });
 
-export { EARTH_RADIUS, boundingBoxCrossesMeridian, checkCrossesMeridian, computeGeometryCentroid, coordinatesToStandardFormat, denormalizeLongitude, extractEdges, extractFirstPointCoordinate, extractPositionsFromGeometry, 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, isBboxInsideFeatureCollection, isFullyContainedInGeoJsonPolygon, isGeoJsonPointInPolygon, isGeoJsonPositionInLinearRing, isPositionInsideRing, normalizeLongitudes, splitPolygonAtAntimeridian, splitPolygonWithHolesAtAntimeridian, toFeatureCollection, toPosition2d, tuGeoJsonPointRadiusSchema, tuGeoJsonPolygonNoHolesSchema, tuGeoJsonRectangularBoxPolygonSchema };
+export { EARTH_RADIUS, EMPTY_FEATURE_COLLECTION, boundingBoxCrossesMeridian, checkCrossesMeridian, computeGeometryCentroid, coordinatesToStandardFormat, denormalizeLongitude, extractEdges, extractFirstPointCoordinate, extractPositionsFromGeometry, 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, isBboxInsideFeatureCollection, isFullyContainedInGeoJsonPolygon, isGeoJsonPointInPolygon, isGeoJsonPositionInLinearRing, isPositionInsideRing, normalizeLongitudes, splitPolygonAtAntimeridian, splitPolygonWithHolesAtAntimeridian, toFeatureCollection, toPosition2d, tuGeoJsonPointRadiusSchema, tuGeoJsonPolygonNoHolesSchema, tuGeoJsonRectangularBoxPolygonSchema, validateBbox, validateBboxWithFallback, validateFeatureCollection, validatePosition };

package/package.json

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

package/src/GeoJsonRuntimeValidation.d.ts

@@ -0,0 +1,38 @@
+import { type GeoJsonBbox, type GeoJsonFeatureCollection, type GeoJsonPosition } from "./GeoJsonSchemas";
+/**
+ * Empty FeatureCollection fallback used when runtime validation fails.
+ */
+export declare const EMPTY_FEATURE_COLLECTION: GeoJsonFeatureCollection;
+/**
+ * Validates a GeoJSON position value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonPosition | null} Parsed position when valid, otherwise null.
+ */
+export declare const validatePosition: (value: unknown, context?: string) => GeoJsonPosition | null;
+/**
+ * Validates a GeoJSON bounding box value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox | null} Parsed bbox when valid, otherwise null.
+ */
+export declare const validateBbox: (value: unknown, context?: string) => GeoJsonBbox | null;
+/**
+ * Validates a GeoJSON bounding box and falls back to a provided default.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param fallback Bbox returned when validation fails.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonBbox} Parsed bbox when valid, otherwise a copied fallback bbox.
+ */
+export declare const validateBboxWithFallback: (value: unknown, fallback: GeoJsonBbox, context?: string) => GeoJsonBbox;
+/**
+ * Validates a GeoJSON FeatureCollection value.
+ *
+ * @param value Unknown runtime value to validate.
+ * @param context Optional prefix used in warn messages.
+ * @returns {GeoJsonFeatureCollection | null} Parsed feature collection when valid, otherwise null.
+ */
+export declare const validateFeatureCollection: (value: unknown, context?: string) => GeoJsonFeatureCollection | null;

package/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./GeoJsonGeometryUtils";
+export * from "./GeoJsonRuntimeValidation";
 export * from "./GeoJsonSchemas";
 export * from "./GeoJsonUtils";
 export * from "./MeridianUtils";