Mavusi.Financials 1.0.1

Mavusi.Financials

A comprehensive fintech calculator library for .NET that makes financial calculations straightforward and user-friendly.

Mavusi.Financials provides production-ready financial calculators for loans, investments, retirement planning, debt management, and more. Every calculation returns a friendly, human-readable message that's ready for your UI—no additional formatting required.

Perfect for fintech applications, personal finance tools, banking platforms, and any .NET project that needs solid financial math.

✨ What You Get

Lending & Loan Management

• Loan Repayment Calculator — Monthly payment, total interest, and total repayment amount
• Amortization Schedules — Month-by-month breakdown with principal, interest, and balance
• Extra Payment Simulations — See how extra payments accelerate payoff and save interest

Interest Rate Conversions

• APR ↔ EAR Calculations — Convert between annual percentage rate and effective annual rate
• Compound Interest — Calculate growth with flexible compounding periods

Investment & Wealth Building

• Investment Growth Projections — Multi-year projections with annual contributions
• NPV/IRR/XIRR Calculations — Evaluate investment returns and profitability
• Scenario Simulations — Compare best-case and worst-case investment outcomes

Debt & Financial Health

• Debt Payoff Optimization — Avalanche (high interest first) and Snowball (smallest balance first) strategies
• Affordability Calculations — Max loan amount and purchase price based on income and DTI
• Tax Estimation — Progressive bracket calculations with effective tax rates

Retirement & Inflation

• Retirement Projections — Nest egg requirements and surplus/shortfall analysis
• Inflation Adjustment — Future/present value calculations and real rate of return
• Scenario Simulations — Test retirement savings across multiple strategies

Utilities

• Business Day Handling — Count, check, and add business days with holiday support
• Currency Utilities — Precise rounding, formatting (R-currency), and conversion
• Date Handling — Easy date arithmetic and business day calculations

🚀 Getting Started

Installation

Install from NuGet (when published):

dotnet add package Mavusi.Financials

Or manually reference the project in your solution.

Supported Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

📚 Usage Examples

Loan Repayment Calculator

Calculate how much you'll pay back on a loan:

using Mavusi.Financials;

var result = LoanRepaymentCalculator.CalculateMonthlyRepayment(
    principal: 500_000m,
    annualInterestRatePercent: 14m,
    months: 60);

Console.WriteLine(result.Message);
// Output: You will be paying back R697,630.80 over 60 months at 14.00% interest.
Console.WriteLine($"Monthly Payment: {result.MonthlyPayment}");  // 11627.18
Console.WriteLine($"Total Interest: {result.TotalInterest}");    // 197630.80

Amortization Schedule

Get a detailed month-by-month breakdown:

var schedule = AmortizationScheduleCalculator.BuildSchedule(
    principal: 500_000m,
    annualInterestRatePercent: 14m,
    termMonths: 60,
    extraMonthlyPayment: 500m);

Console.WriteLine(schedule.Message);
// Output: Generated an amortization schedule of 50 months with total interest of 170,245.62.

foreach (var entry in schedule.Entries.Take(3))
{
    Console.WriteLine($"Month {entry.Month}: " +
        $"Payment {entry.Payment}, " +
        $"Principal {entry.Principal}, " +
        $"Interest {entry.Interest}, " +
        $"Balance {entry.RemainingBalance}");
}

Extra Payment Simulation

See how extra payments save money:

var simulation = ExtraPaymentSimulator.Simulate(
    principal: 500_000m,
    annualInterestRatePercent: 14m,
    termMonths: 60,
    extraMonthlyPayment: 2000m);

Console.WriteLine(simulation.Message);
// Output: Paying an extra R2000.00 monthly saves R27,385.18 in interest and cuts 
//         payoff time from 60 to 47 months.

APR to EAR Conversion

Convert between interest rate formats:

var ear = AprEarCalculator.CalculateEarFromApr(
    aprPercent: 12m,
    compoundsPerYear: 12);

Console.WriteLine(ear.Message);
// Output: An APR of 12.00% compounded 12 times per year yields an EAR of 12.6825%.

Compound Interest

Calculate investment growth:

var result = CompoundInterestCalculator.CalculateGrowth(
    principal: 100_000m,
    annualInterestRatePercent: 9m,
    compoundsPerYear: 12,
    years: 10,
    contributionPerPeriod: 500m);

Console.WriteLine(result.Message);
// Output: Your investment can grow to R743,152.63 over 10 years at 9.00% annual interest.

Investment Growth Projection

