@jjlmoya/utils-motor 1.4.0 → 1.5.0

package/src/tool/evChargingTimeCostPlanner/logic.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { CHARGING_PRESETS, calculateChargingPlan } from './logic';
+import { evaluateChargingStatus } from './evaluator';
+
+describe('EV charging planner', () => {
+  it('calculates battery energy, grid energy, time, cost, losses, and range', () => {
+    const plan = calculateChargingPlan(CHARGING_PRESETS[0]!.inputs);
+
+    expect(plan.chargeFraction).toBeCloseTo(0.48);
+    expect(plan.batteryEnergyKwh).toBeCloseTo(28.8);
+    expect(plan.gridEnergyKwh).toBeCloseTo(32);
+    expect(plan.lossEnergyKwh).toBeCloseTo(3.2);
+    expect(plan.timeMinutes).toBe(260);
+    expect(plan.cost).toBeCloseTo(8);
+    expect(plan.recoveredRangeKm).toBeCloseTo(160);
+    expect(evaluateChargingStatus(plan)).toBe('long');
+  });
+
+  it('returns no charge when the target is below the starting level', () => {
+    const plan = calculateChargingPlan({ ...CHARGING_PRESETS[0]!.inputs, startSoc: 80, endSoc: 40 });
+
+    expect(plan.chargeFraction).toBe(0);
+    expect(plan.timeMinutes).toBe(0);
+    expect(plan.cost).toBe(0);
+    expect(evaluateChargingStatus(plan)).toBe('empty');
+  });
+
+  it('calculates the recovered range from the exact charge window', () => {
+    const plan = calculateChargingPlan({ ...CHARGING_PRESETS[1]!.inputs, endSoc: 90 });
+
+    expect(plan.batteryEnergyKwh).toBeCloseTo(34.8);
+    expect(plan.gridEnergyKwh).toBeCloseTo(37.8261, 3);
+    expect(plan.recoveredRangeKm).toBeCloseTo(193.3333, 3);
+  });
+
+  it('clamps invalid values to safe calculation bounds', () => {
+    const plan = calculateChargingPlan({
+      capacityKwh: Number.NaN,
+      startSoc: -10,
+      endSoc: 140,
+      chargerPowerKw: 0,
+      efficiency: 0,
+      pricePerKwh: -1,
+      consumptionKwhPer100Km: 0,
+      currency: 'USD',
+    });
+
+    expect(plan.batteryEnergyKwh).toBe(60);
+    expect(plan.gridEnergyKwh).toBe(120);
+    expect(plan.timeMinutes).toBe(72000);
+    expect(plan.cost).toBe(0);
+    expect(plan.recoveredRangeKm).toBe(6000);
+  });
+
+  it('converts the same tariff through the selected currency factor', () => {
+    const euroPlan = calculateChargingPlan({ ...CHARGING_PRESETS[0]!.inputs, currency: 'EUR' });
+    const dollarPlan = calculateChargingPlan({ ...CHARGING_PRESETS[0]!.inputs, currency: 'USD', pricePerKwh: 0.25 * 1.1643 });
+
+    expect(dollarPlan.exchangeFactor).toBeCloseTo(1.1643);
+    expect(dollarPlan.pricePerKwhEur).toBeCloseTo(0.25);
+    expect(dollarPlan.cost).toBeCloseTo(euroPlan.cost * 1.1643);
+  });
+
+  it('classifies short and standard charge windows', () => {
+    const shortPlan = calculateChargingPlan({ ...CHARGING_PRESETS[0]!.inputs, startSoc: 50, endSoc: 52, chargerPowerKw: 100 });
+    const standardPlan = calculateChargingPlan({ ...CHARGING_PRESETS[0]!.inputs, startSoc: 40, endSoc: 60, chargerPowerKw: 7.4 });
+
+    expect(evaluateChargingStatus(shortPlan)).toBe('short');
+    expect(evaluateChargingStatus(standardPlan)).toBe('standard');
+  });
+});

package/src/tool/evChargingTimeCostPlanner/logic.ts

