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

/**
 * @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';
}