@jjlmoya/utils-finance 1.35.0 → 1.36.0

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { calculateInflationTimeline, getMilestoneYears } from './logic';
+
+describe('calculateInflationTimeline', () => {
+  it('compounds the cost equivalent and discounts unchanged cash', () => {
+    const result = calculateInflationTimeline({ startingAmount: 1000, annualInflationRate: 5, years: 10, annualCashFlow: 0, cashFlowMode: 'none' });
+    expect(result?.priceFactor).toBe(1.63);
+    expect(result?.points.at(-1)?.costEquivalent).toBe(1628.89);
+    expect(result?.points.at(-1)?.unchangedRealValue).toBe(613.91);
+    expect(result?.purchasingPowerLossPercent).toBe(38.61);
+  });
+
+  it('adds annual contributions to the nominal balance and discounts the result', () => {
+    const result = calculateInflationTimeline({ startingAmount: 1000, annualInflationRate: 2, years: 5, annualCashFlow: 200, cashFlowMode: 'contribution' });
+    expect(result?.points.at(-1)?.nominalBalance).toBe(2000);
+    expect(result?.points.at(-1)?.realBalance).toBe(1811.46);
+  });
+
+  it('stops a withdrawal scenario at zero and reports depletion', () => {
+    const result = calculateInflationTimeline({ startingAmount: 500, annualInflationRate: 2, years: 5, annualCashFlow: 200, cashFlowMode: 'withdrawal' });
+    expect(result?.points.at(-1)?.nominalBalance).toBe(0);
+    expect(result?.depletionYear).toBe(3);
+  });
+
+  it('deduplicates milestone years for short timelines', () => {
+    expect(getMilestoneYears(1)).toEqual([0, 1]);
+    expect(getMilestoneYears(4)).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('rejects invalid rates, periods and amounts', () => {
+    expect(calculateInflationTimeline({ startingAmount: 0, annualInflationRate: 2, years: 5, annualCashFlow: 0, cashFlowMode: 'none' })).toBeNull();
+    expect(calculateInflationTimeline({ startingAmount: 1000, annualInflationRate: -100, years: 5, annualCashFlow: 0, cashFlowMode: 'none' })).toBeNull();
+    expect(calculateInflationTimeline({ startingAmount: 1000, annualInflationRate: 2, years: 5.5, annualCashFlow: 0, cashFlowMode: 'none' })).toBeNull();
+  });
+});

package/src/tool/inflationPurchasingPower/logic.ts

@@ -0,0 +1,92 @@
+export type CashFlowMode = 'none' | 'contribution' | 'withdrawal';
+
+export interface InflationPurchasingPowerInput {
+  startingAmount: number;
+  annualInflationRate: number;
+  years: number;
+  annualCashFlow: number;
+  cashFlowMode: CashFlowMode;
+}
+
+export interface InflationTimelinePoint {
+  year: number;
+  costEquivalent: number;
+  unchangedRealValue: number;
+  nominalBalance: number;
+  realBalance: number;
+}
+
+export interface InflationPurchasingPowerResult {
+  input: InflationPurchasingPowerInput;
+  priceFactor: number;
+  purchasingPowerLossPercent: number;
+  points: InflationTimelinePoint[];
+  milestones: InflationTimelinePoint[];
+  depletionYear: number | null;
+}
+
+const round = (value: number): number => Number(value.toFixed(2));
+
+function hasFiniteValues(input: InflationPurchasingPowerInput): boolean {
+  return [input.startingAmount, input.annualInflationRate, input.years, input.annualCashFlow].every(Number.isFinite);
+}
+
+function hasValidRanges(input: InflationPurchasingPowerInput): boolean {
+  return input.startingAmount > 0
+    && input.annualInflationRate > -100
+    && input.annualInflationRate <= 100
+    && Number.isInteger(input.years)
+    && input.years >= 1
+    && input.years <= 80
+    && input.annualCashFlow >= 0;
+}
+
+function hasValidCashFlowMode(input: InflationPurchasingPowerInput): boolean {
+  return ['none', 'contribution', 'withdrawal'].includes(input.cashFlowMode);
+}
+
+function isValidInput(input: InflationPurchasingPowerInput): boolean {
+  return hasFiniteValues(input) && hasValidRanges(input) && hasValidCashFlowMode(input);
+}
+
+function getNominalBalance(input: InflationPurchasingPowerInput, year: number): number {
+  const flow = input.cashFlowMode === 'contribution' ? input.annualCashFlow : -input.annualCashFlow;
+  if (input.cashFlowMode === 'none') return input.startingAmount;
+  return Math.max(0, input.startingAmount + flow * year);
+}
+
+function createPoint(input: InflationPurchasingPowerInput, year: number): InflationTimelinePoint {
+  const priceFactor = (1 + input.annualInflationRate / 100) ** year;
+  const nominalBalance = getNominalBalance(input, year);
+  return {
+    year,
+    costEquivalent: round(input.startingAmount * priceFactor),
+    unchangedRealValue: round(input.startingAmount / priceFactor),
+    nominalBalance: round(nominalBalance),
+    realBalance: round(nominalBalance / priceFactor),
+  };
+}
+
+export function getMilestoneYears(years: number): number[] {
+  return [...new Set([0, Math.round(years * 0.25), Math.round(years * 0.5), Math.round(years * 0.75), years])];
+}
+
+export function calculateInflationTimeline(input: InflationPurchasingPowerInput): InflationPurchasingPowerResult | null {
+  if (!isValidInput(input)) return null;
+  const points = Array.from({ length: input.years + 1 }, (_, year) => createPoint(input, year));
+  const milestones = getMilestoneYears(input.years)
+    .map((year) => points[year])
+    .filter((point): point is InflationTimelinePoint => point !== undefined);
+  const depletionYear = input.cashFlowMode === 'withdrawal' && input.annualCashFlow > 0
+    ? points.find((point) => point.nominalBalance === 0 && point.year > 0)?.year ?? null
+    : null;
+  const priceFactor = (1 + input.annualInflationRate / 100) ** input.years;
+  return {
+    input,
+    priceFactor: round(priceFactor),
+    purchasingPowerLossPercent: round((1 - 1 / priceFactor) * 100),
+    points,
+    milestones,
+    depletionYear,
+  };
+}

package/src/tool/inflationPurchasingPower/seo.astro

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

package/src/tool/inflationPurchasingPower/storage.ts

@@ -0,0 +1,29 @@
+import type { InflationPurchasingPowerInput } from './logic';
+
+const STORAGE_KEY = 'jjlmoya-finance-inflation-purchasing-power';
+
+function isStoredState(value: Partial<InflationPurchasingPowerInput>): boolean {
+  return typeof value.startingAmount === 'number'
+    && typeof value.annualInflationRate === 'number'
+    && typeof value.years === 'number'
+    && typeof value.annualCashFlow === 'number';
+}
+
+export function loadInflationPurchasingPowerState(fallback: InflationPurchasingPowerInput): InflationPurchasingPowerInput {
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    if (!stored) return fallback;
+    const parsed = JSON.parse(stored) as Partial<InflationPurchasingPowerInput>;
+    if (!isStoredState(parsed)) return fallback;
+    const cashFlowMode = parsed.cashFlowMode === 'contribution' || parsed.cashFlowMode === 'withdrawal' ? parsed.cashFlowMode : 'none';
+    return { ...fallback, ...parsed, cashFlowMode };
+  } catch {
+    return fallback;
+  }
+}
+
+export function saveInflationPurchasingPowerState(state: InflationPurchasingPowerInput): void {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}

package/src/tool/inflationPurchasingPower/ui.ts

@@ -0,0 +1,42 @@
+export interface InflationPurchasingPowerUI extends Record<string, string> {
+  amountLabel: string;
+  amountHelp: string;
+  inflationLabel: string;
+  inflationHelp: string;
+  yearsLabel: string;
+  yearsHelp: string;
+  cashFlowLabel: string;
+  cashFlowHelp: string;
+  cashFlowModeLabel: string;
+  noCashFlowOption: string;
+  contributionOption: string;
+  withdrawalOption: string;
+  costEquivalentLabel: string;
+  realValueLabel: string;
+  nominalBalanceLabel: string;
+  purchasingPowerLossLabel: string;
+  todayLabel: string;
+  endLabel: string;
+  costLineLabel: string;
+  realLineLabel: string;
+  balanceLineLabel: string;
+  chartDescription: string;
+  chartNote: string;
+  milestoneTitle: string;
+  yearHeader: string;
+  costHeader: string;
+  realHeader: string;
+  balanceHeader: string;
+  methodTitle: string;
+  methodText: string;
+  limitationText: string;
+  emptyMessage: string;
+  contributionSummary: string;
+  withdrawalSummary: string;
+  noCashFlowSummary: string;
+  depletionWarning: string;
+  scenarioNote: string;
+  currencyHint: string;
+  yearsSuffix: string;
+  amountSuffix: string;
+}

package/src/tools.ts

@@ -19,5 +19,6 @@ import { PESETA_VALUE_TOOL } from './tool/pesetaValue';
 import { SALARY_EMPLOYER_COST_TOOL } from './tool/salaryEmployerCost';
 import { DIVIDEND_YIELD_TOOL } from './tool/dividendYield';
 import { MORTGAGE_EXTRA_PAYMENT_PLANNER_TOOL } from './tool/mortgageExtraPaymentPlanner';
+import { INFLATION_PURCHASING_POWER_TOOL } from './tool/inflationPurchasingPower';
 
-export const ALL_TOOLS: ToolDefinition[] = [COMPOUND_INTEREST_TOOL, FINANCIAL_FREEDOM_TOOL, PROFITABILITY_TOOL, MORTGAGE_TOOL, INFLATION_TOOL, PERCENTAGE_CALCULATOR_TOOL, LATE_INTEREST_TOOL, IBAN_BIC_SWIFT_TOOL, RENT_INCREASE_TOOL, LOTTERY_OPTIMIZER_TOOL, COURT_FEE_CALCULATOR_TOOL, LEGAL_INTEREST_RATE_TOOL, FIRE_CALCULATOR_TOOL, DEBT_SNOWBALL_TOOL, REVOLVING_CARD_CALCULATOR_TOOL, PESETA_VALUE_TOOL, SALARY_EMPLOYER_COST_TOOL, DIVIDEND_YIELD_TOOL, MORTGAGE_EXTRA_PAYMENT_PLANNER_TOOL];
+export const ALL_TOOLS: ToolDefinition[] = [COMPOUND_INTEREST_TOOL, FINANCIAL_FREEDOM_TOOL, PROFITABILITY_TOOL, MORTGAGE_TOOL, INFLATION_TOOL, PERCENTAGE_CALCULATOR_TOOL, LATE_INTEREST_TOOL, IBAN_BIC_SWIFT_TOOL, RENT_INCREASE_TOOL, LOTTERY_OPTIMIZER_TOOL, COURT_FEE_CALCULATOR_TOOL, LEGAL_INTEREST_RATE_TOOL, FIRE_CALCULATOR_TOOL, DEBT_SNOWBALL_TOOL, REVOLVING_CARD_CALCULATOR_TOOL, PESETA_VALUE_TOOL, SALARY_EMPLOYER_COST_TOOL, DIVIDEND_YIELD_TOOL, MORTGAGE_EXTRA_PAYMENT_PLANNER_TOOL, INFLATION_PURCHASING_POWER_TOOL];