@@ -0,0 +1,174 @@
+export interface CurrencyOption {
+  code: string;
+  symbol: string;
+  name: string;
+  unitsPerEur: number;
+}
+
+export const CURRENCY_OPTIONS = [
+  { code: 'EUR', symbol: '€', name: 'Euro', unitsPerEur: 1 },
+  { code: 'USD', symbol: '$', name: 'US dollar', unitsPerEur: 1.1643 },
+  { code: 'GBP', symbol: '£', name: 'Pound sterling', unitsPerEur: 0.8572 },
+  { code: 'JPY', symbol: '¥', name: 'Japanese yen', unitsPerEur: 185.92 },
+  { code: 'CNY', symbol: 'CN¥', name: 'Chinese yuan', unitsPerEur: 7.8251 },
+  { code: 'INR', symbol: '₹', name: 'Indian rupee', unitsPerEur: 111.0585 },
+  { code: 'BRL', symbol: 'R$', name: 'Brazilian real', unitsPerEur: 6.0126 },
+  { code: 'MXN', symbol: 'MX$', name: 'Mexican peso', unitsPerEur: 19.7327 },
+  { code: 'CAD', symbol: 'CA$', name: 'Canadian dollar', unitsPerEur: 1.613 },
+  { code: 'AUD', symbol: 'A$', name: 'Australian dollar', unitsPerEur: 1.6183 },
+  { code: 'CHF', symbol: 'CHF', name: 'Swiss franc', unitsPerEur: 0.9364 },
+  { code: 'SEK', symbol: 'kr', name: 'Swedish krona', unitsPerEur: 11.0885 },
+  { code: 'PLN', symbol: 'zł', name: 'Polish zloty', unitsPerEur: 4.3365 },
+  { code: 'TRY', symbol: '₺', name: 'Turkish lira', unitsPerEur: 56.1718 },
+  { code: 'KRW', symbol: '₩', name: 'South Korean won', unitsPerEur: 1600.39 },
+  { code: 'IDR', symbol: 'Rp', name: 'Indonesian rupiah', unitsPerEur: 20628.08 },
+] as const;
+
+export type CurrencyCode = typeof CURRENCY_OPTIONS[number]['code'];
+
+export const DEFAULT_CURRENCY: CurrencyCode = 'EUR';
+
+export function isCurrencyCode(value: unknown): value is CurrencyCode {
+  return typeof value === 'string' && CURRENCY_OPTIONS.some((option) => option.code === value);
+}
+
+export function getCurrencyOption(code: CurrencyCode): CurrencyOption {
+  return CURRENCY_OPTIONS.find((option) => option.code === code) ?? CURRENCY_OPTIONS[0]!;
+}
+
+export function convertCurrencyAmount(amount: number, from: CurrencyCode, to: CurrencyCode): number {
+  const fromFactor = getCurrencyOption(from).unitsPerEur;
+  const toFactor = getCurrencyOption(to).unitsPerEur;
+  return (amount / fromFactor) * toFactor;
+}
+
+export function getPriceInputStep(currency: CurrencyCode): number {
+  const factor = getCurrencyOption(currency).unitsPerEur;
+  if (factor >= 1000) return 10;
+  if (factor >= 100) return 1;
+  if (factor >= 10) return 0.1;
+  return 0.01;
+}
+
+export interface ChargingInputs {
+  capacityKwh: number;
+  startSoc: number;
+  endSoc: number;
+  chargerPowerKw: number;
+  efficiency: number;
+  pricePerKwh: number;
+  consumptionKwhPer100Km: number;
+  currency: CurrencyCode;
+}
+
+export interface ChargingPlan {
+  chargeFraction: number;
+  batteryEnergyKwh: number;
+  gridEnergyKwh: number;
+  lossEnergyKwh: number;
+  timeHours: number;
+  timeMinutes: number;
+  cost: number;
+  recoveredRangeKm: number;
+  currency: CurrencyCode;
+  exchangeFactor: number;
+  pricePerKwhEur: number;
+}
+
+export interface ChargingPreset {
+  id: 'home' | 'public' | 'fast';
+  inputs: ChargingInputs;
+}
+
+export const CHARGING_PRESETS: ChargingPreset[] = [
+  {
+    id: 'home',
+    inputs: {
+      capacityKwh: 60,
+      startSoc: 32,
+      endSoc: 80,
+      chargerPowerKw: 7.4,
+      efficiency: 0.9,
+      pricePerKwh: 0.25,
+      consumptionKwhPer100Km: 18,
+      currency: 'EUR',
+    },
+  },
+  {
+    id: 'public',
+    inputs: {
+      capacityKwh: 60,
+      startSoc: 32,
+      endSoc: 80,
+      chargerPowerKw: 11,
+      efficiency: 0.92,
+      pricePerKwh: 0.39,
+      consumptionKwhPer100Km: 18,
+      currency: 'EUR',
+    },
+  },
+  {
+    id: 'fast',
+    inputs: {
+      capacityKwh: 60,
+      startSoc: 32,
+      endSoc: 80,
+      chargerPowerKw: 100,
+      efficiency: 0.94,
+      pricePerKwh: 0.55,
+      consumptionKwhPer100Km: 18,
+      currency: 'EUR',
+    },
+  },
+];
+
+const finiteOr = (value: number, fallback: number): number => (
+  Number.isFinite(value) ? value : fallback
+);
+
+const clamp = (value: number, minimum: number, maximum: number): number => (
+  Math.min(maximum, Math.max(minimum, value))
+);
+
+const safeInputs = (inputs: ChargingInputs): ChargingInputs => ({
+  currency: isCurrencyCode(inputs.currency) ? inputs.currency : DEFAULT_CURRENCY,
+  capacityKwh: clamp(finiteOr(inputs.capacityKwh, 60), 1, 250),
+  startSoc: clamp(finiteOr(inputs.startSoc, 32), 0, 100),
+  endSoc: clamp(finiteOr(inputs.endSoc, 80), 0, 100),
+  chargerPowerKw: clamp(finiteOr(inputs.chargerPowerKw, 7.4), 0.1, 350),
+  efficiency: clamp(finiteOr(inputs.efficiency, 0.9), 0.5, 1),
+  pricePerKwh: clamp(
+    finiteOr(inputs.pricePerKwh, 0.25 * getCurrencyOption(isCurrencyCode(inputs.currency) ? inputs.currency : DEFAULT_CURRENCY).unitsPerEur),
+    0,
+    5 * getCurrencyOption(isCurrencyCode(inputs.currency) ? inputs.currency : DEFAULT_CURRENCY).unitsPerEur,
+  ),
+  consumptionKwhPer100Km: clamp(finiteOr(inputs.consumptionKwhPer100Km, 18), 1, 100),
+});
+
+export function calculateChargingPlan(inputs: ChargingInputs): ChargingPlan {
+  const values = safeInputs(inputs);
+  const chargeFraction = Math.max(0, values.endSoc - values.startSoc) / 100;
+  const batteryEnergyKwh = values.capacityKwh * chargeFraction;
+  const gridEnergyKwh = batteryEnergyKwh / values.efficiency;
+  const lossEnergyKwh = Math.max(0, gridEnergyKwh - batteryEnergyKwh);
+  const timeHours = gridEnergyKwh / values.chargerPowerKw;
+  const timeMinutes = Math.ceil(timeHours * 60);
+  const exchangeFactor = getCurrencyOption(values.currency).unitsPerEur;
+  const pricePerKwhEur = values.pricePerKwh / exchangeFactor;
+  const cost = gridEnergyKwh * pricePerKwhEur * exchangeFactor;
+  const recoveredRangeKm = (batteryEnergyKwh / values.consumptionKwhPer100Km) * 100;
+
+  return {
+    chargeFraction,
+    batteryEnergyKwh,
+    gridEnergyKwh,
+    lossEnergyKwh,
+    timeHours,
+    timeMinutes,
+    cost,
+    recoveredRangeKm,
+    currency: values.currency,
+    exchangeFactor,
+    pricePerKwhEur,
+  };
+}