Project multi-year investment growth:

var projection = InvestmentGrowthProjector.Project(
    startingBalance: 100_000m,
    annualReturnPercent: 9m,
    annualContribution: 24_000m,
    years: 15,
    annualContributionGrowthPercent: 5m);

Console.WriteLine(projection.Message);
// Output: Projected investment value after 15 years is R1,053,847.29.

foreach (var year in projection.Years.Where(y => y.Year % 5 == 0))
{
    Console.WriteLine($"Year {year.Year}: {year.EndingBalance}");
}

NPV and IRR Calculations

Evaluate investment returns:

// NPV: Net Present Value at a 10% discount rate
var npv = NpvIrrXirrCalculator.CalculateNpv(
    discountRatePercent: 10m,
    cashFlows: new[] { -100_000m, 30_000m, 35_000m, 40_000m });

Console.WriteLine(npv.Message);
// Output: The NPV at a discount rate of 10.00% is R1,328.62.

// IRR: Internal Rate of Return (annual return rate)
var irr = NpvIrrXirrCalculator.CalculateIrr(
    cashFlows: new[] { -100_000m, 30_000m, 35_000m, 40_000m });

Console.WriteLine(irr.Message);
// Output: The estimated IRR for this cash flow set is 10.6135%.

XIRR with Dated Cash Flows

Calculate return across irregular dated cash flows:

var xirr = NpvIrrXirrCalculator.CalculateXirr(new[]
{
    new CashFlowPoint(new DateOnly(2024, 1, 1), -120_000m),
    new CashFlowPoint(new DateOnly(2024, 7, 1), 20_000m),
    new CashFlowPoint(new DateOnly(2025, 7, 1), 30_000m),
    new CashFlowPoint(new DateOnly(2026, 7, 1), 95_000m)
});

Console.WriteLine(xirr.Message);
// Output: The estimated XIRR for the dated cash flows is 5.1234%.

Debt Payoff Optimization

Choose the best debt payoff strategy:

var debts = new List<DebtAccount>
{
    new DebtAccount("Credit Card", 15_000m, 23.5m, 300m),
    new DebtAccount("Personal Loan", 25_000m, 12m, 500m),
    new DebtAccount("Car Loan", 80_000m, 8m, 1_200m)
};

// Avalanche: Pay highest interest first (mathematically optimal)
var avalanche = DebtPayoffOptimizer.Optimize(debts, 2_500m, DebtPayoffStrategy.Avalanche);
Console.WriteLine(avalanche.Message);
// Output: Using the Avalanche strategy, you will become debt-free in 47 months 
//         and pay 8,234.50 in interest.

// Snowball: Pay smallest balance first (motivational)
var snowball = DebtPayoffOptimizer.Optimize(debts, 2_500m, DebtPayoffStrategy.Snowball);
Console.WriteLine(snowball.Message);
// Output: Using the Snowball strategy, you will become debt-free in 52 months 
//         and pay 10,123.00 in interest.

Retirement Projection

Plan for retirement:

var retirement = RetirementProjectionCalculator.Project(
    currentAge: 35,
    retirementAge: 65,
    currentSavings: 150_000m,
    annualContribution: 50_000m,
    expectedAnnualReturnPercent: 8m,
    expectedAnnualInflationPercent: 5m,
    desiredAnnualIncomeAtRetirement: 100_000m,
    safeWithdrawalRatePercent: 4m);

Console.WriteLine(retirement.Message);
// Output: At age 65, your projected nest egg is R4,234,567.89; target need is R3,891,234.56, 
//         leaving a surplus of R343,333.33.

Affordability Calculator

Find out what you can afford:

var affordability = AffordabilityCalculator.CalculateMaxAffordablePurchase(
    grossMonthlyIncome: 50_000m,
    existingMonthlyDebtPayments: 5_000m,
    maxDebtToIncomePercent: 43m,
    annualLoanInterestPercent: 8.5m,
    loanTermMonths: 240,
    downPayment: 100_000m);

Console.WriteLine(affordability.Message);
// Output: At a DTI cap of 43.00%, you can afford about 15,650.00 per month, 
//         supporting a loan near 2,350,000.00.

Tax Estimation

Calculate estimated taxes with progressive brackets:

var brackets = new List<TaxBracket>
{
    new TaxBracket(500_000m, 18m),
    new TaxBracket(1_000_000m, 25m),
    new TaxBracket(2_000_000m, 30m),
    new TaxBracket(decimal.MaxValue, 35m)
};

