@trackunit/shared-utils 1.9.122 → 1.10.1

package/index.cjs.js

@@ -1357,33 +1357,131 @@ const uuidv4 = () => {
  */
 const uuidv5 = (name, namespace) => uuid.v5(name, namespace);
 
+const METERS_PER_YARD = 0.9144; // 1 yard = 0.9144 meters
+const METERS_PER_KILOMETER = 1000; // 1 kilometer = 1000 meters
+const YARDS_PER_METER = 1.09361; // 1 meter = 1.09361 yards
+const YARDS_PER_MILE = 1760; // 1 mile = 1760 yards
+const UnitsOfMeasurementSI = {
+    METERS: "METERS",
+    KILOMETERS: "KILOMETERS",
+};
+const UnitsOfMeasurementUSCustomary = {
+    YARDS: "YARDS",
+    MILES: "MILES",
+};
 /**
  * Converts meters to yards
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+const convertMetersToYards = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value * YARDS_PER_METER) : value * YARDS_PER_METER;
+};
+/**
+ * Converts meters to kilometers
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-const convertMetersToYards = (value) => {
+const convertMetersToKilometers = (value, shouldRound = true) => {
     if (isNaN(value)) {
         return;
     }
-    return Math.round(value * 1.09361);
+    return shouldRound ? Math.round(value / METERS_PER_KILOMETER) : value / METERS_PER_KILOMETER;
 };
 /**
  * Converts yards to meters
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+const convertYardsToMeters = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value * METERS_PER_YARD) : value * METERS_PER_YARD;
+};
+/**
+ * Converts yards to miles
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-const convertYardsToMeters = (value) => {
+const convertYardsToMiles = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value / YARDS_PER_MILE) : value / YARDS_PER_MILE;
+};
+/**
+ * Returns a human readable distance in either meters or kilometers
+ *
+ * - less than 1km -> meters rounded to the nearest integer
+ * - less than 100km -> kilometers rounded to 1 decimal
+ * - greater than 100km -> kilometers rounded to the nearest integer
+ *
+ * @param value The distance in meters
+ * @returns {{distance: number; unit: UnitsOfMeasurementSIType} | undefined} The formatted distance
+ */
+const formatSiDistance = (value) => {
+    if (isNaN(value)) {
+        return;
+    }
+    if (value < METERS_PER_KILOMETER) {
+        return { distance: Math.round(value), unit: UnitsOfMeasurementSI.METERS };
+    }
+    else {
+        const kilometers = convertMetersToKilometers(value, false);
+        if (kilometers === undefined) {
+            return;
+        }
+        return {
+            distance: kilometers < 100 ? Number(kilometers.toFixed(1)) : Math.round(kilometers),
+            unit: UnitsOfMeasurementSI.KILOMETERS,
+        };
+    }
+};
+/**
+ * Returns a human readable distance in either yards or miles
+ *
+ * - less than 1 mile -> yards rounded to the nearest integer
+ * - less than 100 miles -> miles rounded to 1 decimal
+ * - greater than 100 miles -> miles rounded to the nearest integer
+ *
+ * @param value The distance in yards
+ * @returns {{distance: number; unit: UnitsOfMeasurementUSCustomaryType} | undefined} The formatted distance
+ */
+const formatUsCustomaryDistance = (value) => {
     if (isNaN(value)) {
         return;
     }
-    return Math.round(value * 0.9144);
+    if (value < YARDS_PER_MILE) {
+        return { distance: Math.round(value), unit: UnitsOfMeasurementUSCustomary.YARDS };
+    }
+    else {
+        const miles = convertYardsToMiles(value, false);
+        if (miles === undefined) {
+            return;
+        }
+        return {
+            distance: miles < 100 ? Number(miles.toFixed(1)) : Math.round(miles),
+            unit: UnitsOfMeasurementUSCustomary.MILES,
+        };
+    }
 };
 
 exports.DateTimeFormat = DateTimeFormat;
 exports.HoursAndMinutesFormat = HoursAndMinutesFormat;
+exports.UnitsOfMeasurementSI = UnitsOfMeasurementSI;
+exports.UnitsOfMeasurementUSCustomary = UnitsOfMeasurementUSCustomary;
 exports.align = align;
 exports.alphabeticallySort = alphabeticallySort;
 exports.arrayLengthCompare = arrayLengthCompare;
@@ -1393,8 +1491,10 @@ exports.calculateImageScaleRatio = calculateImageScaleRatio;
 exports.capitalize = capitalize;
 exports.colorsFromStyleDeclaration = colorsFromStyleDeclaration;
 exports.convertBlobToBase64 = convertBlobToBase64;
+exports.convertMetersToKilometers = convertMetersToKilometers;
 exports.convertMetersToYards = convertMetersToYards;
 exports.convertYardsToMeters = convertYardsToMeters;
+exports.convertYardsToMiles = convertYardsToMiles;
 exports.dateCompare = dateCompare;
 exports.deleteUndefinedKeys = deleteUndefinedKeys;
 exports.difference = difference;
@@ -1407,6 +1507,8 @@ exports.fetchImageAsBase64 = fetchImageAsBase64;
 exports.filterByMultiple = filterByMultiple;
 exports.formatAddress = formatAddress;
 exports.formatCoordinates = formatCoordinates;
+exports.formatSiDistance = formatSiDistance;
+exports.formatUsCustomaryDistance = formatUsCustomaryDistance;
 exports.fuzzySearch = fuzzySearch;
 exports.getAllColors = getAllColors;
 exports.getDifferenceBetweenDates = getDifferenceBetweenDates;

package/index.esm.js

@@ -1355,29 +1355,125 @@ const uuidv4 = () => {
  */
 const uuidv5 = (name, namespace) => v5(name, namespace);
 
+const METERS_PER_YARD = 0.9144; // 1 yard = 0.9144 meters
+const METERS_PER_KILOMETER = 1000; // 1 kilometer = 1000 meters
+const YARDS_PER_METER = 1.09361; // 1 meter = 1.09361 yards
+const YARDS_PER_MILE = 1760; // 1 mile = 1760 yards
+const UnitsOfMeasurementSI = {
+    METERS: "METERS",
+    KILOMETERS: "KILOMETERS",
+};
+const UnitsOfMeasurementUSCustomary = {
+    YARDS: "YARDS",
+    MILES: "MILES",
+};
 /**
  * Converts meters to yards
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+const convertMetersToYards = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value * YARDS_PER_METER) : value * YARDS_PER_METER;
+};
+/**
+ * Converts meters to kilometers
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-const convertMetersToYards = (value) => {
+const convertMetersToKilometers = (value, shouldRound = true) => {
     if (isNaN(value)) {
         return;
     }
-    return Math.round(value * 1.09361);
+    return shouldRound ? Math.round(value / METERS_PER_KILOMETER) : value / METERS_PER_KILOMETER;
 };
 /**
  * Converts yards to meters
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+const convertYardsToMeters = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value * METERS_PER_YARD) : value * METERS_PER_YARD;
+};
+/**
+ * Converts yards to miles
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-const convertYardsToMeters = (value) => {
+const convertYardsToMiles = (value, shouldRound = true) => {
+    if (isNaN(value)) {
+        return;
+    }
+    return shouldRound ? Math.round(value / YARDS_PER_MILE) : value / YARDS_PER_MILE;
+};
+/**
+ * Returns a human readable distance in either meters or kilometers
+ *
+ * - less than 1km -> meters rounded to the nearest integer
+ * - less than 100km -> kilometers rounded to 1 decimal
+ * - greater than 100km -> kilometers rounded to the nearest integer
+ *
+ * @param value The distance in meters
+ * @returns {{distance: number; unit: UnitsOfMeasurementSIType} | undefined} The formatted distance
+ */
+const formatSiDistance = (value) => {
+    if (isNaN(value)) {
+        return;
+    }
+    if (value < METERS_PER_KILOMETER) {
+        return { distance: Math.round(value), unit: UnitsOfMeasurementSI.METERS };
+    }
+    else {
+        const kilometers = convertMetersToKilometers(value, false);
+        if (kilometers === undefined) {
+            return;
+        }
+        return {
+            distance: kilometers < 100 ? Number(kilometers.toFixed(1)) : Math.round(kilometers),
+            unit: UnitsOfMeasurementSI.KILOMETERS,
+        };
+    }
+};
+/**
+ * Returns a human readable distance in either yards or miles
+ *
+ * - less than 1 mile -> yards rounded to the nearest integer
+ * - less than 100 miles -> miles rounded to 1 decimal
+ * - greater than 100 miles -> miles rounded to the nearest integer
+ *
+ * @param value The distance in yards
+ * @returns {{distance: number; unit: UnitsOfMeasurementUSCustomaryType} | undefined} The formatted distance
+ */
+const formatUsCustomaryDistance = (value) => {
     if (isNaN(value)) {
         return;
     }
-    return Math.round(value * 0.9144);
+    if (value < YARDS_PER_MILE) {
+        return { distance: Math.round(value), unit: UnitsOfMeasurementUSCustomary.YARDS };
+    }
+    else {
+        const miles = convertYardsToMiles(value, false);
+        if (miles === undefined) {
+            return;
+        }
+        return {
+            distance: miles < 100 ? Number(miles.toFixed(1)) : Math.round(miles),
+            unit: UnitsOfMeasurementUSCustomary.MILES,
+        };
+    }
 };
 
-export { DateTimeFormat, HoursAndMinutesFormat, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, calculateImageScaleRatio, capitalize, colorsFromStyleDeclaration, convertBlobToBase64, convertMetersToYards, convertYardsToMeters, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, fetchImageAsBase64, filterByMultiple, formatAddress, formatCoordinates, fuzzySearch, getAllColors, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getISOStringFromDate, getMimeTypeFromDataURL, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isSorted, isUUID, isValidImage, loadSVGDimensions, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, pick, preload, removeLeftPadding, removeProperties, removeProperty, replaceNullableNumbersWithZero, resizeBlob, resizeImage, rgb2hex, size, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, svgToPNG, titleCase, toID, toIDs, toPNG, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5 };
+export { DateTimeFormat, HoursAndMinutesFormat, UnitsOfMeasurementSI, UnitsOfMeasurementUSCustomary, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, calculateImageScaleRatio, capitalize, colorsFromStyleDeclaration, convertBlobToBase64, convertMetersToKilometers, convertMetersToYards, convertYardsToMeters, convertYardsToMiles, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, fetchImageAsBase64, filterByMultiple, formatAddress, formatCoordinates, formatSiDistance, formatUsCustomaryDistance, fuzzySearch, getAllColors, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getISOStringFromDate, getMimeTypeFromDataURL, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isSorted, isUUID, isValidImage, loadSVGDimensions, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, pick, preload, removeLeftPadding, removeProperties, removeProperty, replaceNullableNumbersWithZero, resizeBlob, resizeImage, rgb2hex, size, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, svgToPNG, titleCase, toID, toIDs, toPNG, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/shared-utils",
-  "version": "1.9.122",
+  "version": "1.10.1",
   "repository": "https://github.com/Trackunit/manager",
   "engines": {
     "node": ">=24.x"

package/src/UnitOfMeasurementConverter.d.ts

@@ -1,14 +1,70 @@
+export declare const UnitsOfMeasurementSI: {
+    readonly METERS: "METERS";
+    readonly KILOMETERS: "KILOMETERS";
+};
+export declare const UnitsOfMeasurementUSCustomary: {
+    readonly YARDS: "YARDS";
+    readonly MILES: "MILES";
+};
+export type UnitsOfMeasurementSIType = (typeof UnitsOfMeasurementSI)[keyof typeof UnitsOfMeasurementSI];
+export type UnitsOfMeasurementUSCustomaryType = (typeof UnitsOfMeasurementUSCustomary)[keyof typeof UnitsOfMeasurementUSCustomary];
 /**
  * Converts meters to yards
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-export declare const convertMetersToYards: (value: number) => number | undefined;
+export declare const convertMetersToYards: (value: number, shouldRound?: boolean) => number | undefined;
+/**
+ * Converts meters to kilometers
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+export declare const convertMetersToKilometers: (value: number, shouldRound?: boolean) => number | undefined;
 /**
  * Converts yards to meters
  *
  * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
+ * @returns {number | undefined} The converted value
+ */
+export declare const convertYardsToMeters: (value: number, shouldRound?: boolean) => number | undefined;
+/**
+ * Converts yards to miles
+ *
+ * @param value The value to convert
+ * @param shouldRound Whether to round the result to the nearest integer (default: true)
  * @returns {number | undefined} The converted value
  */
-export declare const convertYardsToMeters: (value: number) => number | undefined;
+export declare const convertYardsToMiles: (value: number, shouldRound?: boolean) => number | undefined;
+/**
+ * Returns a human readable distance in either meters or kilometers
+ *
+ * - less than 1km -> meters rounded to the nearest integer
+ * - less than 100km -> kilometers rounded to 1 decimal
+ * - greater than 100km -> kilometers rounded to the nearest integer
+ *
+ * @param value The distance in meters
+ * @returns {{distance: number; unit: UnitsOfMeasurementSIType} | undefined} The formatted distance
+ */
+export declare const formatSiDistance: (value: number) => {
+    distance: number;
+    unit: UnitsOfMeasurementSIType;
+} | undefined;
+/**
+ * Returns a human readable distance in either yards or miles
+ *
+ * - less than 1 mile -> yards rounded to the nearest integer
+ * - less than 100 miles -> miles rounded to 1 decimal
+ * - greater than 100 miles -> miles rounded to the nearest integer
+ *
+ * @param value The distance in yards
+ * @returns {{distance: number; unit: UnitsOfMeasurementUSCustomaryType} | undefined} The formatted distance
+ */
+export declare const formatUsCustomaryDistance: (value: number) => {
+    distance: number;
+    unit: UnitsOfMeasurementUSCustomaryType;
+} | undefined;