Initial Commit

backend/src/shared-minimal/utils/units.ts

@@ -0,0 +1,175 @@
+/**
+ * @ai-summary Unit conversion utilities for Imperial/Metric support
+ * @ai-context Pure functions for converting between unit systems
+ */
+
+export type UnitSystem = 'imperial' | 'metric';
+export type DistanceUnit = 'miles' | 'km';
+export type VolumeUnit = 'gallons' | 'liters';
+export type FuelEfficiencyUnit = 'mpg' | 'l100km';
+
+// Conversion constants
+const MILES_TO_KM = 1.60934;
+const KM_TO_MILES = 0.621371;
+const GALLONS_TO_LITERS = 3.78541;
+const LITERS_TO_GALLONS = 0.264172;
+const MPG_TO_L100KM_FACTOR = 235.214; // Conversion factor for MPG ↔ L/100km
+
+// Distance Conversions
+export function convertDistance(value: number, fromUnit: DistanceUnit, toUnit: DistanceUnit): number {
+  if (fromUnit === toUnit) return value;
+  
+  if (fromUnit === 'miles' && toUnit === 'km') {
+    return value * MILES_TO_KM;
+  }
+  
+  if (fromUnit === 'km' && toUnit === 'miles') {
+    return value * KM_TO_MILES;
+  }
+  
+  return value;
+}
+
+export function convertDistanceBySystem(miles: number, toSystem: UnitSystem): number {
+  if (toSystem === 'metric') {
+    return convertDistance(miles, 'miles', 'km');
+  }
+  return miles;
+}
+
+// Volume Conversions
+export function convertVolume(value: number, fromUnit: VolumeUnit, toUnit: VolumeUnit): number {
+  if (fromUnit === toUnit) return value;
+  
+  if (fromUnit === 'gallons' && toUnit === 'liters') {
+    return value * GALLONS_TO_LITERS;
+  }
+  
+  if (fromUnit === 'liters' && toUnit === 'gallons') {
+    return value * LITERS_TO_GALLONS;
+  }
+  
+  return value;
+}
+
+export function convertVolumeBySystem(gallons: number, toSystem: UnitSystem): number {
+  if (toSystem === 'metric') {
+    return convertVolume(gallons, 'gallons', 'liters');
+  }
+  return gallons;
+}
+
+// Fuel Efficiency Conversions
+export function convertFuelEfficiency(value: number, fromUnit: FuelEfficiencyUnit, toUnit: FuelEfficiencyUnit): number {
+  if (fromUnit === toUnit) return value;
+  
+  if (fromUnit === 'mpg' && toUnit === 'l100km') {
+    return value === 0 ? 0 : MPG_TO_L100KM_FACTOR / value;
+  }
+  
+  if (fromUnit === 'l100km' && toUnit === 'mpg') {
+    return value === 0 ? 0 : MPG_TO_L100KM_FACTOR / value;
+  }
+  
+  return value;
+}
+
+export function convertFuelEfficiencyBySystem(mpg: number, toSystem: UnitSystem): number {
+  if (toSystem === 'metric') {
+    return convertFuelEfficiency(mpg, 'mpg', 'l100km');
+  }
+  return mpg;
+}
+
+// Display Formatting Functions
+export function formatDistance(value: number, unit: DistanceUnit, precision = 1): string {
+  const rounded = parseFloat(value.toFixed(precision));
+  
+  if (unit === 'miles') {
+    return `${rounded.toLocaleString()} miles`;
+  } else {
+    return `${rounded.toLocaleString()} km`;
+  }
+}
+
+export function formatVolume(value: number, unit: VolumeUnit, precision = 2): string {
+  const rounded = parseFloat(value.toFixed(precision));
+  
+  if (unit === 'gallons') {
+    return `${rounded} gal`;
+  } else {
+    return `${rounded} L`;
+  }
+}
+
+export function formatFuelEfficiency(value: number, unit: FuelEfficiencyUnit, precision = 1): string {
+  const rounded = parseFloat(value.toFixed(precision));
+  
+  if (unit === 'mpg') {
+    return `${rounded} MPG`;
+  } else {
+    return `${rounded} L/100km`;
+  }
+}
+
+export function formatPrice(value: number, unit: VolumeUnit, currency = 'USD', precision = 3): string {
+  const rounded = parseFloat(value.toFixed(precision));
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: precision,
+    maximumFractionDigits: precision,
+  });
+  
+  if (unit === 'gallons') {
+    return `${formatter.format(rounded)}/gal`;
+  } else {
+    return `${formatter.format(rounded)}/L`;
+  }
+}
+
+// System-based formatting (convenience functions)
+export function formatDistanceBySystem(miles: number, system: UnitSystem, precision = 1): string {
+  if (system === 'metric') {
+    const km = convertDistanceBySystem(miles, system);
+    return formatDistance(km, 'km', precision);
+  }
+  return formatDistance(miles, 'miles', precision);
+}
+
+export function formatVolumeBySystem(gallons: number, system: UnitSystem, precision = 2): string {
+  if (system === 'metric') {
+    const liters = convertVolumeBySystem(gallons, system);
+    return formatVolume(liters, 'liters', precision);
+  }
+  return formatVolume(gallons, 'gallons', precision);
+}
+
+export function formatFuelEfficiencyBySystem(mpg: number, system: UnitSystem, precision = 1): string {
+  if (system === 'metric') {
+    const l100km = convertFuelEfficiencyBySystem(mpg, system);
+    return formatFuelEfficiency(l100km, 'l100km', precision);
+  }
+  return formatFuelEfficiency(mpg, 'mpg', precision);
+}
+
+export function formatPriceBySystem(pricePerGallon: number, system: UnitSystem, currency = 'USD', precision = 3): string {
+  if (system === 'metric') {
+    const pricePerLiter = pricePerGallon * LITERS_TO_GALLONS;
+    return formatPrice(pricePerLiter, 'liters', currency, precision);
+  }
+  return formatPrice(pricePerGallon, 'gallons', currency, precision);
+}
+
+// Unit system helpers
+export function getDistanceUnit(system: UnitSystem): DistanceUnit {
+  return system === 'metric' ? 'km' : 'miles';
+}
+
+export function getVolumeUnit(system: UnitSystem): VolumeUnit {
+  return system === 'metric' ? 'liters' : 'gallons';
+}
+
+export function getFuelEfficiencyUnit(system: UnitSystem): FuelEfficiencyUnit {
+  return system === 'metric' ? 'l100km' : 'mpg';
+}