@trackunit/shared-utils 0.0.82-alpha-c6639d22933.0 → 0.0.83

package/index.cjs.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var zod = require('zod');
 var uuid = require('uuid');
 
 /**
@@ -413,6 +414,181 @@ searchTerm) => {
         .every(term => filterableProps(asset).some(value => value.toLowerCase().includes(term.toLowerCase()))));
 };
 
+// * NOTE: For simplicity these tools are built for 2D coordinate space only!
+/**
+ * A Position is an array of coordinates. [x, y]
+ * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ */
+const geoJsonPositionSchema = zod.z.tuple([zod.z.number(), zod.z.number()]);
+/**
+ * Point geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.2
+ */
+const geoJsonPointSchema = zod.z.strictObject({
+    type: zod.z.literal("Point"),
+    coordinates: geoJsonPositionSchema,
+});
+/**
+ * MultiPoint geometry object.
+ *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ */
+const geoJsonMultiPointSchema = zod.z.strictObject({
+    type: zod.z.literal("MultiPoint"),
+    coordinates: zod.z.array(geoJsonPositionSchema),
+});
+/**
+ * LineString geometry object.
+ * Minimum length of 2 positions.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.4
+ */
+const geoJsonLineStringSchema = zod.z.strictObject({
+    type: zod.z.literal("LineString"),
+    coordinates: zod.z.array(geoJsonPositionSchema).min(2),
+});
+/**
+ * MultiLineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.5
+ */
+const geoJsonMultiLineStringSchema = zod.z.strictObject({
+    type: zod.z.literal("MultiLineString"),
+    coordinates: zod.z.array(zod.z.array(geoJsonPositionSchema)),
+});
+/**
+ * Helper type for reuse across polygon schemas.
+ *
+ * - A linear ring is a closed LineString with four or more positions.
+ * - The first and last positions are equivalent, and they MUST contain
+      identical values; their representation SHOULD also be identical
+ * - A linear ring is the boundary of a surface or the boundary of a
+      hole in a surface
+ * - A linear ring MUST follow the right-hand rule with respect to the
+      area it bounds, i.e., exterior rings are counterclockwise, and
+      holes are clockwise
+ */
+const geoJsonLinearRingSchema = zod.z
+    .array(geoJsonPositionSchema)
+    .min(4, {
+    message: "Coordinates array must contain at least 4 positions. 3 to make a non-line shape and 1 to close the shape (duplicate of first)",
+})
+    .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: zod.z.ZodIssueCode.custom,
+            message: "First and last coordinate positions must be identical (to close the linear ring aka polygon).",
+        });
+    }
+    // Check if any coordinate is (0, 0)
+    coords.forEach((coord, index) => {
+        if (coord[0] === 0 && coord[1] === 0) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: `Coordinate at index ${index} should not be (0, 0). This is likely not a valid coordinate.`,
+            });
+        }
+    });
+    // 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({
+                code: zod.z.ZodIssueCode.custom,
+                message: `Consecutive coordinates at index ${i - 1} and ${i} should not be identical.`,
+            });
+        }
+    }
+});
+/**
+ * Polygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+const geoJsonPolygonSchema = zod.z.strictObject({
+    type: zod.z.literal("Polygon"),
+    coordinates: zod.z.array(geoJsonLinearRingSchema),
+});
+/**
+ * MultiPolygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.7
+ */
+const geoJsonMultiPolygonSchema = zod.z.strictObject({
+    type: zod.z.literal("MultiPolygon"),
+    coordinates: zod.z.array(zod.z.array(geoJsonLinearRingSchema)),
+});
+// The same for Geometry, GeometryCollection, GeoJsonProperties, Feature, FeatureCollection, etc.
+const geoJsonGeometrySchema = zod.z.union([
+    geoJsonPointSchema,
+    geoJsonMultiPointSchema,
+    geoJsonLineStringSchema,
+    geoJsonMultiLineStringSchema,
+    geoJsonPolygonSchema,
+    geoJsonMultiPolygonSchema,
+]);
+//* -------- Bbox -------- *//
+/**
+ * 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]
+ */
+const geoJsonBboxSchema = zod.z
+    .tuple([zod.z.number(), zod.z.number(), zod.z.number(), zod.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.",
+});
+//* -------- Extras -------- *//
+/**
+ * Polygon geometry object that explicitly disallows holes.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+const geoJsonPolygonNoHolesSchema = zod.z.strictObject({
+    type: zod.z.literal("Polygon"),
+    //uses tuple instead of array to enforce only 1 linear ring aka the polygon itself
+    coordinates: zod.z.tuple([geoJsonLinearRingSchema]),
+});
+/**
+ * A Polygon with exactly 5 points and 4 horizontal/vertical sides that form a normal rectangular box.
+ */
+const geoJsonRectangularBoxPolygonSchema = zod.z
+    .strictObject({
+    type: zod.z.literal("Polygon"),
+    coordinates: zod.z.array(geoJsonLinearRingSchema),
+})
+    .superRefine((data, ctx) => {
+    const coordinates = data.coordinates[0];
+    // Validate polygon has exactly 5 points
+    if ((coordinates === null || coordinates === void 0 ? void 0 : coordinates.length) !== 5) {
+        ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "Polygon must have exactly 5 coordinates to form a closed box.",
+        });
+        return;
+    }
+    // Check each side is either horizontal or vertical
+    for (let i = 0; i < 4; i++) {
+        const point1 = coordinates[i];
+        const point2 = coordinates[i + 1];
+        if (!point1 || !point2) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: "Each coordinate must be a defined point.",
+            });
+            return;
+        }
+        const [x1, y1] = point1;
+        const [x2, y2] = point2;
+        // Ensure each line segment is either horizontal or vertical
+        if (x1 !== x2 && y1 !== y2) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: "Polygon sides must be horizontal or vertical to form a box shape.",
+            });
+            return;
+        }
+    }
+});
+
+const EARTH_RADIUS = 6378137; // Earth’s mean radius in meters
 /**
  * @description Extracts a point coordinate from a GeoJSON object.
  * @param geoObject A GeoJSON object.
@@ -459,6 +635,93 @@ const getMultipleCoordinatesFromGeoJsonObject = (geoObject) => {
         throw new Error(`Unable to extract point coordinate from ${JSON.stringify(geoObject)}`);
     }
 };
+/**
+ * @description Creates a polygon from a bounding box.
+ */
+const getPolygonFromBbox = (bbox) => {
+    const [minLon, minLat, maxLon, maxLat] = bbox;
+    return {
+        type: "Polygon",
+        coordinates: [
+            [
+                [minLon, minLat],
+                [maxLon, minLat],
+                [maxLon, maxLat],
+                [minLon, maxLat],
+                [minLon, minLat],
+            ],
+        ],
+    };
+};
+/**
+ * @description Creates a round polygon from a point and a radius.
+ */
+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 angleStep = (2 * Math.PI) / pointsCount;
+    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);
+        coordinates.push([newLon, newLat]);
+    }
+    return {
+        type: "Polygon",
+        coordinates: [coordinates],
+    };
+};
+/**
+ * @description Creates a TU bounding box from a GeoJson Polygon.
+ */
+const getBoundingBoxFromGeoJsonPolygon = (polygon) => {
+    const points = polygon.coordinates[0];
+    const latitudes = points === null || points === void 0 ? void 0 : points.map(point => point[1]);
+    const longitudes = points === null || points === void 0 ? void 0 : points.map(point => point[0]);
+    if (!latitudes || !longitudes) {
+        return undefined;
+    }
+    return {
+        nw: {
+            latitude: Math.max(...latitudes),
+            longitude: Math.min(...longitudes),
+        },
+        se: {
+            latitude: Math.min(...latitudes),
+            longitude: Math.max(...longitudes),
+        },
+    };
+};
+/**
+ * @description Creates a GeoJSON Polygon from a TU bounding box.
+ */
+const getGeoJsonPolygonFromBoundingBox = (boundingBox) => {
+    const { nw, se } = boundingBox;
+    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
+            ],
+        ],
+    };
+};
+/**
+ * @description Creates TU point coordinate from a GeoJSON Point.
+ */
+const getPointCoordinateFromGeoJsonPoint = (point) => {
+    return { latitude: point.coordinates[1], longitude: point.coordinates[0] };
+};
 
 /**
  * Group an array of items by a key.
@@ -1107,6 +1370,7 @@ const uuidv4 = () => {
 const uuidv5 = (name, namespace) => uuid.v5(name, namespace);
 
 exports.DateTimeFormat = DateTimeFormat;
+exports.EARTH_RADIUS = EARTH_RADIUS;
 exports.align = align;
 exports.alphabeticallySort = alphabeticallySort;
 exports.arrayLengthCompare = arrayLengthCompare;
@@ -1128,12 +1392,29 @@ exports.filterByMultiple = filterByMultiple;
 exports.formatAddress = formatAddress;
 exports.formatCoordinates = formatCoordinates;
 exports.fuzzySearch = fuzzySearch;
+exports.geoJsonBboxSchema = geoJsonBboxSchema;
+exports.geoJsonGeometrySchema = geoJsonGeometrySchema;
+exports.geoJsonLineStringSchema = geoJsonLineStringSchema;
+exports.geoJsonLinearRingSchema = geoJsonLinearRingSchema;
+exports.geoJsonMultiLineStringSchema = geoJsonMultiLineStringSchema;
+exports.geoJsonMultiPointSchema = geoJsonMultiPointSchema;
+exports.geoJsonMultiPolygonSchema = geoJsonMultiPolygonSchema;
+exports.geoJsonPointSchema = geoJsonPointSchema;
+exports.geoJsonPolygonNoHolesSchema = geoJsonPolygonNoHolesSchema;
+exports.geoJsonPolygonSchema = geoJsonPolygonSchema;
+exports.geoJsonPositionSchema = geoJsonPositionSchema;
+exports.geoJsonRectangularBoxPolygonSchema = geoJsonRectangularBoxPolygonSchema;
+exports.getBoundingBoxFromGeoJsonPolygon = getBoundingBoxFromGeoJsonPolygon;
 exports.getDifferenceBetweenDates = getDifferenceBetweenDates;
 exports.getEndOfDay = getEndOfDay;
 exports.getFirstLevelObjectPropertyDifferences = getFirstLevelObjectPropertyDifferences;
+exports.getGeoJsonPolygonFromBoundingBox = getGeoJsonPolygonFromBoundingBox;
 exports.getISOStringFromDate = getISOStringFromDate;
 exports.getMultipleCoordinatesFromGeoJsonObject = getMultipleCoordinatesFromGeoJsonObject;
 exports.getPointCoordinateFromGeoJsonObject = getPointCoordinateFromGeoJsonObject;
+exports.getPointCoordinateFromGeoJsonPoint = getPointCoordinateFromGeoJsonPoint;
+exports.getPolygonFromBbox = getPolygonFromBbox;
+exports.getPolygonFromPointAndRadius = getPolygonFromPointAndRadius;
 exports.getResizedDimensions = getResizedDimensions;
 exports.getStartOfDay = getStartOfDay;
 exports.groupBy = groupBy;

package/index.esm.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { v3, v4, v5 } from 'uuid';
 
 /**
@@ -411,6 +412,181 @@ searchTerm) => {
         .every(term => filterableProps(asset).some(value => value.toLowerCase().includes(term.toLowerCase()))));
 };
 
+// * NOTE: For simplicity these tools are built for 2D coordinate space only!
+/**
+ * A Position is an array of coordinates. [x, y]
+ * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ */
+const geoJsonPositionSchema = z.tuple([z.number(), z.number()]);
+/**
+ * Point geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.2
+ */
+const geoJsonPointSchema = z.strictObject({
+    type: z.literal("Point"),
+    coordinates: geoJsonPositionSchema,
+});
+/**
+ * MultiPoint geometry object.
+ *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ */
+const geoJsonMultiPointSchema = z.strictObject({
+    type: z.literal("MultiPoint"),
+    coordinates: z.array(geoJsonPositionSchema),
+});
+/**
+ * LineString geometry object.
+ * Minimum length of 2 positions.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.4
+ */
+const geoJsonLineStringSchema = z.strictObject({
+    type: z.literal("LineString"),
+    coordinates: z.array(geoJsonPositionSchema).min(2),
+});
+/**
+ * MultiLineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.5
+ */
+const geoJsonMultiLineStringSchema = z.strictObject({
+    type: z.literal("MultiLineString"),
+    coordinates: z.array(z.array(geoJsonPositionSchema)),
+});
+/**
+ * Helper type for reuse across polygon schemas.
+ *
+ * - A linear ring is a closed LineString with four or more positions.
+ * - The first and last positions are equivalent, and they MUST contain
+      identical values; their representation SHOULD also be identical
+ * - A linear ring is the boundary of a surface or the boundary of a
+      hole in a surface
+ * - A linear ring MUST follow the right-hand rule with respect to the
+      area it bounds, i.e., exterior rings are counterclockwise, and
+      holes are clockwise
+ */
+const geoJsonLinearRingSchema = z
+    .array(geoJsonPositionSchema)
+    .min(4, {
+    message: "Coordinates array must contain at least 4 positions. 3 to make a non-line shape and 1 to close the shape (duplicate of first)",
+})
+    .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 any coordinate is (0, 0)
+    coords.forEach((coord, index) => {
+        if (coord[0] === 0 && coord[1] === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Coordinate at index ${index} should not be (0, 0). This is likely not a valid coordinate.`,
+            });
+        }
+    });
+    // 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({
+                code: z.ZodIssueCode.custom,
+                message: `Consecutive coordinates at index ${i - 1} and ${i} should not be identical.`,
+            });
+        }
+    }
+});
+/**
+ * Polygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+const geoJsonPolygonSchema = z.strictObject({
+    type: z.literal("Polygon"),
+    coordinates: z.array(geoJsonLinearRingSchema),
+});
+/**
+ * MultiPolygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.7
+ */
+const geoJsonMultiPolygonSchema = z.strictObject({
+    type: z.literal("MultiPolygon"),
+    coordinates: z.array(z.array(geoJsonLinearRingSchema)),
+});
+// The same for Geometry, GeometryCollection, GeoJsonProperties, Feature, FeatureCollection, etc.
+const geoJsonGeometrySchema = z.union([
+    geoJsonPointSchema,
+    geoJsonMultiPointSchema,
+    geoJsonLineStringSchema,
+    geoJsonMultiLineStringSchema,
+    geoJsonPolygonSchema,
+    geoJsonMultiPolygonSchema,
+]);
+//* -------- Bbox -------- *//
+/**
+ * 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]
+ */
+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.",
+});
+//* -------- Extras -------- *//
+/**
+ * Polygon geometry object that explicitly disallows holes.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+const geoJsonPolygonNoHolesSchema = z.strictObject({
+    type: z.literal("Polygon"),
+    //uses tuple instead of array to enforce only 1 linear ring aka the polygon itself
+    coordinates: z.tuple([geoJsonLinearRingSchema]),
+});
+/**
+ * A Polygon with exactly 5 points and 4 horizontal/vertical sides that form a normal rectangular box.
+ */
+const geoJsonRectangularBoxPolygonSchema = z
+    .strictObject({
+    type: z.literal("Polygon"),
+    coordinates: z.array(geoJsonLinearRingSchema),
+})
+    .superRefine((data, ctx) => {
+    const coordinates = data.coordinates[0];
+    // Validate polygon has exactly 5 points
+    if ((coordinates === null || coordinates === void 0 ? void 0 : coordinates.length) !== 5) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Polygon must have exactly 5 coordinates to form a closed box.",
+        });
+        return;
+    }
+    // Check each side is either horizontal or vertical
+    for (let i = 0; i < 4; i++) {
+        const point1 = coordinates[i];
+        const point2 = coordinates[i + 1];
+        if (!point1 || !point2) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Each coordinate must be a defined point.",
+            });
+            return;
+        }
+        const [x1, y1] = point1;
+        const [x2, y2] = point2;
+        // Ensure each line segment is either horizontal or vertical
+        if (x1 !== x2 && y1 !== y2) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Polygon sides must be horizontal or vertical to form a box shape.",
+            });
+            return;
+        }
+    }
+});
+
+const EARTH_RADIUS = 6378137; // Earth’s mean radius in meters
 /**
  * @description Extracts a point coordinate from a GeoJSON object.
  * @param geoObject A GeoJSON object.
@@ -457,6 +633,93 @@ const getMultipleCoordinatesFromGeoJsonObject = (geoObject) => {
         throw new Error(`Unable to extract point coordinate from ${JSON.stringify(geoObject)}`);
     }
 };
+/**
+ * @description Creates a polygon from a bounding box.
+ */
+const getPolygonFromBbox = (bbox) => {
+    const [minLon, minLat, maxLon, maxLat] = bbox;
+    return {
+        type: "Polygon",
+        coordinates: [
+            [
+                [minLon, minLat],
+                [maxLon, minLat],
+                [maxLon, maxLat],
+                [minLon, maxLat],
+                [minLon, minLat],
+            ],
+        ],
+    };
+};
+/**
+ * @description Creates a round polygon from a point and a radius.
+ */
+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 angleStep = (2 * Math.PI) / pointsCount;
+    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);
+        coordinates.push([newLon, newLat]);
+    }
+    return {
+        type: "Polygon",
+        coordinates: [coordinates],
+    };
+};
+/**
+ * @description Creates a TU bounding box from a GeoJson Polygon.
+ */
+const getBoundingBoxFromGeoJsonPolygon = (polygon) => {
+    const points = polygon.coordinates[0];
+    const latitudes = points === null || points === void 0 ? void 0 : points.map(point => point[1]);
+    const longitudes = points === null || points === void 0 ? void 0 : points.map(point => point[0]);
+    if (!latitudes || !longitudes) {
+        return undefined;
+    }
+    return {
+        nw: {
+            latitude: Math.max(...latitudes),
+            longitude: Math.min(...longitudes),
+        },
+        se: {
+            latitude: Math.min(...latitudes),
+            longitude: Math.max(...longitudes),
+        },
+    };
+};
+/**
+ * @description Creates a GeoJSON Polygon from a TU bounding box.
+ */
+const getGeoJsonPolygonFromBoundingBox = (boundingBox) => {
+    const { nw, se } = boundingBox;
+    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
+            ],
+        ],
+    };
+};
+/**
+ * @description Creates TU point coordinate from a GeoJSON Point.
+ */
+const getPointCoordinateFromGeoJsonPoint = (point) => {
+    return { latitude: point.coordinates[1], longitude: point.coordinates[0] };
+};
 
 /**
  * Group an array of items by a key.
@@ -1104,4 +1367,4 @@ const uuidv4 = () => {
  */
 const uuidv5 = (name, namespace) => v5(name, namespace);
 
-export { DateTimeFormat, HoursAndMinutesFormat, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, capitalize, convertBlobToBase64, convertMetersToYards, convertYardsToMeters, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, filterByMultiple, formatAddress, formatCoordinates, fuzzySearch, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getISOStringFromDate, getMultipleCoordinatesFromGeoJsonObject, getPointCoordinateFromGeoJsonObject, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isSorted, isUUID, isValidImage, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, pick, removeLeftPadding, resizeBlob, resizeImage, size, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, titleCase, toID, toIDs, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5 };
+export { DateTimeFormat, EARTH_RADIUS, HoursAndMinutesFormat, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, capitalize, convertBlobToBase64, convertMetersToYards, convertYardsToMeters, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, filterByMultiple, formatAddress, formatCoordinates, fuzzySearch, geoJsonBboxSchema, geoJsonGeometrySchema, geoJsonLineStringSchema, geoJsonLinearRingSchema, geoJsonMultiLineStringSchema, geoJsonMultiPointSchema, geoJsonMultiPolygonSchema, geoJsonPointSchema, geoJsonPolygonNoHolesSchema, geoJsonPolygonSchema, geoJsonPositionSchema, geoJsonRectangularBoxPolygonSchema, getBoundingBoxFromGeoJsonPolygon, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getGeoJsonPolygonFromBoundingBox, getISOStringFromDate, getMultipleCoordinatesFromGeoJsonObject, getPointCoordinateFromGeoJsonObject, getPointCoordinateFromGeoJsonPoint, getPolygonFromBbox, getPolygonFromPointAndRadius, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isSorted, isUUID, isValidImage, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, pick, removeLeftPadding, resizeBlob, resizeImage, size, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, titleCase, toID, toIDs, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5 };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@trackunit/shared-utils",
-  "version": "0.0.82-alpha-c6639d22933.0",
+  "version": "0.0.83",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=20.x"
   },
   "dependencies": {
-    "uuid": "^10.0.0"
+    "uuid": "^10.0.0",
+    "zod": "3.22.4"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/GeoJson/GeoJsonSchemas.d.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+/**
+ * A Position is an array of coordinates. [x, y]
+ * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ */
+export declare const geoJsonPositionSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+export type GeoJsonPosition = z.infer<typeof geoJsonPositionSchema>;
+/**
+ * Point geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.2
+ */
+export declare const geoJsonPointSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Point">;
+    coordinates: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, "strict", z.ZodTypeAny, {
+    type: "Point";
+    coordinates: [number, number];
+}, {
+    type: "Point";
+    coordinates: [number, number];
+}>;
+export type GeoJsonPoint = z.infer<typeof geoJsonPointSchema>;
+/**
+ * MultiPoint geometry object.
+ *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ */
+export declare const geoJsonMultiPointSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MultiPoint">;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiPoint";
+    coordinates: [number, number][];
+}, {
+    type: "MultiPoint";
+    coordinates: [number, number][];
+}>;
+export type GeoJsonMultiPoint = z.infer<typeof geoJsonMultiPointSchema>;
+/**
+ * LineString geometry object.
+ * Minimum length of 2 positions.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.4
+ */
+export declare const geoJsonLineStringSchema: z.ZodObject<{
+    type: z.ZodLiteral<"LineString">;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "LineString";
+    coordinates: [number, number][];
+}, {
+    type: "LineString";
+    coordinates: [number, number][];
+}>;
+export type GeoJsonLineString = z.infer<typeof geoJsonLineStringSchema>;
+/**
+ * MultiLineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.5
+ */
+export declare const geoJsonMultiLineStringSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MultiLineString">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiLineString";
+    coordinates: [number, number][][];
+}, {
+    type: "MultiLineString";
+    coordinates: [number, number][][];
+}>;
+export type GeoJsonMultiLineString = z.infer<typeof geoJsonMultiLineStringSchema>;
+/**
+ * Helper type for reuse across polygon schemas.
+ *
+ * - A linear ring is a closed LineString with four or more positions.
+ * - The first and last positions are equivalent, and they MUST contain
+      identical values; their representation SHOULD also be identical
+ * - A linear ring is the boundary of a surface or the boundary of a
+      hole in a surface
+ * - A linear ring MUST follow the right-hand rule with respect to the
+      area it bounds, i.e., exterior rings are counterclockwise, and
+      holes are clockwise
+ */
+export declare const geoJsonLinearRingSchema: z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>;
+export type GeoJsonLinearRing = z.infer<typeof geoJsonLinearRingSchema>;
+/**
+ * Polygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+export declare const geoJsonPolygonSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodArray<z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}>;
+export type GeoJsonPolygon = z.infer<typeof geoJsonPolygonSchema>;
+/**
+ * MultiPolygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.7
+ */
+export declare const geoJsonMultiPolygonSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MultiPolygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>, "many">, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiPolygon";
+    coordinates: [number, number][][][];
+}, {
+    type: "MultiPolygon";
+    coordinates: [number, number][][][];
+}>;
+export type GeoJsonMultiPolygon = z.infer<typeof geoJsonMultiPolygonSchema>;
+export declare const geoJsonGeometrySchema: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"Point">;
+    coordinates: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, "strict", z.ZodTypeAny, {
+    type: "Point";
+    coordinates: [number, number];
+}, {
+    type: "Point";
+    coordinates: [number, number];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"MultiPoint">;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiPoint";
+    coordinates: [number, number][];
+}, {
+    type: "MultiPoint";
+    coordinates: [number, number][];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"LineString">;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "LineString";
+    coordinates: [number, number][];
+}, {
+    type: "LineString";
+    coordinates: [number, number][];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"MultiLineString">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiLineString";
+    coordinates: [number, number][][];
+}, {
+    type: "MultiLineString";
+    coordinates: [number, number][][];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodArray<z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"MultiPolygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>, "many">, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "MultiPolygon";
+    coordinates: [number, number][][][];
+}, {
+    type: "MultiPolygon";
+    coordinates: [number, number][][][];
+}>]>;
+export type GeoJsonGeometry = z.infer<typeof geoJsonGeometrySchema>;
+/**
+ * 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]
+ */
+export declare const geoJsonBboxSchema: z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, [number, number, number, number], [number, number, number, number]>;
+export type GeoJsonBbox = z.infer<typeof geoJsonBboxSchema>;
+/**
+ * Polygon geometry object that explicitly disallows holes.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+export declare const geoJsonPolygonNoHolesSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodTuple<[z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>], null>;
+}, "strict", z.ZodTypeAny, {
+    type: "Polygon";
+    coordinates: [[number, number][]];
+}, {
+    type: "Polygon";
+    coordinates: [[number, number][]];
+}>;
+export type GeoJsonPolygonNoHoles = z.infer<typeof geoJsonPolygonNoHolesSchema>;
+/**
+ * A Polygon with exactly 5 points and 4 horizontal/vertical sides that form a normal rectangular box.
+ */
+export declare const geoJsonRectangularBoxPolygonSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodArray<z.ZodEffects<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">, [number, number][], [number, number][]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}>, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}, {
+    type: "Polygon";
+    coordinates: [number, number][][];
+}>;

package/src/GeoJson/GeoJsonUtils.d.ts

@@ -0,0 +1,52 @@
+import { GeoJsonBbox, GeoJsonPoint, GeoJsonPolygon } from "./GeoJsonSchemas";
+export declare const EARTH_RADIUS = 6378137;
+interface PointCoordinate {
+    longitude: number;
+    latitude: number;
+}
+interface BoundingBox {
+    nw: PointCoordinate;
+    se: PointCoordinate;
+}
+interface GeoJSONGeometry {
+    type?: unknown;
+    coordinates?: number[] | number[][] | number[][][] | null;
+}
+interface GeoJsonFeature {
+    type?: unknown;
+    geometry?: GeoJSONGeometry | null;
+}
+/**
+ * @description Extracts a point coordinate from a GeoJSON object.
+ * @param geoObject A GeoJSON object.
+ * @returns {PointCoordinate} A point coordinate.
+ */
+export declare const getPointCoordinateFromGeoJsonObject: (geoObject: GeoJsonFeature | GeoJSONGeometry | undefined | null) => PointCoordinate | undefined;
+/**
+ * @description Extracts multiple point coordinates from a GeoJSON object.
+ * @param geoObject A GeoJSON object.
+ * @returns {PointCoordinate[]} An array of point coordinates.
+ * @example getMultipleCoordinatesFromGeoJsonObject({ type: "Point", coordinates: [1, 2] }) // [{ longitude: 1, latitude: 2 }]
+ */
+export declare const getMultipleCoordinatesFromGeoJsonObject: (geoObject: GeoJsonFeature | GeoJSONGeometry | undefined | null) => PointCoordinate[] | undefined;
+/**
+ * @description Creates a polygon from a bounding box.
+ */
+export declare const getPolygonFromBbox: (bbox: GeoJsonBbox) => GeoJsonPolygon;
+/**
+ * @description Creates a round polygon from a point and a radius.
+ */
+export declare const getPolygonFromPointAndRadius: (point: GeoJsonPoint, radius: number) => GeoJsonPolygon;
+/**
+ * @description Creates a TU bounding box from a GeoJson Polygon.
+ */
+export declare const getBoundingBoxFromGeoJsonPolygon: (polygon: GeoJsonPolygon) => BoundingBox | undefined;
+/**
+ * @description Creates a GeoJSON Polygon from a TU bounding box.
+ */
+export declare const getGeoJsonPolygonFromBoundingBox: (boundingBox: BoundingBox) => GeoJsonPolygon;
+/**
+ * @description Creates TU point coordinate from a GeoJSON Point.
+ */
+export declare const getPointCoordinateFromGeoJsonPoint: (point: GeoJsonPoint) => PointCoordinate;
+export {};

package/src/index.d.ts

@@ -9,7 +9,8 @@ export * from "./enumUtils";
 export * from "./exhaustiveCheck";
 export * from "./fastArrayOperations";
 export * from "./filter";
-export * from "./GeoJsonUtils";
+export * from "./GeoJson/GeoJsonSchemas";
+export * from "./GeoJson/GeoJsonUtils";
 export * from "./groupBy/groupBy";
 export * from "./GroupingUtility";
 export * from "./idUtils";

package/src/GeoJsonUtils.d.ts

@@ -1,26 +0,0 @@
-interface PointCoordinate {
-    longitude: number;
-    latitude: number;
-}
-interface GeoJSONGeometry {
-    type?: unknown;
-    coordinates?: number[] | number[][] | null;
-}
-interface GeoJsonFeature {
-    type?: unknown;
-    geometry?: GeoJSONGeometry | null;
-}
-/**
- * @description Extracts a point coordinate from a GeoJSON object.
- * @param geoObject A GeoJSON object.
- * @returns {PointCoordinate} A point coordinate.
- */
-export declare const getPointCoordinateFromGeoJsonObject: (geoObject: GeoJsonFeature | GeoJSONGeometry | undefined | null) => PointCoordinate | undefined;
-/**
- * @description Extracts multiple point coordinates from a GeoJSON object.
- * @param geoObject A GeoJSON object.
- * @returns {PointCoordinate[]} An array of point coordinates.
- * @example getMultipleCoordinatesFromGeoJsonObject({ type: "Point", coordinates: [1, 2] }) // [{ longitude: 1, latitude: 2 }]
- */
-export declare const getMultipleCoordinatesFromGeoJsonObject: (geoObject: GeoJsonFeature | GeoJSONGeometry | undefined | null) => PointCoordinate[] | undefined;
-export {};