package/src/tool/evChargingTimeCostPlanner/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { evChargingTimeCostPlanner } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = evChargingTimeCostPlanner.i18n[locale] ?? evChargingTimeCostPlanner.i18n.en;
+const content = await loader?.();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/evChargingTimeCostPlanner/storage.ts

@@ -0,0 +1,27 @@
+import type { ChargingInputs } from './logic';
+
+const STORAGE_KEY = 'jjlmoya-ev-charging-time-cost-planner';
+
+export function loadChargingInputs(): Partial<ChargingInputs> | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const value: unknown = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    return value as Partial<ChargingInputs>;
+  } catch {
+    return null;
+  }
+}
+
+export function saveChargingInputs(inputs: ChargingInputs): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(inputs));
+  } catch {}
+}
+
+export function clearChargingInputs(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {}
+}

package/src/tool/evChargingTimeCostPlanner/ui.ts

@@ -0,0 +1,50 @@
+export interface EVChargingTimeCostPlannerUI extends Record<string, string> {
+  defaultCurrency: string;
+  currencyLabel: string;
+  currencyHint: string;
+  currencyMenuLabel: string;
+  currencyFactorTemplate: string;
+  presetMetaTemplate: string;
+  presetLabel: string;
+  homePreset: string;
+  publicPreset: string;
+  fastPreset: string;
+  resetLabel: string;
+  setupLabel: string;
+  setupHint: string;
+  chargeWindowLabel: string;
+  chargeWindowHint: string;
+  startSocLabel: string;
+  startSocHint: string;
+  endSocLabel: string;
+  endSocHint: string;
+  capacityLabel: string;
+  capacityHint: string;
+  chargerPowerLabel: string;
+  chargerPowerHint: string;
+  efficiencyLabel: string;
+  efficiencyHint: string;
+  priceLabel: string;
+  priceHint: string;
+  consumptionLabel: string;
+  consumptionHint: string;
+  resultKicker: string;
+  resultTitle: string;
+  batterySceneLabel: string;
+  startingChargeLabel: string;
+  targetChargeLabel: string;
+  batteryEnergyLabel: string;
+  gridEnergyLabel: string;
+  lossesLabel: string;
+  timeLabel: string;
+  costLabel: string;
+  rangeLabel: string;
+  statusEmpty: string;
+  statusShort: string;
+  statusStandard: string;
+  statusLong: string;
+  summaryTemplate: string;
+  formulaLabel: string;
+  formulaText: string;
+  rangeUnit: string;
+}