var estimate = TaxEstimator.EstimateAnnualTax(1_500_000m, brackets);
Console.WriteLine(estimate.Message);
// Output: Estimated annual tax on R1,500,000.00 is R357,500.00 (effective rate 23.83%).

Business Day Handling

Work with business days:

// Check if a date is a business day
var checkDay = BusinessDayDateHandler.CheckBusinessDay(new DateOnly(2024, 5, 10));
Console.WriteLine(checkDay.Message);
// Output: 2024-05-10 is a business day.

// Count business days between two dates
var businessDayCount = BusinessDayDateHandler.CountBusinessDays(
    new DateOnly(2024, 5, 1),
    new DateOnly(2024, 5, 31));
Console.WriteLine(businessDayCount.Message);
// Output: There are 23 business days between 2024-05-01 and 2024-05-31.

// Add business days to a date
var newDate = BusinessDayDateHandler.AddBusinessDays(
    new DateOnly(2024, 5, 10),
    5);
Console.WriteLine(newDate.Message);
// Output: Adding 5 business days to 2024-05-10 results in 2024-05-17.

Currency Utilities

Format and convert currency:

// Format as R-currency (South African Rand)
var formatted = CurrencyUtilities.AsRand(25_567.89m);
Console.WriteLine(formatted);  // Output: R25,567.89

// Convert currency with exchange rate
var converted = CurrencyUtilities.Convert(
    amount: 10_000m,
    sourceCurrency: "ZAR",
    targetCurrency: "USD",
    fxRate: 0.055m);  // Example rate
Console.WriteLine(converted.Message);
// Output: Converting R10,000.00 at 0.055000 gives $550.00 USD.

Inflation Adjustment

Calculate inflation impact:

// What will R100,000 be worth in 10 years?
var future = InflationAdjuster.AdjustToFutureValue(
    amountToday: 100_000m,
    annualInflationPercent: 6m,
    years: 10);
Console.WriteLine(future.Message);
// Output: R100,000.00 today is equivalent to R179,084.77 in 10 years at 6.00% inflation.

// Real rate of return
var realRate = InflationAdjuster.CalculateRealRate(
    nominalAnnualRatePercent: 10m,
    annualInflationPercent: 6m);
Console.WriteLine(realRate.Message);
// Output: A nominal return of 10.00% with inflation at 6.00% gives a real return of 3.7736%.

Scenario Simulation

Compare multiple investment scenarios:

var scenarios = new List<ScenarioDefinition>
{
    new ScenarioDefinition("Conservative", AnnualReturnPercent: 5m, AnnualContribution: 24_000m, Years: 20),
    new ScenarioDefinition("Balanced", AnnualReturnPercent: 8m, AnnualContribution: 24_000m, Years: 20),
    new ScenarioDefinition("Aggressive", AnnualReturnPercent: 12m, AnnualContribution: 24_000m, Years: 20)
};

var simulation = ScenarioSimulator.RunInvestmentScenarios(
    startingBalance: 50_000m,
    scenarios: scenarios);

Console.WriteLine(simulation.Message);
// Output: Best scenario is Aggressive at 1,234,567.89 real value; 
//         worst is Conservative at 654,321.10.

foreach (var outcome in simulation.Outcomes)
{
    Console.WriteLine($"{outcome.Name}: {outcome.Message}");
}

🔧 API Design

All calculators return strongly-typed result records that include:

• Numeric outputs — The main calculation results
• Structured breakdowns — Line-by-line details where applicable (e.g., amortization)
• Message field — A friendly, formatted string ready for display to users

Example result structure:

public sealed record LoanRepaymentResult(
    decimal MonthlyPayment,
    decimal TotalPayment,
    decimal TotalInterest,
    string Message);

No additional formatting or string interpolation needed—just display the Message directly.

📦 Building & Packaging

Build

export PATH=$HOME/.dotnet:$PATH
dotnet build Mavusi.Financials/Mavusi.Financials.csproj

Pack for NuGet

export PATH=$HOME/.dotnet:$PATH
dotnet pack Mavusi.Financials/Mavusi.Financials.csproj -c Release

Packages are output to artifacts/packages/.

Publish to NuGet.org

dotnet nuget push artifacts/packages/Mavusi.Financials.1.0.0.nupkg \
  --api-key YOUR_NUGET_API_KEY \
  --source https://api.nuget.org/v3/index.json

📄 License

MIT License — see LICENSE file for details.

Questions or suggestions? Open an issue or contribute a pull request!