@jjlmoya/utils-finance 1.40.0 → 1.41.0

package/src/tool/savingsRate/entry.ts

@@ -0,0 +1,31 @@
+import type { FinanceToolEntry, ToolLocaleContent } from "../../types";
+import type { SavingsRateUI } from "./ui";
+
+export type SavingsRateLocaleContent = ToolLocaleContent<SavingsRateUI>;
+
+export const savingsRate: FinanceToolEntry<SavingsRateUI> = {
+  id: "savings-rate-calculator",
+  icons: {
+    bg: "mdi:wallet-outline",
+    fg: "mdi:chart-donut",
+  },
+  i18n: {
+    en: () => import("./i18n/en").then((module) => module.content),
+    de: () => import("./i18n/de").then((module) => module.content),
+    es: () => import("./i18n/es").then((module) => module.content),
+    fr: () => import("./i18n/fr").then((module) => module.content),
+    id: () => import("./i18n/id").then((module) => module.content),
+    it: () => import("./i18n/it").then((module) => module.content),
+    ja: () => import("./i18n/ja").then((module) => module.content),
+    ko: () => import("./i18n/ko").then((module) => module.content),
+    nl: () => import("./i18n/nl").then((module) => module.content),
+    pl: () => import("./i18n/pl").then((module) => module.content),
+    pt: () => import("./i18n/pt").then((module) => module.content),
+    ru: () => import("./i18n/ru").then((module) => module.content),
+    sv: () => import("./i18n/sv").then((module) => module.content),
+    tr: () => import("./i18n/tr").then((module) => module.content),
+    zh: () => import("./i18n/zh").then((module) => module.content),
+  },
+};
+
+export { bibliography } from "./bibliography";

package/src/tool/savingsRate/i18n/de.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("de");

package/src/tool/savingsRate/i18n/en.ts

@@ -0,0 +1 @@
+export { content } from "../content";

package/src/tool/savingsRate/i18n/es.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("es");

package/src/tool/savingsRate/i18n/fr.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("fr");

package/src/tool/savingsRate/i18n/id.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("id");

package/src/tool/savingsRate/i18n/it.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("it");

package/src/tool/savingsRate/i18n/ja.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("ja");

package/src/tool/savingsRate/i18n/ko.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("ko");

package/src/tool/savingsRate/i18n/nl.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("nl");

package/src/tool/savingsRate/i18n/pl.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("pl");

package/src/tool/savingsRate/i18n/pt.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("pt");

package/src/tool/savingsRate/i18n/ru.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("ru");

package/src/tool/savingsRate/i18n/sv.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("sv");

package/src/tool/savingsRate/i18n/tr.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("tr");

package/src/tool/savingsRate/i18n/zh.ts

@@ -0,0 +1,3 @@
+import { createSavingsRateContent } from "../content";
+
+export const content = createSavingsRateContent("zh");

package/src/tool/savingsRate/index.ts

@@ -0,0 +1,11 @@
+import { savingsRate } from "./entry";
+import type { ToolDefinition } from "../../types";
+
+export * from "./entry";
+
+export const SAVINGS_RATE_TOOL: ToolDefinition = {
+  entry: savingsRate,
+  Component: () => import("./component.astro"),
+  SEOComponent: () => import("./seo.astro"),
+  BibliographyComponent: () => import("./bibliography.astro"),
+};

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { calculateSavingsRate } from "./logic";
+
+describe("calculateSavingsRate", () => {
+  it("calculates the current rate, annualized totals, and target gap", () => {
+    const result = calculateSavingsRate({
+      income: 4000,
+      saved: 1200,
+      extraContribution: 200,
+      targetRate: 40,
+      incomeChange: 0,
+      spendingChange: 0,
+      period: "monthly",
+    });
+
+    expect(result).toMatchObject({
+      spending: 2600,
+      saved: 1400,
+      rate: 35,
+      annualIncome: 48000,
+      annualSaved: 16800,
+      targetGap: 5,
+      additionalToTarget: 200,
+    });
+    expect(result?.scenario.rate).toBe(35);
+  });
+
+  it("shows how income and spending changes alter the rate", () => {
+    const result = calculateSavingsRate({
+      income: 3000,
+      saved: 900,
+      extraContribution: 0,
+      targetRate: 40,
+      incomeChange: 10,
+      spendingChange: -5,
+      period: "monthly",
+    });
+
+    expect(result?.scenario.income).toBe(3300);
+    expect(result?.scenario.spending).toBe(1995);
+    expect(result?.scenario.saved).toBe(1305);
+    expect(result?.scenario.rate).toBe(39.55);
+    expect(result?.scenario.changeFromBase).toBe(9.55);
+  });
+
+  it("does not ask for more savings when the target is already met", () => {
+    const result = calculateSavingsRate({
+      income: 5000,
+      saved: 2500,
+      extraContribution: 0,
+      targetRate: 40,
+      incomeChange: 0,
+      spendingChange: 0,
+      period: "yearly",
+    });
+
+    expect(result?.additionalToTarget).toBe(0);
+    expect(result?.targetGap).toBe(-10);
+    expect(result?.annualIncome).toBe(5000);
+  });
+
+  it("rejects impossible or incomplete inputs", () => {
+    expect(
+      calculateSavingsRate({
+        income: 0,
+        saved: 0,
+        extraContribution: 0,
+        targetRate: 20,
+        incomeChange: 0,
+        spendingChange: 0,
+        period: "monthly",
+      }),
+    ).toBeNull();
+
+    expect(
+      calculateSavingsRate({
+        income: 3000,
+        saved: 3500,
+        extraContribution: 0,
+        targetRate: 20,
+        incomeChange: 0,
+        spendingChange: 0,
+        period: "monthly",
+      }),
+    ).toBeNull();
+  });
+});