package/src/tools.ts

@@ -4,5 +4,8 @@ import { CAR_MOTORCYCLE_GEAR_RATIO_CALCULATOR_TOOL } from './tool/carMotorcycleG
 import { MOTORCYCLE_SKID_MARK_SPEED_ESTIMATOR_TOOL } from './tool/motorcycleSkidMarkSpeedEstimator';
 import { REAL_FUEL_CONSUMPTION_CALCULATOR_TOOL } from './tool/realFuelConsumptionCalculator';
 import { TIRE_PRESSURE_CONVERTER_TOOL } from './tool/tirePressureConverter';
+import { EV_CHARGING_TIME_COST_PLANNER_TOOL } from './tool/evChargingTimeCostPlanner';
 
-export const ALL_TOOLS = [BRAKING_DISTANCE_CALCULATOR_TOOL, REAL_FUEL_CONSUMPTION_CALCULATOR_TOOL, CAR_MOTORCYCLE_GEAR_RATIO_CALCULATOR_TOOL, TIRE_PRESSURE_CONVERTER_TOOL, MOTORCYCLE_SKID_MARK_SPEED_ESTIMATOR_TOOL];
+export const ALL_TOOLS = [BRAKING_DISTANCE_CALCULATOR_TOOL, REAL_FUEL_CONSUMPTION_CALCULATOR_TOOL, CAR_MOTORCYCLE_GEAR_RATIO_CALCULATOR_TOOL, TIRE_PRESSURE_CONVERTER_TOOL, MOTORCYCLE_SKID_MARK_SPEED_ESTIMATOR_TOOL, EV_CHARGING_TIME_COST_PLANNER_TOOL];
+export { evChargingTimeCostPlanner } from './tool/evChargingTimeCostPlanner/entry';
+export type { EVChargingTimeCostPlannerLocaleContent } from './tool/evChargingTimeCostPlanner/entry';