package/src/tool/savingsRate/logic.ts

@@ -0,0 +1,121 @@
+export type SavingsPeriod = "monthly" | "yearly";
+
+export interface SavingsRateInput {
+  income: number;
+  saved: number;
+  extraContribution: number;
+  targetRate: number;
+  incomeChange: number;
+  spendingChange: number;
+  period: SavingsPeriod;
+}
+
+export interface SavingsRateScenario {
+  income: number;
+  spending: number;
+  saved: number;
+  rate: number;
+  changeFromBase: number;
+  targetGap: number;
+  additionalToTarget: number;
+}
+
+export interface SavingsRateResult {
+  period: SavingsPeriod;
+  income: number;
+  spending: number;
+  saved: number;
+  rate: number;
+  annualIncome: number;
+  annualSaved: number;
+  targetRate: number;
+  targetGap: number;
+  additionalToTarget: number;
+  scenario: SavingsRateScenario;
+}
+
+const round = (value: number, decimals = 2): number => {
+  const factor = 10 ** decimals;
+  return Math.round((value + Number.EPSILON) * factor) / factor;
+};
+
+const safeRate = (saved: number, income: number): number => {
+  if (income <= 0) return 0;
+  return round((saved / income) * 100);
+};
+
+const annualize = (value: number, period: SavingsPeriod): number =>
+  period === "monthly" ? value * 12 : value;
+
+const isValidInput = (input: SavingsRateInput): boolean => {
+  const values = [
+    input.income,
+    input.saved,
+    input.extraContribution,
+    input.targetRate,
+    input.incomeChange,
+    input.spendingChange,
+  ];
+  return (
+    !values.some((value) => !Number.isFinite(value)) &&
+    input.income > 0 &&
+    input.saved >= 0 &&
+    input.extraContribution >= 0 &&
+    input.targetRate >= 0 &&
+    input.targetRate <= 100 &&
+    ["monthly", "yearly"].includes(input.period) &&
+    input.saved + input.extraContribution <= input.income
+  );
+};
+
+const buildScenario = (
+  input: SavingsRateInput,
+  spending: number,
+  baseRate: number,
+): SavingsRateScenario => {
+  const scenarioIncome = input.income * (1 + input.incomeChange / 100);
+  const scenarioSpending = Math.max(
+    0,
+    spending * (1 + input.spendingChange / 100),
+  );
+  const scenarioSaved = scenarioIncome - scenarioSpending;
+  const scenarioRate = safeRate(scenarioSaved, scenarioIncome);
+  return {
+    income: round(scenarioIncome),
+    spending: round(scenarioSpending),
+    saved: round(scenarioSaved),
+    rate: scenarioRate,
+    changeFromBase: round(scenarioRate - baseRate),
+    targetGap: round(input.targetRate - scenarioRate),
+    additionalToTarget: round(
+      Math.max(0, (input.targetRate / 100) * scenarioIncome - scenarioSaved),
+    ),
+  };
+};
+
+export function calculateSavingsRate(
+  input: SavingsRateInput,
+): SavingsRateResult | null {
+  if (!isValidInput(input)) return null;
+  const saved = input.saved + input.extraContribution;
+  const spending = input.income - saved;
+  const rate = safeRate(saved, input.income);
+  const additionalToTarget = Math.max(
+    0,
+    (input.targetRate / 100) * input.income - saved,
+  );
+
+  return {
+    period: input.period,
+    income: round(input.income),
+    spending: round(spending),
+    saved: round(saved),
+    rate,
+    annualIncome: round(annualize(input.income, input.period)),
+    annualSaved: round(annualize(saved, input.period)),
+    targetRate: round(input.targetRate),
+    targetGap: round(input.targetRate - rate),
+    additionalToTarget: round(additionalToTarget),
+    scenario: buildScenario(input, spending, rate),
+  };
+}